Upgrade TKG Service from a Private Registry

Refer to these instructions to asynchronously upgrade the TKG Service version using an image hosted in a private container registry. You can use this approach to upgrade the TKG Service if you are operating in an internet restricted ("air-gapped") environment and you cannot or do not want to wait for the next vCenter Server release.

Requirements

These instructions assume you are using the Harbor Supervisor Service as the private registry. If you are using a different registry, adjust accordingly.

These instructions assume you have a client machine with Docker installed. See Using Private Registries with TKG Service Clusters for more information.

Install Carvel

The system uses the Carvel packaging system. For more information about the Carvel imgpkg utility, see https://carvel.dev/imgpkg/docs/v0.42.x/install/.

Install the Carvel imgpkg utility.

wget -O- https://carvel.dev/install.sh > install.sh
sudo bash install.sh

Verify Carvel installation.
```
imgpkg version
```

Generate the TKG Service Binary Package

Generate the TKG Service binary package by downloading the TKG Service definition YAML from the public site and creating the binary tar file.

Download the TKG Service definition YAML from the public site.
https://www.vmware.com/go/supervisor-service
For example, if you want to upgrade from TKG Service 3.0 to TKG Service 3.1, download the TKG Service 3.1 YAML.

Open the TKG Service YAML and get the image path for the package.

For example, for TKG Service 3.1 it is the following.

projects.packages.broadcom.com/vsphere/iaas/tkg-service/3.1.0/tkg-service:3.1.0

Which can be located in the YAML as follows:

...
template:
    spec:
      fetch:
      - imgpkgBundle:
          image: projects.packages.broadcom.com/vsphere/iaas/tkg-service/3.1.0/tkg-service:3.1.0

As a convenience, consider creating an environment variable for the image path named TKGS_REPO_PATH or similar.
```
export TKGS_REPO_PATH="projects.packages.broadcom.com/vsphere/iaas/tkg-service/3.1.0/tkg-service:3.1.0"
```
Verify the environment variable:
```
printenv TKGS_REPO_PATH
```
Note: The environment variable is not a requirement as long as the imgpkg copy command (used next) includes the properly replaced path.
Generate a tar binary of the imgpkg bundle.
```
imgpkg copy -b ${TKGS_REPO_PATH} --to-tar tkg-service-v3.1.0.tar --cosign-signatures
```
Or, if you did not create the environment variable, use the following command.
```
imgpkg copy -b projects.packages.broadcom.com/vsphere/iaas/tkg-service/3.1.0/tkg-service:3.1.0 --to-tar tkg-service-v3.1.0.tar --cosign-signatures
```
Important: To relocate the images, you must use the copy command and not the push and pull commands because they do not pull down all referenced images.

Verify success.

copy | exporting 31 images...
copy | will export projects.packages.broadcom.com/vsphere/iaas/tkg-service/3.1.0/tkg-service@sha256:02ffc87c3ebd2f8eed545f405e05443feb9b6675d                           7835a4d30bb8a939e54dcb9
...
copy | exported 31 images
copy | writing layers...
copy | done: file 'manifest.json' (71.384µs)
copy | done: file 'sha256-0f8b424aa0b96c1c388a5fd4d90735604459256336853082afb61733438872b5.tar.gz' (32.162µs)
...

Succeeded

Verify the local copy of the binary package tkg-service-v3.1.0.tar.

Upload the TKG Service Binary to the Private Registry

The next step is to upload the TKG Service binary to the private registry.

Log in to Harbor and create a project for the TKG Service named tkgs or similar.
Download the Harbor registry certificate file named ca.crt to your Ubuntu host.
Log in to the Habor registry using Docker.
```
docker login harbor.example.com
```
Note: imgpkg honors the system's trust settings and Docker's configuration for authentication. If your registry requires authentication, first log in with the Docker CLI command docker login ${registry_url}.
Create an environment variable for the registry URL.
```
export REGISTRY_URL="harbor.example.com/tkgs"
```
Verify the environment variable:
```
printenv REGISTRY_URL
```
Upload the imgpkg bundle to your private container image registry.
```
imgpkg copy --tar tkg-service-v3.1.0.tar --to-repo ${REGISTRY_URL}/tkg-service --cosign-signatures --registry-ca-cert-path ca.crt
```
Where
- --tar tkg-service-v3.1.0.tar is the name of the binary you created
- --to-repo harbor.example.com/tkgs is the registry URL
- --registry-ca-cert-path ca.crt is the registry certificate

Verify success.

imgpkg copy --tar tkg-service-v3.1.0.tar --to-repo harbor.example.com/tkgs/tkg-service --cosign-signatures --registry-ca-cert-path ca.crt
copy | importing 31 images...

337.24 MiB / 53.97 MiB [--------------------------------------------------------------------------------------] 624.91% 11.62 MiB p/s
copy |
copy | done uploading images
337.24 MiB / 53.97 MiB [--------------------------------------------------------------------------------------] 624.91% 11.62 MiB p/s
copy | Tagging images

Succeeded

Verify that the TKG Service container image and tag are pushed to the registry.
An obvious method is to log into the private registry and verify that the image is present. Another method to verify the image copy succeeded is to run the following command where REGISTRY_URL is equivalent to the entry under imgpkgBundle.image in the manifest.
```
imgpkg describe -b ${REGISTRY_URL}/tkg-service:3.1.0
```
Or, depending on how you configured your Docker client, you may need to include the certificate.
```
imgpkg describe -b $REGISTRY_URL/tkg-service:3.1.0 --registry-ca-cert-path ca.crt
```

Upgrade the TKG Service from a Private Registry

The last step is to upgrade the TKG Service from the package that is stored in your private registry.

Open with a text editor the local TKG Service YAML file.
Locate the imgpkg bundle location.
Update the path to use the path of the private registry location of the image.
```
template:
  spec:
    fetch:
    - imgpkgBundle:
        image: ${REGISTRY_URL}/tkg-service:3.1.0
```
Note: The tag, 3.1.0 in this example, will vary based on the version of the service definition you downloaded. See Generate the TKG Service Binary Package.
Register the new service definition with Supervisor.
See Register a New Version of the TKG Service.
Upgrade the TKG Service.
See Upgrade the TKG Service Version.