Skip to content
GluuGluu
Browse Gluu Server 4.5

Release

Upgrade to 4.5

#Overview

The Gluu Server cannot be upgraded with a simple apt-get upgrade. You will need to either use our in-place upgrade script or explicitly install the new version and export/import your data. Find the existing version below for upgrade instructions to Gluu Server 4.5.

#Pre-requisites

  • Before upgrading, make sure to back up the Gluu container or LDAP LDIF.

  • Upgrades should always be thoroughly scoped and tested on a development environment first.

  • This upgrade process only upgrades versions 4.0.x through 4.5.0. To upgrade from a previous version, first upgrade to 4.0.

  • Upgrade script runs on Python 3. You need to install Python 3 before running the script.

    • On CentoOS/RHEL: yum install -y python3
    • On Ubuntu/Debian: apt-get update && apt-get install -y python3

#Online Upgrade from 4.x to 4.5.0

The upgrade script downloads all needed software and applications from the internet. You can perform an online upgrade by following these steps:

  • Download the upgrade script
wget https://raw.githubusercontent.com/GluuFederation/gluu4/refs/heads/4.5/community-edition-package/update/4.5.0/upg4xto450.py
  • Execute the script:
python3 upg4xto450.py

Your upgrade directory will be the /opt/upd/4.5.0/dist. The script will create these sub directories: app, gluu, and tmp. It also downloads latest setup files to /install/community_edition_setup_4.5.0.

#Offline Upgrade from 4.x to 4.5.0

If your machine is not open to public internet, you can download self extracting upgrade script form https://repo.gluu.org/upd/4.5-0.upg.run and you can run inside Gluu CE container as

sh 4.5-0.upg.run

The script extracts contents to /opt/upd/4.5.0/dist, and writes latest setup files to /install/community_edition_setup_4.5.0

#Minor update

If you want to perform a minor update from 4.5.x to 4.5.y, here is the procedure:

  • Backup existing oxauth.war and identity.war
    • oxauth.war location: /opt/gluu/jetty/oxauth/webapps/
    • identity.war location: /opt/gluu/jetty/identity/webapps/
  • Download oxauth 4.5.y from here
  • Download identity 4.5.y from here
  • You may download other artifacts like oxShibboleth or oxd here
  • Rename newly downloaded artifacts to oxauth.war and identity.war respectively.
  • Stop identity service: service identity stop
  • Stop oxauth service: service oxauth stop
  • Check if there are any jetty's temp directories available inside /opt/jetty-x.x/temp/
    • If you find jetty-localhost-8082-identity.war there, remove that/those directories from this temp directory
  • Same goes for jetty-localhost-8081-oxauth.war, remove them.
  • Now put newly downloaded oxuath.war and identity.war into proper location ( /opt/gluu/jetty/oxauth/webapps/ and /opt/gluu/jetty/identity/webapps/ )
  • Start oxauth and identity service
  • Test

#Overview

This guide introduces how to upgrade cloud native edition from one version to another. We support both upgrading from different versions, for example 4.4 to 4.5, or doing a patch upgrade of the same version. You can upgrade using either pygluu or helm.

#pygluu upgrade

In order to upgrade your deployment using pygluu, you have to first install and build the pygluu tool.

  1. Clone latest stable manifests.

    git clone --recursive --depth 1 --branch 4.5 https://github.com/GluuFederation/cloud-native-edition && cd cloud-native-edition/pygluu/kubernetes/templates/helm/gluu

  2. Modify all images inside main values.yaml to the latest images according to the upgrade target version. Also make sure your override.yaml other options are moved correctly to the new values.yaml.

  3. Move the old settings.json that was used in the 4.4 installation into the same directory pygluu-kubernetes.pyz exists in. The json file can be generated using ./pygluu-kubernetes.pyz generate-settings.

  4. Execute the following command:

    ./pygluu-kubernetes.pyz upgrade-values-yaml

#helm upgrade

Another way to upgrade your deployment is by simply going over your override.yaml used in 4.4 and adjust it according to the 4.5 values.yaml.

  1. Inside your new override.yaml set global.upgrade.enabled to true and global.persistence.enabled to false.

    global:
    upgrade:
        enabled: true
        sourceVersion: "4.4"
        targetVersion: "4.5"  
    persistence:
        enabled: false

    To perform a patch upgrade, where the source and target version are the same, your override.yaml will be:

        global:
        upgrade:
            enabled: true
            sourceVersion: "4.5"
            targetVersion: "4.5"  
        persistence:
            enabled: true

  2. Delete oxAuthExpiration index

    kubectl exec -ti gluu-opendj-0 -n <namespace> -- /opt/opendj/bin/dsconfig delete-backend-index --backend-name userRoot --index-name oxAuthExpiration --hostName 0.0.0.0 --port 4444 --bindDN 'cn=Directory Manager' --trustAll -f

    You will be prompted to enter the LDAP password and confirm the deletion.

  3. Run helm upgrade

    helm upgrade <helm-release-name> gluu/gluu -f override.yaml -n <namespace>

  4. Once done revert global.upgrade.enabled to false and global.persistence.enabled to true.

#pygluu upgrade

In order to upgrade your deployment using pygluu, you have to first install and build the pygluu tool.

  1. Clone latest stable manifests.

    git clone --recursive --depth 1 --branch 4.5 https://github.com/GluuFederation/cloud-native-edition && cd cloud-native-edition/pygluu/kubernetes/templates/helm/gluu

  2. Modify all images inside main values.yaml to the latest images according to the upgrade target version. Also make sure your override.yaml other options are moved correctly to the new values.yaml. For example, make sure your couchbase url, crt and other configurations are filled and correctly.

  3. Move the old settings.json that was used in the 4.4 installation into the same directory pygluu-kubernetes.pyz exists in. The json file can be generated using ./pygluu-kubernetes.pyz generate-settings.

  4. Execute the following command:

    ./pygluu-kubernetes.pyz upgrade-values-yaml

