🔁Upgrading

This document describes how to upgrade the Toucan Helm chart between breaking changes.

If you wish to consult, how to upgrade in general, you can consult this document:

🔁Upgrades and rollbacks

v1 to v2

Moving from Laputa to Garage

Context

Garage (Self-hosted S3 storage provider) is now deployed as part of the Helm Charts.

The storage is still attached to Laputa, but, you'll need to migrate the data from Laputa to Garage. Instead of doing it manually, we provide a sidecar container to transfer the data automatically.

By default, the migration is disabled.

Conditions

To check if you are affected by the migration, as an admin, run the following commands:

kubectl exec -it -n <namespace> toucan-stack-laputa-0 -c laputa -- bash

find storage/ -type f

If there are any files in the storage directory, you are affected.

Procedure

Follow the following instructions:

1. Edit the values.override.yaml to add the new secrets:

   # Run `openssl rand -hex 32` to generate a secret
   global:
     s3:
       keys:
         dataexecution:
           secret: '<random hex string with 64 characters>'
           # OR a secret:
           existingSecret:
             name: '<secretName>'
             key: 'dataexecution-secret-key'
         toucan:
           secret: '<random hex string with 64 characters>'
           # OR a secret:
           existingSecret:
             name: '<secretName>'
             key: 'toucan-secret-key'
         toucan_ro:
           secret: '<random hex string with 64 characters>'
           # OR a secret:
           existingSecret:
             name: '<secretName>'
             key: 'toucan-ro-secret-key'
   
   garage:
     secrets:
       rpc: '<random hex string with 64 characters>'
       admin: '<random hex string with 64 characters>'
   
       # OR a secret that contains the keys:
       # - garage-rpc-secret
       # - garage-admin-secret
       existingSecret: ''
   
   laputa:
     s3migration:
       enabled: true

2. Deploy the upgrade:

   helm upgrade -n <namespace> toucan-stack oci://quay.io/toucantoco/charts/toucan-stack -f ./values.override.yaml

   This will deploy the data-execution service, the s3 storage provider and change features flags on the services.

3. Check the logs of the sidecar container to see if the migration was successful. You can also check the sidecar logger container.

   # Sidecar handling the migration
   kubectl logs <pod-name> -n <namespace> -c laputa-migration-to-hades
   
   # Sidecar logger
   kubectl logs <pod-name> -n <namespace> -c tail-worker
   # Search for "copy_datasources_to_s3_job"

SpiceDB certificates are now handled internally

Context

The certificates for SpiceDB are now handled internally inside the Helm Charts instead of using extraVolumes and extraVolumeMounts.

Conditions

To check if you are affected by the migration, check the values.override.yaml, if you used extraVolumes and extraVolumeMounts with spicedb-certs for dataset, layout and laputa.

Procedure

Remove the following sections for dataset, layout and laputa in your values.override.yaml:

 dataset:
   extraVolumes:
-     - name: spicedb-certs
-       secret:
-         secretName: '{{ template "toucan-stack.spicedb.tls.secretName" . }}'
-         items:
-           - key: ca.crt
-             path: ca.crt
      - name: my-certs
        # ...
   extraVolumeMounts:
-     - name: spicedb-certs
-       mountPath: /spicedb-certs
      - name: my-certs
        # ...

Custom certificates for Laputa now requires to be mounted elsewhere

Context

Because the embedded S3 provider requires a custom certificate, the ca-certificates.crt must contain the CA certificate of the S3 provider.

Conditions

To check if you are affected by the migration, check the values.override.yaml for extraVolumes and extraVolumeMounts of laputa. If you have mounted a CA certificate for Laputa, you'll need to update the values.

If you don't update the values, Laputa won't be able to connect to the S3 provider.

Procedure

Edit the values.override.yaml to move your CA certificate:

 laputa:
   extraVolumes:
      - name: ca-bundle
        secret:
          secretName: 'my-ca-secret'
          items:
            - key: ca.crt
-             path: ca-certificates.crt
+             path: my-ca.crt
   extraVolumeMounts:
      - name: ca-bundle
-       mountPath: /etc/ssl/certs
+       mountPath: /usr/local/share/ca-certificates/my-ca.crt
+       subPath: my-ca.crt

Laputa will naturally combine the certificates.

You also need to add your CA certificates to the dataexecution service:

dataexecution:
  api:
    extraVolumes:
      - name: ca-bundle
        secret:
          secretName: 'my-ca-secret'
          items:
            - key: tls.crt
              path: my-ca.crt

    extraVolumeMounts:
      - name: ca-bundle
        mountPath: /usr/local/share/ca-certificates/my-ca.crt
        subPath: my-ca.crt

  worker:
    extraVolumes:
      - name: ca-bundle
        secret:
          secretName: 'my-ca-secret'
          items:
            - key: tls.crt
              path: my-ca.crt

    extraVolumeMounts:
      - name: ca-bundle
        mountPath: /usr/local/share/ca-certificates/my-ca.crt
        subPath: my-ca.crt