Pattern 6: API-M Deployment with IS as Key Manager¶

This deployment consists of a single API-M node with a single API-M runtime with IS configured as a third party key manager.

Contents¶

Pattern 6: API-M Deployment with IS as Key Manager
Contents
Prerequisites
Minimal Configuration
Further IS Customizations
Configuration

Prerequisites¶

Before you begin, ensure you have the following prerequisites in place:

Set Up Basic Configurations¶

Info

The following tools and configurations are necessary for deploying WSO2 API-M in a Kubernetes environment.

Install the required tools:
Git
Helm
Kubernetes client
Ensure you have a running Kubernetes cluster.
Install a routing controller. Choose either:
Envoy Gateway (enabled by default) - RECOMMENDED (modern Gateway API-based routing)
NGINX Ingress Controller (disabled by default) - DEPRECATED (traditional Ingress-based routing)

Add the WSO2 Helm chart repository:

helm repo add wso2 https://helm.wso2.com && helm repo update

Build WSO2 Identity Server Docker Image¶

This deployment pattern uses WSO2 Identity Server 7.x as a third-party Key Manager.
Download the WSO2 Identity Server Docker image from DockerHub or use the WSO2 Private Docker Registry if you have an active WSO2 subscription.
Since WSO2 IS 7.x needs to be configured as a Key Manager for WSO2 API Manager, you need to create a custom Docker image with the necessary configurations and extensions.
Below is a sample Dockerfile to build a custom WSO2 IS image for use as a Key Manager:

FROM registry.wso2.com/wso2-is/is:7.2.0.0

ARG USER=wso2carbon
ARG USER_HOME=/home/${USER}
ARG WSO2_SERVER_NAME=wso2is
ARG WSO2_SERVER_VERSION=7.0.0
ARG WSO2_SERVER=${WSO2_SERVER_NAME}-${WSO2_SERVER_VERSION}
ARG WSO2_SERVER_HOME=${USER_HOME}/${WSO2_SERVER}

# Add notification event handler JAR for API Manager integration
ADD --chown=wso2carbon:wso2 https://maven.wso2.org/nexus/content/repositories/releases/org/wso2/km/ext/wso2is/wso2is.notification.event.handlers/2.1.3/wso2is.notification.event.handlers-2.1.3.jar ${WSO2_SERVER_HOME}/repository/components/dropins

After building your custom Docker image, push it to your container registry so it can be accessed by your Kubernetes cluster:
```
docker build -t CONTAINER_REGISTRY/wso2is-km:7.2.0.0 .
docker push CONTAINER_REGISTRY/wso2is-km:7.2.0.0
```

Configure WSO2 Identity Server as Key Manager¶

This section explains how to configure WSO2 Identity Server 7.x as a Key Manager for WSO2 API Manager. In this deployment pattern, both API Manager and Identity Server run as separate containerized applications in the Kubernetes cluster.

Info

Before you begin: You need to import the public certificate of the WSO2 Identity Server 7.x to the truststore of the WSO2 API Manager, and vice-versa. For information on importing the certificates, see the Importing certificates to the truststore guide.

To configure WSO2 Identity Server 7.x to work as a Key Manager with WSO2 API Manager, you need to apply the following configurations:

Configure WSO2 Identity Server using the Helm chart's values.yaml file:

    deploymentToml:
      extraConfigs: |
        [oauth]
        authorize_all_scopes = true

        [[resource.access_control]]
        context="(.*)/scim2/Me"
        secure=true
        http_method="GET"
        cross_tenant=true
        permissions=[]
        scopes=[]

        [[event_listener]]
        id = "token_revocation"
        type = "org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"
        name = "org.wso2.is.notification.ApimOauthEventInterceptor"
        order = 1
        [event_listener.properties]
        notification_endpoint = "https://<APIM_HOST>:<APIM_PORT>/internal/data/v1/notify"
        username = "${admin.username}"
        password = "${admin.password}"
        'header.X-WSO2-KEY-MANAGER' = "WSO2-IS"

Minimal Configuration¶

If you want to quickly try out WSO2 API Manager with WSO2 Identity Server 7.x as a Key Manager on Kubernetes with minimal configuration, you can use the default values provided in the default_values.yaml file.

