Documentation structure for LLMs (llms.txt)
CircleCI Logo

Upgrade server

11 minutes ago
Server 4.10 Server Admin

This page describes the steps needed to upgrade your CircleCI Server installation to 4.10.

Upgrade paths

Before upgrading to server 4.10, you must first upgrade to the latest patch release of server 4.9.x which is currently 4.9.4.

We recommend that you do not skip releases when upgrading, however some patch releases can be skipped. Your upgrade path will depend on your current version, and the currently available version releases.

When upgrading from one minor version to the next, ensure your upgrade path includes the last patch release for your current minor version.

To see some common upgrade path options, see this support article.

Recommendations

We have moved away from Vault to Tink for encryption. The process for migration is documented here. The migration includes a convenience script to move existing secrets.

If you are using Vault, you must complete the migration to Tink on your current installation. Complete this migration before backing up your server in preparation for upgrading to 4.10.

Customers that do not perform this step may have issues restoring Vault from backup in server 4.10.

Prerequisites

  • Ensure you have upgraded to the latest patch release of server 4.9.x which is currently 4.9.4.

  • Ensure you have access to the Kubernetes cluster in which CircleCI Server is installed.

  • Ensure you have set up Backup and Restore.

  • Ensure there is a recent backup. For more information, see the Backup and Restore guide.

  • Server 4.10 requires mongoDB 7.0 or higher. If your Mongo DB is not externalized, ensure you are running MongoDB 7.0 or higher. Follow our Upgrade MongoDB to 7.0 Guide for steps to upgrade your MongoDB instance.

Upgrade steps

  1. Ensure your cluster is running a compatible Kubernetes version for this release (1.33 - 1.35).

  2. Check the changelog and make sure there are no actions you need to take before deploying a new version.

  3. Optionally, confirm what the update is going to do using Helm Diff:

    helm diff upgrade circleci-server oci://cciserver.azurecr.io/circleci-server -n $namespace --version 4.10.0 -f <path-to-values.yaml> --username $USERNAME --password $PASSWORD

  4. Upgrade your Nomad clients and servers (if externalized) Terraform modules to the 4.10 release. Follow the documentation to plan and apply the Terraform changes for your AWS or GCP environment.

  5. Perform the upgrade:

    helm upgrade circleci-server oci://cciserver.azurecr.io/circleci-server -n $namespace --version 4.10.0 -f <path-to-values.yaml> --username $USERNAME --password $PASSWORD

  6. Deploy and run reality check in your test environment to ensure your installation is fully operational.

  7. If you have configured a custom workflow data retention period, re-apply it after upgrading. In server 4.10 the setting key changed from :wfc-workflow-deletion-retention-period to :wfc-workflow-expired-delete-after-days, and the existing value is not migrated automatically. If you leave the new key unset, workflow retention reverts to the default of 660 days. See the Data Retention in Server guide for the steps to set the new key.

  8. Migrate any existing machine runner instances from the launch agent to the machine runner 3.0 agent, see the Migration Guide. The launch agent is not supported.