Skip to content

Pattern 0: API-M Deployment with All-in-One Setup

This deployment consists of a single API-M node with a single API-M runtime. You can use this pattern if you expect to receive low traffic to your deployment and do not need any high availability in your environment.

single-node api-m deployment

Info

For advanced details on the deployment pattern, please refer to the official documentation.

Contents

Prerequisites

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

Step 1 - Set Up Basic Configurations

Info

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

  1. Install the required tools:
  2. Git
  3. Helm

  4. Kubernetes client

  5. Ensure you have a running Kubernetes cluster.

  6. Install a routing controller. Choose either:

  7. Envoy Gateway (disabled by default in 4.6.x) - RECOMMENDED

  8. NGINX Ingress Controller (enabled by default in 4.6.x for backward compatibility) - LEGACY

  9. Add the WSO2 Helm chart repository: 

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

Minimal Configuration

If you want to quickly try out WSO2 API 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.

Deploy API Manager with minimal configuration using the following command:

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

In 4.6.x, the default values keep NGINX Ingress enabled for backward compatibility. If you want to use Gateway API instead, follow the steps in 1.1 Add Gateway API controller or Ingress controller, install Envoy Gateway, apply the sample Gateway manifest, and enable Gateway API in your Helm values before deployment.

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. In 4.6.x, charts keep NGINX Ingress enabled by default for backward compatibility. If you want to use Gateway API instead, disable Ingress and enable Gateway API 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 https://raw.githubusercontent.com/wso2/helm-apim/4.6.x/docs/assets/sample-gateway.yaml -n <namespace>

Ensure that the hostnames and Gateway name in your Gateway manifest match the values configured in your Helm chart. Also ensure that the TLS secret created above is referenced in the Gateway listeners.

  • Create a ConfigMap containing the CA certificate for backend TLS verification and reference it under backendTLSPolicy.caCertificateConfigMap in the Helm chart values if backend TLS verification is enabled.

    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>
  • 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>"

Option 2: NGINX Ingress Controller (Ingress-based approach) - DEFAULT IN 4.6.x

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 Encrypting Secrets

  • If you need to use 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 cipher-tool.sh -Dconfigure
  • Also the apictl can be used to encrypt password as well. Reference can be found in following.
  • Then the encrypted values should be filled in the the relevant fields of values.yaml.
  • Since internal keystore password is required to resolve the encrypted value in runtime, we need to store the value in the cloud provider's secret manager. You can use the cloud provider's secret store to store the password of the internal keystore. The following section can be used to add the cloud provider's credentials to fetch the internal keystore password. Configuration for aws can be at as below. 
    internalKeystorePassword:
  # -- 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.

1.4 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 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 - Universal Gateway - Update the admin credentials in the configuration directory. 
      # -- Super admin username
  adminUsername: ""
  # -- Super admin password
  adminPassword: ""

1.5 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. All-in-One Configurations

This section covers the specific configurations relevant to the All-in-One deployment pattern.

2.1 Configure Multiple Gateways

If you need to distribute the Gateway load that comes in, you can configure multiple API Gateway environments in WSO2 API Manager to publish to a single Developer Portal. See more... 

gateway:
    # -- APIM Gateway environments
    environments:
    - name: "Default"
      type: "hybrid"
      gatewayType: "Regular"
      provider: "wso2"
      visibility:
      displayInApiConsole: true
      description: "This is a hybrid gateway that handles both production and sandbox token traffic."
      showAsTokenEndpointUrl: true
      serviceName: "apim-gw-wso2am-gateway-service"
      servicePort: 9443
      wsHostname: "websocket.wso2.com"
      httpHostname: "gw.wso2.com"
      websubHostname: "websub.wso2.com"
    - name: "Default_apk"
      type: "hybrid"
      provider: "wso2"
      gatewayType: "APK"
      displayInApiConsole: true
      description: "This is a hybrid gateway that handles both production and sandbox token traffic."
      showAsTokenEndpointUrl: true
      serviceName: "apim-gw-wso2am-gateway-service"
      servicePort: 9443
      wsHostname: "websocket.wso2.com"
      httpHostname: "default.gw.wso2.com:9095"
      websubHostname: "websub.wso2.com"

2.2 Configure User Store Properties

You can configure user store properties as described in this documentation:

    userStore:
    # -- User store type.
    type: "database_unique_id"
    # -- User store properties
    properties:
        ReadGroups: true

Configuration Note

If you do not want to configure any of these properties, you must remove the properties block from the YAML file to prevent deployment issues.

For a complete list of available user store properties and their descriptions, refer to the documentation.

2.3 Configure JWKS URL

By default, for the super tenant, the Resident Key Manager's JWKS URL is set to https://<HOSTNAME>:9443/oauth2/jwks. If you are using a virtual host like am.wso2.com that is not globally routable, this URL will be incorrect. You can configure the correct JWKS URL for the super tenant using the Helm chart as shown below:

wso2:
  apim:
    configurations:
      oauth_config:
        oauth2JWKSUrl: "https://localhost:9443/oauth2/jwks"

2.4 Deploy All-in-One

After configuring all the necessary parameters, you can deploy the All-in-One pattern using Helm:

  1. Create a namespace for your deployment
  2. Install the Helm chart with your custom configurations
# Create namespace for deployment
kubectl create namespace <namespace>

# Deploy API Manager using Helm
helm install <release-name> <helm-chart-path> \
  --version 4.6.0-1 \
  --namespace <namespace> \
  --dependency-update \
  -f values.yaml \
  --create-namespace

Deployment Parameters

  • <release-name>: Choose a name for your release (e.g., apim)
  • <namespace>: Specify the Kubernetes namespace (e.g., wso2)
  • <helm-chart-path>: Path to the Helm chart (e.g., ./all-in-one or use the repository URL)

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

If you are using Gateway API, obtain the external address by listing Gateway resources.

kubectl get gateway -n <NAMESPACE>

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

kubectl get ing -n <NAMESPACE>

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

If the defined hostnames are backed by a DNS service, add DNS records that map the hostnames to the external IP in the relevant DNS service.

If the defined hostnames are not backed by a DNS service, for evaluation purposes you may add entries to the /etc/hosts file on the client side.

For Gateway API:

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

For Ingress:

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

4. Access Management Consoles

If you enabled Gateway API:

  • 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
  • Universal Gateway: https://<kubernetes.gatewayAPI.gateway.hostname>

If you are using Ingress:

  • API Manager Publisher: https://<kubernetes.ingress.management.hostname>/publisher
  • API Manager DevPortal: https://<kubernetes.ingress.management.hostname>/devportal
  • API Manager Carbon Console: https://<kubernetes.ingress.management.hostname>/carbon
  • Universal Gateway: https://<kubernetes.ingress.gateway.hostname>