When using your organization's container registry with ArcGIS Enterprise on Kubernetes, you must prepare it with the Esri container images prior to new deployments, updates, or upgrades. To do so, you can use the registry tools that are included with the software to push Esri's Docker Hub images to your organization's container registry.
Understand registry tools
The ArcGIS Enterprise on Kubernetes deployment package includes a set of tools that are used to transfer images to your organization's container registry.
These tools are found under setup/tools/registry-tools in the directory where you extracted the deployment package and include the following:
- image-download.sh—Downloads all container images to your specified storage device as .tar.gz archives.
- image-upload.sh—Uploads container images from the storage device to your container registry.
- image-transfer.sh—Transfers images directly between two registries. This is faster than using image-download.sh and image-upload.sh if the client workstation can access both registries.
- create-offline-manifest.sh—Downloads the version manifest and imports it into your organization, allowing offline access to updates and upgrades.
The registry-tools folder also contains the registry-tools.properties.template file. This template properties file can be used with the image-download.sh, image-upload.sh, and image-transfer.sh tools. Refer to the Readme.md file within this folder for more information on the properties file and registry tools.
Prepare your registry when the client machine has access to Docker Hub and your organization's registry
If your client machine has access to Docker Hub and your organization's registry, you can prepare your registry for a new deployment, update, or upgrade by using the image-transfer.sh tool.
To prepare your registry, complete the following steps:
- From My Esri, obtain the software version of ArcGIS Enterprise on Kubernetes that you intend to deploy.
- Download and extract the deployment script to your client machine.
To prepare for an upgrade, download the new version of the deployment script to get the latest images.
- Open a terminal and change directories to the setup/tools/registry-tools directory.
- If your registry requires you to pre-create the image repositories, for example in Amazon Elastic Container Registry (ECR), run the following command to get a list of required image repositories:
/setup/tools/registry-tools/image-transfer.sh -l - Identify the corresponding version tag for the software release you intend to deploy by referring to the release notes or by running the following command to view the available image tags:
/setup/tools/registry-tools/image-transfer.sh -s - Use the template located in the registry-tools folder or create a separate properties file and include these parameters:
DOWNLOAD_REGISTRY="docker.io/esridocker" DOWNLOAD_USER="<username>" DOWNLOAD_PASS="<password>" CURRENT_VERSION="<current_version_tag>" DOWNLOAD_TAG="<version_tag>" UPLOAD_REGISTRY="<registry_host>/<organization>" UPLOAD_USER="<username>" UPLOAD_PASS="<password>" UPLOAD_TAG"="<version_tag>" DOWNLOAD_DIR="</path/to/download/directory>" ENCRYPTION_KEYFILE"</path/to/keyfile.txt>"The encryption keyfile is a plain text file used for AES-256 encryption and decryption of passwords. The content of this file is text that you specify and should not contain passwords. This file should remain in a fixed location and the contents should not be changed. For example:
$ echo 'My Encryption Text!' >> /path/to/keyfile.txt - Run the script using the following command:
./image-transfer.sh -f </properties/file/path>Because the script transfers all tagged images to your container registry, it takes some time to complete. If a transfer is interrupted, rerun the script to resume it.
Tip:
After the image_transfer.sh tool completes, the images still exist within the container runtime cache. To free up space after it has completed successfully, it is recommended to clean up items not needed in the Docker cache. You can do this by running docker system prune or docker image rm.
Prepare your registry when your organization's registry is disconnected from the internet
If your organization's registry is disconnected from the internet, you can prepare your registry for a new deployment, update, or upgrade by using the image-download.sh and image-upload.sh tools.
To prepare your registry, complete the following steps:
- From My Esri, obtain the software version of ArcGIS Enterprise on Kubernetes that you intend to deploy.
- Download and extract the deployment scripts to the client machine running the download tool and the client machine running the upload tool.
It is recommended that you use the same version of the deployment scripts. To prepare for an upgrade, download the new version of the deployment scripts to get the latest images.
- On the client machine running the download tool, open a terminal and change directories to the setup/tools/registry-tools directory.
- If your registry requires you to pre-create the image repositories, for example in Amazon Elastic Container Registry (ECR), run the following command to get a list of required image repositories:
/setup/tools/registry-tools/image-download.sh -l - Identify the corresponding version tag for the software release you intend to deploy by referring to the release notes or by running the following command to view the available image tags:
/setup/tools/registry-tools/image-download.sh -s - If you are not using the properties file, run the image-download.sh tool using the following command format:
./image-download.sh -r docker.io/esridocker -u <username> -p <password> -d </path/to/download/directory> -t <version_tag> - If you are using the properties file, use the template located in the registry-tools folder or create a separate properties file and include these parameters:
DOWNLOAD_REGISTRY="<docker.io/esridocker>" DOWNLOAD_USER="<username>" DOWNLOAD_PASS="<password>" DOWNLOAD_TAG="<version_tag>" DOWNLOAD_DIR="</path/to/download/directory>" ENCRYPTION_KEYFILE="</path/to/keyfile.txt>"The encryption keyfile is a plain text file used for AES-256 encryption and decryption of passwords. The content of this file is text that you specify and should not contain passwords. This file should remain in a fixed location and the contents should not be changed. For example:
$ echo 'My Encryption Text!' >> /path/to/keyfile.txt- Run the script using the following command:
./image-download.sh -f </properties/file/path>Because the script downloads all tagged images from the Esri repository, it takes some time to complete. If a download is interrupted, rerun the script to resume it.
Tip:
After the image_download.sh tool completes, the images still exist within the container runtime cache. To free up space after it has completed successfully, it is recommended to clean up items not needed in the Docker cache. You can do this by running docker system prune or docker image rm.
- Run the script using the following command:
- Follow your organization's processes for moving images to your disconnected client machine.
This machine must have access to your private registry.
- On the client machine with access to your container registry, open a terminal and change directories to the setup/tools/registry-tools directory.
- If you are not using the properties file, run the image-upload.sh tool using the following command format:
./image-upload.sh -r <registry_host>/<organization> -u <username> -p <password> -d </path/to/download/directory> -t <version_tag> - If you are using the properties file, use the template located in the registry-tools folder or create a separate properties file and include these parameters:
UPLOAD_REGISTRY="<registry_host>/<organization>" UPLOAD_USER="<username>" UPLOAD_PASS="<password>" UPLOAD_TAG="<version_tag>" DOWNLOAD_DIR="</path/to/download/directory>" ENCRYPTION_KEYFILE="</path/to/keyfile.txt>"- Run the script use the following command:
./image-upload.sh -f <properties file path>Because the script uploads all tagged images to your container registry, it takes some time to complete. If an upload is interrupted, rerun the script to resume it.
Note:
After the image-upload.sh tool completes, the images still exist within the container runtime cache. To free up space after it has completed successfully, it's recommended to clean up items not needed in the Docker cache. You can do this by running docker system prune or docker image rm.
- Run the script use the following command:
Prepare your registry for updates or upgrades
If you are preparing your registry before applying the latest update or upgrading your organization, use a properties file and set the CURRENT_VERSION property to ensure that the registry tool only downloads or transfers required images. Once you have completed steps 1-4 in one of the sections above and have populated the properties file, complete the following steps:
- Identify the current version of your organization by signing into the Admin API and combining the version and build.
For example, for version 11.4.0 and build 6144 the CURRENT_VERSION would be 11.4.0.6144.
- Set the CURRENT_VERSION property in the properties file.
- If you are preparing to apply the latest update, run the image-transfer.sh or image-download.sh tools.
- If your client workstation has direct access to both Docker Hub and the target organization registry, run the command in the following format:
./image-transfer.sh -f <properties_file> --update - If your client workstation has access to Docker Hub but not the target organization registry, run the command in the following format:
./image-download.sh -f <properties_file> --update
- If your client workstation has direct access to both Docker Hub and the target organization registry, run the command in the following format:
- If you are preparing to upgrade your organization to the next released version, run the image-transfer.sh or image-download.sh tools.
- If your client workstation has direct access to both Docker Hub and the target organization registry, run the command in the following format:
./image-transfer.sh -f <properties_file> --upgrade - If your client workstation has access to Docker Hub but not the target organization registry, run the command in the following format:
./image-download.sh -f <properties_file> --upgrade
- If your client workstation has direct access to both Docker Hub and the target organization registry, run the command in the following format: