configuring-sys-image-registry.html.md.erb

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

This topic describes how to relocate VMware <%= vars.app_runtime_full %>
(<%= vars.app_runtime_short %>) images to a private container image registry.

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

Before installing <%= vars.app_runtime_short %>, 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 <%= vars.app_runtime_short %> End-User License Agreement (EULA).
* Follow the procedures in:
    * [Preparing to Install <%= vars.app_runtime_full %>](preparing-to-install-tas-for-kubernetes.html)
    * [Configuring Installation Values](configuring-installation-values.html)
* If installing <%= vars.app_runtime_short %> from a private container image 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 <%= vars.app_runtime_short %> must always be available when a container is started on a new host.

You can use either the VMware Tanzu Network or a private container image registry as your system registry:

* 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 container image registry as your system registry, follow the procedures in
[Configure a Private Container Image Registry as Your System Registry](#configure-for-private).  
<br>
    Install from a private container image 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 <%= vars.app_runtime_short %> installation.

<br>


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

<%= vars.app_runtime_short %> 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 <%= vars.app_runtime_short %> with VMware Tanzu Network user credentials:

1. Navigate to the `configuration-values` directory you created earlier.
1. Open the `values.yml` file.
1. Populate the `system_registry` section in the `values.yml` file with the following:

    ```yaml
    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, which will ensure that this account has a signed <%= vars.app_runtime_short %> EULA.
    * `PASSWORD` is the password for the account you specified.

## <a id='configure-for-private'></a> Configure a Private Container Image Registry as Your System Registry
Before installing <%= vars.app_runtime_short %> from a private container image registry,
you must relocate the <%= vars.app_runtime_short %> image from the VMware Tanzu Network Registry to the private container image registry.

To relocate the <%= vars.app_runtime_short %> image to a private container image registry:

* [Download the <%= vars.app_runtime_short %> Images](#downloading-the-images)
* [Upload the <%= vars.app_runtime_short %> Images to the Private Container Image Registry](#uploading-the-images)
* [Customize Your Configuration to Use Your Private System Registry](#configure-for-private-registry)

### <a id='downloading-the-images'></a> Download the <%= vars.app_runtime_short %> Images

To download the <%= vars.app_runtime_short %> Images from the 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 <%= vars.app_runtime_short %> Images to the Private Container Image Registry

To upload the <%= vars.app_runtime_short %> images to the private container image registry:

1. Log in to the private container image registry.

    ```
    docker login PRIVATE_REPOSITORY \
                       -u USERNAME \
                       -p PASSWORD
    ```

    Where:
    * `PRIVATE-REPOSITORY` is the FQDN or IP address for the private container image registry repository to log in to.
    * `USERNAME` is a user account with write access to the registry.
    * `PASSWORD` is the password for the user account.

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

        ```
        kbld unpackage -f <(ytt -f config/image-overrides.yml \
                         -f config/_values.yml) \
                         -i /tmp/images.tar \
                         -r PRIVATE-REPOSITORY/PROJECT/IMAGE \
                         --lock-output relocated_images.yml
        ```

        Where:
        * `PRIVATE-REPOSITORY` is the FQDN or IP address for the private container image registry repository to log in to.
        * `PROJECT` is the project name in the registry.
        * `IMAGE` is the image name to reallocate the images.
<br>
    * If your client does not have the private container image registry CA certificates:

        ```
        kbld unpackage -f <(ytt -f config/image-overrides.yml \
                         -f config/_values.yml) \
                         -i /tmp/images.tar \
                         -r PRIVATE-REPOSITORY/PROJECT/IMAGE \
                         --lock-output relocated_images.yml \
                         --registry-verify-certs=false
        ```

        Where:
        * `PRIVATE-REPOSITORY` is the FQDN or IP address for the private container image registry repository to log in to.
        * `PROJECT` is the project name in your private registry
        * `IMAGE` is the image name to reallocate the images.


<p class="note"><strong>Note:</strong>All of the required TAS images you upload have the same image name, but different SHAs.</p>

### <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. Open `configuration-values/values.yml` in a text editor.
1. To point the system registry variables to the private registry, 
configure the `system_registry` section:

    ```
    #@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.  
1. Save the `values.yml` file.

## <a id="next"></a> Next Steps

After you complete this procedure, proceed to
[Configuring Your System Databases](configuring-system-databases.html).