Obtaining product files

Obtain the product files, upload the images to a Docker registry, and decompress the operators and templates.

1. Obtain the API Connect files:
   1. Go to the What's New in the latest version information page.
   2. Locate the Note: You can access the latest files from <URL link>. Select the <URL link> to go directly to the Announce page on Fix Central, where you can download files for the latest version of API Connect.

   The following files are used for initial 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> 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. Optionally, you can verify the integrity of the downloaded files to ensure that they originated from IBM and are not modified. See Signature verification by using PGP.
3. Load the image-tool image in your Docker local registry. The image is contained in the IBM® API Connect <version> for Containers download file. For example:

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

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

4. 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 5.)
   1. Run the following command to get a list of the images from image-tool:

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

   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>

5. 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
        

6. Download the file IBM® API Connect <version> Operator Release Files for Containers
   1. Decompress the downloaded 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 Files 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 deploying on native Kubernetes.

   2. To access the API Connect custom resource templates and Certificate Manager, decompress the archive helper_files.zip.

      The zip file contains custom resource templates for:

      • Deployment of each subsystem.
      • Backup and restore of each subsystem
      • Custom certificates, both external and internal, for either standard deployments or 2-site HA deployments
      • Certificate support for multi-namespace deployments
      • Multi-site secret generation in a two data center deployment on Kubernetes.
      • Ingress Issuer and Subsystem Certificates Resources, for either standard deployments or 2-site HA deployments
      • Setting an administrator secret for DataPower Gateway

      The templates will be used later in deployment instructions.