Upgrade

danger

Do not roll back or downgrade without consulting our support team first. Certain scenarios may necessitate restoring the database from a pre-upgrade backup due to the complexity of reversing some database migrations.

KOTS-based installation

Requirements

Preflight checks are critical for a successful installation. The following rules apply:

• ❌ Preflight Check Failures: If preflight checks fail, the upgrade must not continue until the targeted environment meets all requirements. Please reach out to our support team.
• ⚠️ Preflight Check Warnings: If preflight checks return warnings, the installation can proceed, but it is recommended that you address these warnings to comply with our recommendations.

Upgrading the GitGuardian application

caution

Prior to upgrading, ensure you back up your PostgreSQL database. For detailed instructions, refer to the Backup page.

The GitGuardian application can be updated through the KOTS Admin Console in the "Version History" tab. First, you need to check for updates. This can be done manually or automatically. Then, you can deploy a newer version by clicking the "Deploy" button.

tip

On Embedded clusters V2, updating the application through the KOTS Admin Console also upgrades the Kubernetes cluster if needed.

You can find more information on the KOTS documentation.

caution

During upgrades, workers are stopped but new commits are still queued and will be processed after the upgrade. Upgrades do not stop the dashboard, but they introduce a temporary delay in message processing and alerting. We advise running upgrades during a low-traffic period.

Upgrading the GitGuardian application in Airgap

To upgrade the KOTS admin interface, follow the installation instructions: install the latest version of the KOTS plugin of your machine, download the latest KOTS bundle and upload these images to your registry. Then, instead of running the installation command, you will need to upgrade the KOTS application running in the cluster:

kubectl kots admin-console upgrade --namespace <namespace>

If needed, specify the Kubernetes namespace with --namespace (default namespace is used if not specified).

To upgrade the GitGuardian application, first download the latest application bundle on the download portal. Then go to your KOTS Admin Console on the "Version History", and click on "Upload new version". Upload the bundle and deploy it.

Required versions

KOTS Admin Console will show some versions as "Required".

If you have several versions to upgrade, you'll have to upgrade to each required version between your current version and your target version.

After each deployment, you should wait for the application to be fully upgraded. To that extent, you can monitor pods' status and wait for all pods to be live and all jobs to be completed.

watch kubetcl get po -n <namespace>

The application is restarted when all pods are in the running status:

Every 2.0s: kubectl get po -n default             gitguardian-example: Thu Jul  4 06:11:24 2024

NAME                                      READY   STATUS      RESTARTS      AGE
beat-677d68bb9f-8f5lp                     1/1     Running     0             23m
kotsadm-56dd9b7866-cv4jc                  1/1     Running     0             30m
kotsadm-rqlite-0                          1/1     Running     0             33m
kurl-proxy-kotsadm-7cdfc47bf4-nr55l       1/1     Running     0             33m
nginx-578786cd47-6ccfh                    1/1     Running     0             23m
nginx-578786cd47-cx899                    1/1     Running     0             23m
post-deploy-f77kq                         0/1     Completed   0             23m
postgresql-0                              1/1     Running     0             29m
pre-deploy-hnpbq                          0/1     Completed   0             28m
redis-master-0                            1/1     Running     0             29m
replicated-76bff7f9bb-zb2lb               1/1     Running     0             23m
webapp-hook-5745c9995-6p7ph               1/1     Running     0             23m
webapp-internal-api-55fdd98d4d-9x25r      1/1     Running     1 (22m ago)   23m
webapp-internal-api-long-b98b68fb-x6q7s   1/1     Running     0             23m
webapp-public-api-7d4b7f8956-2jvf4        1/1     Running     0             23m
worker-email-755dd6db6b-4drhj             1/1     Running     0             23m
worker-email-755dd6db6b-6lrhc             1/1     Running     0             23m
worker-long-tasks-54875654d8-jl57k        1/1     Running     0             23m
worker-long-tasks-54875654d8-mh47g        1/1     Running     0             23m
worker-realtime-ods-7b844db9c6-6rcsl      1/1     Running     0             23m
worker-realtime-ods-7b844db9c6-hb8lq      1/1     Running     0             23m
worker-scanners-55fc98d756-mrqsx          1/1     Running     0             23m
worker-scanners-55fc98d756-rz6xz          1/1     Running     0             23m
worker-worker-85bff7dc8f-6zs98            1/1     Running     0             23m
worker-worker-85bff7dc8f-vd5vx            1/1     Running     0             23m

