Upgrade to a new minor or patch version of Astro Private Cloud

• Astronomer recommends that you upgrade through minor versions in order. Include every minor version between your current version and your target version.
• The upgrade doesn’t restart running Airflow tasks, as long as astronomer.houston.upgradeDeployments.enabled=false stays set in your upgrade command.
• A 2.x to 2.x upgrade needs no values.yaml migration script. The migration scripts in the bin/ folder of the Astronomer Helm chart apply only to the 1.x and 0.37 upgrade paths.
• This document assumes a single Helm release. If global.plane.mode is unified, that’s your whole installation. If you run a split control plane and one or more data planes (control and data mode), each is a separate Helm release with its own namespace and values.yaml, and Steps 7 through 11 apply once per release. Upgrade the control plane first, then each data plane. See Migrate from unified mode to a split control plane and data plane for what these modes mean.

​

Step 1: Read the release notes and breaking changes

• Soft delete is removed. When you delete a Deployment, APC now removes the Deployment immediately, along with its Airflow database if APC created that database. A database that APC didn’t provision is left in place.
• The default USER role no longer includes the system.workspace.create permission. Authenticated users can no longer create a Workspace without an explicit grant. If your Teams create their own Workspaces, grant system.workspace.create through a custom role or a system role assignment before you upgrade. See Start using custom roles after you upgrade to 2.1.
• Default container security contexts follow the Kubernetes Pod Security Standards Restricted profile. If you set a securityContext for a component, provide the whole block. APC doesn’t deep-merge your values with the defaults. See Configure security contexts.
• global.acme is removed. Remove it from values.yaml before you upgrade, because the strict schema validator rejects unknown keys.
• Cluster Admin permissions are folded into System Admin. Review any automation that asserts an exact permission set.
• The Airflow Operator sub-chart condition changed. The sub-chart is gated on airflow-operator.enabled first and global.airflowOperator.enabled second. If your cluster already runs a standalone Airflow Kubernetes Operator, set airflow-operator.enabled: false so that APC doesn’t install a second one.

​

Step 2: Check permissions

kubectl auth can-i create pods --namespace <your-platform-namespace>
kubectl auth can-i create sa --namespace <your-platform-namespace>
kubectl auth can-i create jobs --namespace <your-platform-namespace>

​

Step 3: Check version compatibility

​

Step 4: Get the platform Helm chart

helm repo add --force-update astronomer https://helm.astronomer.io
helm repo update

​

Step 5: Mirror the platform container images

1. Gather the list of platform images for your target version with one of the following methods:

