Store Aspen Mesh container images in a private image registry#

Container images and the image registry#

Aspen Mesh container images#

Aspen Mesh runs as a set of containers whose images are stored in an image registry and pulled (downloaded) when necessary.

When Aspen Mesh container images are pulled#

Kubernetes pulls Aspen Mesh container images during a clean installation or an upgrade and while Aspen Mesh is running on your cluster.

Default image registry versus private image registry#

By default, Kubernetes pulls Aspen Mesh container images from the Aspen Mesh image registry, which is available over the public internet. However, you can store the Aspen Mesh container images in a private image registry and tell Kubernetes to use that registry when it needs an Aspen Mesh container image.

Note

The private image registry must be accessible by your cluster.

When to use a private image registry#

Use a private image registry instead of the default image registry if any of the following are true:

Your cluster is not connected to the public internet (this is sometimes referred to as an air-gapped cluster).
You want to use your own infrastructure to store Aspen Mesh container images for improved security and reliability.

Store Aspen Mesh container images in a private image registry#

When to follow these instructions#

Follow the instructions below only if you want to use a private image registry and only when the clean-installation or upgrade instructions tell you to do so. Perform the tasks in order.

Log in to the Aspen Mesh image registry#

Make sure your computer is connected to the public internet.
Make sure you’re in the Aspen Mesh release directory.
Execute the script to log in to the Aspen Mesh image registry:
```
$ ./tools/aspen-mesh-image-registry-login.sh
```

Pull the images from the Aspen Mesh image registry#

In the Aspen Mesh release directory, pull all the images listed in the images-used file to your computer:
```
$ cat images-used | xargs -L1 docker pull
```
You may now disconnect your computer from the public internet.

Rename the pulled images with the private repository address#

Make sure you’re in the Aspen Mesh release directory.
Execute the script to rename the pulled images, making sure to replace <privateRepositoryAddress> with the address of the private repository you want to push the Aspen Mesh images to (for example, registry.company.com/aspenmesh):
```
$ registry_repo=<privateRepositoryAddress> ./tools/rename-images.sh
```

Push the pulled images to the private image repository#

Make sure your computer has access to the private image registry.
If the private image registry requires authentication, make sure you’re logged in to the private image registry (for example, registry.company.com) and have privileges to create repositories (for example, aspenmesh) in that registry.
Make sure you’re in the Aspen Mesh release directory.
Execute the script to push the pulled images from your computer to the private image repository, making sure to replace <privateRepositoryAddress> with the address of the private repository you want to push the Aspen Mesh images to (for example, registry.company.com/aspenmesh):
```
$ registry_repo=<privateRepositoryAddress> ./tools/push-images.sh
```

Replace the Aspen Mesh image-registry pull secret with the private image-registry pull secret (if the private image registry requires authentication)#

Important

Perform this task only if the private image registry requires authentication (that is, you must provide credentials to access the registry). Typically, a private image registry in an air-gapped cluster doesn’t require authentication.

In both the istio-system and kube-system namespaces, create a pull secret that Kubernetes will use to authenticate with the private image registry and pull images from it.

Note

You can use any name you like for the pull secret except aspen-mesh-pull-secret, which is reserved for the Aspen Mesh image-registry pull secret.

Most image registries can provide you with a pull-secret manifest, which looks like this:
```
apiVersion: v1
kind: Secret
metadata:
  name: private-registry-pull-secret
data:
  .dockerconfigjson: eyJodHRwczovL2luZGV4L...J0QUl6RTIifX0=
type: kubernetes.io/dockerconfigjson
```
If your registry can’t provide you with a pull-secret manifest, see Pull an Image from a Private Registry.
Open your Aspen Mesh override values file (for example, aspen-mesh-override-values.yaml) in a text editor.

Add the following code at the top level of the hierarchy:

global:
  imagePullSecrets:
  - <privateRegistryPullSecretName>

Replace <privateRegistryPullSecretName> with the name of the private image registry’s pull secret (for example, private-registry-pull-secret).
Save and close the file.

Update your Aspen Mesh override values file with the address of the private image repository#

Open your Aspen Mesh override values file (for example, aspen-mesh-override-values.yaml) in a text editor.

If the file doesn’t contain the following hub fields, copy this information and paste it into the file at the top level of the hierarchy:

global:
  hub: <privateRepositoryAddress>

# This section is required only if you use the istio-cni chart (that is, you use OpenShift).
cni:
  hub: <privateRepositoryAddress>
  repair:
    hub: <privateRepositoryAddress>

Replace <privateRepositoryAddress> (or the existing address if applicable) with the address of the repository you pushed the Aspen Mesh images to (for example, registry.company.com/aspenmesh).
Save and close the file.

You can now perform the clean installation or the upgrade.