wso2/is-pattern-1

Helm Chart for a clustered deployment of WSO2 Identity Server

Resources for building a Helm chart for a clustered deployment of WSO2 Identity Server.

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

Contents

• Prerequisites
• Quick Start Guide
• Configuration
• Runtime Artifact Persistence and Sharing
• Managing Java Keystores and Truststores
• Centralized Logging

Prerequisites

• WSO2 product Docker images used for the Kubernetes deployment.

WSO2 product Docker images available at DockerHub package General Availability (GA) versions of WSO2 products with no WSO2 Updates.

For a production grade deployment of the desired WSO2 product-version, it is highly recommended to use the relevant Docker image which packages WSO2 Updates, available at WSO2 Private Docker Registry. In order to use these images, you need an active WSO2 Subscription.

• Install Git, Helm and Kubernetes client in order to run the steps provided in the following quick start guide.
  
  

• An already setup Kubernetes cluster.
  
  

• Install NGINX Ingress Controller.
  
  

• Add the WSO2 Helm chart repository.

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

Quick Start Guide

1. Install the Helm Chart

You can install the relevant Helm chart either from WSO2 Helm Chart Repository or by source.

Note:

• NAMESPACE should be the Kubernetes Namespace in which the resources are deployed.

Install Chart From WSO2 Helm Chart Repository

Helm version 2

 helm install --name <RELEASE_NAME> wso2/is-pattern-1 --version 5.11.0-2 --namespace <NAMESPACE>

Helm version 3

• Create the Kubernetes Namespace.

  kubectl create ns <NAMESPACE>
  

• Deploy the Kubernetes resources using the Helm Chart

  helm install <RELEASE_NAME> wso2/is-pattern-1 --version 5.11.0-2 --namespace <NAMESPACE>
  

The above steps will deploy the deployment pattern using WSO2 product Docker images available at DockerHub.

If you are using WSO2 product Docker images available from WSO2 Private Docker Registry, please provide your WSO2 Subscription Credentials via input values (using --set argument).

Refer the following example.

 helm install --name <RELEASE_NAME> wso2/is-pattern-1 --version 5.11.0-2 --namespace <NAMESPACE> --set wso2.subscription.username=<SUBSCRIPTION_USERNAME> --set wso2.subscription.password=<SUBSCRIPTION_PASSWORD>

Install Chart From Source

In the context of this document,
* KUBERNETES_HOME will refer to a local copy of the wso2/kubernetes-is Git repository.
* HELM_HOME will refer to <KUBERNETES_HOME>/advanced.

Clone the Helm Resources for WSO2 Identity Server Git repository.

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

Deploy Helm chart for a clustered deployment of WSO2 Identity Server.

Helm version 2

 helm install --dep-up --name <RELEASE_NAME> <HELM_HOME>/is-pattern-1 --version 5.11.0-2 --namespace <NAMESPACE>

Helm version 3

• Create the Kubernetes Namespace to which you desire to deploy the Kubernetes resources.

  kubectl create ns <NAMESPACE>
  

• Deploy the Kubernetes resources using the Helm Chart

  helm install <RELEASE_NAME> <HELM_HOME>/is-pattern-1 --version 5.11.0-2 --namespace <NAMESPACE> --dependency-update
  

The above steps will deploy the deployment pattern using WSO2 product Docker images available at DockerHub.

If you are using WSO2 product Docker images available from WSO2 Private Docker Registry, please provide your WSO2 Subscription Credentials via input values (using --set argument).

Refer the following example.

 helm install --name <RELEASE_NAME> <HELM_HOME>/is-pattern-1 --version 5.11.0-2 --namespace <NAMESPACE> --set wso2.subscription.username=<SUBSCRIPTION_USERNAME> --set wso2.subscription.password=<SUBSCRIPTION_PASSWORD>

2. Obtain the external IP

Obtain the external IP (EXTERNAL-IP) of the Identity Server Ingress resource, by listing down the Kubernetes Ingresses.

kubectl get ing -n <NAMESPACE>

The output under the relevant column stands for the following.

• NAME: Metadata name of the Kubernetes Ingress resource (defaults to wso2is-pattern-1-identity-server-ingress)
• HOSTS: Hostname of the WSO2 Identity service (<wso2.deployment.wso2is.ingress.identity.hostname>)
• ADDRESS: External IP (EXTERNAL-IP) exposing the Identity service to outside of the Kubernetes environment
• PORTS: Externally exposed service ports of the Identity service

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

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

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

<EXTERNAL-IP> <wso2.deployment.wso2is.ingress.identity.hostname>

4. Access Management Console, Console and My Account

• Identity Server’s Carbon Management Console: https://<wso2.deployment.wso2is.ingress.identity.hostname>/carbon
• Identity Server’s Console: https://<wso2.deployment.wso2is.ingress.identity.hostname>/console
• Identity Server’s My Account: https://<wso2.deployment.wso2is.ingress.identity.hostname>/myaccount

Configuration

The following tables lists the configurable parameters of the chart and their default values.

WSO2 Subscription Configurations

Parameter	Description	Default Value
wso2.subscription.username	Your WSO2 Subscription username	-
wso2.subscription.password	Your WSO2 Subscription password	-

If you do not have an active WSO2 subscription, do not change the parameters wso2.subscription.username and wso2.subscription.password.

Chart Dependencies

Parameter	Description	Default Value
wso2.deployment.dependencies.mysql.enabled	Enable the deployment and usage of WSO2 IAM MySQL based Helm Chart	true

We recommend you to persist the database data of the Kubernetes based MySQL deployment using an appropriate Kubernetes StorageClass. You can achieve this by setting the property mysql-is.mysql.persistence.storageClass to the desired StorageClass.

