Installing the Gateway subsystem into a Kubernetes environment
Use the Install Assist utility program to install the Gateway subsystem into your Kubernetes runtime environment.
Before you begin
Before installing the Gateway subsystem, complete the steps described in First steps for installing API Connect: Upload files to registry. For instructions on using the APICUP installer, see Tips and tricks for using APICUP.
Procedure
- Add a gateway service to your Kubernetes cluster by configuring a
gateway subsystem.
- The use of namespaces is required. Namespaces must be configured in Kubernetes before starting the installation process. We do not recommend that you use the default namespace.
- DNS domain names must be configured for the endpoints. Domain names that are used for endpoints cannot contain the underscore "_" character. See Pre-installation requirements.
- Resource allocation sizes are recommended minimums and will depend upon your environment.
Note: The steps in this procedure are not needed if you are using a DataPower appliance as your gateway. - The commands for installing the Gateway subsystem are described in the following table.
Sample code is also provided. Note: Host names and DNS entries may not be changed on a cluster after the initial installation.
Command Values/Definition apicup initInitializes the apicup installation utility and creates the apiconnect-up.ymlconfiguration file.apicup subsys create gwy gateway --k8sDescribes a gateway subsystem in the Kubernetes cluster. The identifier gwyis the name you have assigned to your gateway service. You can assign it any name, as long as the identifier consists of lower case alphanumeric characters or '-', with no spaces, starts with an alphabetic character, and ends with an alphanumeric character. The commandgatewayindicates that you are creating a gateway subsystem.apicup subsys set gwy extra-values-file<path/file name>- Path to the extra values file. One extra values file is permitted. The extra values file requires a.yamlformat. It contains the ingress annotations and other settings for the subsystem. For an example of an extra values file for each subsystem, see Creating an extra values file in a Kubernetes environment.apicup subsys set gwy api-gatewaygw.<hostname>.<domainname>- The endpoint the gateway uses for API traffic. All endpoints have to be resolvable by DNS. Domain names that are used for endpoints cannot contain the underscore "_" character. See Pre-installation requirements. Enter this endpoint as the API Invocation Endpoint when configuring a Gateway Service in Cloud Manager. Refer to the deployment overview diagram for information about endpoints and certificates: Deployment overview for endpoints and certificates.apicup subsys set gwy apic-gw-servicegwd.<hostname>.<domain name>- The endpoint the gateway uses for network communication. All endpoints have to be resolvable by DNS. Domain names that are used for endpoints cannot contain the underscore "_" character. See Pre-installation requirements. Enter this endpoint as the Management Endpoint when configuring a Gateway Service in Cloud Manager.apicup subsys set gwy namespace<namespaceName>- Defines the namespace where the gateway service resides; every subsystem can be in a separate namespace. Valid namespaces are configured in Kubernetes prior to starting the API Connect installationapicup subsys set gwy registry<registry-url>- The location where you are running the image registry (for example, Artifactory). If the registry-url setting is used, it takes precedence over<image-repository>and<image-tag>values that may have been set.apicup subsys set gwy registry-secretFor example, <registrySecret>- Kubernetes secret with Docker credentials to authenticate with the image registry. The value forregistry-secretmust match the name of the secret created using thekubectl create secretcommand. It contains the Docker credentials for accessing the registry.apicup subsys set gwy image-repositoryPoints to the repository containing the gateway service image. Must match the values set using the docker tag command for <REGISTRY_HOST>/<IMAGE_NAME>. For example, My Registry/MyImage.apicup subsys set gwy image-tagPoints to the image-tag in the local repository, use double-quotes, for example, "2018.4.1.X.999999-release-prod"Note: To install a non-production DataPower image, the image-tag value must bedatapower-api-gateway.apicup subsys set gwy monitor-image-repositoryPoints to the repository containing the gateway service monitor pod image. The monitor pod watches for gateways going up or down, and removes stale gateway peer information from the pods that remain in the cluster. Removal of stale peer information improves the resiliency of the cluster. There is only one monitor pod per gateway service, regardless of how many gateway server pods (replicas) there are in the gateway service. Must match the values set using the docker tag command for <REGISTRY_HOST>/<IMAGE_NAME>. For example,
"MyRegistry/k8s-datapower-monitor". This command is required. If it is omitted, neither the DataPower monitor pod or the gateway pod will start.apicup subsys set gwy monitor-image-tagPoints to the monitor-image-tag in the local repository, use double-quotes, for example,
"2018.4.1.7". This command is required. If it is omitted, neither the DataPower monitor pod or the gateway pod will start.apicup subsys set gwy image-pull-policyDetermines how to obtain an image from the repository when a gateway pod is restarted. Ensures that the correct image is used by the gateway pod. Always- Always pull a new image when a pod is restarted. Pulls the image that is referred to by theimage-tag.IfNotPresent- If an image cannot be accessed locally, then pull a new image.Never- Never pull a new image. Image must be reloaded manually.
apicup subsys set gwy replica-count3 is a recommended minimum; actual value will depend upon your environment. apicup subsys set gwy max-cpuThe default is 4. The recommended minimum is 4. The actual value will depend upon your environment. apicup subsys set gwy max-memory-gbThe default is 6GB. The recommended minimum is 6GB. The actual value will depend upon your environment. apicup subsys set gwy storage-class<storageClass>- Refers to a valid StorageClass object in your Kubernetes cluster that supports dynamic PersistentVolume provisioning. Static or manual PersistentVolume provisioning can be used, but it requires additional steps not covered in this documentation. 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. Note that NFS is not supported.apicup subsys set gwy v5-compatibility-modeDetermines which type of gateway to install, either a DataPower® Gateway (v5 compatible) or a DataPower API Gateway. The DataPower Gateway (v5 compatible) is a v5- compatible gateway. The compatibility mode must match the type of image pointed to by the image-tagvalue. If the image contains a DataPower Gateway (v5 compatible) release, set the compatibility mode totrue. If the image contains a DataPower API Gateway release, set the compatibility mode tofalse.false- Disables thev5-compatibility-modewhen installing a DataPower API Gateway gatewaytrue- Enables thev5-compatibility-modewhen installing a DataPower Gateway (v5 compatible) gateway
apicup subsys set gwy enable-tmsDetermines whether to enable the OAuth Token Management System (tms). The Token Management System is required for a DataPower API Gateway. When the v5-compatibility-mode is set to false, theenable-tmsparameter must be set totrue. When the v5-compatibility-mode is set totrue, theenable-tmsparameter must be set tofalse.true-enable-tmswill be enabled, required when installing a DataPower API Gatewayfalse-enable-tmswill be disabled, required when installing a DataPower Gateway (v5 compatible)
apicup subsys set gwy tms-peering-storage-size-gbSize of the storage volume for the Token Management System storage. The default is 10GB. The recommended minimum is 10GB. The actual value will depend upon your environment. apicup subsys set gwy enable-high-performance-peeringDetermines whether to enabled high performance peering mode for a DataPower API Gateway. Enabling high performance peering is highly recommended for new deployments. "true"- Enable high performance peering for DataPower API Gateways."false"- Disable high performance peering for DataPower API Gateways.
The values are strings, not booleans, so must be enclosed in double quotes.
The requirement for use of this parameter is determined by the value of your
v5-compatibility-modeparameter:- When
v5-compatibility-modeisfalse, theenable-high-performance-peeringparameter is required and must be set. - When
v5-compatibility-modeistrue, theenable-high-performance-peeringparameter has no effect, and is not required.
For information on enabling high performance peering on existing deployments of version 2018.4.1.7 or later, see Enabling high performance peering for DataPower API Gateway on Kubernetes.
apicup subsys set gwy modeDetermines whether the installation is for development, testing, and demo purposes or for a production environment. If not explicitly set, the mode will default to dev(development and testing) for versions 2018.4.1.4 and later. For versions 2018.4.1.3 and earlier, the default for mode isstandard.dev- (Default) Use dev mode for development, testing, and demo purposes. It allows one instance of each subsystem to be created.standard- Use standard mode for production environments. It allows multiple instances of each subsystem to be created.
apicup subsys set gwy ingress-typeMust be explicitly set to routefor an OpenShift environment. For a standard K8s environment,ingress-typedefaults toingressand there is no need to explicitly enter this parameter.apicup subsys set gwy license-version<license>- Specify the type of gateway license, one ofDevelopers,Production, orNonproduction. If not specified, the default value isDevelopers.The Gateway server image that you are installing must match the license version. Note that this requirement does not apply to the other API Connect subsystems (Management, Analytics, and Developer Portal), because they do not have separate images for each license version.
apicup certs set gwy CERT_NAME[CERT_FILE KEY_FILE CA_FILE] [flags]- Set the required certificates for the subsystem. Custom certificates may be set, otherwise, default certificates are automatically configured. For information on what certificates are available and how to set them see: Working with certificates.apicup subsys installgwy- Starts the installation of the gateway serviceapicup subsys create gwy gateway --k8s apicup subsys set gwy extra-values-file=<path/file name> apicup subsys set gwy api-gateway=gw.<hostname>.<domainname> apicup subsys set gwy apic-gw-service=gwd.<hostname>.<domainname> apicup subsys set gwy namespace=<namespaceName> apicup subsys set gwy registry=<registry-uri> apicup subsys set gwy registry-secret=<registrySecret> apicup subsys set gwy image-repository=<ibmcom/datapower> apicup subsys set gwy image-tag="release_name" apicup subsys set gwy monitor-image-repository="ibmcom/k8s-datapower-monitor" apicup subsys set gwy monitor-image-tag="2018.4.1.7" apicup subsys set gwy image-pull-policy=Always apicup subsys set gwy replica-count=3 apicup subsys set gwy max-cpu=4 apicup subsys set gwy max-memory-gb=6 apicup subsys set gwy storage-class=<storageClass> apicup subsys set gwy v5-compatibility-mode=false apicup subsys set gwy enable-high-performance-peering=true apicup subsys set gwy enable-tms=true apicup subsys set gwy tms-peering-storage-size-gb=10 apicup subsys set gwy mode=dev apicup subsys set gwy ingress-type=route <for OpenShift environments only> apicup subsys set gwy license-version=<license> //Set the certificates apicup certs set gwy CERT_NAME=[CERT_FILE KEY_FILE CA_FILE] [flags] // OPTIONAL: Write the plan to an output directory to inspect myProject/install-plan prior to installation apicup subsys install gwy --out=gwy-install-plan // Start the installation from the output directory. Enter the full path to the output directory. apicup subsys install gwy --plan-dir=./myProject/gwy-install-plan //If output file is not used, enter the following command to start the installation apicup subsys install gwyInstalling a DataPower API Gateway or a DataPower Gateway (v5 compatible)
The values for the
v5-compatibility-modeandenable-tmsparameters determine whether you are installing a DataPower API Gateway or a DataPower Gateway (v5 compatible). The following table shows the required settings for installing both types of gateways:v5-compatibility-mode enable-tms DataPower API Gateway false true DataPower Gateway (v5 compatible) true false - An alternate deployment scenario is to use a physical DataPower appliance for the gateway. If you are using an appliance for the gateway, do not run any of the APICUP commands described on this page, since you do not need to configure a gateway subsystem in your Kubernetes cluster when using an appliance. For an appliance-based gateway, you must configure two endpoints in DataPower to be used as the Gateway Service Management Endpoint and the API invocation Endpoint. Enter these endpoints in the Configure Gateway Service screen in Cloud Manager. See Configuring a DataPower Gateway on an appliance for instructions for configuring a DataPower appliance.
- After running the
apicup subsys installcommand, run theapicup subsys get <gateway_subsys_name> --validateto validate the installation. You must correct any errors indicate by--validateprior to continuing. Following is an example for the --validate output:Kubernetes settings =================== Name Value ---- ----- extra-values-file ✔ ingress-type ingress ✔ mode standard ✔ namespace prod ✔ registry apic-dev-docker-local.artifactory.swg-devops.com/apicup-imgs/2018.4.1-550 ✔ registry-secret apiconnect-image-pull-secret ✔ storage-class rook-block ✔ Subsystem settings ================== Name Value ---- ----- enable-tms true ✔ image-pull-policy Always ✔ image-repository ibmcom/datapower ✔ image-tag 2018.4.1.x-999999-release-prod ✔ monitor-image-repository ibmcom/k8-datapower-monitor ✔ monitor-image-tag 2018.4.1.7 ✔ enable-high-performance-peering "true" ✔ max-cpu 4 ✔ max-memory-gb 6 ✔ replica-count 3 ✔ tms-peering-storage-size-gb 10 ✔ v5-compatibility-mode false ✔ Endpoints ========= Name Value ---- ----- api-gateway gw.1.23.123.45.sample.io ✔ apic-gw-service gwd.1.23.123.45.sample.io ✔