Upgrading instructions

Before you start upgrading

For each upgrade you need to run through the previous upgrade steps. Failing to do so may result in an incorrectly configured platform.

Upgrading from 5.1.1 to 5.2

  • As of Axual Platform 5.2, the broker image has been upgraded to 5.1.0, containing Apache Kafka 2.2.0. Please follow these instructions to upgrade.

Want to know what is new in Apache Kafka 2.2.0? Check the official release notes.

Upgrading platform-deploy

Download Axual platform for local deployment and use axual-platform-local-5-2-0/local-config/platform-deploy to upgrade your config to latest platform-deploy.

Upgrading config repo

Step 1: Add new cluster level properties

  • USE_PRINCIPAL_CHAIN : New property introduced to define if the cluster’s broker authorises using Fully Qualified principal chain or not. This property is passed to cluster-api so that it can decide which principal to use while creating ACL’s.

USE_PRINCIPAL_CHAIN=true

  • SUPERUSER_PRINCIPALS_CHAIN : Chained super user principal. Principal with the chain attached. This will get picked up when USE_PRINCIPAL_CHAIN is set to true for the cluster.

SUPERUSER_PRINCIPALS_CHAIN="[0] CN=Axual Dummy Root 2018, [1] CN=Axual Dummy Intermediate 2018 01, [2] CN=broker-su,OU=Axual,O=Axual B.V.,L=Utrecht,ST=Utrecht,C=NL"

  • DISTRIBUTION_PATTERN: Topic Pattern on which distribution ACLs require access. This is used to grant the distribution tasks produce and consumer access on the topics starting with the prefix.

Distribution ACLs are no longer added during topic apply but on startup of distribution tasks using this property.

If no value is provided the LITERAL pattern with wildcard(*) is used and distribution gets access to all topics

DISTRIBUTION_PATTERN="{tenant}-{instance}-"

Monitoring

  • DATA_DIR_MOUNTPOINT: Variable required by Prometheus, to monitor the mountpoint (NOT directory!!) our kafka "logs".

DATA_DIR_MOUNTPOINT=/appl/kafka

  • LOG_DIR_MOUNTPOINT: Variable required by Prometheus, to monitor the mountpoint (NOT directory!!) our application logs.

LOG_DIR_MOUNTPOINT=/appl/logs

Step 2: Add new instance level properties

  • DISTRIBUTION_PRINCIPAL_CHAIN : Chained distribution principal. Principal with the chain attached. This will get picked up when USE_PRINCIPAL_CHAIN is set to true for the cluster.

DISTRIBUTION_PRINCIPAL_CHAIN="[0] CN=Axual Dummy Root 2018, [1] CN=Axual Dummy Intermediate 2018 01, [2] CN=axual-local-distributor-target-client,OU=Axual B.V.,O=Axual B.V.,L=Utrecht,ST=Utrecht,C=NL"

  • SCHEMAREGISTRY_PRINCIPAL_CHAIN : Chained schema registry principal. Principal with the chain attached. This will get picked up when USE_PRINCIPAL_CHAIN is set to true for the cluster.

SCHEMAREGISTRY_PRINCIPAL_CHAIN="[0] CN=Axual Dummy Root 2018, [1] CN=Axual Dummy Intermediate 2018 01, [2] CN=axual-local-schemaregistry-client,OU=Axual B.V.,O=Axual B.V.,L=Utrecht,ST=Utrecht,C=NL"
The principal chain values and Mountpoint monitoring values provided above are for demonstration purpose only. Please update the values as per the certificates used by the components in your config.

Upgrading from 5.1 to 5.1.1

The following steps are necessary to make your "platform-config" from version 5.1 to 5.1.1.

Upgrading platform-deploy

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

Step 1: Move and rename DISCOVERYAPI_ADVERTISED_HOST

  1. Remove "DISCOVERYAPI_CLUSTER_ADVERTISED_HOST" as a cluster level config

  2. Introduce "DISCOVERYAPI_ADVERTISED_HOST" as an instance level config.

Step 2: Define DISCOVERYAPI_SERVER_SSL_PROTOCOLS

In platform-config introduce the changes as indicated below as a cluster level config:

  DISCOVERYAPI_SERVER_SSL_PROTOCOLS="+TLSv1,+TLSv1.1,+TLSv1.2"

Step 3: Update versions of following components

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

DISCOVERYAPI_VERSION=2.0.5
INSTANCEAPI_VERSION=1.3.0

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

In platform-config introduce the changes as indicated below as a cluster level config:

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