Installing API Connect on OpenShiftIBM®

Installing API Connect in an OpenShift environment is a Kubernetes installation with additional steps.

Before you begin

Before starting the installation into an OpenShift runtime environment, consider the following information:

During installation, OpenShift requires the ingress-type to be set to route for each subsystem, for example, apicup subsys set SUB_SYS ingress-type route.
If using an OpenShift registry, execute the oc new-project apiconnect command to create the apiconntect project prior to uploading the images using the apicup registry-upload command.
SSH access must be disabled for the Gateway. Note that it is disabled by default.
OpenShift routes do not redirect URLs for the api-manager-ui and cloud-admin-ui endpoints. To open the API Manager and Cloud Manager UIs in an OpenShift environment, the complete URLs for the API Manager and Cloud Manager UIs must be entered in the browser as follows:
- API Manager user interface: https://api_manager_ui_endpoint/manager
- Cloud Manager user interface: https://cloud_admin_ui_endpoint/admin
On OpenShift, the API Connect management subsystem sets resource requests but does not set resource limits. Limits are not specified so that pods can request the necessary resources. If you choose to modify OpenShift to set resource limits, such as for CPU or memory, you must set the same value in the API Connect extra values YAML file. Ensure that the values in the YAML file match the values you set in OpenShift.
Note: Setting of resource requests and limits on OpenShift is not supported for the API Connect Analytics subsystem.

Procedure

Create namespaces or a namespace for API Connect. You can create separate namespaces for each subsystem, or place all subsystems in a single namespace.
Following is an example for separate namespaces for each subsystem:
```
oc create ns apic-management
oc create ns apic-gateway
oc create ns apic-analytics
oc create ns apic-portal
```
Following is an example for one namespace containing all subsystems:
```
oc create ns apiconnect
```
Following is an example for Management, Portal and Analytics in a one namespace and Gateway in a separate namespace:
```
oc create ns apic-mpa
oc create ns apic-gateway
```
Create a registry secret in the namespace where the subsystems will be deployed.
```
oc apply -f <path-to-registry-secret>
```
This secret is referenced in the APICUP installer commands for each subsystem, for example:
apicup subsys set SUB_SYS registry-secret=<registrySecret>
Refer to the installation instructions for each subsystem, for example, Installing the Management subsystem into a Kubernetes environment.

Install and configure Tiller.

Configure Tiller either globally on the cluster or scoped to a single namespace.

The following example configures Tiller globally on the cluster:

oc create ns tiller
export TILLER_NAMESPACE=tiller
oc process -f https://github.com/openshift/origin/raw/master/examples/helm/tiller-template.yaml -p TILLER_NAMESPACE="${TILLER_NAMESPACE}" -p HELM_VERSION=v2.10.0 | oc create -n "${TILLER_NAMESPACE}" -f -
oc create clusterrolebinding tiller-binding --clusterrole=cluster-admin --user=system:serviceaccount:tiller:tiller

The following example installs Tiller scoped to a single namespace, where ${NAMESPACE} is the namespace for API Connect or the namespace for a specific subsystem:

export TILLER_NAMESPACE=${NAMESPACE}
oc process -f https://github.com/openshift/origin/raw/master/examples/helm/tiller-template.yaml -p TILLER_NAMESPACE="${TILLER_NAMESPACE}" -p HELM_VERSION=v2.10.0 | oc create -n "${TILLER_NAMESPACE}" -f -
oc create rolebinding ${NAMESPACE}-tiller-cluster-admin --clusterrole=cluster-admin --serviceaccount=${NAMESPACE}:tiller --namespace=${NAMESPACE}

Note: When Tiller is scoped to a single namespace, with OpenShift 4.3, the Tiller account might need additional permissions. Permissions must be updated when you see the following errors:

Running apicup subsys install mgmt --debug returns:
```
no permissions to get CRDs
```

Running oc get crd from the Tiller account returns:

Error from server (Forbidden): 
customresourcedefinitions.apiextensions.k8s.io is forbidden:
User "system:serviceaccount:apiconnect:tiller" cannot list resource "customresourcedefinitions" 
in API group "apiextensions.k8s.io" at the cluster scope

