Skip to content

Deploy WSO2 Identity Server on OpenShift Using Helm

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

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

Deployment Version
OpenShift v4.18.x

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

Prerequisites

Before proceeding, ensure you have the following:

Step 1: Set environment variables

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

export NAMESPACE=<your-namespace>
export RELEASE_NAME=<your-helm-release-name>

Note

  • Replace <your-namespace> with the desired OpenShift namespace for deploying WSO2 Identity Server.
  • Replace <your-helm-release-name> with a unique name for your Helm release.

Step 2: Create the OpenShift namespace

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

oc get namespace $NAMESPACE || oc create namespace $NAMESPACE

Step 3: Build an OpenShift-compatible Docker image

OpenShift doesn't let containers run as the root user for security reasons. Instead, each time, it runs them as a random user that belongs to the root group (GID 0). Because of this, the default WSO2 Identity Server Docker image might not work as expected as the random user may not have permission to access important files. To overcome this, you can use one of the following methods.

Option 1: Create a custom Docker image

Create a custom Docker image that sets the group ownership of files and folders to the root group, and give that group the right permissions.

Learn more with a sample docker image
FROM wso2/wso2is:7.1.0-alpine

USER root
RUN chgrp -R root /home/wso2carbon/wso2is-* && chmod -R g+rwX /home/wso2carbon/wso2is-*
USER wso2carbon

Option 2: Use the official Docker image by altering settings

Important

While it's technically possible to use the official Docker image for WSO2 Identity Server or similar applications without building a custom image, doing so by bypassing OpenShift security mechanisms is not recommended, especially for production environments.

Instead of creating a custom Docker image, you can use the official image by adjusting some security settings:

  • Disable seccomp during deployment by adding this Helm option: 
    --set deployment.securityContext.seccompProfile.enabled="false"
    If you are setting this flag, you need to remove following configs from the Helm command: 
    --set deployment.securityContext.runAsUser.enabled="false" \
--set deployment.entrypoint.defaultMode=0457
  • Grant anyuid permissions to the service account running the deployment with this OpenShift command: 
    oc adm policy add-scc-to-user anyuid -z <service-account> -n $NAMESPACE

Step 4: Install the Helm Chart

The WSO2 Identity Server Helm chart is available through the WSO2 Helm repository or source code.

Option 1: Install from the Helm Repository

  1. Add the WSO2 Helm repository and update:

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

  2. Install the chart:

    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.securityContext.enableRunAsUser="false" \
  --set deployment.configMaps.entryPoint.defaultMode=0457
    Get the latest helm chart version

    To find the latest version, you can use the WSO2 Identity Server Artifact Hub.

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

Option 2: Install from source

  1. Clone the WSO2 Kubernetes repository:

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

    Note

    You can modify confs/deployment.toml to customize server configurations.

  2. Install the chart:

    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" \
  --set deployment.securityContext.enableRunAsUser="false" \
  --set deployment.configMaps.entryPoint.defaultMode=0457
Use a custom docker image digest

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 5: Configure resource limits

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

Minimum required resources

CPU Memory
2 cores 2Gi

Maximum allowed resources

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 6: Expose WSO2 Identity Server service

To make WSO2 Identity Server accessible from outside your OpenShift cluster, you need to expose the service. Depending on your setup, you can use either OpenShift routes or ingress.

Option 1: Using OpenShift routes

Enable route-based access by setting the following Helm flag during deployment:

--set deployment.route.enabled=true

Option 2: Using ingress

If you prefer to use ingress, after deploying WSO2 Identity Server, find its external IP address by listing the ingress resources in your namespace:

oc 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 OpenShift cluster.
  • PORTS: The externally accessible service ports.

Step 7: 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 8: Access WSO2 Identity Server

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

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