In-cluster deployment

Setting Up an AKS Cluster for PPC

This is the in-cluster deployment guide for Azure. The Azure Kubernetes Service (AKS) cluster and supporting Azure resources are provisioned by the user. The PPC installer then runs only Stage 05 (Helm releases) to deploy the application. The infrastructure is provisioned outside the installer. The cluster must therefore meet the specifications mentioned here.

Follow the prerequisites below and make sure every item matches how the cluster is created.

Deploying PPC using In-Cluster Deployment (AKS)

To deploy PPC, complete the following steps in order. Each step is described in detail in the sections below.

Before you begin

Prerequisites checklist

Before deployment, confirm that the environment meets all the prerequisites below. The installer’s readiness check validates applicable requirements before Stage 05.

Access & permissions

Verify that the required permissions are in place at each Azure scope:

Network scopes are the most common blocker. The subnet and private DNS zone are often owned by IT in a different resource group or subscription. Ask the scope owner to assign Network Contributor on the subnet and Private DNS Zone Contributor on the DNS zone. Assign both roles to the AKS managed identity. Without both, the private cluster creation fails.

Backup storage

Identities and RBAC

AKS cluster

Application node pool

Storage class

For an externally provisioned cluster, both StorageClasses required by PPC must exist before installation. Stage 05 provisions volumes using the classes named in the installer’s storage_class_name and backup_storage_class_name. Otherwise, readiness check fails and deployment cannot proceed.

Install inputs (tfvars)

Deploying PPC

After all prerequisites are met, deploy PPC by following these steps.

1. Preparing a jump box

Create a jump box or use an existing one that has network access to the AKS cluster. The jump box must be able to access the private AKS API server endpoint.

2. Downloading and extracting the release archive

To download and extract the PCT, refer to Preparing for PPC deployment.

3. Installing required tools

To install the required tools from the extracted PPC release archive, run the following command:

./bootstrap-scripts/setup-devtools-azure.sh

The script installs the following tools:

4. Logging in to Azure CLI

To authenticate with the Azure CLI, use the device code flow.

az login --use-device-code

Note: CLI login using Single Sign-On (SSO) is not supported. Use az login --use-device-code or authenticate as a Service Principal.

If more than one subscription is available, select the target subscription.

az account set --subscription <SUBSCRIPTION-ID>

5. Configuring AKS access

To retrieve the AKS credentials and configure kubectl to communicate with the cluster, run the following command:

az aks get-credentials --resource-group "<resource-group>" --name "<cluster-name>" --overwrite-existing

6. Verifying cluster connectivity

To confirm that the jump box can reach the cluster API, run the following commands:

kubectl get pods -A
kubectl get nodes

All nodes should be listed and in Ready state before proceeding.

7. Gathering values for terraform.tfvars

Complete each of the following sub-steps to populate terraform.tfvars with the required cluster-specific values.

7.1 Storage class

List the existing storage classes on the cluster and update both the storage_class_name and backup_storage_class_name values in terraform.tfvars.

kubectl get sc -A

Review the output and select only storage classes that already exist in the cluster.

• storage_class_name: Choose the storage class that will be used by PPC application workloads. This must match an existing storage class on the cluster.

• backup_storage_class_name: Choose the storage class used for backup-related volumes, such as Velero backup data. This must also match an existing storage class on the cluster.

For example, if the output shows the following:

NAME                     PROVISIONER          RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
managed-csi-premium      disk.csi.azure.com   Delete          WaitForFirstConsumer   true                   ...
managed-csi-premium-v2   disk.csi.azure.com   Delete          WaitForFirstConsumer   true                   ...

then set the values as follows:

storage_class_name        = "managed-csi-premium-v2"
backup_storage_class_name = "managed-csi-premium"

Note: Use only storage classes that are visible in the cluster output. If the selected storage class is not present, PPC deployment may fail. The workload or backup storage class is unavailable.

7.2 Pod CIDR

Retrieve the pod CIDR for the cluster and update the pod_cidr value in terraform.tfvars.

az aks show --resource-group <RESOURCE-GROUP> --name <CLUSTER-NAME> --query "networkProfile.podCidr" -o tsv

This cluster uses the required Azure CNI Overlay and Cilium networking (refer to the AKS cluster prerequisites). The command returns a populated pod CIDR, for example, 10.244.0.0/16. Set pod_cidr in terraform.tfvars to that exact value.

Note: pod_cidr must match the cluster’s network profile and must not overlap the VNet, service CIDR, or node subnet ranges.

Important: If this command returns an empty value, the cluster is not using Azure CNI Overlay. Overlay is a required, immutable prerequisite for PPC (NAP depends on it). An empty podCidr indicates the cluster was built with the wrong network configuration. Do not substitute the node subnet CIDR. Recreate the cluster with Azure CNI Overlay and Cilium as described in the AKS cluster prerequisites.

