Skip to content

Deploy WSO2 Identity Server on Kubernetes using Helm

This guide walks you through deploying WSO2 Identity Server as a containerized application on a Kubernetes cluster using the official Helm chart. Helm simplifies the deployment by automating the configuration and management of Kubernetes resources, simplifying setup and maintenance.

The WSO2 Identity Server Helm Chart has been tested in the following environments:

Deployment Version
Kubernetes v1.30.x
RKE2 v1.31.8+rke2r1

The Helm chart for the WSO2 Identity Server is available here.

Prerequisites

Make sure you have the following before starting this guide.

Step 1: Set up environment variables

Define environment variables for the Kubernetes namespace and Helm release name.

export NAMESPACE=<Kubernetes Namespace to deploy the resources>
export RELEASE_NAME=<Helm release name of the deployment>

Note

  • Replace with the namespace where WSO2 Identity Server should be deployed.
  • Replace with a unique name for the Helm release.

Step 2: Create a Kubernetes namespace

Ensure that the specified namespace exists or create a new one using the following command.

kubectl get namespace $NAMESPACE || kubectl create namespace $NAMESPACE

Step 3: Install the Helm chart

There are two ways to install the WSO2 Identity Server using the Helm chart. The Helm chart source code can be found in the kubernetes-is repository.

Option 1: Install the chart from the Helm repository

  1. Add the WSO2 Helm chart repository

    Before installing WSO2 Identity Server, add the WSO2 Helm chart repository and update it to fetch the latest charts.

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

  2. Install the Helm chart from the Helm repository.

    helm install $RELEASE_NAME wso2/identity-server --version 7.1.0 \
-n $NAMESPACE \
--set deployment.image.registry="wso2" \
--set deployment.image.repository="wso2is" \
--set deployment.image.tag="7.1.0" \
--set deployment.apparmor.enabled="false" \
--set deployment.externalJKS.enabled="true"
    Get the latest helm chart version
    To find the latest version, you can use the [WSO2 Identity Server Artifact Hub](https://artifacthub.io/packages/helm/wso2/identity-server){: target="_blank"}.

Set `--version` with the version of WSO2 Identity Server Helm chart you want to deploy.

Option 2: Install the Chart from source

If you prefer to build the chart from the source, follow the steps below:

  1. Clone the WSO2 Kubernetes repository.

    git clone https://github.com/wso2/kubernetes-is.git
cd kubernetes-is

    Note

    You can customize the product configuration by modifying the kubernetes-is/confs/deployment.toml file after cloning the repository.

  2. Install the Helm chart from the cloned repository:

    helm install $RELEASE_NAME -n $NAMESPACE . \
--set deployment.image.registry="wso2" \
--set deployment.image.repository="wso2is" \
--set deployment.image.tag="7.1.0" \
--set deployment.apparmor.enabled="false"
Use a custom docker image

The above commands use the publicly released WSO2 Identity Server Docker image. To use a custom docker image, update the registry, repository, and tag accordingly. You can also specify an image digest instead of a tag as shown below:

--set deployment.image.digest=<digest>
Troubleshoot startup issues in resource-constrained environments

If you are deploying the Helm chart in a resource-constrained environment and the startup takes longer than expected, the shutdown hook of the is may get triggered due to startup probe failures. To avoid this issue, adjust the startup probe parameters when installing the Helm chart:

--set deployment.startupProbe.initialDelaySeconds=<value> \
--set deployment.startupProbe.failureThreshold=<value>

(Optional) Step 4: Configure resource limits

By default, the Helm chart for WSO2 Identity Server requests and limits the following resources in your Kubernetes cluster:

Resource requests (Minimum required)

CPU Memory
2 cores 2Gi

Resource requests (Maximum allowed)

CPU Memory
3 cores 4Gi

To customize resource requests and limits in your Helm deployment, use the following flags:

--set deployment.resources.requests.cpu="<value>" \
--set deployment.resources.requests.memory="<value>" \
--set deployment.resources.limits.cpu="<value>" \
--set deployment.resources.limits.memory="<value>"

Step 5: Obtain the External IP

After deploying WSO2 Identity Server, you need to find its external IP address to access it outside the cluster. Run the following command to list the ingress resources in your namespace:

kubectl get ing -n $NAMESPACE

The output will contain the following columns:

  • HOSTS: The hostname assigned to WSO2 Identity Server (Default: wso2is.com).
  • ADDRESS: The external IP address that exposes WSO2 Identity Server outside the Kubernetes cluster.
  • PORTS: The externally accessible service ports.

Step 6: Configure DNS

If your hostname is backed by a DNS service, create a DNS record that maps the hostname to the external IP. If there is no DNS service, you can manually add an entry to the /etc/hosts file on your local machine (for evaluation purposes only):

<EXTERNAL-IP> wso2is.com

Step 7: Access WSO2 Identity Server

Once everything is set up, you can access WSO2 Identity Server using the following URLs:

  • Console: https://wso2is.com/console
  • My Account portal: https://wso2is.com/myaccount

Congratulations! You have successfully deployed WSO2 Identity Server on Kubernetes using Helm.

If you are deploying WSO2 Identity Server on Azure Kubernetes Service (AKS) and require an advanced set up, refer to the relevant section in the documentation.