Requirements for deploying IBM API Connect into a Kubernetes environment
Describes the system requirements for deploying into a Kubernetes runtime environment.
Before you begin
These instructions assume you have a working Kubernetes environment and understand how to manage Kubernetes.
Kubernetes is a platform for automated deployment, scaling, and operation of application containers across clusters of hosts, providing container-centric infrastructure. For more information, see https://kubernetes.io.
- Pre-installation Requirements
-
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.
- 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
andfoo.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])?)*')
- Cloud Manager URL:
- 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 API invocation endpoint that is defined by
- 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
- 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.
- The
- 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:
- 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
- Version 2018.4.1.4 and later:
- Use of
standard
mode is supported only on installations with three or more nodes. Installations with less than three nodes must usedev
mode. If you install instandard
mode with only a single node, some pods can remain in a pending state. To avoid having pods remain pending, either install indev
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"
- 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
- System and Software Requirements
-
The installation instructions have been tested with the requirements described in the Software Product Compatibility Reports. See Detailed system requirements for a specific product
Note: API Connect v2018 cannot be deployed on NFS.Important: There are known GlusterFS issues that affect the following functionality areas:- Elasticsearch, which is used in the API Connect analytics service.
- The Developer Portal service.
If you use GlusterFS, you might encounter severe performance degradation and, in some cases, loss of data.