info

We have set a 30-days TTL (Time To Live) for pre-deploy and post-deploy jobs to allow for log retrieval if needed. It is recommended not to delete these pods, as they can be useful for troubleshooting.

Upgrading KOTS

Please remember that regular upgrades of KOTS are necessary. GitGuardian releases are thoroughly tested with the latest KOTS release. To ensure full functionality and compatibility, some features may not perform as expected on older versions of KOTS. We strongly recommend staying updated with the most recent releases.

To check the KOTS plugin version, run the following command:

kubectl kots version

If there is an update available, follow the instructions and run this command:

curl https://kots.io/install | bash

For existing cluster, you will need to upgrade the KOTS application running in the cluster:

kubectl kots admin-console upgrade -n <namespace>

For Embedded cluster V1 (kURL), simply re-run the same installation command as outlined in the installation guide.

⚠️ During the upgrade you will be prompted (possibly more than once) with a Y/N question to drain the node and apply the upgrade. You should respond with Y to continue. Because this step deletes all pods on the node, there will be some brief downtime while the upgrade happens and you should plan accordingly.

💡 If you have migrated from the legacy architecture to the new architecture, use the following command to upgrade KOTS: sudo -i; curl -sSL https://kurl.sh/gitguardian-seal | bash.

🌐 If you are using an HTTP proxy, ensure that you follow the instructions.

For further instructions on upgrading KOTS, refer to the Replicated documentation.

info

In some cases, the preflight checks may not detect the KOTS admin version change correctly, leading to failures even when using the required minimum KOTS version. To address this issue, follow these steps:

1. Navigate to the KOTS Admin Console.
2. Go to Config > Advanced Options.
3. Adjust the number of email worker replicas (for example, from 2 to 1).
4. Deploy your configuration change.
5. Click the Check for update link.
6. Run the preflight checks again.
7. Once the preflight checks are completed, revert the change by restoring the number of email worker replicas to its original value.

Upgrading Kubernetes on Embedded Cluster V1 (kURL)

To upgrade your Kubernetes version for the embedded cluster, follow these steps:

1. Simply re-run the same installation command as outlined in the installation guide.

   ⚠️ During the upgrade you will be prompted (possibly more than once) with a Y/N question to drain the node and apply the upgrade. You should respond with Y to continue. Because this step deletes all pods on the node, there will be some brief downtime while the upgrade happens and you should plan accordingly.

   💡 If you have migrated from the legacy architecture to the new architecture, use the following command to upgrade Kubernetes: sudo -i; curl -sSL https://kurl.sh/gitguardian-seal | bash.

   🌐 If you are using an HTTP proxy, ensure that you follow the instructions.

2. To verify the Kubernetes version, execute the following command:

kubectl version

Helm-based Installation

caution

Prior to upgrading, ensure you back up your PostgreSQL database. For detailed instructions, refer to the Backup page.

Upgrading to 2024.11

The 2024.11 release introduces the following breaking change:

The legacy parameter replicated.images.replicated-sdk has been replaced with two new parameters:

• replicated.image.repository
• replicated.image.tag

Be sure to update your Helm values file accordingly.

Note that the global.imageRegistry now also applies to the replicated-sdk image, meaning you need both Replicated and Gitguardian images in the private registry when you set global.imageRegistry.

Upgrading to 2024.7

The 2024.7 release brings improved consistency by standardizing the existingSecret usage across the Helm chart for Redis Sentinel, Ingress, and CustomCA, accompanied by the following breaking changes:

• Redis Sentinel

The secret keys for the password and URL have been renamed:

