Skip to main content

Upgrade Requirements

Carefully read this information before upgrading AtScale to the corresponding release.

C2024.10.0​

Manual steps required for internal PostgreSQL update​

In C2024.10.0, AtScale updated the PostgreSQL database to 16.4.0 (PostgreSQL chart 12.0.5 to 14.3.5). This change requires some manual effort on behalf of the AtScale admin when upgrading to C2024.10.0. Should you require assistance from AtScale, reach out to AtScale Support.

  1. Before upgrading, backup PostgreSQL with the following command. Note that this requires pg_dumpall to be installed. The pg_dumpall install process may be different for each OS.

    export PGPASSWORD=$(kubectl get secret -n <NAMESPACE> postgres-default-user -o json | jq -r '.data.password' | base64 -d)
    kubectl port-forward -n <NAMESPACE> svc/postgres-pgpool <DESTINATION_PORT>:10518
    pg_dumpall -h 127.0.0.1 -p <DESTINATION_PORT> -U postgres --no-password > backup.dump

    Be sure to replace <NAMESPACE> with the namespace where AtScale is installed, and <DESTINATION_PORT> with a free port on your local environment. A commonly used port is 25432.

    note

    Some warnings might appear; this is expected.

  2. The replication manager update should be enabled, and the number of replicas should be set to 1. In order to this, update values.yaml with the following:

    postgres:
        postgresql:
            replicaCount: 1
            upgradeRepmgrExtension: true

  3. Run a helm upgrade normally.

  4. On postgres-postgresql-0, there should be COLLATION ERRORS. To resolve these, connect to postgres-postgresql-0 with your preferred Database Manager (DBeaver, DataGrip, HeidiSQL, etc.) and run the following commands:

    ALTER DATABASE atscale REFRESH COLLATION VERSION;
    ALTER DATABASE keycloak REFRESH COLLATION VERSION;
    ALTER DATABASE pgwire REFRESH COLLATION VERSION;
    ALTER DATABASE postgres REFRESH COLLATION VERSION;
    ALTER DATABASE repmgr REFRESH COLLATION VERSION;
    ALTER DATABASE template1 REFRESH COLLATION VERSION;
    note

    If you need assistance connecting to postgres-postgresql-0, reach out to AtScale support.

  5. Undo the changes made in Step 2, then run helm upgrade again.

    note

    It may take some time to recreate all replicas.

Delete Kong resources after upgrading​

In C2024.10.0, the technology behind AtScale’s ingress controller changed. If you deployed AtScale using a base deployment (OOTB), Nginx will supplant Kong as the ingress controller, and the upgrade will automatically switch from Kong to Nginx.

As a result, some Kong resources will be left over. AtScale recommends that you remove these resources post-upgrade (note, however, that this is optional).

note

This recommendation assumes you have not used Kong for any application other than AtScale.

To remove the remaining Kong resources, run the following after upgrading to C2024.10.0:

kubectl delete crd $(kubectl get crd | grep konghq | awk '{print $1}')

If you added any customizations to Kong, they will likely need to be migrated to Nginx.

If you use a third party load balancer in lieu of AtScale’s ingress controller, Nginx does not need to be deployed. AtScale recommends that any deployment mimic its official Helm chart as closely as possible.

DOC-1520

Manually transition engine settings to a global settings file​

In C2024.10.0, AtScale introduced a new system for managing global settings: global_settings.yml files managed in Git, as opposed to the Settings configuration page. Although the Settings page is still available in C2024.10.0, AtScale recommends that you begin manually transitioning your existing engine settings to a global settings file. For instructions on creating and updating global settings files, see Configuring Global Settings.

ATSCALE-21925

Update calculation groups in SML​

C2024.10.0 introduced updates to the calculation_groups property in SML dimension files. After upgrading to this release, you must update any calculation groups in your dimensions to use the new syntax. Make the following changes:

  • For the calculation_groups property:

    • Change the name property to unique_name.
    • Add the label property. This property is required.

  • For the calculation_groups > calculated_members property:

    • Change the name property to unique_name.

For more information on defining calculation groups in SML, refer to the SML Object Documentation on GitHub.

ATSCALE-22943

C2024.9.0​

Update the atscale-api and atscale-engine clients​