7.3 Registry credentials

When using an authenticated private registry, set harbor_secret to harbor-secret in terraform.tfvars. Export the container registry credentials before running tofu apply. Otherwise, the apply fails while pulling PPC images and charts. Leave harbor_secret empty for an unauthenticated registry.

export TF_VAR_username="<REGISTRY-USERNAME>"
export TF_VAR_password="<REGISTRY-PASSWORD>"

Note: Registry credentials are passed as environment variables (TF_VAR_username and TF_VAR_password) and are not set directly in terraform.tfvars.

7.4 Federated credentials

Set the cluster context variables and retrieve the OIDC issuer URL. Then create the Velero and OpenSearch federated credentials against this cluster’s issuer.

export CLUSTER_NAME=<CLUSTER-NAME>
export RESOURCE_GROUP=<RESOURCE-GROUP>
ISSUER="$(az aks show -g "$RESOURCE_GROUP" -n "$CLUSTER_NAME" --query "oidcIssuerProfile.issuerUrl" -o tsv)"

az identity federated-credential create \
  --name "velero-workload-identity-$CLUSTER_NAME" \
  --identity-name "<VELERO-MANAGED-IDENTITY-NAME>" \
  --resource-group "$RESOURCE_GROUP" \
  --issuer "$ISSUER" \
  --subject "system:serviceaccount:pty-backup-recovery:backup-recovery-utility" \
  --audiences "api://AzureADTokenExchange"

az identity federated-credential create \
  --name "opensearch-workload-identity-$CLUSTER_NAME" \
  --identity-name "<OPENSEARCH-MANAGED-IDENTITY-NAME>" \
  --resource-group "$RESOURCE_GROUP" \
  --issuer "$ISSUER" \
  --subject "system:serviceaccount:pty-insight:opensearch-cluster-master" \
  --audiences "api://AzureADTokenExchange"

Note: Bash variable names cannot contain hyphens. Use $RESOURCE_GROUP, not $RESOURCE-GROUP. The subject strings must be exact.

7.5 Node architecture

1. Check the architecture of the cluster nodes:

kubectl get nodes -L kubernetes.io/arch

2. Set architecture in 05_helm_releases/terraform.tfvars to match the kubernetes.io/arch values:

architecture = "arm64" # For *ps_v5 (Arm) VM sizes; use "amd64" (default) for *as_v5 / x86 sizes.

All node pools must use the same architecture. For example, Standard_D2ps_v5 system nodes and Standard_D8ps_v5 application nodes require architecture = "arm64". Readiness check 13 uses this value to select the minimum VM sizes. Leaving the default amd64 value on an arm64 cluster causes the VM size check to fail.

8. Updating terraform.tfvars

To update the terraform.tfvars file, perform the following steps:

1. Navigate to the Helm releases module directory.

cd iac/azure/cluster/modules/05_helm_releases

2. After completing Steps 7.1 through 7.5, set the following variables in 05_helm_releases/terraform.tfvars.

3. Add the following variables to terraform.tfvars before allowing Stage 05 to apply.

run_readiness_check = true
check_prev_stage    = false

These variables ensure that PPC performs a readiness check on the existing AKS environment. They skip the previous automated stage validation, since those resources were created outside the installer.

4. Save the file and exit the editor.

9. Running the readiness check

Run the readiness check script and review any reported errors. Resolve all errors before proceeding to the next step.

To run the readiness check, run the following command:

./bootstrap-scripts/readiness-helm-azure.sh

10. Applying the OpenTofu configuration

To initialize and apply the OpenTofu configuration to deploy all PPC Helm charts onto the cluster, perform the following steps:

1. Navigate to the Helm releases module directory.

cd iac/azure/cluster/modules/05_helm_releases

Important: Before running tofu plan or tofu apply, review all values in terraform.tfvars and confirm that they match the target environment.

2. To initialize, plan, and apply the OpenTofu configuration to deploy all PPC Helm charts onto the cluster, run the following commands:

    tofu init
    tofu plan          # Review the planned resources that will be created.
    tofu apply         # When prompted with "Enter a value:", type "yes".

3. To verify the resources created in this stage, run the following commands:

# Confirm nodes are Ready
kubectl get nodes

# Confirm pods are Running
kubectl get pods -A

Readiness checklist

Each readiness check maps to one or more prerequisite sections. Use this table to confirm that all applicable requirements are met. Do this before running the check.

Common problems

If the readiness check fails

The readiness check is read-only and validates the applicable requirements in the prerequisite checklist. Use the table below to find a fix for each failure. Settings marked immutable cannot be changed after cluster creation; recreate the cluster with the correct settings described in AKS cluster.

Note: A public cluster with disabled OIDC or Workload Identity, incorrect networking, and a missing system-pool taint require cluster recreation. Configure these correctly in AKS cluster before creating the cluster. A correctly configured az aks create command addresses all of these immutable requirements.