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.

Docker Installation#

Overview#

Note

Starting from Gluu v4.5.17, the pygluu-compose (docker-based) installer has been removed in favor of Helm chart (kubernetes-based) installer.

This guide provides an example of migrating the Gluu Server (that was installed using pygluu-compose with mysql as selected persistence) to kubernetes using Helm chart.

Pre-requisites#

  1. Prepare kubernetes cluster.

  2. Prepare MySQL database.

  3. Prepare a new Gluu Server using Helm chart manually.

    Warning

    DO NOT run helm install command before finishing the instructions below as we need to modify override-values.yaml before installing Gluu's Helm chart.

Instructions#

Before running the instructions, make sure to go the working directory (where files are generated by pygluu-compose), for example:

cd /path/to/working/directory

A typical working directory structure is shown below (some files that aren't required for the migration are omitted):

/path/to/working/directory
├── generate.json
├── settings.py
├── sql_password
├── vault_role_id.txt
├── vault_secret_id.txt

Extracting existing configuration#

  1. Open generate.json file:

    {
    "admin_pw": "Test1234#",
    "city": "Austin",
    "country_code": "US",
    "email": "support@demoexample.gluu.org",
    "hostname": "demoexample.gluu.org",
    "org_name": "Gluu",
    "state": "TX"
}

    Modify override-values.yaml file and apply values above:

    global:
  domain: "demoexample.gluu.org"        # hostname

config:
  adminPass: "Test1234#"                # admin_pw
  city: "Austin"                        # city
  countryCode: "US"                     # country_code
  email: "support@demoexample.gluu.org" # email
  orgName: "Gluu"                       # org_name
  state: "TX"                           # state

  2. Open settings.py file:

    SVC_SCIM = True
SVC_FIDO2 = True
SVC_OXSHIBBOLETH = True
DOCUMENT_STORE_TYPE = "DB"
SVC_CASA = True
SVC_CR_ROTATE = True
SVC_OXPASSPORT = True
PERSISTENCE_TYPE = "sql"
SVC_MYSQL = True
SQL_DB_DIALECT = "mysql"
# the following keys will be used for exporting persistence data
SQL_DB_NAME = "gluu"
SQL_DB_HOST = "mysql"
SQL_DB_PORT = 3306
SQL_DB_USER = "gluu"

    Modify override-values.yaml file and apply values above:

    global:
  domain: "demoexample.gluu.org"                # hostname
  gluuPersistenceType: "sql"                    # PERSISTENCE_TYPE
  scim:
    enabled: true                               # SVC_SCIM = True
  fido2:
    enabled: true                               # SVC_FIDO2 = True
  oxshibboleth:
    enabled: true                               # SVC_OXSHIBBOLETH = True
  casa:
    enabled: true                               # SVC_CASA = True
  cr-rotate:
    enabled: true                               # SVC_CR_ROTATE = True
  oxpassport:
    enabled: true                               # SVC_OXPASSPORT = True

config:
  adminPass: "Test1234#"                        # admin_pw
  city: "Austin"                                # city
  countryCode: "US"                             # country_code
  email: "support@demoexample.gluu.org"         # email
  orgName: "Gluu"                               # org_name
  state: "TX"                                   # state
  configmap:
    gluuDocumentStoreType: "DB"                 # DOCUMENT_STORE_TYPE
    cnSqlDbDialect: mysql
    cnSqlDbHost: mysql.sql.svc.cluster.local    # new MySQL host (adjust as needed)
    cnSqlDbPort: 3306                           # new MySQL port
    cnSqlDbName: gluu                           # new MySQL database name
    cnSqlDbUser: gluu                           # new MySQL database user
    cnSqldbUserPassword: Test1234#              # new MySQL user's password

Migrating persistence data#

  1. Get the password to access the persistence specified in sql_password file:

    Test1234#

  2. Dump database from mysql container:

    Note

    Adjust the SQL_DB_* placeholders using the same name found in settings.py file.

    docker exec -ti mysql mysqldump -u SQL_DB_USER -P SQL_DB_PORT -h SQL_DB_HOST -r /tmp/gluu.sql -y -c -p SQL_DB_NAME

    When prompted, enter password to access persistence.

  3. Copy the exported gluu.sql file from container to host:

    docker cp mysql:/tmp/gluu.sql ./gluu.sql

  4. Import gluu.sql into new MySQL database manually. This will create tables and seed the data.

Exporting configmaps and secrets#

  1. Create empty files as configmaps and secrets placeholders:

    touch config.json
touch secret.json

  2. Deploy container to export configmaps and secrets:

    docker run \
    --rm \
    --network "$(basename $PWD)_default" \
    -e GLUU_CONFIG_CONSUL_HOST=consul \
    -e GLUU_SECRET_VAULT_HOST=vault \
    -v ./vault_role_id.txt:/etc/certs/vault_role_id \
    -v ./vault_secret_id.txt:/etc/certs/vault_secret_id \
    -v ./config.json:/tmp/config.json \
    -v ./secret.json:/tmp/secret.json \
    gluufederation/config-init:4.5.17-1 dump \
        --config-file /tmp/config.json \
        --secret-file /tmp/secret.json

Deploy the Gluu Server#

  1. Create configmap to store config.json:

    kubernetes -n <namespace> create cm config-json --from-file=config.json

  2. Create secret to store secret.json:

    kubernetes -n <namespace> create secret generic secret-json --from-file=secret.json

  3. Modify override-values.yaml file:

    global:
  domain: "demoexample.gluu.org"                # hostname
  gluuPersistenceType: "sql"                    # PERSISTENCE_TYPE
  scim:
    enabled: true                               # SVC_SCIM = True
  fido2:
    enabled: true                               # SVC_FIDO2 = True
  oxshibboleth:
    enabled: true                               # SVC_OXSHIBBOLETH = True
  casa:
    enabled: true                               # SVC_CASA = True
  cr-rotate:
    enabled: true                               # SVC_CR_ROTATE = True
  oxpassport:
    enabled: true                               # SVC_OXPASSPORT = True

config:
  adminPass: "Test1234#"                        # admin_pw
  city: "Austin"                                # city
  countryCode: "US"                             # country_code
  email: "support@demoexample.gluu.org"         # email
  orgName: "Gluu"                               # org_name
  state: "TX"                                   # state
  configmap:
    gluuDocumentStoreType: "DB"                 # DOCUMENT_STORE_TYPE
    cnSqlDbDialect: mysql
    cnSqlDbHost: mysql.sql.svc.cluster.local    # new MySQL host (adjust as needed)
    cnSqlDbPort: 3306                           # new MySQL port
    cnSqlDbName: gluu                           # new MySQL database name
    cnSqlDbUser: gluu                           # new MySQL database user
    cnSqldbUserPassword: Test1234#              # new MySQL user's password
  # volumes for config.json and secret.json
  volumes:
    - name: config-json
      configMap:
        name: config-json
    - name: secret-json
      secret:
        secretName: secret-json
  # load config.json and secret.json
  volumeMounts:
    - name: config-json
      mountPath: /app/db/config.json
      subPath: config.json
    - name: secret-json
      mountPath: /app/db/secret.json
      subPath: secret.json

persistence:
  usrEnvs:
    normal:
      # skip adding default data
      GLUU_PERSISTENCE_IMPORT_BUILTIN_LDIF: "false"

  4. Test and install the chart:

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

    If there's no errors, proceed with installation:

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

  5. Validate the new Gluu Server installation is working as expected.

  6. Modify override-values.yaml to remove configuration for migration:

    global:
  domain: "demoexample.gluu.org"                # hostname
  gluuPersistenceType: "sql"                    # PERSISTENCE_TYPE
  scim:
    enabled: true                               # SVC_SCIM = True
  fido2:
    enabled: true                               # SVC_FIDO2 = True
  oxshibboleth:
    enabled: true                               # SVC_OXSHIBBOLETH = True
  casa:
    enabled: true                               # SVC_CASA = True
  cr-rotate:
    enabled: true                               # SVC_CR_ROTATE = True
  oxpassport:
    enabled: true                               # SVC_OXPASSPORT = True

config:
  adminPass: "Test1234#"                        # admin_pw
  city: "Austin"                                # city
  countryCode: "US"                             # country_code
  email: "support@demoexample.gluu.org"         # email
  orgName: "Gluu"                               # org_name
  state: "TX"                                   # state
  configmap:
    gluuDocumentStoreType: "DB"                 # DOCUMENT_STORE_TYPE
    cnSqlDbDialect: mysql
    cnSqlDbHost: mysql.sql.svc.cluster.local    # new MySQL host (adjust as needed)
    cnSqlDbPort: 3306                           # new MySQL port
    cnSqlDbName: gluu                           # new MySQL database name
    cnSqlDbUser: gluu                           # new MySQL database user
    cnSqldbUserPassword: Test1234#              # new MySQL user's password
  volumes: []
  volumeMounts: []

persistence:
  usrEnvs:
    normal: {}

    This step is required before running subsequent helm install or helm upgrade.

Uninstall the old Gluu Server#

Run the following command to delete all objects during the deployment:

./pygluu-compose.pyz down