Quick Start Configuration

This minimal configuration includes:

H2 database (embedded)
Default keystore and truststore
Basic settings for testing purposes

Note: This configuration is ideal for development environments or quick evaluation but is not recommended for production use.

Before you begin

You need to import the public certificate of the WSO2 Identity Server 7.x to the truststore of the WSO2 API Manager, and vice-versa. For information on importing the certificates, see the Importing certificates to the truststore guide.

Follow the steps in the 1.2 Mount Keystore and Truststore section to create a Kubernetes secret containing the keystore and truststore files. Here you will need two keystores: one for the API Manager and one for the Identity Server. The truststore should contain the public certificate of the Identity Server.

To add external keystores and truststores to IS, you can enable externalJKS and define the secretName
To add external keystores and truststores to API Manager, you can specify jksSecretName

Create a namespace for the deployment

kubectl create namespace apim

First download the IS values.yaml

helm show values wso2/identity-server --version next > default_values.yaml

Update the IS default_values.yaml file with the above configurations.
Install the Envoy Gateway as follows:

helm install envoy-gateway oci://docker.io/envoyproxy/gateway-helm \
  --version v1.7.0 -n envoy-gateway-system \
  --set config.envoyGateway.extensionApis.enableBackend=true \
  --set envoyGateway.gateway.experimentalFeatures.enabled=true \
  --create-namespace

Apply the sample Gateway manifest to create Gateway and GatewayClass resources.

kubectl apply -f https://raw.githubusercontent.com/wso2/helm-apim/4.7.x/docs/assets/sample-gateway.yaml -n apim

Deploy IS with minimal configuration using the following command:

helm install is wso2/identity-server --version next \
-f default_values.yaml -n apim

Before running the Helm install command for API Manager, set wso2.apim.configurations.encryption.key in the API Manager values file.
Deploy API Manager with minimal configuration using the following command:

helm install apim wso2/wso2am-all-in-one --version 4.7.0-1 -f https://raw.githubusercontent.com/wso2/helm-apim/4.7.x/docs/am-pattern-0-all-in-one/default_values.yaml -n apim

The Helm chart uses Gateway API by default. If you prefer Ingress instead, follow the steps in 1.1 Add Gateway API controller or Ingress controller to configure and enable it.

For this pattern, you will need to deploy both API Manager and Identity Server in your Kubernetes cluster. Configure the values files for both API Manager and Identity Server with the necessary settings and deploy them using Helm.

Further IS Customizations¶

For advanced deployment scenarios and further customizations of WSO2 Identity Server on Kubernetes, refer to the official WSO2 Identity Server Kubernetes deployment documentation. This guide covers topics such as:

Customizing Helm chart values for production
Enabling persistence and external databases
Integrating with external identity providers
Configuring monitoring and logging
Scaling and high availability options

Review these resources to tailor your deployment to your specific requirements and production standards.

Configuration¶

1. General Configuration of Helm Charts¶

The Helm charts for the API Manager deployment are available in the WSO2 Helm Chart Repository. You can either use the charts from the repository or clone the repository and use the charts from the local copy.

Resource Naming Convention

The helm naming convention for APIM follows a simple pattern:

<RELEASE_NAME>-<CHART_NAME>-<RESOURCE_NAME>

1.1 Add Gateway API controller or Ingress controller

You can use either Envoy Gateway (Gateway API-based) or NGINX Ingress Controller (Ingress-based) for routing traffic to API Manager. By default, charts are configured to use Envoy Gateway. If you want to use NGINX Ingress Controller instead, disable Gateway API and enable Ingress in your Helm values.

Note: It is recommended to use Gateway API with Envoy Gateway instead of NGINX Ingress Controller (Deprecated).

TLS Certificate Configuration (Required for both options)

Create a Kubernetes secret containing the TLS certificate and private key. This secret is used for TLS termination at the load balancer level.

kubectl create secret tls my-tls-secret --key <private key filename> --cert <certificate filename> -n <namespace>

If you use Gateway API, reference this secret in the TLS listeners of your Gateway manifest. If you use NGINX Ingress Controller, set tlsSecret to this secret name in Helm values.

Option 1: Envoy Gateway (Gateway API-based approach) - RECOMMENDED

