Obtaining files for upgrade from 2018

Obtain the product files, load them into a local Docker registry, and then upload them as required to a remote Docker registry. Decompress the release files that are distributed as a zip file.

1. Obtain the API Connect files from IBM Fix Central:

   The following files are used for deployment on native Kubernetes:

   IBM® API Connect <version> for Containers

   Docker images for all API Connect subsystems

   IBM® API Connect <version> Operator Release Files for Containers

   Kubernetes operators and API Connect Custom Resource (CR) templates

   IBM® API Connect <version> Operator Upgrade Release Files for Containers

   Kubernetes upgrade operators and API Connect upgrade CRs.

   IBM® API Connect <version> Toolkit for <operating_system_type>

   Toolkit command line utility. Packaged standalone, or with API Designer or Loopback:

   • IBM® API Connect <version> Toolkit for <operating_system_type>
   • IBM® API Connect <version> Toolkit with Loopback for <operating_system_type>
   • IBM® API Connect <version> Toolkit Designer with Loopback for <operating_system_type>

   Not required during initial installation. After installation, you can download directly from the Cloud Manager UI and API Manager UI. See Installing the toolkit.

   IBM® API Connect <version> Local Test Environment

   Optional test environment. See Testing an API with the Local Test Environment

   IBM® API Connect <version> Security Signature Bundle File

   Checksum files that you can use to verify the integrity of your downloads.

2. Load the image-tool image in your Docker local registry:

   docker load < apiconnect-image-tool-<version>.tar.gz 

   Ensure that the registry has sufficient disk space for the files.

3. If your Docker registry requires repositories to be created before images can be pushed, create the repositories for each of the images listed by the image tool. (If your Docker registry does not require creation of repositories, skip this step and go to Step 4.)
   1. Run the following command to get a list of the images from image-tool:

      docker run --rm apiconnect-image-tool-<version> version  --images

      For docker run: For example, version is 10.0.1.5. Note that the value does not contain an -eus suffix.

   2. From the output of each entry of the form <image-name>:<image-tag>, use your Docker registry repository creation command to create a repository for <image-name>.
      For example in the case of AWS ECR the command would be for each <image-name>:

      aws ecr create-repository --repository-name <image-name>

4. Upload the image:
   • If you do not need to authenticate with the docker registry, use:

     docker run --rm apiconnect-image-tool-<version> upload <registry-url>

   • Otherwise, if your docker registry accepts authentication with username and password arguments, use:

     docker run --rm apiconnect-image-tool-<version> upload <registry-url> --username <username> --password <password>

   • Otherwise, such as with IBM Container Registry, if you need the image-tool to use your local Docker credentials, first authenticate with your Docker registry, then upload images with the command:

     docker run --rm -v ~/.docker:/root/.docker --user 0 apiconnect-image-tool-<version> upload <registry-url>

     Note: The previous command does not work on macOS if Docker is configured to use the osxkeychain credential store. In this case, complete the following steps:

     1. Disable Docker > Preferences... > Securely store Docker logins in the macOS keychain.
     2. Inspect ~/.docker/config.json to make sure that it does not contain "credSstore": "osxkeychain", as some versions of Docker-for-mac may handle the setting correctly per https://github.com/docker/for-mac/issues/4192.
     3. Authenticate with the Docker registry you intend to upload to.
     4. Run the command:

        docker run --rm -v ~/.docker:/root/.docker --user 0 apiconnect-image-tool-<version> upload <registry-url>

     5. Once the upload of images is successful you may enable Docker > Preferences... > Securely store Docker logins in the macOS keychain.

   Docker authentication notes:

   • Both HTTPS and HTTP are supported. Best practice for Docker registry security is to use HTTPS by utilizing standard Docker load tools, to ensure your images and platform are protected. However, when necessary you can use HTTP by specifying the --tls-verify=false flag.
   • When using a Docker registry on localhost, you might encounter that the image-tool Docker container is on the Docker network and typically without access to localhost. You can workaround this issue by using the --network host argument to the Docker command. Note that --network host is a Docker argument, not an image-tool argument.
   • Example of using --network host and --tls-verify=false:

     $ docker run -d -p 5000:5000 --name registry registry:2
     ...
     $ docker run --rm --network host apiconnect-image-tool-<version> upload localhost:5000 --tls-verify=false
     ...

   Providing a certificate for verification, or disabling TLS verification

   See the sample output of the tool usage for options to provide a certificate for verification or to disable TLS verification:

   $ docker run --rm apiconnect-image-tool-<version> upload --help
   upload docker images
   
   Usage:
     image-tool upload REGISTRY [flags]
   
   Flags:
         --cert-dir string   Directory with destination registry certificate tls.crt file
         --username string   User name
     -h, --help              help for upload
         --password          password for <username>
         --tls-verify        Verify TLS on destination registry (default true)
   
   Global Flags:
         --accept-license   Accept the license for API Connect
         --debug            Enable debug logging   
   

   Notes:

   • --username=<username> and --password=<password> can be used to specify credentials for authentication with the destination Docker registry.
   • --tls-verify=false can be used to disable verification of the destination Docker registry certificate
   • --cert-dir <path> can be used to provide a tls.crt file to be used for validation of the destination Docker registry certificate. For example:

     docker run --rm -v <path-to-folder-with-tls.crt-file>:/cert apiconnect-image-tool-<version> upload <registry> --cert-dir /cert
        

5. Download and decompress the IBM® API Connect <version> files needed for upgrade:
   1. Decompress IBM® API Connect <version> Operator Release Files for Containers.

      Contents:

      • API Connect Operator operator custom resource definition (CRDs)
      • API Connect Operator Deployment and required resources CRDs
      • API Connect Operator Deployment and required resources CRDs, for multiple-namespace installations
      • DataPower Gateway Operator operator custom CRDs
      • API Connect custom resource templates, and Certificate Manager

      The Operator Release for Containers files will be used later in deployment instructions.

      Note: The Operator Release files may include catalog and operator source for OpenShift. These files are not used when upgrading on native Kubernetes.

   2. Decompress IBM® API Connect <version> Operator Upgrade Release Files for Containers.

      Contents:

      • API Connect Operator upgrade operator custom resource definition (CRDs).
      • API Connect Upgrade Operator Deployment and required resources CRDs, for single-namespace installations.
      • API Connect Upgrade Operator Deployment and required resources CRDs, for multiple-namespace installations.
      • API Connect upgrade custom resource templates, and Certificate Manager.
   3. Decompress the archive helper_files.zip from IBM® API Connect <version> Operator Upgrade Release Files for Containers, to access the API Connect custom resource templates and Certificate Manager for use in upgrade.

      The zip file contains custom resource templates for:

      • Upgrade CRs for each subsystem (Management, Portal, Gateway, and Analytics)
      • Certificate Manager
      • Ingress Issuer and Subsystem Certificates Resources.

      The templates will be used later in deployment instructions.

6. Next, prepare the API Connect cluster for upgrade.

   There are separate instructions for 2018 single namespace clusters and multi-namespace cluster. Continue with the instructions that apply to your deployment:

   • Deploying operators in a single-namespace API Connect cluster
   • Deploying operators in a multi-namespace API Connect cluster