optional-image-relocation.html.md.erb

---
title: Configuring Your System Image Registry
owner: Tanzu Application Service Release Engineering
---

This topic describes how to relocate VMware Tanzu Application Service for Kubernetes 
(TAS for Kubernetes) images to a private container image registry.  

## <a id='prerequisites'></a> Prerequisites

Before installing TAS for Kubernetes, complete the following: 

* Ensure you have a [VMware Tanzu Network](https://network.pivotal.io/) account to 
use to download container images from the VMware Tanzu Network Registry. 
  Ensure this account has a signed TAS for Kubernetes EULA.
* Follow the procedures in:  
    * [Preparing to Install Tanzu Application Service for Kubernetes](preparing-to-install-tas-for-kubernetes.html) 
    * [Configuring Installation Values for Tanzu Application Service for Kubernetes]
    (configuring-installation-values.html) 
* If installing TAS for Kubernetes from a private registry:  
 
    * Grant write access to your private container image registry.  

## <a id='overview'></a> Overview

In Kubernetes, containers can be re-created at various times and a system image for the new container will be pulled 
from your system registry. The system registry you use for TAS for Kubernetes must always be available when a container is started on a new host.  

You can use either the VMware Tanzu Network or a private registry as your system registry.  

You should install TAS for Kubernetes from a private registry for the following situations:  

* Your deployment has limited network egress because of firewall or network bandwidth.  
* You want to reduce the external runtime dependencies of your TAS for Kubernetes installation. 

<br>
To configure the VMware Tanzu Network as your system registry, follow the procedures in 
[Configure the VMware Tanzu Network as Your System Registry](#configure-for-tanzu-network).

To configure a private registry as your system registry, follow the procedures in 
[Configure a Private Registry as Your System Registry](#configure-for-private).

<p class="note"><strong>Note</strong>: The following procedure is validated 
  for the Google Container Registry and for Harbor registries. 
</p>

## <a id='configure-for-tanzu-network'></a> Configure the VMware Tanzu Network as Your System Registry

To configure the VMware Tanzu Network as your system registry:  

* [Configure VMware Tanzu Network Account Credentials](#configure-system-registry-values)

### <a id='configure-system-registry-values'></a>Configure VMware Tanzu Network Account Credentials

TAS for Kubernetes requires a registered 
[VMware Tanzu Network](https://network.pivotal.io) account to pull container images for 
system components from the [VMware Tanzu Network container registry](https://registry.pivotal.io/).

To configure TAS for Kubernetes with VMware Tanzu Network user credentials:

1. Change directory into the `configuration-values` directory you created earlier.

1. Create a file named `system-registry-values.yml` in the `configuration-values` directory.  
1. Populate the `system-registry-values.yml` file with the following:

    ```yaml
    #@data/values
    ---
    system_registry:
      hostname: registry.pivotal.io
      username: "USERNAME"
      password: "PASSWORD"
    ```

    Where:
    * `USERNAME` is the username of the account to use to download 
    container images from the VMware Tanzu Network Registry. 
    Ensure this account has a signed TAS for Kubernetes EULA.
    * `PASSWORD` is the password for the account you specified.  

    <p class="note"><strong>Note:</strong> VMware recommends you 
      provide the VMware Tanzu Network account credentials you used to download 
      TAS for Kubernetes.
    </p>

## <a id='configure-for-private'></a> Configure a Private Registry as Your System Registry

To configure a private registry as your system registry:  

* [Relocate TAS for Kubernetes Images](#relocate-tas-for-k8s-images)
* [Customize Your Configuration to Use Your Private System Registry](#configure-for-private-registry)
* [Validate Your Installation Configuration](#configure-for-private-registry)

### <a id='relocate-tas-for-k8s-images'></a> Relocate TAS for Kubernetes Images

Before installing TAS for Kubernetes from a private registry, 
you must relocate the TAS for Kubernetes image from the VMware Tanzu Network Registry to the private registry:  

* [Download the TAS for Kubernetes Images](#downloading-the-images)
* [Upload the TAS for Kubernetes Images to the Private Registry](#uploading-the-images)

#### <a id='downloading-the-images'></a> Download the TAS for Kubernetes Images

To download the TAS for Kubernetes Images from VMware Tanzu Network Registry:

1. In your terminal, navigate to the `tanzu-application-service` directory.

1. Log in to the VMware Tanzu Network Registry.

    ```
    docker login registry.pivotal.io \
                       -u USERNAME \
                       -p PASSWORD
    ```

    Where:
    * `USERNAME` is a VMware Tanzu Network user account. 
    * `PASSWORD` is the password for the VMware Tanzu Network user account. 

1. Package the images into a tarball.  

    ```
    kbld package -f <(ytt \
                   -f config/image_overrides.yml \
                   -f config/values.yml ) \
                   --output /tmp/images.tar
    ```

    Packaging the image takes about 5 minutes to complete.

#### <a id='uploading-the-images'></a> Upload the TAS for Kubernetes Images to the Private Registry

To upload the TAS for Kubernetes images to the private registry:

1. Log in to the private registry.  

    ```
    docker login registry.SYSTEM-DOMAIN/ORG-NAME/REPOSITORY \
                       -u USERNAME \
                       -p PASSWORD
    ```

    Where:
    * Where `SYSTEM-DOMAIN` is the system domain, such as `example.com`, that you previously selected for your 
    TAS for Kubernetes installation.
    * `ORG-NAME` is your organization name, such as a Cloud Foundry Org name.
    * `REPOSITORY` is the private registry repository to log in to.
    * `USERNAME` is a user account with write access to the private registry. 
    * `PASSWORD` is the password for the user account. 

1. Unpackage the image tarball and upload to the private registry.  
    * If your client has the private registry CA certificates:  

        ```
        kbld unpackage -f <(ytt -f config/image_overrides.yml \
                         -f config/values.yml) \
                         -i /tmp/images.tar \
                         -r registry.SYSTEM-DOMAIN/ORG-NAME/REPOSITORY \
                         --lock-output relocated_images.yml
        ```

        Where:
        * Where `SYSTEM-DOMAIN` is the system domain, such as `example.com`, that you previously selected for your 
        TAS for Kubernetes installation.
        * `ORG-NAME` is your organization name, such as a Cloud Foundry Org name.
        * `REPOSITORY` is the private registry repository to log in to.  
<br>
    * If your client does not have the private registry CA certificates:  

        ```
        kbld unpackage -f <(ytt -f config/image_overrides.yml \
                         -f config/values.yml) \
                         -i /tmp/images.tar \
                         -r registry.SYSTEM-DOMAIN/ORG-NAME/REPOSITORY \
                         --lock-output relocated_images.yml \
                         --registry-verify-certs=false
        ```

        Where:
        * Where `SYSTEM-DOMAIN` is the system domain, such as `example.com`, that you previously selected for your 
        TAS for Kubernetes installation.
        * `ORG-NAME` is your organization name, such as a Cloud Foundry Org name.
        * `REPOSITORY` is the private registry repository to log in to.  

### <a id='configure-for-private-registry'></a> Customize Your Configuration to Use Your Private System Registry

To customize your configuration files for your private registry: 

1. Move the `config/image_overrides.yml` file to the `config-optional` directory.
1. To point the system registry variables to the private registry, 
modify the `configuration-values/system-registry-values.yml` as follows:

    ```
    #@data/values
    ---
    system_registry:
      hostname: "REGISTRY-HOSTNAME"
      username: "REGISTRY-USERNAME"
      password: "REGISTRY-PASSWORD"
    ```

    Where:
    * `REGISTRY-HOSTNAME` is the hostname of your private registry.
    * `REGISTRY-USERNAME` is a user account with write access to the private registry. 
    * `REGISTRY-PASSWORD` is the password for the user account.  

### <a id='configure-for-private-registry'></a> Validate Your Installation Configuration

To verify your TAS for Kubernetes installation configuration: 

1. Confirm your root TAS for Kubernetes directory contains the following subdirectories:
    - `configuration-values`
    - `tanzu-application-service`
1. Confirm the `configuration-values` subdirectory contains the following files:
    - `app-registry-values.yml`
    - `system-registry-values.yml`
    - all other customized installation YAML files you have created