Store Aspen Mesh container images in a private artifact registry#

Container images and the artifact registry#

Aspen Mesh container images#

Aspen Mesh runs as a set of containers whose images are stored in an artifact 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 artifact registry versus private artifact registry#

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

Note

The private artifact registry must be an OCI-compliant registry.
The private artifact registry must be accessible by your cluster.

When to use a private artifact registry#

Use a private artifact registry instead of the default artifact 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 artifact registry#

When to follow these instructions#

Follow the instructions below only if you want to use a private artifact 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 artifact 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 artifact registry:
```
$ ./tools/aspen-mesh-artifact-registry-login.sh
```

Pull the images from the Aspen Mesh artifact 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 artifact repository#

Make sure your computer has access to the private artifact registry.
If the private artifact registry requires authentication, make sure you’re logged in to the private artifact 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 artifact 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 artifact-registry pull secret with the private artifact-registry pull secret (if the private artifact registry requires authentication)#

Important

Perform this task only if the private artifact registry requires authentication (that is, you must provide credentials to access the registry). Typically, a private artifact 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 artifact 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 artifact-registry pull secret.

Most artifact 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 (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 artifact 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 artifact repository#

Open your Aspen Mesh override values file (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.