It is recommended to use Gateway API with Envoy Gateway instead of NGINX Ingress Controller. Gateway API provides a more expressive, extensible, and role-oriented API for configuring traffic routing in Kubernetes.

Install Envoy Gateway.

helm install envoy-gateway oci://docker.io/envoyproxy/gateway-helm \
  --version v1.7.0 -n envoy-gateway-system \
  --set config.envoyGateway.extensionApis.enableBackend=true \
  --set envoyGateway.gateway.experimentalFeatures.enabled=true \
  --create-namespace

Create and apply Gateway and GatewayClass resources.

kubectl apply -f <your-gateway-manifest> -n <namespace>

Ensure that the hostnames and Gateway name in your created Gateway manifest match those configured in your Helm chart values. Additionally the TLS secret created above should be correctly referenced in the listeners of the Gateway resource for TLS termination.

Create a ConfigMap containing the CA certificate for backend TLS verification and reference it under backendTLSPolicy.caCertificateConfigMap in the Helm chart values. This is required if you have enabled backend TLS verification in the Gateway configuration.

Note: A default ConfigMap with the name wso2-ca-cert is created when the defaultConfigMapCreation option is enabled in the values.yaml. This default ConfigMap uses the default certificates provided in the APIM truststore. However, for production deployments, it is recommended to create and manage the ConfigMap with the CA certificate yourself, and set defaultConfigMapCreation to false

kubectl create configmap wso2-ca-cert --from-file=ca.crt=/path/to/your/certificate.pem -n <namespace>

Configure the backend traffic policy in the Gateway configuration to enable session affinity if required. This can be done by setting the backendTrafficPolicy in the Helm chart values.
Update values.yaml to enable Gateway API and configure backend TLS policy.

kubernetes:
  gatewayAPI:
    enabled: true
    gatewayName: "wso2-apim-gateway"
    defaultConfigMapCreation: false
    management:
      enabled: true
      hostname: "am.wso2.com"
    gateway:
      enabled: true
      hostname: "gw.wso2.com"
    websocket:
      enabled: true
      hostname: "websocket.wso2.com"
    websub:
      enabled: true
      hostname: "websub.wso2.com"
    backendTLSPolicy:
      enabled: true
      caCertificateConfigMap: "wso2-ca-cert"
      hostname: "<hostname used in the TLS certificate>"
    backendTrafficPolicy:
        enabled: true
        cookie:
          name: "WSO2_CP_STICKY_SESSION"
          ttl: "0s"

If you require further routing customizations, use Gateway API Extensions provided by Envoy.

Option 2: NGINX Ingress Controller (Ingress-based approach) - DEPRECATED

You can install the NGINX Ingress Controller using the official Helm chart

Some sample annotations that can be used with Ingress resources are as follows:

The ingress class should be nginx if you are using NGINX Ingress Controller.
The following annotations can be included in Helm values for Ingress resources depending on requirements. Refer to NGINX annotation documentation for details.

ingressClass: "nginx"
ingress:
  tlsSecret: ""
  ratelimit:
    enabled: false
    zoneName: ""
    burstLimit: ""
  controlPlane:
    hostname: "am.wso2.com"
    annotations:
      nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
      nginx.ingress.kubernetes.io/affinity: "cookie"
      nginx.ingress.kubernetes.io/session-cookie-name: "route"
      nginx.ingress.kubernetes.io/session-cookie-hash: "sha1"

1.2 Mount Keystore and Truststore

If you are not including the keystore and truststore into the docker image, you can mount them using a Kubernetes secret. Following steps shows how to mount the keystore and truststore using a Kubernetes secret.
Create a Kubernetes secret with the keystore and truststore files. The secret should contain the primary keystore file, secondary keystore file, internal keystore file, and the truststore file. Note that the secret should be created in the same namespace in which you will be setting up the deployment.
Make sure to use the same secret name when creating the secret and when configuring the helm chart.
If you are using a different keystore file name and alias, make sure to update the helm chart configurations accordingly. In addition to the primary, internal keystores and truststore files, you can also include the keystores for HTTPS transport as well.
Refer the following sample command to create the secret and use it in the APIM.

kubectl create secret generic apim-keystore-secret --from-file=wso2carbon.jks --from-file=client-truststore.jks --from-file=wso2internal.jks -n <namespace>

