Deploying operators in a single-namespace API Connect cluster

When upgrading from 2018 to the latest release of v10, first deploy the operators to your namespace.

Before you begin

You must have completed the prerequisite steps and obtained the latest API Connect v10 software. See Preparing the 2018 deployment for upgrade.

Procedure

  1. Apply the new version 10 Custom Resource Definitions (CRDs) and the upgrade operator CRDs into the 2018 cluster at your namespace.
    1. version 10 CRDs:
      kubectl apply -f ibm-apiconnect-crds.yaml
    2. version 2018 to version 10 upgrade CRDs:
      kubectl apply -f ibm-apiconnect-upgrade-crds.yaml
  2. Create secrets to pull down version 10 images from docker registry:
    1. Create apic-registry-secret secret to pull down product v10 API Connect images.
      kubectl create secret docker-registry apic-registry-secret 
          --docker-server=<registry_server> 
          --docker-username=<username@example.com> 
          --docker-password=<password> 
          --docker-email=<username@example.com> 
          -n <v2018_namespace>
    2. Create datapower-docker-local-cred secret to pull down DataPower images:
      kubectl create secret docker-registry datapower-docker-local-cred 
           --docker-server=<docker_server> 
           --docker-username=<username@example.com> 
           --docker-password=<password> 
           --docker-email=<username@example.com> 
           -n <v2018_namespace>  
    3. Create datapower-admin-secret
      kubectl create secret generic datapower-admin-credentials 
           --from-literal=password=admin 
           -n <v2018_namespace>

    You will use the image pull secret key name in the CR files, spec.ImagePullSecret.

  3. Install cert-manager and configure certificates:
    1. Install cert-manager 1.9.1 but do not specify a custom namespace because cert manager will be installed in its own namespace.
      kubectl apply -f <path>/cert-manager-1.9.1.yaml
    2. Wait for cert-manager pods to enter Running 1/1 status before proceeding. Use the following command to check:
      kubectl -n cert-manager get po

      There are 3 cert-manager pods in total.

  4. Install ingress-issuer-v1.yaml.
    kubectl apply -f <path>/ingress-issuer-v1.yaml -n <v2018_namespace>

    This step creates ingress resources in the namespace of v2018 subsystems.

  5. Apply the version 10 apiconnect-operator into your namespace.

    The apiconnect-operator launches and maintains the v10 micro-services.

    1. If you are using a namespace other than default, open ibm-apiconnect.yaml in a text editor. Replace each occurrence of default with the 2018 namespace for your deployment.
    2. Open ibm-apiconnect.yaml in a text editor. Replace REPLACE-DOCKER-REGISTRY with the root of the docker registry you are working with.
    3. Install the ibm-apiconnect Kubernetes deployment.
      kubectl apply -f ibm-apiconnect.yaml -n <2018_namespace>

      This command gets the version 10 apiconnect-operator up and running in the namespace of the 2018 subsystems.

  6. Start the DataPower operator in the cluster namespace.
    Note: Deployment of the DataPower operator is only needed if you have at least one API Connect 2018 Gateway subsystem (whether v5-compatible or not) to upgrade. If you are using DataPower in a different form factor such as an Appliance, you will not have an API Connect 2018 Gateway subsystem to upgrade, and will not need the DataPower operator for your upgrade.

    Create ibm-datapower.yaml in the cluster namespace:

    1. Open ibm-datapower.yaml and replace REPLACE-DOCKER-REGISTRY with the root of the docker registry you are working with.
    2. Use the following command to start the version 10 operator in the cluster (namespace):
      kubectl apply -f ibm-datapower.yaml -n <2018_namespace>
  7. Apply the version 10 ibm-apiconnect-upgrade operator into your namespace, to perform the 2018-to-10 upgrade process.
    1. Open ibm-apiconnect-upgrade.yaml in a text editor.
      1. If you are using a namespace other than default, replace each occurrence of default with the API Connect 2018 namespace for your deployment.
      2. Replace REPLACE-DOCKER-REGISTRY with the root of the docker registry you are working with.
      3. Optionally, you can supply values for the environment variables DEFAULT_IMAGE_REGISTRY and DEFAULT_IMAGE_PULL_SECRET in ibm-apiconnect-upgrade.yaml

        If you do not set these variables in ibm-apiconnect-upgrade.yaml, you can (and must) set $IMAGE_REGISTRY and $IMAGE_PULL_SECRET later in the upgrade CR for each subsystem.

        Example:

        ---
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: ibm-apiconnect-upgrade
        <...>
              containers:
              - name: ibm-apiconnect-upgrade
                image: REPLACE-DOCKER-REGISTRY/ibm-apiconnect-upgrade-operator@sha256:b1e09c3ed2f52b6724c7ef8a399ac36db63f9f64f19458736fec9a043458435e
                command:
                - ibm-apiconnect-upgrade
                args:
                - --zap-time-encoding=iso8601
                imagePullPolicy: Always
                env:
                - name: WATCH_NAMESPACE
                  valueFrom:
                    fieldRef:
                      fieldPath: metadata.namespace
                - name: POD_NAMESPACE
                  valueFrom:
                    fieldRef:
                      fieldPath: metadata.namespace
                - name: POD_NAME
                  valueFrom:
                    fieldRef:
                      fieldPath: metadata.name
                - name: OPERATOR_NAME
                  value: ibm-apiconnect-upgrade
                - name: DEFAULT_IMAGE_REGISTRY
                  value: <registry-url>
                - name: DEFAULT_IMAGE_PULL_SECRET
                  value: <image-pull-secret-name>
    2. Install the ibm-apiconnect upgrade Kubernetes deployment.
      kubectl apply -f ibm-apiconnect-upgrade.yaml -n <v2018_namespace>

      This command gets the v10 apiconnect upgrade operator up and running in the namespace.

  8. Next, upgrade the subsystems. Continue with Upgrading the Management subsystem from 2018 to v10.