Skip to content

Attention

All Linux assets, packages, and binaries require a support contract for access. Contact sales@gluu.org for more information. For free up-to-date binaries, check out the latest releases at The Linux Foundation Janssen Project, the new upstream open-source project.

The Kubernetes recipes#

Getting Started with Kubernetes#

The Kubernetes deployment of the Gluu Server, also called Cloud Native (CN) Edition, requires some special considerations compared to other deployments. This page details the installation and initial configuration of a CN deployment. More advanced configuration details are available on the appropriate pages throughout the Gluu documentation. For convenience, links to those documents follow:

Requirements for accessing docker images and assets#

Note

Starting from version 4.5.17, steps 1–3 will no longer be required and will be removed; they will be replaced entirely by step 4.

  1. Contact sales@gluu.org for credentials (username and password/token) to access and pull our docker images. Existing customers should have received the credentials already.

  2. Create secrets to access and pull images from Docker hub repo. The secrets must lives in the same namespace (create the namespace if doesn't exist yet).

    kubectl create namespace <namespace>

    If you're planning to use istio, set the label as well:

    kubectl label namespace <namespace> istio-injection=enabled

    Afterwards, create the required secrets (in this example, regcred is the name of the secret):

    kubectl -n <namespace> create secret docker-registry regcred --docker-server=https://index.docker.io/v1/ --docker-username=<username> --docker-password=<password/token>

  3. Create override-values.yaml for installation.

    helm repo add gluu https://gluufederation.github.io/gluu4/pygluu/kubernetes/templates/helm
helm show values gluu/gluu --version=1.8.x > override-values.yaml

    Inject the secret name in your override-values.yaml at image.pullSecrets for each service. For example:

    oxauth:
  image:
    # -- Image pullPolicy to use for deploying.
    pullPolicy: IfNotPresent
    # -- Image to use for deploying.
    repository: gluufederation/oxauth
    # -- Image  tag to use for deploying.
    tag: 4.5.17-1
    # -- Image Pull Secrets
    pullSecrets:
      - name: regcred

  4. Inject the SSA generated in your override-values.yaml at global.gluuLicenseSsa.

Migrating from pygluu-kubernetes.pyz tool#

Warning

Starting from version 4.5.17, the pygluu-kubernetes.pyz tool is no longer supported. We recommend to use helm commands directly to install/upgrade the charts.

To migrate from pygluu-kubernetes.pyz tool:

  1. Get the override-values.yaml used in chart installation.

    There are 2 ways to get this file:

    1. Go to working directory where the pygluu-kubernetes.pyz is located. A typical working directory layout is shown below for example:

      /path/to/working/directory
├── alb
├── couchbase
├── gluu_versions.json
├── helm
├── ldap
├── LICENSE
├── nginx
├── pygluu-kubernetes.pyz
└── README.md

      Copy the helm/gluu/values.yaml file and save it as override-values.yaml, hence the final layout is:

      /path/to/working/directory
├── alb
├── couchbase
├── gluu_versions.json
├── helm
├── ldap
├── LICENSE
├── nginx
├── pygluu-kubernetes.pyz
├── override-values.yaml
└── README.md

      You will only need the override-values.yaml and may ignore other files and directories.

    2. Extract the values using the following command:

      helm -n $NAMESPACE get values $RELEASE_NAME -o yaml > override-values.yaml

      The generated override-values.yaml is the only file that is required for chart upgrade.

  2. Modify the override-values.yaml directly and use helm commands to manage the chart (e.g. install/upgrade/etc.), for example:

    helm -n $NAMESPACE upgrade $RELEASE_NAME gluu/gluu --version $CHART_VERSION -f override-values.yaml

System Requirements for cloud deployments#

Note

For local deployments like minikube and microk8s or cloud installations for demoing Gluu may set the resources to the minimum and hence can have 8GB RAM, 4 CPU, and 50GB disk in total to run all services.

Please calculate the minimum required resources as per the services deployed. The following table contains the default recommended resources to start with. Depending on the use of each service the resources may be increased or decreased.

Service CPU Unit RAM Disk Space Processor Type Required
oxAuth 2.5 2.5GB N/A 64 Bit Yes
LDAP 1.5 2GB 10GB 64 Bit if using hybrid or LDAP for persistence
Couchbase - - - - If using hybrid or couchbase for persistence
FIDO2 0.5 0.5GB N/A 64 Bit No
SCIM 1.0 1.0GB N/A 64 Bit No
config - job 0.5 0.5GB N/A 64 Bit Yes on fresh installs
persistence - job 0.5 0.5GB N/A 64 Bit Yes on fresh installs
oxTrust 1.0 1.0GB N/A 64 Bit No
oxShibboleth 1.0 1.0GB N/A 64 Bit No
oxPassport 0.7 0.9GB N/A 64 Bit No
NGINX 1 1GB N/A 64 Bit Yes if not ALB
key-rotation 0.3 0.3GB N/A 64 Bit No
cr-rotate 0.2 0.2GB N/A 64 Bit No
CASA 0.5 0.5GB N/A 64 Bit No
  1. Configure cloud or local kubernetes cluster:

Amazon Web Services (AWS) - EKS#

Setup Cluster#

  • Follow this guide to install a cluster with worker nodes. Please make sure that you have all the IAM policies for the AWS user that will be creating the cluster and volumes.

  • To be able to attach volumes to your pod, you need to install the Amazon EBS CSI driver

Requirements#

  • The above guide should also walk you through installing kubectl, aws-iam-authenticator and aws cli on the VM you will be managing your cluster and nodes from. Check to make sure.

    aws-iam-authenticator help
aws-cli
kubectl version

  • Optional[alpha]: If using Istio please install it prior to installing Gluu. You may choose to use any installation method Istio supports. If you have installed istio ingress, a loadbalancer will have been created. Please save the address of the loadbalancer for use later during installation.

Note

Default AWS deployment will install a classic load balancer with an IP that is not static. Don't worry about the IP changing. All pods will be updated automatically with our script when a change in the IP of the load balancer occurs. However, when deploying in production, DO NOT use our script. Instead, assign a CNAME record for the LoadBalancer DNS name, or use Amazon Route 53 to create a hosted zone. More details are in this AWS guide.

Warning

In recent releases we have noticed that the ALB does not properly work with the oxtrust admin UI. Functions such as access and cache refresh do not work. There is an issue open but the main issue is in the fact that ALB does not support rewrites.

GCE (Google Cloud Engine) - GKE#

Setup Cluster#

  1. Install gcloud

  2. Install kubectl using gcloud components install kubectl command

  3. Create a cluster using a command such as the following example:

    gcloud container clusters create exploringgluu --num-nodes 2 --machine-type e2-highcpu-8 --zone us-west1-a

    where CLUSTER_NAME is the name you choose for the cluster and ZONE_NAME is the name of zone where the cluster resources live in.

  4. Configure kubectl to use the cluster:

    gcloud container clusters get-credentials CLUSTER_NAME --zone ZONE_NAME

    where CLUSTER_NAME is the name you choose for the cluster and ZONE_NAME is the name of zone where the cluster resources live in.

  5. Afterwards, run kubectl cluster-info to check whether kubectl is ready to interact with the cluster. Make sure you are authenticated by using one of the several ways

  6. Optional[alpha]: If using Istio please install it prior to installing Gluu. You may choose to use any installation method Istio supports. If you have installed istio ingress, a loadbalancer will have been created. Please save the ip of loadbalancer for use later during installation.

DigitalOcean Kubernetes (DOKS)#

Setup Cluster#

  • Follow this guide to create a digital ocean kubernetes service cluster and connect to it.

  • Optional[alpha]: If using Istio please install it prior to installing Gluu. You may choose to use any installation method Istio supports. If you have installed istio ingress, a loadbalancer will have been created. Please save the ip of loadbalancer for use later during installation.

Azure - AKS#

Warning

Pending

Requirements#

  • Follow this guide to install Azure CLI on the VM that will be managing the cluster and nodes. Check to make sure.

  • Follow this section to create the resource group for the AKS setup.

  • Follow this section to create the AKS cluster

  • Follow this section to connect to the AKS cluster

  • Optional[alpha]: If using Istio please install it prior to installing Gluu. You may choose to use any installation method Istio supports. If you have installed istio ingress, a loadbalancer will have been created. Please save the ip of loadbalancer for use later during installation.

Minikube#

Requirements#

  1. Install minikube.

  2. Install kubectl.

  3. Create cluster:

    minikube start

  4. Configure kubectl to use the cluster:

    kubectl config use-context minikube

  5. Enable ingress on minikube

    minikube addons enable ingress

  6. Optional[alpha]: If using Istio please install it prior to installing Gluu. You may choose to use any installation method Istio supports. Please note that at the moment Istio ingress is not supported with Minikube.

MicroK8s#

Requirements#

  1. Install MicroK8s

  2. Make sure all ports are open for microk8s

  3. Enable helm3, hostpath-storage, and dns:

    sudo microk8s.enable dns
sudo microk8s.enable hostpath-storage
sudo microk8s.enable helm3

    Make aliases for kubectl and helm3:

    sudo snap alias microk8s.kubectl kubectl
sudo snap alias microk8s.helm3 helm

  4. Optional: If using nginx ingress, please enable it.

    sudo microk8s.enable ingress

    Note

    If using self-generated SSL certificate and key generated by installer, enable ingress after config job is finished. This will skip the creation of SSL certificate and key generated by ingress.

  5. Optional[alpha]: If using Istio please enable it. 

    sudo microk8s.enable community
sudo microk8s.enable istio

    Note

    The istio ingress gateway service is deployed as LoadBalancer type which requires external IP. Some cloud providers has their own loadbalancer that can assign external IP for istio ingress gateway. If there's no external loadbalancer (as in baremetal VM), an alternative is to install MetalLB:

    sudo microk8s.enable metallb

    This command will prompt for IP address pool. Refer to metallb addons docs for details.

  1. Install using one of the following :

Install Gluu using Helm#

Prerequisites#

  • Kubernetes >=1.19x
  • Persistent volume provisioner support in the underlying infrastructure
  • Install Helm

Installing Gluu using Helm manually#

  1. Create your override-values.yaml file:

    helm repo add gluu https://gluufederation.github.io/gluu4/pygluu/kubernetes/templates/helm
helm repo update
kubernetes create ns <namespace>
helm show values gluu/gluu --version=1.8.x > override-values.yaml

  2. Optional if not using Istio ingress: Install NGINX-Ingress Helm Chart.

    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo add stable https://charts.helm.sh/stable
helm repo update
helm install <nginx-release-name> ingress-nginx/ingress-nginx --namespace=<nginx-namespace>

    • If the FQDN for gluu i.e. demoexample.gluu.org is registered and globally resolvable, forward it to the loadbalancer address created in the previous step by NGINX-Ingress. A record can be added on most cloud providers to forward the domain to the loadbalancer. For example, on AWS assign a CNAME record for the LoadBalancer DNS name, or use Amazon Route 53 to create a hosted zone. More details in this AWS guide. Another example on GCE.

    • If the FQDN is not registered acquire the loadbalancer ip if on GCE, or Azure using kubectl get svc <release-name>-nginx-ingress-controller --output jsonpath='{.status.loadBalancer.ingress[0].ip}' and if on AWS get the loadbalancer addresss using kubectl -n ingress-nginx get svc ingress-nginx \--output jsonpath='{.status.loadBalancer.ingress[0].hostname}'.

  4. If deploying on the cloud make sure to take a look at the Helm cloud-specific notes before continuing:

    If deploying locally make sure to take a look at the helm-specific notes below before continuing:

  5. Optional: If using PostgreSQL as the persistence backend. In a production environment, a production-grade PostgreSQL server should be used such as Cloud SQL in GCP or Amazon RDS in AWS.

    For testing purposes, you can deploy it on your Kubernetes cluster using the following commands: 

    wget https://raw.githubusercontent.com/GluuFederation/flex/nightly/automation/pgsql.yaml
kubectl apply -f pgsql.yaml

    Add the following yaml snippet to your override-values.yaml file: 

    global:
  gluuPersistenceType: sql
config:
  configmap:
    cnSqlDbName: gluu
    cnSqlDbPort: 5432
    cnSqlDbDialect: pgsql
    cnSqlDbHost: postgresql.gluu.svc
    cnSqlDbUser: postgres
    cnSqlDbTimezone: UTC
    cnSqldbUserPassword: Test1234#

  6. Optional: If using MySQL as the persistence backend. In a production environment, a production grade MySQL server should be used such as Cloud SQL in GCP or Amazon RDS in AWS.

    For testing purposes, you can deploy it on your Kubernetes cluster using the following commands:

    wget https://raw.githubusercontent.com/GluuFederation/flex/nightly/automation/mysql.yaml
kubectl apply -f mysql.yaml

    Add the following yaml snippet to your override-values.yaml file: 

    global:
  gluuPersistenceType: sql
config:
  configmap:
    cnSqlDbName: gluu
    cnSqlDbPort: 3306
    cnSqlDbDialect: mysql
    cnSqlDbHost: mysql.gluu.svc
    cnSqlDbUser: root
    cnSqlDbTimezone: UTC
    cnSqldbUserPassword: Test1234#

  7. Optional: If using couchbase as the persistence backend.

    1. Setup a Couchbase cluster either using Operator or remote Couchbase

    2. Add the following yaml snippet to your override-values.yaml file:

      global:
  gluuPersistenceType: couchbase
config:
  configmap:
    # base64 string of couchbase certificate
    gluuCouchbaseCrt: ZmFrZWNlcnQK
    gluuCouchbasePass: Test1234#
    gluuCouchbaseSuperUserPass: Test1234#
    gluuCouchbaseSuperUser: admin
    gluuCouchbaseUser: gluu
    gluuCouchbaseBucketPrefix: gluu
    gluuCouchbaseUrl: cbgluu.default.svc.cluster.local

  8. Install Gluu chart by executing the following commands:

    helm install gluu gluu/gluu -n <namespace> --version=<version> -f override-values.yaml

EKS Helm notes#

Required changes to the override-values.yaml#

Inside the global override-values.yaml change the marked keys with CHANGE-THIS to the appropriate values :

#global values to be used across charts
global:
  storageClass:
    provisioner: kubernetes.io/aws-ebs
  domain: demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
  isDomainRegistered: "false" # CHANGE-THIS  "true" or "false" to specify if the domain above is registered or not.    
nginx-ingress:
  ingress:
    enabled: true
    path: /
    hosts:
      - demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
    tls:
      - secretName: tls-certificate
        hosts:
          - demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
config:
  configmap:
    lbAddr: "" #CHANGE-THIS to the address received in the previous step axx-109xx52.us-west-2.elb.amazonaws.com

Tweak the optional parameters in override-values.yaml to fit the setup needed.

GKE Helm notes#

Required changes to the override-values.yaml#

Inside the global override-values.yaml change the marked keys with CHANGE-THIS to the appropriate values :

#global values to be used across charts
global:
  storageClass:
    provisioner: kubernetes.io/gce-pd
  domain: demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
  # Networking configs
  lbIp: "" #CHANGE-THIS  to the IP received from the previous step
  isDomainRegistered: "false" # CHANGE-THIS  "true" or "false" to specify if the domain above is registered or not.
nginx-ingress:
  ingress:
    enabled: true
    path: /
    hosts:
      - demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
    tls:
      - secretName: tls-certificate
        hosts:
          - demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu

Tweak the optional parameters in override-values.yaml to fit the setup needed.

Minikube Helm notes#

Required changes to the override-values.yaml#

Inside the global override-values.yaml change the marked keys with CHANGE-THIS to the appropriate values :

#global values to be used across charts
global:
  storageClass:
    provisioner: k8s.io/minikube-hostpath
  domain: demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
  lbIp: "" #CHANGE-THIS  to the IP of minikube <minikube ip>

nginx-ingress:
  ingress:
    enabled: true
    path: /
    hosts:
      - demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
    tls:
      - secretName: tls-certificate
        hosts:
          - demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu

Tweak the optional parameters in override-values.yaml to fit the setup needed.

  • Map gluu's FQDN at /etc/hosts file to the minikube IP as shown below.

    ##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
192.168.99.100  demoexample.gluu.org #minikube IP and example domain
127.0.0.1   localhost
255.255.255.255 broadcasthost
::1             localhost

Microk8s helm notes#

Required changes to the override-values.yaml#

Inside the global override-values.yaml change the marked keys with CHANGE-THIS to the appropriate values :

#global values to be used across charts
global:
  storageClass:
    provisioner: microk8s.io/hostpath
  domain: demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
  lbIp: "" #CHANGE-THIS  to the IP of the microk8s VM

nginx-ingress:
  ingress:
    enabled: true
    path: /
    hosts:
      - demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu
    tls:
      - secretName: tls-certificate
        hosts:
          - demoexample.gluu.org #CHANGE-THIS to the FQDN used for Gluu

Tweak the optional parameters in override-values.yaml to fit the setup needed.

  • Map gluu's FQDN at /etc/hosts file to the microk8s VM IP as shown below.
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
192.168.99.100    demoexample.gluu.org #microk8s IP and example domain
127.0.0.1 localhost
255.255.255.255   broadcasthost
::1             localhost

Uninstalling the Chart#

To uninstall/delete my-release deployment:

helm delete <my-release>

If during installation the release was not defined, the release name is checked by running helm ls then deleted using the previous command and the default release name.

Configuration#

Instructions on how to install different services#

Enabling the following services automatically install the corresponding associated chart. To enable/disable them set true or false in the override-values.yaml as shown below: 

global:
  cr-rotate:
    enabled: true
  oxpassport:
    enabled: true
  casa:
    enabled: true
  oxshibboleth:
    enabled: true
  oxauth-key-rotation:
    enabled: true
  cleanup:
    enabled: true

Install Gluu using the gui installer#

Warning

The GUI installer is no longer supported. Please use Helm chart to install Gluu.

settings.json parameters file contents#

Warning

The settings.json file that was previously used in pygluu-kubernetes.pyz is no longer supported since version 4.5.17.

Below is a list of parameters in settings.json that mapped to attributes in default values.yaml:

Parameter (settings.json) Attribute (values.yaml)
TEST_ENVIRONMENT global.cloud.testEnvironment
ADMIN_PW config.adminPass
USE_ISTIO global.istio.enabled
USE_ISTIO_INGRESS global.istio.ingress
ISTIO_SYSTEM_NAMESPACE global.istio.namespace
HOST_EXT_IP global.lbIp
ARN_AWS_IAM global.alb.ingress.additionalAnnotations.["alb.ingress.kubernetes.io/certificate-arn"]
LB_ADD config.configmap.lbAddr
PERSISTENCE_BACKEND global.gluuPersistenceType
REDIS_URL config.configmap.gluuRedisUrl
REDIS_TYPE config.configmap.gluuRedisType
REDIS_PW config.redisPass
REDIS_USE_SSL config.configmap.gluuRedisUseSsl
REDIS_SSL_TRUSTSTORE config.configmap.gluuRedisSslTruststore
REDIS_SENTINEL_GROUP config.configmap.gluuRedisSentinelGroup
COUCHBASE_URL config.configmap.gluuCouchbaseUrl
COUCHBASE_USER config.configmap.gluuCouchbaseUser
COUCHBASE_BUCKET_PREFIX config.configmap.gluuCouchbaseBucketPrefix
COUCHBASE_PASSWORD config.configmap.gluuCouchbasePass
COUCHBASE_SUPERUSER config.configmap.gluuCouchbaseSuperUser
COUCHBASE_SUPERUSER_PASSWORD config.configmap.gluuCouchbaseSuperUserPass
COUCHBASE_CRT config.configmap.gluuCouchbaseCrt
COUCHBASE_INDEX_NUM_REPLICA config.configmap.gluuCouchbaseIndexNumReplica
GLUU_CACHE_TYPE config.configmap.gluuCacheType
GLUU_FQDN global.domain
COUNTRY_CODE config.countryCode
STATE config.state
EMAIL config.email
CITY config.city
ORG_NAME config.orgName
LDAP_PW config.ldapPass
IS_GLUU_FQDN_REGISTERED global.isDomainRegistered
LDAP_STORAGE_SIZE opendj.persistence.size
OXAUTH_KEYS_LIFE oxauth-keys-rotation.keysLife
FIDO2_REPLICAS fido2.replicas
SCIM_REPLICAS scim.replicas
OXAUTH_REPLICAS oxauth.replicas
OXTRUST_REPLICAS oxtrust.replicas
LDAP_REPLICAS opendj.replicas
OXSHIBBOLETH_REPLICAS oxshibboleth.replicas
OXPASSPORT_REPLICAS oxpassport.replicas
CASA_REPLICAS casa.replicas
ENABLE_OXTRUST_API config.gluuOxtrustApiEnabled
ENABLE_OXTRUST_TEST_MODE config.gluuOxtrustApiTestMode
ENABLE_CACHE_REFRESH global.cr-rotate.enabled
ENABLE_OXPASSPORT global.oxpassport.enabled
ENABLE_OXSHIBBOLETH global.oxshibboleth.enabled
ENABLE_CASA global.casa.enabled
ENABLE_FIDO2 global.fido2.enabled
ENABLE_SCIM global.scim.enabled
ENABLE_OXAUTH_KEY_ROTATE global.oxauth-key-rotation.enabled
CASA_IMAGE_NAME casa.image.repository
CASA_IMAGE_TAG casa.image.tag
CONFIG_IMAGE_NAME config.image.repository
CONFIG_IMAGE_TAG config.image.tag
CACHE_REFRESH_ROTATE_IMAGE_NAME cr-rotate.image.repository
CACHE_REFRESH_ROTATE_IMAGE_TAG cr-rotate.image.tag
CERT_MANAGER_IMAGE_NAME oxauth-key-rotation.image.repository
CERT_MANAGER_IMAGE_TAG oxauth-key-rotation.image.tag
LDAP_IMAGE_NAME ldap.image.repository
LDAP_IMAGE_TAG ldap.image.tag
OXAUTH_IMAGE_NAME oxauth.image.repository
OXAUTH_IMAGE_TAG oxauth.image.tag
OXPASSPORT_IMAGE_NAME oxpassport.image.repository
OXPASSPORT_IMAGE_TAG oxpassport.image.repository
FIDO2_IMAGE_NAME fido2.image.repository
FIDO2_IMAGE_TAG fido2.image.tag
SCIM_IMAGE_NAME scim.image.repository
SCIM_IMAGE_TAG scim.image.tag
OXSHIBBOLETH_IMAGE_NAME oxshibboleth.image.repository
OXSHIBBOLETH_IMAGE_TAG oxshibboleth.image.tag
OXTRUST_IMAGE_NAME oxtrust.image.repository
OXTRUST_IMAGE_TAG oxtrust.image.tag
PERSISTENCE_IMAGE_NAME persistence.image.repository
PERSISTENCE_IMAGE_TAG persistence.image.tag
UPGRADE_IMAGE_NAME global.upgrade.image.repository
UPGRADE_IMAGE_TAG global.upgrade.image.tag
GLUU_SQL_DB_DIALECT config.configmap.cnSqlDbDialect
GLUU_SQL_DB_HOST config.configmap.cnSqlDbHost
GLUU_SQL_DB_PORT config.configmap.cnSqlDbPort
GLUU_SQL_DB_NAME config.configmap.cnSqlDbName
GLUU_SQL_DB_USER config.configmap.cnSqlDbUser
GLUU_SQL_DB_PASSWORD config.configmap.cnSqldbUserPassword
GOOGLE_SERVICE_ACCOUNT_BASE64 config.configmap.cnGoogleServiceAccount
GOOGLE_SPANNER_INSTANCE_ID config.configmap.cnGoogleSpannerInstanceId
GOOGLE_SPANNER_DATABASE_ID config.configmap.cnGoogleSpannerDatabaseId
GOOGLE_PROJECT_ID config.configmap.cnGoogleProjectId
MIGRATION_ENABLED config.migration.enabled
MIGRATION_DIR config.migration.migrationDir
MIGRATION_DATA_FORMAT config.migration.migrationDataFormat
GLUU_SCIM_PROTECTION_MODE config.configmap.gluuScimProtectionMode

Note

Some of the parameters from settings.json aren't listed in list above as they are not applicable in values.yaml.

Use Couchbase solely as the persistence layer#

Requirements#

Notes

  • If you are installing on microk8s or minikube, the VM being used must at least have 8GB RAM and 2 CPU available.
  • An m5.xlarge EKS cluster with 3 nodes at the minimum or n2-standard-4 GKE cluster with 3 nodes. We advise contacting Gluu regarding production setups.

  1. Install Couchbase Operator.

  2. Configure a Couchbase cluster using custom files below (please adjust as needed):

    1. couchbase-user.yaml

    2. couchbase-group.yaml

    3. couchbase-rolebinding.yaml

    4. storageclasses.yaml

    5. couchbase-buckets.yaml

    6. couchbase-ephemeral-buckets.yaml

    7. couchbase-cluster.yaml

      Note

      • Please note the couchbase-cluster.yaml file must include at least three defined spec.servers with the labels couchbase_services: index, couchbase_services: data and couchbase_services: analytics
      • If you wish to get started fast just change the values of spec.servers.name and spec.servers.serverGroups inside couchbase-cluster.yaml to the zones of your EKS nodes and continue.

  3. Run kubectl apply command for each of YAML files mentioned above:

    kubectl apply -f <couchbase-yaml-file>

Use remote Couchbase as the persistence layer#

  • Install couchbase version 6.x.

  • Obtain the Public DNS or FQDN of the couchbase node.

  • Head to the FQDN of the couchbase node to setup your Couchbase cluster. When setting up please use the FQDN as the hostname of the new cluster.

How to expand EBS volumes#

  1. Make sure the StorageClass used in your deployment has the allowVolumeExpansion set to true. If you have used our EBS volume deployment strategy then you will find that this property has already been set for you.

  2. Edit your persistent volume claim using kubectl edit pvc <claim-name> -n <namespace> and increase the value found for storage: to the value needed. Make sure the volumes expand by checking the kubectl get pvc <claim-name> -n <namespace>.

  3. Restart the associated services

Scaling pods#

Note

When using Mircok8s substitute kubectl with microk8s.kubectl in the below commands.

To scale pods, run the following command:

kubectl scale --replicas=<number> <resource> <name>

In this case, <resource> could be Deployment or Statefulset and <name> is the resource name.

Examples:

  • Scaling oxAuth:

    kubectl scale --replicas=2 deployment oxauth

  • Scaling oxTrust:

    kubectl scale --replicas=2 statefulset oxtrust

Working with Jackrabbit#

Warning

Jackrabbit is deprecated since Gluu v4.5.2. To customize public pages, it is recommended to use ConfigMaps directly.

Services Folder / File Jackrabbit Repository Method
oxAuth /opt/gluu/jetty/oxauth/custom /repository/default/opt/gluu/jetty/oxauth/custom PULL from Jackrabbit
oxTrust /opt/gluu/jetty/identity/custom /repository/default/opt/gluu/jetty/identity/custom PULL from Jackrabbit
Casa /opt/gluu/jetty/casa /repository/default/opt/gluu/jetty/casa PULL from Jackrabbit

The above means that Jackrabbit will maintain the source folder on all replicas of a service. If one pushed a custom file to /opt/gluu/jetty/oxauth/custom at one replica all other replicas would have this file.

oxTrust --> Jackrabbit --> oxShibboleth#

Info

Gluu v4.5.2 introduces persistence-based document store to distribute Shibboleth config files generated by oxTrust to oxShibboleth.

Services Folder / File Jackrabbit Repository Method
oxTrust /opt/shibboleth-idp /repository/default/opt/shibboleth-idp PUSH to Jackrabbit
oxShibboleth /opt/shibboleth-idp /repository/default/opt/shibboleth-idp PULL from Jackrabbit

oxAuth --> Jackrabbit --> Casa#

Info

Since Gluu v4.5.2, the /etc/certs/otp_configuration.json and /etc/certs/super_gluu_creds.json files shared by oxAuth and Casa are synchronized via secrets instead of Jackrabbit.

Services Folder / File Jackrabbit Repository Method
oxAuth /etc/certs/otp_configuration.json N/A PUSH to secrets
oxAuth /etc/certs/super_gluu_creds.json N/A PUSH to secrets
Casa /etc/certs/otp_configuration.json N/A PULL from secrets
Casa /etc/certs/super_gluu_creds.json N/A PULL from secrets

svg

Note

You can use any client to connect to Jackrabbit. We assume Gluu is installed in gluu namespace

  1. Port forward Jackrabbit at localhost on port 8080

        kubectl port-forward jackrabbit-0 --namespace gluu 8080:8080

  2. Optional: If your managing VM is in the cloud you must forward the connection to the Mac, Linux or Windows computer you are working from.

        ssh -i <key.pem> -L 8080:localhost:8080 user-of-managing-vm@ip-of-managing-vm

  3. Use any filemanager to connect to Jackrabbit. Here are some examples:

    Open file manager which maybe Nautilus and find Connect to Server place the address which should be dav://localhost:8080/repository/default. By default, the username and password are admin if not changed in /etc/gluu/conf/jackrabbit_admin_password inside the pod.

    Install a WebDav client such as WinSCP. Connect using the jackrabbit address which should be http://localhost:8080/repository/default. By default, the username and password are admin if not changed in /etc/gluu/conf/jackrabbit_admmin_password inside the pod.

    Open Finder , Go then Connect to Server and place the address which should be http://localhost:8080/repository/default. By default, the username and password are admin if not changed in /etc/gluu/conf/jackrabbit_admin_password inside the pod.

Warning

Used for quick testing with Jackrabbit and should be avoided.

  1. Login to the Jackrabbit container, for example: kubectl -n gluu exec -ti jackrabbit-0 -- sh.

  2. Go to /opt/webdav directory; create any files or directory under this directory.

  3. Run python3 /app/scripts/jca_sync.py.

Working with Persistence Document Store#

Info

The new persistence-based document store (called DB) is introduced since Gluu v4.5.2.

One of the main purposes of DB document store is to replace Jackrabbit (JCA) for distributing files across the pods, i.e. copying Shibboleth files generated by oxTrust to oxShibboleth (see the table below):

oxTrust --> persistence --> oxShibboleth#

Services Folder / File Method
oxTrust /opt/shibboleth-idp PUSH to persistence
oxShibboleth /opt/shibboleth-idp PULL from persistence

Migrating from Jackrabbit#

Steps to migrate from Jackrabbit (JCA) to Persistence (DB) document store in existing installation:

  1. Change the value of gluuDocumentStoreType in override-values.yaml, for example:

    config:
  configmap:
    # previously set to JCA
    gluuDocumentStoreType: DB

    Afterwards, upgrade the Helm chart to newest version, for example: helm -n <namespace> upgrade <release-name> gluu/gluu -f override-values.yaml --version <version>.

  2. Check GLUU_DOCUMENT_STORE_TYPE env var in configmaps:

    kubectl -n <namespace> get cm <release-name>-config-cm --template={{.data.GLUU_DOCUMENT_STORE_TYPE}}

    If the value is set to JCA, change it to DB by running the following command:

    kubectl -n <namespace> patch cm <release-name>-config-cm --type json --patch '[{"op": "replace", "path": "/data/GLUU_DOCUMENT_STORE_TYPE", "value": "DB"}]'

  3. Check selected document store in oxTrust UI by navigating to Configuration > JSON Configuration > Store Provider Configuration page. Change the value of Document store Type form field from JCA to DB if needed and save configuration.

  4. Rollout restart all deployments/statefulsets to force updates.

Info

If Jackrabbit was previously used for distributing custom pages, switch to ConfigMaps approach instead.

Architectural diagram of all Gluu services#

svg

Network traffic between Gluu services#

  1. Database Access: all Gluu services require access to the database.

  2. Pod-2-Pod Communication: Gluu services communicate with each other as depicted.

  3. External/Internet Communication:

    • Oxauth: should be publically accessible.

    • Rest of the pods: We recommend to only keep the .well-known endpoints public and protect the rest.

Architectural diagram of oxPassport#

svg

Architectural diagram of Casa#

svg

Architectural diagram of SCIM#

svg

Minimum Couchbase System Requirements for cloud deployments#

Note

Couchbase needs optimization in a production environment and must be tested to suit the organizational needs.

NAME # of nodes RAM(GiB) Disk Space CPU Total RAM(GiB) Total CPU
Couchbase Index 1 3 5Gi 1 3 1
Couchbase Query 1 - 5Gi 1 - 1
Couchbase Data 1 3 5Gi 1 3 1
Couchbase Search, Eventing and Analytics 1 2 5Gi 1 2 1
Grand Total 7-8 GB (if query pod is allocated 1 GB) 20Gi 4