Before upgrading to AtScale C2024.9.0, you need to update the atscale-api and atscale-engine clients with additional service account roles.

  1. In the Identity Broker, click Clients in the left-hand navigation, then click the atscale-engine client.

  2. On the Settings tab, in the Capability config section, locate the Authentication flow field and enable Service accounts roles.

  3. Click Save.

  4. Go to the Service accounts roles tab.

  5. Click Assign role, then assign the atscale-engine client following roles:

    • admin realm role
    • uma_protection client role

  6. Click Clients in the left-hand navigation and select the atscale-api client.

  7. On the Settings tab, in the Capability config section, locate the Authentication flow field and enable Service accounts roles.

  8. Click Save.

  9. Go to the Service accounts roles tab.

  10. Click Assign role and assign the atscale-api client the admin realm role.

note

If these changes are made post-upgrade, the engine and API containers need to be restarted.

DOC-1446

Update semi-additive metrics​

C2024.9.0 introduced updates to the semi_additive property in SML metric files. After upgrading to this release, you must update any semi-additive metrics in your models to use the new syntax. For the full reference for the new properties, refer to the AtScale SML Object Documentation on GitHub.

Update atscale.yml files​

In C2024.9.0, the atscale.yml file was renamed to catalog.yml, and its as_version property was renamed to version. After upgrading to this release, AtScale recommends making the following changes to the atscale.yml files in any existing models you have:

  1. Rename the files to catalog.yml.
  2. Rename their as_version properties to version.

C2024.8.0​

Resize the PostgreSQL and MinIO PVCs​

In C2024.8.0, the default sizes required for the MinIO and PostgreSQL PVCs included with AtScale increased from 16Gi to 64Gi. You must manually resize these as part of the upgrade procedure.

Note

The following procedure uses the default names for the PVCs and StatefulSets. Be sure to use the names specific to your cluster when performing these steps.

  1. Before upgrading AtScale:

    1. Ensure resizing is enabled for the PVCs:

      1. Find the PVC storage class:

        kubectl get pvc -n <namespace>

      2. Enable resizing:

        kubectl patch sc <storage_class_name> -p '{"allowVolumeExpansion": true}'

    2. Resize the PostgreSQL PVCs:

      KUBE_EDITOR="sed -i s/16Gi/64Gi/g" kubectl edit pvc -n <namespace> data-postgres-postgresql-0
      KUBE_EDITOR="sed -i s/16Gi/64Gi/g" kubectl edit pvc -n <namespace> data-postgres-postgresql-1
      KUBE_EDITOR="sed -i s/16Gi/64Gi/g" kubectl edit pvc -n <namespace> data-postgres-postgresql-2

    3. Resize the MinIO PVCs:

      KUBE_EDITOR="sed -i s/16Gi/64Gi/g" kubectl edit pvc -n <namespace> minio

    4. Delete the PostgreSQL StatefulSet:

      kubectl delete sts -n <namespace> --cascade=orphan postgres-postgresql

      PostgreSQL is a High Availability cluster and is therefore deployed as a StatefulSet. Because these don't support changes, you must delete them. Note that --cascade=orphan leaves all pods running, so you should not experience any downtime.

  2. Upgrade the AtScale chart:

    helm upgrade atscale oci://docker.io/atscaleinc/atscale --version <version> -n <namespace> -f <override_file>

    Where:

    • <version> is the version of AtScale you want to upgrade to.
    • <namespace> is the namespace in which AtScale is installed.
    • <override_file> is your values override file.

  3. Restart the pods in order to resize the mounted volume:

    kubectl rollout restart sts -n <namespace> postgres-postgresql

C2024.7.0​

Aggregate Rebuild on Upgrade Warning for IRIS Data Warehouses​

If you use InterSystems IRIS, aggregate tables will be rebuilt when you upgrade from C2024.1.1 to C2024.7.0 or later. You should plan your upgrade so that the system has time to rebuild the affected aggregates outside of business operations.

If you want to perform the upgrade without immediately rebuilding the aggregates, do the following:

  1. Before upgrading, set the custom global setting aggregate.maintenance.job.invalid-physical-plans.enabled = False and restart the engine.
  2. Perform the upgrade.
  3. When you are ready to rebuild aggregates after the upgrade, set aggregate.maintenance.job.invalid-physical-plans.enabled = True and restart the engine.

ATSCALE-21956