Upgrading to 2.31.0
This note describes the necessary steps to upgrade to Stellio 2.31.0
API gateway configuration
The services URLs are now fully configurable inside the api-gateway.
As part of this change the APPLICATION_SEARCH_SERVICE_URL and APPLICATION_SUBSCRIPTION_SERVICE_URL
properties must now contain the entire URL, not only the hostname.
For example:
APPLICATION_SEARCH_SERVICE_URL=my-hostname
APPLICATION_SUBSCRIPTION_SERVICE_URL=my-hostname
must now be:
APPLICATION_SEARCH_SERVICE_URL=http://my-hostname:8083
APPLICATION_SUBSCRIPTION_SERVICE_URL=http://my-hostname:8084
If you don't use one of these variables, the change will not impact you.
Migrate the current authorization setup
The new authorization system works using only the OIDC token. For existing setup, this now lets you assign permission to Keycloak roles instead of groups. It also means that a desynchronization of Stellio subjects information will no longer impact the NGSI-LD endpoints (only the subject endpoints).
New configuration properties
As a result of this change, two new configuration properties are introduced and described in the documentation:
APPLICATION_AUTHENTICATION_CLAIMS_PATHSAPPLICATION_TENANTS_0_ACCESSTOKENURL
They have default values that will work for existing deployments using Keycloak. Check and configure them if you are using a different setup.
Migrate groups permission
Warning: You should follow this migration if you have permissions targeting groups.
Existing permission targeting groups need to access the user groups ids in the token. For this we have developed a new token mapper which is present in the Keycloak images provided by us starting from version 26.5.5.
Once the keycloak image is upgraded, you can configure the token mapper to add the groups uuids in the token.
1 - Add the Groups UUID Mapper in Clients scopes > roles > Mappers > Add Mapper > by configuration
You can use the roles scope or create your own scope (make sure it is used when generating the token).
2 - Configure the mapper to add the ids behind the groups_uuids claim.
3 - Verify that the groups uuids are present in the token. (in Clients > your-client > Clients scopes > evaluate > Generated access token)
When all the realms used by Stellio have the groups_uuids claim configured, you are ready to upgrade to version 2.31.0.
Upgrade to TimescaleDB 2.25.2
The Timescale extension has been upgraded to 2.25.2. A new Docker image is available on DockerHub.
The general upgrade procedure is described in the Timescale documentation and more specifically in the Docker upgrade section.
If using the docker-compose configuration provided in the Stellio repository, the upgrade can be done in this way (remember to do a backup of the database before starting the upgrade!):
docker compose pull
docker compose up -d
docker exec -it stellio-postgres psql --host=localhost -d stellio_search -U stellio -W -X -c "ALTER EXTENSION timescaledb UPDATE;"
docker exec -it stellio-postgres psql --host=localhost -d stellio_subscription -U stellio -W -X -c "ALTER EXTENSION timescaledb UPDATE;"