By default, this deployment uses the default keystores and truststores provided by the relevant WSO2 product. For advanced details with regards to managing custom Java keystores and truststores in a container based WSO2 product deployment please refer to the official WSO2 container guide.

1.3 Configure Internal Encryption Key (Mandatory)

This section is for the internal encryption key (wso2.apim.configurations.encryption.key), which is mandatory and used by API Manager to encrypt and decrypt internal/shared data.

Generate a unique 256-bit secret key. If you use OpenSSL, the command will be as follows:
```
openssl rand -hex 32
```

Add the generated key to the following location in your values.yaml:

wso2:
  apim:
    configurations:
      encryption:
        key: "<generated-64-char-hex-key>"

If secrets are encrypted using cipher tool and secure vault according to section 1.4, encrypt the generated internal encryption key and set the encrypted value to wso2.apim.configurations.encryption.key.

Warning

Distributed and Cloud Deployments

In a distributed or high-availability deployment, all API Manager instances must use the exact same internal encryption key (wso2.apim.configurations.encryption.key). Each instance encrypts and decrypts shared registry resources using this key, so a mismatch will cause decryption failures across the cluster. Configure the shared key on every node before the first startup.

1.4 Encrypting Secrets (Cipher Tool and Secure Vault)

If you need to use the cipher tool to encrypt the passwords in the secret, first you need to encrypt the passwords using the cipher tool. The cipher tool can be found in the bin directory of the product pack. The following command can be used to encrypt the password:
```
sh ciphertool.sh -Dconfigure -Dsymmetric -Dkey.based.encryption
```
Also, the apictl can be used to encrypt passwords as well. Reference can be found in the documentation.
Then, the encrypted values should be filled in the relevant fields of values.yaml.
Since the encryption key is required to resolve the encrypted value at runtime, you need to store the value in the cloud provider's secret manager. You can use the cloud provider's secret store to store the encryption key. The following section can be used to add the cloud provider's credentials to fetch the encryption key. Configuration for AWS can be as below:
```
aws:
  secretsManager:
    secretIdentifiers:
      secretEncryptionKey:
        # -- AWS Secrets Manager secret name
        secretName: ""
        # -- AWS Secrets Manager secret key
        secretKey: ""
```
Please note that currently AWS, Azure, and GCP Secrets Managers are only supported for this.

Warning

Use the Same Secret Encryption Key Across All Nodes

If secure vault is enabled, all API-M nodes must use the same secretEncryptionKey reference and underlying key material. A mismatch will cause secret resolution and decryption failures across nodes.

Note

These are two different keys serving distinct purposes. The internal encryption key (wso2.apim.configurations.encryption.key) defined in section 1.3 is mandatory and is used by API Manager for internal encryption of data such as registry resources and shared configuration. The secret encryption key (secretEncryptionKey under AWS/Azure/GCP) is a separate key used only when secure vault is enabled, allowing the runtime to fetch and decrypt secrets stored in a cloud provider's secret manager (which may itself include an encrypted copy of the internal encryption key).

1.5 Configure Docker Image and Databases

Add the following configurations to reflect the docker image created previously in the helm chart.
```
wso2:
  deployment:
    image:
      imagePullSecrets:
        enabled: false
        username: ""
        password: ""        
      registry: ""
      repository: ""
      digest: ""
```
If you are using a private Docker registry, you must enable imagePullSecrets.enabled and provide the username and password. - Provide the database configurations under the following section.
```
wso2:
  apim:
    configurations:
      databases:
        apim_db:
          url: ""
          username: ""
          password: ""
        shared_db:
          url: ""
          username: ""
          password: ""
```
- If you need to change the hostnames, update them under the Kubernetes Gateway API or ingress section. - Update the keystore passwords in the security section of the values.yaml file. - Review the descriptions of other configurations and modify them as needed to meet your requirements. A simple deployment can be achieved using the basic configurations provided in the values.yaml file. All configuration options for each Helm chart are documented in their respective component guides: - All-in-one - Classic Gateway - Update the admin credentials in the configuration directory.
```
  # -- Super admin username
  adminUsername: ""
  # -- Super admin password
  adminPassword: ""
```

