Requirements for deploying IBM API Connect into a Kubernetes environment

• Refer to the IBM® Software Product Compatibility Reports site for detailed requirements for operating systems, supporting software, and other prerequisites. Ensure that your Helm installation is up-to-date and compatible with your Kubernetes version. See Detailed system requirements for a specific product.
• The Management server and Gateway firmware versions must match, for example, API Connect 2018.4.1.3 and DataPower 2018.4.1.3.
• For API Connect v2018.4.1.15 and later, Helm v3 is required. See https://helm.sh/.
• Namespaces must be configured in Kubernetes before starting the installation process. We recommend that you do not use the default namespace.
• The timezone for API Connect pods is set to UTC. Do not change the timezone for the pods.
• Block storage is required. Select a block storage format of your choosing in order for API Connect components to be supported. GlusterFS is not recommended as a storage option due to severe performance degradation. For AWS, the gp2 and io1 types of Elastic Block Storage (EBS) are supported. The Developer Portal and the Analytics component additionally support the use of local volume storage and do not require block storage.
• Manually create the required CustomResourceDefinitions if you are not going to use the APICUP commands in Install Assist to create them. For more information, see Manually creating a CustomResourceDefinition in a Kubernetes environment and Installing the Management subsystem into a Kubernetes environment.
• When deploying with a DataPower appliance, configure a Gateway Service Management Endpoint and API invocation Endpoint in DataPower. See Configuring API Connect Gateway Service.
• Configure a remote server for logging. Follow these instructions: Configuring remote logging for a Kubernetes deployment. Pods are terminated during an upgrade, and the logs will be lost if not stored remotely.
• Configure the log rotation by setting the max-size and max-files values to a setting appropriate for your deployment. In a Kubernetes deployment, insufficient values for max-size and max-files can cause logs to grow too large and eventually force pods to restart.

  For information, visit the Docker documentation and search for "JSON File logging driver".