To resolve the problem, assign additional permissions to the Tiller account:

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: helm-clusterrole
rules:
  - apiGroups:
    - ""
    - rbac.authorization.k8s.io
    - roles.rbac.authorization.k8s.io
    - authorization.k8s.io
    - apiextensions.k8s.io
    resources:
    - "clusterroles"
    - "clusterrolebindings"
    - "customresourcedefinitions"
    verbs: ["create","get","escalate"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["list", "get"]

---

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: helm-clusterrolebinding
roleRef:
  kind: ClusterRole
  apiGroup: rbac.authorization.k8s.io
  name: helm-clusterrole
subjects:
  - kind: ServiceAccount
    name: tiller
    namespace: {TILLER_APIC_NAMESPACE}

Replace {TILLER_APIC_NAMESPACE} with the namespace where both Tiller and API Connect are to be deployed.

Update the deployment's Tiller YAML:
Update the YAML. Locate the following statement:
```
image: 'gcr.io/kubernetes-helm/tiller:v2.10.0'
```
And modify it to match the following example:
```
image: 'ghcr.io/helm/tiller:v2.10.0'
```

Assign Security Context Constraint (SCC) permissions to Service Accounts. The commands will vary depending upon the namespace configuration and permission level. Following are examples:
Attention: If you plan to install the Analytics subsystem so that data is stored locally (that is, ingestion-only is set to false, then you must install Analytics into a separate namespace where you can assign the privileged level of SCC access to it. See example 2 for more information.
Example 1: To assign anyuid access to all Service Accounts in a namespace, enter this command:
```
oc adm policy add-scc-to-group anyuid system:serviceaccounts:<namespace>
```
where <namespace> is the API Connect namespace, for example, apiconnect, that contains all four subsystems (Management, Gateway, Portal, Analytics). This command assigns anyuid permissions to all subsystems contained in the namespace. For a configuration with all four subsystems in one namespace, anyuid permissions are required because the Gateway requires anyuid.
Note: Use this approach when you install Analytics using the ingestion-only configuration.
Example 2: To assign anyuid access to the Management, Gateway, and Portal Service Accounts in one namespace, and assign privileged access to the Analytics Service Account in another namespace, enter the following commands:
```
#Assign anyuid access to the Management, Gateway, and Portal Service Accounts:
oc adm policy add-scc-to-group anyuid system:serviceaccounts:<namespace>
```
where <namespace> is the API Connect namespace (for example, apiconnect) that contains the Management, Gateway, and Portal subsystems. This command assigns anyuid permissions to all subsystems contained in the namespace, so be sure to set up a separate namespace for Analytics.
```
#Assign privileged access to the Analytics Service Account in a different namespace:
oc adm policy add-scc-to-group privileged system:serviceaccounts:<Analytics_namespace>
```
where <Analytics_namespace> is the namespace (for example, analytics) for the Analytics subsystem.

Note: Use this approach if you will install Analytics using with ingestion-only set to false. The privileged access level provides much greater access to resources in a namespace, and should only be used where necessary. Since only the Analytics subsystem requires this access level, you should assign the anyuid access level to the remaining subsystems (which requires them to be hosted in a different namespace).
Example 3: To assign non-root access to all Service Accounts except the Gateway, create a namespace that contains the Management, Portal and Analytics subsystems. Then create a namespace that contains only the Gateway subsystem. Enter these commands:
```
#Set nonroot permissions for all subsystems (Management, Portal, and Analytics) in the namespace
oc adm policy add-scc-to-group nonroot system:serviceaccounts:<namespace>
```
where <namespace> is the namespace that contains the Management, Portal and Analytics subsystems. This assigns nonroot permissions to all subsystems contained in the namespace.
```
#Set anyuid permission for the gateway subsystem
oc adm policy add-scc-to-group anyuid system:serviceaccounts:<namespace>
```
where <namespace> is the namespace that contains the gateway subsystem. This assigns anyuid permissions to the gateway.
For the DataPower® WebUI setup, depending on whether the default SCC which is installed as part of OpenShift has been modified, assign anyuid access to DAC_OVERRIDE, SETUID, SETGID, and SYS_CHGROOT. See the following examples.
Example 1: To assign anyuid access to DAC_OVERRIDE for the gateway subsystem, enter this command:
```
oc adm policy add-scc-to-group anyuid system:dac_override:<namespace>
```
where <namespace> is the namespace that contains the gateway subsystem.
Example 2: To assign anyuid access to SETUID for the gateway subsystem, enter this command:
```
oc adm policy add-scc-to-group anyuid system:setuid:<namespace>
```
where <namespace> is the namespace that contains the gateway subsystem.
Example 3: To assign anyuid access to SETGID for the gateway subsystem, enter this command:
```
oc adm policy add-scc-to-group anyuid system:setgid:<namespace>
```
where <namespace> is the namespace that contains the gateway subsystem.
Example 4: To assign anyuid access to SYS_CHGROOT for the gateway subsystem, enter this command:
```
oc adm policy add-scc-to-group anyuid system:sys_chgroot:<namespace>
```
where <namespace> is the namespace that contains the gateway subsystem.
Note: If you encounter problems assigning Security Context Constraints (SCC) in order to enable the WebUI for DataPower, see the recommendation to create a new SCC: https://www.ibm.com/mysupport/s/question/0D50z00006RZGPB/apic-2018-gateway-service-error-when-enabling-datapower-web-ui?language=en_US.
Install the subsystems following the instructions for installing API Connect on Kubernetes. Set the ingress-type to route for each subsystem, for example, apicup subsys set SUB_SYS ingress-type route. See Installing and upgrading on Kubernetes.