Upgrading instructions

Upgrading from 5.0.0 to 5.1

In release 5.1, SSL has been introduced and enforced for both Management UI and API. Also, Management API now manages sessions in a stateless way using JWT tokens and has CSRF protection enabled. Please follow the instructions below to make sure you make use of this feature.

Upgrading Management UI and API

Step 1: preparing SSL certificates

  1. Create server SSL certificates for both Management UI and API, using the Subject Alternative Name (SAN) of UI and API location

  2. Make sure you use the following names: mgmt-ui.server.certificate.crt and mgmt-ui.server.certificate.key

  3. Place the certificate for mgmt-api and mgmt-ui in the security directory next to platform-deploy

Step 2: Update platform-config to use the certificates

Locate cluster.sh in your platform-config and introduce the changes as indicated below:

MGMT_API_URL = Update url to https
MGMT_API_SERVER_HTTP2_ENABLED = true
MGMT_API_SERVER_SSL_ENABLED = true
MGMT_API_SERVER_SSL_KEY_STORE_PASSWORD ="password"
MGMT_API_SERVER_SSL_KEY_STORE=/security/mgmt-api.server.keystore.jks
MGMT_API_SERVER_SSL_KEY_ALIAS ="keyAlias"
MGMT_API_SERVER_SSL_KEY_STORE_PASSWORD ="password"

MGMT_UI_HOST=https://your.url.to.management.ui/           - Used for the CSP header allowing resources coming the UI host
MGMT_API_HOST=https://your.url.to.management.api          - Used for the CSP header allowing resources coming the API host
MGMT_DOMAIN=your.domain                                   - This domain is used by the CSRF cookie in case that CSRF protection is enabled ( it should point out to the highest possible domain in case that UI and API are deployed to different subdomains
MGMT_API_CSRF_ENABLED=true                                - Enable CSRF check ( useful for dev environments )
MGMT_API_COOKIE_HTTPONLY=true                             - Force JWT cookie to be read only while passing it during HTTP requests and not from Javascript
MGMT_API_COOKIE_SECURE=true                               - JWT cookie is served over HTTPS

Step 3: Update cluster component versions

Locate versions.sh files for your cluster(s) inside your platform-config and update them as follows:

MGMT_UI_VERSION=3.1.0
MGMT_API_VERSION=2.1.0

Step 4: Update instance component versions

Locate versions.sh files for your instance(s) inside your platform-config and update them as follows:

INSTANCEAPI_VERSION=1.2.0

Step 5: Update platform-deploy version inside config repo

$ cd platform-deploy
$ git fetch --tags
$ git checkout 5.1.0
$ cd ..
$ git add .
$ git commit -m "Updated platform-deploy to 5.1.0"
$ git push origin branch-name

Perform manual instance assignment

As per release 5.1, instances are strictly bound to a tenant. This means that instances are now under the tenant context, and created instances will automatically fall under that tenant. Existing instances need to be linked to a tenant by setting tenant_id for all the instances in the instance table. You can find your tenant by name in the tenants table.

Tip: extracting .key and .crt files from a JKS file

If you have used keytool to generate a JKS file, you can use the following commands to extract the .key and .crt files from it.

Use the following steps to extract the .crt and .key files from the JKS:

$ keyool -importkeystore -srckeystore cert.jks -destkeystore keystore.p12 -deststoretype PKCS12
$ openssl pkcs12 -in keystore.p12 -nodes -nocerts -out mgmt-ui.server.certificate.key
$ openssl pkcs12 -in keystore.p12 -nokeys -out mgmt-ui.server.certificate.crt