• DNS must be configured with domain names that correspond to the endpoints configured at installation time for each subsystem.
  Note: Host names and DNS entries may not be changed on a cluster after the initial installation.
  The endpoints are also subsequently entered in the Cloud Manager UI to configure the services for your cloud. We recommend that you keep a record of the DNS entries and endpoint names, as you will need to map the DNS entries and use the same endpoints when restoring a backup of the management database. Note that endpoints are FQDNs, entered in all lowercase. See Defining your topology. The following endpoints require DNS entries:
  Important: For API Connect on native Kubernetes and OpenShift, do not use coredns 1.8.1 through 1.8.3. These releases have a defect that can prevent pods for Developer Portal from starting. See https://coredns.io/.
  • Four domain names are recommended for the endpoints for the manager subsystem (although these may be mapped to one domain name, if desired), as follows:
    • Cloud Manager URL: <cm>.<hostname>.<domainname>
    • API Manager URL: <apim>.<hostname>.<domainname>
    • Platform REST API Endpoint for admin and provider APIs: <api>.<hostname>.<domainname>
    • Platform REST API Endpoint for consumer APIs: <consumer>.<hostname>.<domainname>
    Note:

    Kubernetes ingress limits the character set for DNS names to not support the underscore character "_". This means you cannot specify underscores in domain names that are used as endpoints. For example, foo_abc.bar.com and foo.bar_abc.com are not supported for <xxx>.<hostname>.<domainname>, and will cause an error. For example:

    Invalid value: "foo_abc.bar.com": a DNS-1123 subdomain must consist of lowercase alphanumeric characters, '-' or '.', 
    and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is
     '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')

  • The Gateway service requires two domain names to correspond to the following endpoints (both of these endpoints are entered in the Cloud Manager when defining a Gateway service). See Registering a gateway service.
    • The API invocation endpoint that is defined by api-gateway, for example: <gw>.<hostname>.<domainname>. This is the API Endpoint Base defined in Cloud Manager.
    • The management endpoint that is defined by apic-gw-service, for example, <gwd>.<hostname>.<domainname>. This is the Management Endpoint defined in Cloud Manager.
  • The Analytics service requires two domain names to correspond to the following endpoints:
    • The analytics-ingestion endpoint, for example, <ai>.<hostname>.<domainname>.
    • The management endpoint that is defined by analytics-client, for example, <ac>.<hostname>.<domainname>. This is the endpoint that is entered when defining an analytics service in Cloud Manager (see Registering an analytics service)
  • The Portal service requires two domain names to correspond to the following endpoints (both of these endpoints are entered in the Cloud Manager when defining a Portal service. See Registering a portal service:
    • The portal-admin endpoint, for example, <padmin>.<hostname>.<domainname>. This is the Management Endpoint defined in Cloud Manager.
    • The portal-www endpoint, for example, <portal>.<hostname>.<domainname>. This is the Portal Website URL defined in Cloud Manager.
• IBM API Connect requires certain repositories, and APICUP automatically creates the repositories in most cases. In some instances, for example, if installing into AWS ECR, you will need to manually create the following repositories for each subsystem:

  MANAGEMENT REPOSITORIES
  apim
  client-downloads-server
  ui
  juhu
  lur
  analytics-proxy
  ldap
  busybox
  cassandra
  cassandra-operator
  cassandra-health-check
  migration
  k8s-init
  
  PORTAL REPOSITORIES
  portal-db
  portal-dbproxy
  portal-admin
  portal-web
  openresty
  portal-exec-job
  
  ANALYTICS REPOSITORIES
  analytics-cronjobs
  analytics-client
  analytics-ingestion
  analytics-mq-kafka
  analytics-mq-zookeeper
  analytics-storage
  analytics-operator
  k8s-init
  
  GATEWAY REPOSITORIES
  datapower-api-gateway
  k8s-datapower-monitor

• Decide the mode to use for the installation.

  Table 1. Deployment modes

  Mode	Description
  dev	Development mode (dev) deploys a subsystem with the scale of one. Development mode is recommended for development, testing, and demonstration purposes. apicup subsys set mgmt mode=dev Do not use dev mode for production environments. Development mode does not provide high availability.
  standard	Standard mode (standard) deploys in high availability mode for a production environment. apicup subsys set mgmt mode=standard

  Usage:

  • Mode is set for each subsystem type: Management, Analytics, Developer Portal, and Gateway.
  • If you do not specify the mode, a default mode is applied, as follows:
    • Version 2018.4.1.4 and later: dev mode
    • Version 2018.4.1.3 and earlier: standard mode
  • Use of standard mode is supported only on installations with three or more nodes. Installations with less than three nodes must use dev mode. If you install in standard mode with only a single node, some pods can remain in a pending state. To avoid having pods remain pending, either install in dev mode or add additional nodes.
• To ensure the API Connect services have time to start, we recommend increasing the proxy-read-timeout and proxy-send-timeout values in the config.map used to configure the kubernetes/ingress-nginx ingress controller. The following settings should be increased:
  • proxy-read-timeout: "240"
  • proxy-send-timeout: "240"
  240 seconds (4 minutes) is a recommended minimum; actual value will vary depending upon your environment. If there is a load balancer in front of the worker node(s), then the load balancer configuration may also need to have extended timeouts.
• Ensure that your Kubernetes deployment addresses known security vulnerabilities with SSH to prevent the use of weak SSH Message Authentication Code (MAC) and Key exchange algorithms (KexAlgorithms) with TCP over port 22. Use of weak algorithms can allow an attacker to recover the plain text message from the encrypted text. If you have not yet addressed the security vulnerabilities with weak MACs and KexAlgorithms, update your configuration manually by adding the following lines to /etc/ssh/sshd_config:

  KexAlgorithms curve25519-sha256@libssh.org,diffie-hellman-group-exchange-sha256
  MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com,umac-128-etm@openssh.com,hmac-sha2-512,hmac-sha2-256,umac-128@openssh.com

The installation instructions have been tested with the requirements described in the Software Product Compatibility Reports. See Detailed system requirements for a specific product