Upgrade to Gluu Server 4.5#

Community Edition

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

Cloud Native Edition

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 helm.

LDAP

helm upgrade#

To upgrade your deployment, simply going over your override-values.yaml used in 4.4 and adjust it according to the 4.5 default values.yaml.

Inside your new override-values.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-values.yaml will be:

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

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.

Run helm upgrade

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

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

Couchbase

helm upgrade#

To upgrade your deployment, simply going over your override-values.yaml used in 4.4 and adjust it according to the 4.5 default values.yaml.

Inside your new override-values.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-values.yaml will be:

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

Run helm upgrade

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

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

Hybrid

helm upgrade#

To upgrade your deployment, simply going over your override-values.yaml used in 4.4 and adjust it according to the 4.5 default values.yaml.

Inside your new override-values.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-values.yaml will be:

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

Run helm upgrade

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

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

SQL

helm upgrade#

To upgrade your deployment, simply going over your override-values.yaml used in 4.4 and adjust it according to the 4.5 default values.yaml.

Inside your new override-values.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-values.yaml will be:

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

Run helm upgrade

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

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

Exporting Data#

Note

This step is not needed.

Make sure to backup existing LDAP data
Set environment variable as a placeholder for LDAP server password (for later use):
```
export LDAP_PASSWD=YOUR_PASSWORD_HERE
```

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

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

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

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

Unset LDAP_PASSWD environment variable