Skip to main content
Version: 1.2.0

Upgrade Guide

This guide provides step-by-step instructions to help you transition your Ansible files from earlier versions. Each section highlights specific configuration changes and the necessary actions to update your files manually.

Follow each section carefully to ensure your configuration reflects the latest structure and standards. Where applicable, this guide also includes example values and references to additional documentation to assist you with specific settings.

Updating Inventory File from CIVITAS/CORE v1.1 to v1.2​

This section will guide you through the necessary updates for transitioning your Ansible inventory file from version v1.1 to v1.2. Each section outlines specific changes along with instructions for manually updating your inventory file.

warning

Unfortunately, APISIX is not update compatible with the current helm chart used. The upgrade will fail if you run ansible with the message Forbidden: updates to statefulset spec for fields .... You can either disabled APISIX in your upgrade inventory, or remove the helm release from your cluster.

Please BACKUP your manually created routes before running the upgrade, if any.

warning

Default keycloak roles for the admin user will be added if not present any more. If you removed the roles on purpose, please make sure you remove them again after upgrading.

1. Configurable Database Ports​

Change: All database ports can now be configured individually if required.

Action: Add or update the following section in your inventory (optional, default is 5432):

inv_mngd_db:
  keycloak_postgres:
    port: "5432" # Specify the desired port for Keycloak PostgreSQL

2. Private Registry Configuration​

Change: Support for configuring a private registry for all platform container images has been added. If all the platform container images are available in a private registry, this can be configured here Naming concept resembles the harbor configuration, i.e. <project_name>/<original_docker_io_path>.

Action: Add or update the following configuration:

inv_op_stack:
  private_registry:
    enable: false # Enable if using a private registry
    # registry_username: ""
    # registry_password: ""
    # registry_url: ""
    # registry_full_url: ""
    # registry_user_email: ""

3. Default Service Configuration​

Change: All services are now disabled by default (enable is almost always set to false).

Action: Review and adjust service enablement settings as needed.

4. Dataspace Configuration​

Change: Dataspaces can now be configured/created via the inventory file. additional_dataspaces now supports to create multiple dataspaces. It is a list of dataspace names to be added to frost and stellio. All of these dataspaces will be added as private spaces.

Action: Add or update the following sections:

inv_access:
  open_data_dataspace: ds_open_data # Default name of open data space (public access)

  additional_dataspaces:
    - "additional_data_space1"
    - "additional_data_space2"

5. Removal of inv_access.group​

Change: The inv_access.group key has been removed. Use inv_access.open_data_dataspace instead.

Action: Remove inv_access.group and ensure open_data_dataspace is configured appropriately.

6. Service Portal Configuration​

Change: A service portal can now be configured as the entry page for the platform.

Action: Add the following configuration:

inv_access:
  service_portal:
    enable: false # Enable the service portal
    ns_create: true
    ns_name: "{{ ENVIRONMENT }}-access-stack"
    ns_kubeconfig: "{{ kubeconfig_file }}"
    replicas: 1
    # Set the pathes to the certificate, the CRL and the CRL in PEM format
    # Only required for self-signed certificates (e.g. for local development)
    # If set, they will be offered for download on the portal page
    certs:
      enable: false
      civitas_crt: "/workspaces/civitas-core/local_deployment/.ssl/civitas.crt"
      civitas_crl: "/workspaces/civitas-core/local_deployment/.ssl/civitas.crl"
      civitas_crl_pem: "/workspaces/civitas-core/local_deployment/.ssl/civitas.crl.pem"
    oidc:
      # If enabled, the user is logged in when accessing the portal
      enable: false
      oidc_authority: "https://idm.{{ DOMAIN }}/auth/realms/{{ ENVIRONMENT }}"
      oidc_client_id: "api-access"
      oidc_admin_role: ""
      oidc_user_role: ""
    apps:
      portainer: false # Enable if you installed a portainer instances, e.g. via local deployment

7. Frost MQTT Session Affinity​

Change: Support for configuring session affinity in Frost MQTT has been added. If you use WSL on Windows, set this to None.

Action: Add or update the following configuration:

inv_cm:
  frost:
    mqtt:
      session_affinity: "ClientIP" # Set to None for local deployment on WSL2

8. Custom Harbor Instance Configuration​