#helm upgrade

Another way to upgrade your deployment is by simply going over your override.yaml used in 4.4 and adjust it according to the 4.5 values.yaml.

  1. Inside your new override.yaml set global.upgrade.enabled to true and global.persistence.enabled to false.

    global:
    upgrade:
        enabled: true
        sourceVersion: "4.4"
        targetVersion: "4.5"  
    persistence:
        enabled: false

    To perform a patch upgrade, where the source and target version are the same, your override.yaml will be:

        global:
        upgrade:
            enabled: true
            sourceVersion: "4.5"
            targetVersion: "4.5"  
        persistence:
            enabled: true

  2. Run helm upgrade

    helm upgrade <helm-release-name> gluu/gluu -f override.yaml -n <namespace>

  3. Once done revert global.upgrade.enabled to false and global.persistence.enabled to true.

#pygluu upgrade

In order to upgrade your deployment using pygluu, you have to first install and build the pygluu tool.

  1. Clone latest stable manifests.

    git clone --recursive --depth 1 --branch 4.5 https://github.com/GluuFederation/cloud-native-edition && cd cloud-native-edition/pygluu/kubernetes/templates/helm/gluu

  2. Modify all images inside main values.yaml to the latest images according to the upgrade target version. Also make sure your override.yaml other options are moved correctly to the new values.yaml. Also make sure your override.yaml other options are moved correctly to the new values.yaml. For example, make sure your couchbase url, crt and other configurations are filled and correctly.

  3. Move the old settings.json that was used in the 4.4 installation into the same directory pygluu-kubernetes.pyz exists in. The json file can be generated using ./pygluu-kubernetes.pyz generate-settings.

  4. Execute the following command:

    ./pygluu-kubernetes.pyz upgrade-values-yaml

#helm upgrade

Another way to upgrade your deployment is by simply going over your override.yaml used in 4.4 and adjust it according to the 4.5 values.yaml.

  1. Inside your new override.yaml set global.upgrade.enabled to true and global.persistence.enabled to false.

    global:
    upgrade:
        enabled: true
        sourceVersion: "4.4"
        targetVersion: "4.5"  
    persistence:
        enabled: false

    To perform a patch upgrade, where the source and target version are the same, your override.yaml will be:

        global:
        upgrade:
            enabled: true
            sourceVersion: "4.5"
            targetVersion: "4.5"  
        persistence:
            enabled: true

  2. Run helm upgrade

    helm upgrade <helm-release-name> gluu/gluu -f override.yaml -n <namespace>

  3. Once done revert global.upgrade.enabled to false and global.persistence.enabled to true.

#pygluu upgrade

In order to upgrade your deployment using pygluu, you have to first install and build the pygluu tool.

  1. Clone latest stable manifests.

    git clone --recursive --depth 1 --branch 4.5 https://github.com/GluuFederation/cloud-native-edition && cd cloud-native-edition/pygluu/kubernetes/templates/helm/gluu

  2. Modify all images inside main values.yaml to the latest images according to the upgrade target version. Also make sure your override.yaml other options are moved correctly to the new values.yaml.

  3. Move the old settings.json that was used in the 4.4 installation into the same directory pygluu-kubernetes.pyz exists in. The json file can be generated using ./pygluu-kubernetes.pyz generate-settings.

  4. Execute the following command:

    ./pygluu-kubernetes.pyz upgrade-values-yaml

#helm upgrade

Another way to upgrade your deployment is by simply going over your override.yaml used in 4.4 and adjust it according to the 4.5 values.yaml.

  1. Inside your new override.yaml set global.upgrade.enabled to true and global.persistence.enabled to false.

    global:
    upgrade:
        enabled: true
        sourceVersion: "4.4"
        targetVersion: "4.5"  
    persistence:
        enabled: false

    To perform a patch upgrade, where the source and target version are the same, your override.yaml will be:

        global:
        upgrade:
            enabled: true
            sourceVersion: "4.5"
            targetVersion: "4.5"  
        persistence:
            enabled: true

  2. Run helm upgrade

    helm upgrade <helm-release-name> gluu/gluu -f override.yaml -n <namespace>

  3. Once done revert global.upgrade.enabled to false and global.persistence.enabled to true.

#Exporting Data

  1. Make sure to backup existing LDAP data

  2. Set environment variable as a placeholder for LDAP server password (for later use):

    export LDAP_PASSWD=YOUR_PASSWORD_HERE

  3. Assuming that existing LDAP container called ldap has data, export data from each backend:

    1. Export o=gluu

      kubectl exec -ti ldap /opt/opendj/bin/ldapsearch \
    -Z \
    -X \
    -D "cn=directory manager" \
    -w $LDAP_PASSWD \
    -p 1636 \
    -b "o=gluu" \
    -s sub \
    'objectClass=*' > gluu.ldif

    2. Export o=site

      kubectl exec -ti ldap /opt/opendj/bin/ldapsearch \
    -Z \
    -X \
    -D "cn=directory manager" \
    -w $LDAP_PASSWD \
    -p 1636 \
    -b "o=site" \
    -s sub \
    'objectClass=*' > site.ldif

    3. Export o=metric

      kubectl exec -ti ldap /opt/opendj/bin/ldapsearch \
    -Z \
    -X \
    -D "cn=directory manager" \
    -w $LDAP_PASSWD \
    -p 1636 \
    -b "o=metric" \
    -s sub \
    'objectClass=*' > metric.ldif

  4. Unset LDAP_PASSWD environment variable