1.6 Configure SSL in Service Exposure

SSL Configuration Best Practices

For WSO2 recommended best practices in configuring SSL when exposing internal services to outside of the Kubernetes cluster, refer to the official WSO2 container guide.

Proper SSL configuration is critical for securing API traffic and maintaining compliance with security standards.

2. Add WSO2 Identity Server as Key Manager¶

After setting up WSO2 Identity Server 7.x, you need to configure API Manager to use it as a Key Manager:

Access the API Manager Admin Portal: https://<API-M-HOSTNAME>:9443/admin
Navigate to Key Managers and click Add Key Manager.
Configure the Key Manager with the following settings:

Field	Value
Name	WSO2IS7
Display Name	WSO2 Identity Server 7
Key Manager Type	WSO2 Identity Server 7
Well-known URL	https://wso2is.km:9443/oauth2/token/.well-known/openid-configuration
Issuer	https://wso2is.km:9443/oauth2/token
Client Registration Endpoint	https://wso2is.km:9443/api/identity/oauth2/dcr/v1.1/register
Introspection Endpoint	https://wso2is.km:9443/oauth2/introspect
Token Endpoint	https://wso2is.km:9443/oauth2/token
Display Token Endpoint	https://wso2is.km:9443/oauth2/token
Revoke Endpoint	https://wso2is.km:9443/oauth2/revoke
Display Revoke Endpoint	https://wso2is.km:9443/oauth2/revoke
UserInfo Endpoint	https://wso2is.km:9443/scim2/Me
Authorize Endpoint	https://wso2is.km:9443/oauth2/authorize
Scope Management Endpoint	https://wso2is.km:9443/api/identity/oauth2/v1.0/scopes
Certificate Type	JWKS
JWKS URL	https://wso2is.km:9443/oauth2/jwks
Username (connector config)	admin
Password (connector config)	admin
WSO2 Identity Server 7 API Resource Management Endpoint	https://wso2is.km:9443/api/server/v1/api-resources
WSO2 Identity Server 7 Roles Endpoint	https://wso2is.km:9443/scim2/v2/Roles
Create roles in WSO2 Identity Server 7	Enable if needed

For all these configurations to work correctly in Kubernetes, you must ensure proper service discovery between API Manager and Identity Server pods. Configure the necessary Kubernetes services and ingresses to enable communication between these components.
Update your Helm chart values to include the Identity Server deployment and services along with API Manager.

Note

When using WSO2 IS 7.x as a Key Manager, note the following limitations:

WSO2 IS 7.x cannot be set up as a Resident Key Manager. It can only be set up as a Third-party Key Manager.
Role creation in WSO2 Identity Server 7.x is supported from WSO2 API Manager 4.4.0.5 update level onwards.

3. Add a DNS record mapping the hostnames and the external IP¶

Obtain the external IP (ADDRESS) of Gateway API resources by listing Gateway objects.

kubectl get gateway -n <NAMESPACE>

If you are using Ingress instead of Gateway API, obtain the external IP from Ingress resources.

kubectl get ing -n <NAMESPACE>

Use the value from ADDRESS or EXTERNAL-IP as the external IP.

If the defined hostnames (in the previous step) are backed by a DNS service, add a DNS record mapping the hostnames and the external IP (EXTERNAL-IP) in the relevant DNS service.

If the defined hostnames are not backed by a DNS service, for the purpose of evaluation you may add an entry mapping the hostnames and the external IP in the /etc/hosts file at the client-side.

<EXTERNAL-IP> <kubernetes.gatewayAPI.management.hostname> <kubernetes.gatewayAPI.gateway.hostname> <kubernetes.gatewayAPI.websub.hostname> <kubernetes.gatewayAPI.websocket.hostname>

4. Access Management Consoles¶

API Manager Publisher: https://<kubernetes.gatewayAPI.management.hostname>/publisher
API Manager DevPortal: https://<kubernetes.gatewayAPI.management.hostname>/devportal
API Manager Carbon Console: https://<kubernetes.gatewayAPI.management.hostname>/carbon
Classic Gateway: https://<kubernetes.gatewayAPI.gateway.hostname>
Identity Server Management Console: https://<kubernetes.gatewayAPI.is.hostname>/carbon