Deploying operators in a single-namespace API Connect cluster

Deploy the Kubernetes operator files in a single namespace cluster.

Before you begin

Ensure you completed the prerequisite tasks for installing operators. See Deploying operators.
Be sure to review your strategy for using certificates with API Connect. See Deployment requirements.

Note: If you are deploying a multi-namespace API Connect cluster, do not use these instructions. Instead, go to Deploying operators in a multi-namespace API Connect cluster.

Procedure

Ensure KUBECONFIG is set for the target cluster:
```
export KUBECONFIG=<path_to_cluster_config_YAML_file>
```
An example path is /Users/user/.kube/clusters/<cluster_name>/kube-config-<cluster_name>.yaml
Decide on a namespace to be used for installation.
If not using the default namespace, create the namespace in the Kubernetes cluster where the API Connect deployment will take place. Use the following command, replacing <namespace> with the namespace for the deployment:
```
kubectl create ns <namespace>
```
Install a cert-manager.
Use of a certificate manager adds convenience to the generation and management of certificate, but is not required. Whenever a custom resource (CR) takes a certificate secret name as input, you can point to any secret name, as long as the secret exists before deploying the CR, and the secret contains relevant certificate data. Typically, this is tls.crt, tls.key, and ca.crt files. See Certificates in a Kubernetes environment.
Note:
Do not use this step to install a cert-manager if:
- You want to use custom certificates. See Custom certificates on Kubernetes
- You are deploying with IBM Kubernetes Service. See Using custom certificates with IBM Kubernetes Service.
- You are deploying a two data center disaster recovery deployment on Kubernetes, see Installing cert-manager and certificates in a two data center deployment.
Note that when using custom certificates or IBM Kubernetes Service, you will use a different version of cert-manager and the ingress-issuer yaml file.

After you complete one of the alternate sets of instructions in the links in this Note, continue with Step 4.
1. Obtain the certificate manager.
  API Connect v10 uses cert-manager v1.5.1 of cert-manager, which is a native Kubernetes certificate management controller.
  
  You can obtain cert-manager v1.5.1 from the API Connect v10 distribution helper_files.zip archive.
  
  Note: cert-manager is bundled as a common service in IBM CloudPack for Integration.
2. Apply the CR:
```
kubectl apply -f cert-manager-1.5.1.yaml
```
  Do not specify a custom namespace.
  
  See https://cert-manager.io/docs/release-notes/release-notes-1.5/.
3. Wait for cert-manager pods to enter Running 1/1 status before proceeding. To check the status:
```
kubectl get po -n cert-manager 
```
  There are 3 cert-manager pods in total.
Create a registry secret with credentials to be used to pull down product images.
Use the following command, replacing <namespace> with the namespace for your deployment, and replacing <registry_server> with the location of the Docker Registry where the installation product images were pushed:
```
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 <namespace>
 
```

Create a registry secret for the DataPower registry with the credentials to be used to pull down product images.

Use the following command, replacing <namespace> with the desired namespace for the deployment:

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 <namespace>

Create a DataPower admin secret.
Use the following command, replacing <namespace> with the desired namespace for the deployment:
```
kubectl create secret generic datapower-admin-credentials --from-literal=password=admin -n <namespace>
```
The admin secret will be used for $ADMIN_USER_SECRET when deploying the gateway CR.
If you are using a namespace other than default, open ibm-apiconnect.yaml in a text editor. Replace each occurrence of default with the namespace for your deployment.

Open ibm-apiconnect.yaml in a text editor. Replace the value of each image: key with the location of the apiconnect operator images (from the ibm-apiconnect container and the ibm-apiconnect-init container), either uploaded to your own registry or pulled from a public registry.


  serviceAccountName: ibm-apiconnect
   imagePullSecrets:
   - name: apic-registry-secret
   initContainers:
   - name: ibm-apiconnect-init
    image: <My_registry_or_public_registry>/ibm-apiconnect-operator-init@sha256:0d3bbac7c67372ad013407a8049c69dbd08b1559b59a7606fcd87eb0f4519ce1
...
   containers:
    - name: ibm-apiconnect
    image: <My_registry_or_public registry>/ibm-apiconnect-operator@sha256:a7473ee26c252fca4931b682cd95d73b4149e4b5b773834408f9f22d0246a76c