Important: In a production grade deployment, it is highly recommended to host the product databases in an external database server.

Persistent Runtime Artifact Configurations

Parameter	Description	Default Value
wso2.deployment.persistentRuntimeArtifacts.storageClass	Appropriate Kubernetes Storage Class	-
wso2.deployment.persistentRuntimeArtifacts.sharedArtifacts.enabled	Enable persistence/sharing of runtime artifacts between instances of the Identity Server profile	false
wso2.deployment.persistentRuntimeArtifacts.sharedArtifacts.capacity.tenants	Capacity for tenant data between Identity Server instances	100M
wso2.deployment.persistentRuntimeArtifacts.sharedArtifacts.capacity.userstores	Capacity for secondary user stores between Identity Server instances	50M

Please refer to the section Runtime Artifact Persistence and Sharing for details.

Identity Server Configurations

Parameter	Description	Default Value
wso2.deployment.wso2is.dockerRegistry	Registry location of the Docker image to be used to create Identity Server instances	-
wso2.deployment.wso2is.imageName	Name of the Docker image to be used to create Identity Server instances	wso2is
wso2.deployment.wso2is.imageTag	Tag of the image used to create Identity Server instances	5.11.0
wso2.deployment.wso2is.imagePullPolicy	Refer to doc	Always
wso2.deployment.wso2is.replicas	Number of replicas for IS node	2
wso2.deployment.wso2is.livenessProbe.initialDelaySeconds	Initial delay for the live-ness probe for IS node	120
wso2.deployment.wso2is.livenessProbe.periodSeconds	Period of the live-ness probe for IS node	10
wso2.deployment.wso2is.readinessProbe.initialDelaySeconds	Initial delay for the readiness probe for IS node	120
wso2.deployment.wso2is.readinessProbe.periodSeconds	Period of the readiness probe for IS node	10
wso2.deployment.wso2is.resources.requests.memory	The minimum amount of memory that should be allocated for a Pod	3Gi
wso2.deployment.wso2is.resources.requests.cpu	The minimum amount of CPU that should be allocated for a Pod	3000m
wso2.deployment.wso2is.resources.limits.memory	The maximum amount of memory that should be allocated for a Pod	4Gi
wso2.deployment.wso2is.resources.limits.cpu	The maximum amount of CPU that should be allocated for a Pod	4000m
wso2.deployment.wso2is.resources.jvm.heap.memory.xms	The initial memory allocation for JVM Heap	2048m
wso2.deployment.wso2is.resources.jvm.heap.memory.xmx	The maximum memory allocation for JVM Heap	2048m
wso2.deployment.wso2is.config	Custom deployment configuration file (<WSO2IS>/repository/conf/deployment.toml)	-
wso2.deployment.wso2is.ingress.identity.hostname	Hostname for for Identity service	identity.wso2.com
wso2.deployment.wso2is.ingress.identity.annotations	Ingress resource annotations for Identity service	Community NGINX Ingress controller annotations

The above referenced default, minimum resource amounts for running WSO2 Identity Server profiles are based on its official documentation.

The above referenced JVM settings are based on its official documentation.

Centralized Logging Configurations

Parameter	Description	Default Value
wso2.centralizedLogging.enabled	Enable Centralized logging for WSO2 components	false
wso2.centralizedLogging.logstash.imageTag	Logstash Sidecar container image tag	7.8.1
wso2.centralizedLogging.logstash.elasticsearch.username	Elasticsearch username	elastic
wso2.centralizedLogging.logstash.elasticsearch.password	Elasticsearch password	changeme

Monitoring Configurations

Parameter	Description	Default Value
wso2.monitoring.enabled	Enable Prometheus monitoring	false
wso2.monitoring.prometheus.jmxJobName	Prometheus job name	jmx
wso2.monitoring.prometheus.serviceMonitor.labels	Prometheus labels for identifying Service Monitor	release: monitoring
wso2.monitoring.prometheus.serviceMonitor.blackBoxNamespace	Prometheus blackbox exporter namespace

Runtime Artifact Persistence and Sharing

• In a production grade deployment, it is highly recommended to enable persistence and sharing of runtime artifacts such as, user stores and tenant data between instances of the Identity Server profile (i.e. set wso2.deployment.persistentRuntimeArtifacts.sharedArtifacts.enabled to true).

• It is mandatory to set an appropriate Kubernetes StorageClass when you enable this feature. Only persistent storage solutions supporting ReadWriteMany access mode are applicable for wso2.deployment.persistentRuntimeArtifacts.storageClass.

• Please refer to the official WSO2 container guide for advanced details with regards to WSO2 recommended, storage options.

Managing Java Keystores and Truststores

For advanced details with regards to managing Java keystores and truststores in a container based WSO2 product deployment please refer to the official WSO2 container guide.

Centralized Logging

• Centralized logging with Logstash and Elasticsearch is disabled, by default.

• However, if it is required to be enabled, the following steps should be adopted.

1. Set wso2.centralizedLogging.enabled to true in the values.yaml file.

2. Add Elasticsearch Helm repository to download sub-charts required for centralized logging.

   helm repo add elasticsearch https://helm.elastic.co
   

3. Add the following dependencies in the requirements.yaml file.

   dependencies:
     - name: kibana
       version: "7.8.1"
       repository: "https://helm.elastic.co"
       condition: wso2.centralizedLogging.enabled
     - name: elasticsearch
       version: "7.8.1"
       repository: "https://helm.elastic.co"
       condition: wso2.centralizedLogging.enabled
   

4. Add override configurations for Elasticsearch in the values.yaml file.

   wso2:
     ( ... )
   elasticsearch:
     clusterName: wso2-elasticsearch