• From redis.main.existingSecretKeys.sentinel.password to redis.main.existingSecretKeys.sentinelPassword.

• From redis.main.existingSecretKeys.sentinel.url to redis.main.existingSecretKeys.sentinelUrl.

• Ingress

The TLS secret reference in the Ingress configuration has been renamed:

• From front.ingress.tls.secretName to front.ingress.tls.existingSecret.

• CustomCA

Adjustments to the CustomCA configuration:

• From tls.customCa.caCert to tls.customCa.caCrt.
• From tls.customCa.existingSecretCaCertKey to tls.customCa.existingSecretKeys.caCrt and set the default to "".

Make sure you update your helm value file accordingly.

Upgrading to 2024.5

The 2024.5 adds Argo CD support and includes the following breaking changes:

• TLS secrets

If you use TLS certificates for Postgresql or Redis, you need to adapt your Helm custom values by following the installation guide.

If you use an existing secret with miscEncryption.existingSecret to specify the DjangoSecretKey for example, you need to configure miscEncryption.existingSecretKeys parameters since they are left empty now by default.

You can also refer to the Helm values documentation.

• GitGuardian secret

The GitGuardian managed secret (gim-secrets) is now part of the Helm release and is no longer created during the hook phase, so you need to import the gim-secrets resource to the Helm release by running the following commands:

Remember to replace <namespace> and <your.release.name> placeholders according to your environment. Specify an existing Kubernetes namespace using the -n option. If not specified, the script will run in your default namespace.

kubectl -n <namespace> annotate secret gim-secrets meta.helm.sh/release-namespace=<namespace>
kubectl -n <namespace> annotate secret gim-secrets meta.helm.sh/release-name=<your.release.name>
kubectl -n <namespace> label secret gim-secrets app.kubernetes.io/managed-by=Helm

Run preflight checks 🚦

Requirements

Preflight checks are critical for a successful installation. The following rules apply:

• ❌ Preflight Check Failures: If preflight checks fail, the upgrade must not continue until the targeted environment meets all requirements. Please reach out to our support team if needed.
• ⚠️ Preflight Check Warnings: If preflight checks return warnings, the installation can proceed, but it is recommended that you address these warnings to comply with our recommendations.

We strongly advise you to run our preflight script to ensure your existing cluster meets Gitguardian's requirements.

Retrieve the script from our public repository here

Specify an existing Kubernetes namespace using the -n option. If not specified, the script will run in your default namespace.

./preflights.sh -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian -f local-values.yaml

Upgrading version

Log in to the registry with the following command:

helm registry login registry.replicated.com --username your.name@yourcompany.com

Upgrade the GitGuardian application to the latest version in the Kubernetes cluster and namespace where it's installed:

helm upgrade <release-name> -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian -f local-values.yaml

Replace <release-name> with the name used during the initial installation (use helm ls to find it). If needed, specify the namespace with -n (default namespace is used if not specified).

This will upgrade your application to the latest version. To upgrade to a specific version, use the --version flag:

helm upgrade <release-name> -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian --version 2024.x.y -f local-values.yaml

Updating application configuration

Modify the application configuration with an updated values file using the helm upgrade command. Stick to the same version using the --version flag:

helm upgrade <release-name> -n <namespace> oci://registry.replicated.com/gitguardian/gitguardian --version 2024.x.y -f local-values.yaml

Replace <release-name> with the name used during the initial installation (use helm ls to find it). If needed, specify the Kubernetes namespace with -n (default namespace is used if not specified).

Additional notes

• Pod update strategy

The goal is to find a balance between service continuity and available resources on the cluster. You can define which update strategy to use during an upgrade / update.

This configuration is possible for celeryWorkers (celeryWorkers.worker.updateStrategy) and webapps (webapps.app.updateStrategy).

If not defined, this default strategy applies:

• If less than 3 replicas

type: RollingUpdate
rollingUpdate:
    maxUnavailable: 50%
    maxSurge: 50%

• Else

type: RollingUpdate
rollingUpdate:
    maxUnavailable: 25%
    maxSurge: 25%