Required: If you are using the IBM Kubernetes Service (IKS) and setting up a two data center disaster recovery deployment, edit the ibm-apiconnect.yaml file.
After the line spec.affinity.containers.env, insert:
```
- name: DISABLE_CERT_MANAGER
          value: "true"
```
Note: This step is not required for normal Kubernetes.
If DataPower Gateway is desired in this installation, and if you are using a namespace other than default, open ibm-datapower.yaml in a text editor. Replace each occurrence of default with the namespace for your deployment.
Open ibm-datapower.yaml in a text editor.
1. Locate the image: key in the containers section of the deployment yaml immediately after imagePullSecrets:. Replace the value of the image: key with the location of the datapower operator image, either uploaded to your own registry or pulled from a public registry.
2. Update the IBM_DOCKER_HUB and IBM_ENTITLED_REGISTRY value in the env section with the registry address where the images were uploaded with the image-tool in Obtaining product files.
  For example, the default entries are:
```
            - name: IBM_ENTITLED_REGISTRY
              value: "cp.icr.io/cp/datapower"
            - name: IBM_DOCKER_HUB
              value: "cp.icr.io/cp/datapower"
```

Install the ibm-apiconnect CRDs.

kubectl apply -f ibm-apiconnect-crds.yaml

Install the ibm-apiconnect Kubernetes deployment.
```
kubectl apply -f ibm-apiconnect.yaml
```
If DataPower Gateway is desired in this installation, install the ibm-datapower Kubernetes deployment for DataPower Gateway, with the following command, replacing <namespace> with the desired namespace for the deployment (-n <namespace> may be omitted if default namespace is being used for installation):
```
kubectl apply -f ibm-datapower.yaml -n <namespace>
```
Note: There is a known issue on Kubernetes version 1.19.4 or higher that can cause the DataPower operator to fail to start. In this case, the DataPower Operator pods can fail to schedule, and will display the status message: no nodes match pod topology spread constraints (missing required label). For example:
```
0/15 nodes are available: 12 node(s) didn't match pod topology spread constraints (missing required label), 
3 node(s) had taint {node-role.kubernetes.io/master: }, that the pod didn't tolerate.
```
You can workaround the issue by editing the DataPower operator deployment and re-applying it, as follows:
1. Delete the DataPower operator deployment, if deployed already:
```
kubectl delete -f ibm-datapower.yaml -n <namespace>
```
2. Open ibm-datapower.yaml, and locate the topologySpreadConstraints: section. For example:
```
topologySpreadConstraints:
- maxSkew: 1
  topologyKey: zone
  whenUnsatisfiable: DoNotSchedule
```
3. Replace the values for topologyKey: and whenUnsatisfiable: with the corrected values shown in the example below:
```
topologySpreadConstraints:
- maxSkew: 1
  topologyKey: topology.kubernetes.io/zone
  whenUnsatisfiable: ScheduleAnyway
```
4. Save ibm-datapower.yaml and deploy the file to the cluster:
```
kubectl apply -f ibm-datapower.yaml -n <namespace>
```
Install the ingress-ca Issuer to be used by cert-manager.
Note:
If you are installing a two data center disaster recovery deployment, skip this step as you already have the ingress-ca installed as described here: Installing cert-manager and certificates in a two data center deployment.

If you are using IBM Kubernetes Service (IKS) skip this step. When using IKS, the installation of cert-manager V0.12 is required and custom certificates must be generated or provided, and used. The custom certificates must exist prior to installing the API Connect subsystems. See Using custom certificates with IBM Kubernetes Service.
1. Use the following command, replacing <namespace> with the desired namespace for the deployment:
```
kubectl apply -f ingress-issuer-v1.yaml -n <namespace>
```
  The file ingress-issuer-v1.yaml is supplied by cert-manager.
2. Validate that the command succeeded:
```
kubectl get certificates -n <namespace>
```
  Example output indicating success:
```
NAME                         READY   SECRET                       AGE
analytics-client-client      True    analytics-client-client      70s
analytics-ingestion-client   True    analytics-ingestion-client   70s
gateway-peering              True    gateway-peering              69s
gateway-service              True    gateway-service              69s
ingress-ca                   True    ingress-ca                   71s
portal-admin-client          True    portal-admin-client          71s
portal-tunnel-client         True    portal-tunnel-client         70s
```
  The list of certificates might vary based on your deployment.
Continue with Installing the API Connect subsystems.