First steps for installing API Connect: Upload files to registry

Before installing API Connect into a Kubernetes environment, you must first download the tar files and then upload them to your registry.

Download the appropriate files and then upload them to your image registry.

1. To obtain the most recent release, download the latest Fix Pack from IBM® Fix Central. For new installations, select ALL to list all versions, and then choose the latest version. For existing installations, choose your current installed version number to obtain the upgrade files. See IBM Fix Central.
   1. You will need a tar file for each subsystem and the Install Assist file for your operating system. Install Assist is an easy-to-use tool that automatically manages certificate creation, deployment configuration, and other technical aspects of configuring an IBM API Connect installation. The Install Assist download file contains the APICUP installation program, which automates the installation process. Following are the available files for a Kubernetes deployment:

      Description	File name
      IBM API Connect Management V2018.4.x.x Containers	management-images-kubernetes_lts_v2018.4.x.x.tgz
      IBM API Connect Developer Portal V2018.4.x.x Containers	portal-images-kubernetes_lts_v2018.4.x.x.tgz
      IBM API Connect Analytics V2018.4.x.x Containers	analytics-images-kubernetes_lts_v2018.4.x.x.tgz
      IBM API Connect Install Assist V2018.4.x.x for Linux	apicup-linux_lts_v2018.4.x.x
      IBM API Connect Install Assist V2018.4.x.x for Mac	apicup-mac_lts_v2018.4.x.x
      IBM API Connect Install Assist V2018.4.x.x for Windows	apicup-windows_lts_v2018.4.x.x
      Production DataPower Gateway	idg_dk20184xx.lts.prod.tar.gz
      Nonproduction DataPower Gateway	idg_dk20184xx.lts.nonprod.tar.gz
      Kubernetes DataPower Monitor	dpm2018417.lts.tar.gz

      The production version of the Gateway is for use in a production environment. The nonproduction version is for use in a test or development environment.
   2. The toolkit files (with or without API Designer) can be downloaded from Fix Central directly, or from the Cloud Manager and API Manager UIs after installation is completed. See Installing the toolkit.
2. Upload API Connect files to the registry. Ensure that the registry has sufficient disk space for the files.

   For the Management, Portal, and Analytics subsystems, upload the tar files directly to the image registry using the registry-upload command. The registry-upload command creates the tags required to push the files to the registry, as follows:

   apicup registry-upload <subsystem_type> <image_tgz> <registry_host>

   where:

   • subsystem_type is the name of subsystem for the file you are uploading, one of management, portal, or analytics.
   • image_tgz is the name of the tar file you are uploading
   • registry_host is the hostname of the target registry where you are uploading tar files. For IBM Container Service Registry, a namespace is required, for example: us.icr.io/<namespace> or <region>.icr.io/<namespace>. See https://cloud.ibm.com/docs/services/Registry?topic=registry-registry_overview#registry_regions_local