CHART_VERSION=<v-prefixed version of the Astro Private Cloud platform chart>
UNPREFIXED_CHART_VERSION=${CHART_VERSION#v}
curl -s https://updates.astronomer.io/astronomer-software/releases/astronomer-${UNPREFIXED_CHART_VERSION}.json | jq -r '(.astronomer.images, .airflow.images) | to_entries[] | "\(.value.repository):\(.value.tag)"'| sort -u

$CHART_VERSION = "<v-prefixed version>"
$UNPREFIXED_CHART_VERSION = $CHART_VERSION.TrimStart('v')
$jsonUrl     = "https://updates.astronomer.io/astronomer-software/releases/astronomer-$UNPREFIXED_CHART_VERSION.json"
$jsonContent = Invoke-WebRequest $jsonUrl -UseBasicParsing
$json        = $jsonContent.Content | ConvertFrom-Json
$astronomerImages = $json.astronomer.images.PSObject.Properties.Value
$airflowImages    = $json.airflow.images.PSObject.Properties.Value

$images = $astronomerImages + $airflowImages

$images |
    ForEach-Object { "$($_.repository):$($_.tag)" } |
    Sort-Object -Unique

2. Copy the images into your registry with the same naming scheme that you configured at install time. See Configure the Docker registry used for platform images and Configure a custom registry for Deployment images.

​

Step 6: Back up the platform database

​

Step 7: Check that the platform is healthy

kubectl get pods -n <your-platform-namespace>
kubectl get pods -n <your-deployment-namespace>

​

Step 8: Prepare values.yaml

1. Retrieve the live platform configuration:
   helm get values <your-platform-release-name> -n <your-platform-namespace> > values.yaml
   
2. Open the file. If it contains the line USER-SUPPLIED VALUES:, delete that line.
3. Copy the file to old_values.yaml. Keep this copy in case you need to roll back.
4. Add or change the values that the release notes for your target version call for. For an upgrade to 2.1, this includes the following changes:
   • Remove global.acme.
   • Set airflow-operator.enabled: false if your cluster already runs a standalone Airflow Kubernetes Operator.
   • Set astronomer.houston.config.customRBAC.enabled: true on the control plane if you want to use custom roles. This is an APC API setting, so it belongs only in the control plane’s values.yaml — there’s no equivalent data plane change. See Start using custom roles after you upgrade to 2.1.

​

Step 9: Validate the upgrade (dry run)

helm upgrade -f ./values.yaml -n <your-platform-namespace> <your-platform-release-name> astronomer/astronomer --version <target-version> --dry-run

​

Step 10: Run the upgrade

#!/bin/bash
set -xe

# typically astronomer
RELEASE_NAME=<astronomer-platform-release-name>
# typically astronomer
NAMESPACE=<astronomer-platform-namespace>
# typically astronomer/astronomer
CHART_NAME=<chart name>
# format is v<major>.<minor>.<patch> e.g. v2.1.0
CHART_VERSION=<v-prefixed version of the Astro Private Cloud platform chart>

helm upgrade --namespace $NAMESPACE \
            -f ./values.yaml \
            --reset-values \
            --version $CHART_VERSION \
            --debug \
            --timeout 20m \
            --set astronomer.houston.upgradeDeployments.enabled=false \
            $RELEASE_NAME \
            $CHART_NAME $@

• CHART_NAME: astronomer/astronomer if you pull the chart from a Helm repository. If you install from a file, use the filename of the chart, for example astronomer-2.1.0.tgz.
• CHART_VERSION: your target APC version, including the patch number and a v prefix, for example v2.1.0.

• astronomer.houston.upgradeDeployments.enabled=false stops APC from upgrading the Airflow charts, so running Airflow tasks aren’t disturbed. You upgrade your Deployments separately in Step 12.
• --reset-values makes values.yaml the single source of truth for the release. This is why Step 8 retrieves the live values first. Without the live values in the file, --reset-values drops your current configuration.

​

Step 11: Verify the upgrade

kubectl get pods -n <your-platform-namespace>

• Sign in to the APC UI.
• See your Workspaces and Deployments.
• See metrics for a Deployment.
• Run astro deploy for an existing Deployment.
• Open the Airflow UI for a Deployment.
• Read task logs in the Airflow UI.
• Create a new Deployment that becomes healthy.

​

Step 12: Upgrade Airflow Deployments

• APC UI: Open each Deployment and trigger an upgrade.
• APC API: Use the upsertDeployment mutation for programmatic or bulk upgrades.
• Astro CLI: Use the astro deploy command.

​

Step 13: Upgrade the Astro CLI

​

Start using custom roles after you upgrade to 2.1

​

Enable custom roles

astronomer:
  houston:
    config:
      customRBAC:
        enabled: true

​

Move Teams onto custom roles

1. Create the role from an existing one. Click Create Role, then use Start from an existing role to populate the permission picker from any built-in or custom role at the same scope. Alternatively, open a built-in role and use Clone Role to make an independent copy. Both options give you the access your Teams have today.
2. Remove the permissions that the Team doesn’t need, and add any permissions the built-in role doesn’t already grant — for example system.workspace.create, which the default USER role loses in 2.1 (see the warning above).
3. Assign the new role to one Team.
4. Confirm the result on the Permission audit page, which shows what that Team can do and where the access comes from.
5. Move the remaining Teams after the first one works as expected.

• Custom roles to create, clone, edit, and assign roles.
• Permission audit to verify who has access to what.
• Role and permission reference for the permission catalog and the built-in role defaults.
• User permissions for Teams and user roles.

​

Roll back

helm rollback <your-platform-release-name> <previous-revision> --namespace <your-platform-namespace>
cp old_values.yaml values.yaml