Change: Support for configuring a custom Harbor instance for container image replication. With this configuration, the images are replicated to the custom Harbor instance.

Action: Add or update the following configuration:

inv_infra:
  harbor:
    enable: false # Enable if using a custom Harbor instance
    username: ""
    password: ""
    debug: false
    base_url: ""

If you identify any additional necessary changes, please let us know.

Updating Inventory File from CIVITAS/CORE v1.0 to v1.1​

This section will walk you through the necessary updates for transitioning your Ansible inventory file from version v1.0 to v1.1. Each section highlights specific changes along with guidance for manually updating your inventory file.

1. Ingress Configuration for local deployment and custom SSL certificates​

Change: A new ingress section has been added to support local deployment of the platform. The ca_path value is set to the path to your local self-signed CA certificate (see local deployment guide for details). The http value is set to true if you want to allow HTTP access (without SSL).

Action: Add or update the following sections:

inv_k8s:
  ingress:
    ca_path: "" # Path to your local self-signed CA certificate
    http: false # Allow HTTP access (without SSL)

2. Prometheus and Grafana Storage Adjustments​

Change: Prometheus can be disabled via the inv_op_stack.prometheus section.

Action: Add or update these values:

inv_op_stack:
  prometheus:
    enable: false # Prometheus can be disabled

3. PostgreSQL Version Upgrade​

Change: PostgreSQL version is updated from 14 to 15.

Action: For all PostgreSQL configurations, update pg_version to 15:

pg_version: "15" # PostgreSQL version

4. Inventory Access and IDM Configurations​

Change: inv_access.base_domain has been removed.

Action: Remove base_domain and update values as follows:

5. APISIX and Mimir Enhancements​

Change: Added ingress_controller configuration within apisix. This allows to enable or disable the Ingress controller. For a standard CIVITAS deployment, this can be set to false. This allows to run multiple APISIX instances on the same cluster.

Action: Add the ingress_controller section within apisix:

inv_access:
  apisix:
    ingress_controller:
      enable: false # Enable or disable the Ingress controller

6. Typo in Superset variable​

Change: A typo was fixed in the variable redis_auth_password for Superset. In existing inventories this typo must be fixed, too.

Action: Change the variable redis_auth_pasword in section superset:

inv_da:
  superset:
    redis_auth_password: "yoursecretgeneratedpassword"

7. APISix Configuration​

Change: Two new configuration options have been added to APISix: enableIPv6 and volumePermissions to provide more control over network configuration and permissions.

  • enableIPv6: Controls whether APISix listens on IPv6 addresses. Enabled (true) by default, it can be set to false if IPv6 support is not required.
  • volumePermissions: Manages permissions for the etcd volume. If you encounter permission issues (e.g., on Minikube), set this to true to ensure correct permissions.

Action: Add or update the following configuration within your inventory:

inv_access:
  apisix:
    enableIPv6: true  # Enable or disable IPv6 for APISix
    etcd:
      volumePermissions: false  # Set to true if permission issues arise in your environment

8. Global Proxy Configuration​

Change: Global proxy configuration support has been introduced to ensure that containers and pods can connect to external services using the appropriate proxy settings.

Action: Add the following proxy configuration to your inventory file under the general settings:

# Proxy environment variables for accessing external resources
inv_proxy:
  http_proxy: "http://user:password@proxy:3128"
  https_proxy: "http://user:password@proxy:3128"
  no_proxy: "localhost,127.0.0.1,10.1.0.0/16,10.152.183.0/24"

9. Manual cleanup of redirect URLs in geostack client​

Change: A new installation of the V1.1 Platform has a reduced number of redirect URLs in the geostack client in keycloak. All former URLs containing .pre.{{DOMAIN}} are not needed anymore.

Action: To avoid unwanted deletions of URLs, we decided not to automate the deletion. So please login to keycloak, goto the realm, which was created for your platform and open the geostack client. On the main page, the list of redirect URLs is shown. You can delete all URLs which contain .pre.{{DOMAIN}} in the name.

Be careful if you entered additional URLs for other use cases - delete only the preones.

The standard platform only needs these:

    "https://oauth.geoportal.{{ DOMAIN }}/*",
    "https://geoportal.{{ DOMAIN }}/*"

If you find any additional necessary changes, please let us know.