3. Upload the DataPower Gateway images and any necessary supporting files.
   Note: For API Connect Version 2018.4.1.7 or earlier, production deployments that use v5-compatible Gateway Servers also require an Application Optimization module. For these deployments, do not use Step 3.a. Instead, use the alternative instructions in the IBM technical note: https://www.ibm.com/support/pages/node/1283110.

   Note that for Version 2018.4.1.8 or later, all deployments use Step 3.a on this page.

   1. Upload the DataPower Gateway image (either Production or Nonproduction) that you downloaded in Step 1.
      1. Load the Gateway image to your local docker registry:

         docker load -i idg_dk2018417.lts.prod.tar.gz

         For these examples, the version number is 2018.4.1.7 and the production (-prod) version is downloaded. The image is automatically tagged in the docker registry to ibmcom/datapower:2018.4.1.7.312001-prod.
      2. Re-tag the image for the new registry with the registry host, image name, and tag in the following format:

         docker tag <existing REGISTRY_HOST>/<IMAGE_NAME>:<TAG> <new REGISTRY_HOST>/<IMAGE_NAME>:<TAG>
         

         Table 1. Docker tag parameters

         Parameter	Description
         <REGISTRY_HOST>/ <IMAGE_NAME>	Enter your registry host name and an image name, for example, My Registry/MyImage. The <REGISTRY_HOST>/<IMAGE_NAME> matches the value entered for installation in the apicup subsys set gwy image-repository command.
         <TAG>	Enter a tag for the image, for example, 2018.4.1.7-312001-release-prod. The <TAG> value must match the value entered for the gateway image tag during installation using the apicup subsys set gwy image-tag command. You can look up required tag using the ./apicup version --images command to list all images required by APICUP. The tag must match the tag for the datapower-api-gateway image, for example: apiconnect/datapower-api-gateway:2018.4.1.7-312001-release-prod.

         For example:

         
         docker tag ibmcom/datapower:2018.4.1.7.312001-prod MyRegistry/datapower-api-gateway:2018.4.1.7-312001-release-prod

      3. Push the Gateway image to the new registry: docker push <REGISTRY_HOST>/<IMAGE_NAME>:<TAG>. For example:

         docker push MyRegistry/datapower-api-gateway:2018.4.1.7-312001-release-prod

      4. The image is now added to your registry. You can now upload the DataPower Monitor image. Continue with Step 3.b.
   2. For the Gateway Kubernetes DataPower Monitor, load the images into your local Docker registry, re-tag them, and push them to the image repository, as follows:
      1. Load the Kubernetes DataPower Monitor image to your local docker registry:

         docker load -i dpm2018417.lts.tar.gz

         The image is automatically tagged in the docker registry:

         ibmcom/k8s-datapower-monitor:2018.4.1-9-00bcbcf

      2. Re-tag the image for the new registry:

         docker tag <existing REGISTRY_HOST>/<IMAGE_NAME>:<TAG> <new REGISTRY_HOST>/<IMAGE_NAME>:<TAG>
         

         Table 2. Docker tag parameters

         Parameter	Description
         <REGISTRY_HOST>/ <IMAGE_NAME>	Enter your registry host name and an image name, for example, My Registry/k8s-datapower-monitor. The <REGISTRY_HOST>/<IMAGE_NAME> matches the value entered for installation in the apicup subsys set gwy monitor-image-repository command.
         <TAG>	Enter a tag for the image, for example, 2018.4.1-9-00bcbcf. The <TAG> value must match the value entered for the gateway image tag during installation using the apicup subsys set gwy monitor-image-tag command. You can look up required tag using the ./apicup version --images command to list all images required by APICUP. The tag must match the tag for the Kubernetes DataPower Monitor. For example: 2018.4.1-9-00bcbcf.

         For example:

         docker tag ibmcom/k8s-datapower-monitor:2018.4.1-9-00bcbcf MyRegistry/k8s-datapower-monitor:2018.4.1-9-00bcbcf

      3. Push the monitor pod image to the new registry: docker push <REGISTRY_HOST>/<IMAGE_NAME>:<TAG>. For example:

         docker push MyRegistry/k8s-datapower-monitor:2018.4.1-9-00bcbcf

   3. For DataPower Gateway, BusyBox 1.29 is required.
      Note: An internet connection is required to obtain the BusyBox image from Docker Hub. If you want to download the image and copy it to the system containing the DataPower image, follow these steps:

      1. Download the Docker image for BusyBox from a system with an internet connection:

         docker pull busybox:1.29-glibc

      2. Save the image to a tar file:

         docker save busybox:1.29-glibc > ./busybox-1.29-glibc.tar

      3. Copy the image to the same location as the DataPower image and load it:

         docker load < ./busybox-1.29-glibc.tar

      4. Tag the image and push it to your local registry:

         docker tag busybox:1.29-glibc <MyRegistry>/busybox:1.29-glibc
         docker push MyRegistry/busybox:1.29-glibc 

      1. Login to Docker Hub https://hub.docker.com/_/busybox?tab=tags to obtain BusyBox 1.29.
      2. Tag the image and push it to your local registry:

         docker pull busybox:1.29-glibc
         docker tag busybox:1.29-glibc <MyRegistry>/busybox:1.29-glibc
         docker push MyRegistry/busybox:1.29-glibc 

      The images for all subsystems and BusyBox are now stored in the appropriate registries. The registry locations will be set by APICUP commands during the installation process.

4. Create one project directory, for example, myProject and change directories to the myProject directory. Run the apicup init command to initialize the project directory. An apiconnect-up.yml configuration file will be created. The apiconnect-up.yml file contains all values entered during the installation process as you move forward.
   For example:

   mkdir ./myProject
   cd ./myProject
   apicup init

   Important:

   Use a single APICUP project for all subsystems, even those in a different cluster. Multiple projects will result in multiple certificate chains which will not match.

   The original project directory created with APICUP during the initial product installation (for example, myProject) is required to both restore the database and to upgrade your deployment. You cannot restore the database or perform an upgrade without the initial project directory because it contains pertinent information about the cluster. Note that the endpoints and certificates cannot change; the same endpoints and certificates will be used in the restored or upgraded system. A good practice is to back up the original project directory to a location from where it can always be retrieved.