Installation

• 1: Prerequisites
• 2: Preparing for PPC deployment
• 3: Deploying PPC
• 3.1: Automated script-based installation
• 3.2: Manual component-based installation
• 3.3: In-cluster deployment

1 - Prerequisites

Microsoft Azure Resource Providers

The following Microsoft Azure resource providers are registered.

• Microsoft.ContainerService
• Microsoft.Network
• Microsoft.Compute
• Microsoft.Storage
• Microsoft.KeyVault
• Microsoft.ManagedIdentity

Creating a Storage Account in Azure

An Azure Storage Account is required to store cluster backup data. The following steps guide you through creating the storage account. They also cover configuring the required blob container, provisioning a Key Vault, and assigning the necessary permissions.

1. Creating the Storage Account

Create an Azure Storage Account to serve as the backend for cluster backup and restore operations using Velero.

To create a storage account, perform the following steps:

1. Sign in to the Azure portal.
2. Navigate to Home > Storage accounts, then select Create.
3. On the Basics tab, provide the required details:
   • Subscription: The Azure subscription to bill for this resource.
   • Resource group: The logical container that groups related Azure resources.
   • Storage account name: A globally unique name using only lowercase letters and numbers.
   • Region: The Azure datacenter location where the storage account will be hosted.
   • Primary service: The primary Azure service that will use this storage account (e.g., Blob Storage, Azure Files).
   • Performance tier: Choose Standard for general-purpose workloads or Premium for low-latency requirements.
   • Redundancy option: The replication strategy for your data (e.g., LRS, GRS, ZRS).
4. Keep the default values for the remaining tabs unless a specific project requirement applies.
5. On the Review + create tab, review the configuration, then select Create.
6. After deployment completes, select Go to resource to open the newly created storage account.

Note: A blob container named velero must be created inside the storage account before installation. If the container does not exist, the installation will fail when the deployment attempts to access it.

2. Creating a container inside the storage account

Create a blob container named velero within the storage account. This container is used by Velero to store backup snapshots.

To create a container inside the storage account, perform the following steps:

1. Navigate to Home > Storage accounts, then select the required storage account.
2. In the left pane, under Data storage, select Containers.
3. Select Add Container.
4. In the New container pane, enter velero as the container name.
5. Set the anonymous access level to Private (no anonymous access).
6. Select Create, and verify that the velero container appears in the container list.

3. Creating a Key Vault

Create an Azure Key Vault to securely store the encryption keys used during cluster deployment.

To create a Key Vault, perform the following steps:

1. Navigate to Home > Key vaults, then select Create.
2. Fill out the required details in the Basics section.
3. Leave the Access configuration, Networking, and Tags sections at their default values.
4. Select Review + create, then select Create.

4. Assigning the Key Vault Administrator role

The Key Vault Administrator role must be assigned to the identity performing the installation. This role is required to create, update, and manage secrets, certificates, and keys. Those items are stored in the Key Vault used during deployment. Without this permission, the installation may fail.

Verifying current role assignments

To verify current role assignments, perform the following steps:

1. Navigate to Home > Key vaults, then select the key vault.
2. In the left pane, select Access control (IAM), then select View my access.
3. Confirm whether the Key Vault Administrator role is already assigned.

Adding the Key Vault Administrator role

To add the Key Vault Administrator role, perform the following steps:

1. In Access control (IAM), select Add role assignment.
2. Search and select Key Vault Administrator.
3. Under Members, add the required members.
4. Leave Conditions unchanged, then select Review + assign.
5. Verify that the Key Vault Administrator role is now listed for the selected key vault.

5. Adding Keys to the Key Vault

Generate an encryption key inside the Key Vault. This key is referenced during cluster installation to encrypt storage and other sensitive resources.

To add keys to the Key Vault, perform the following steps:

1. Navigate to Home > Key vaults, then select the key vault.
2. In the left pane, select Objects > Keys, then select Generate/Import.
3. Provide the required key details and complete key generation.

   Note: For the Key Vault keys, only RSA keys are supported.

Note the values for the following. They are required during cluster installation.

• Storage account name
• Key vault
• Key name

Permissions to deploy AKS

Update the following custom role permissions.

Before you begin

• Identify the resource group where the AKS cluster will be created.
• Ensure that a custom role is already created in the subscription or resource group.
• Complete this configuration before starting the AKS installation process.

To update the permission for the custom role, perform the following steps:

1. Navigate to the required resource group in the Azure portal.

2. Open Access control (IAM) for the selected resource group.

3. Locate the existing custom role.

4. Select the custom role and click Edit.

5. Select JSON and click Edit.

   Update the role by adding the following permissions:

  {
    "id": "/subscriptions/<SUBSCRIPTION-ID>/providers/Microsoft.Authorization/roleDefinitions/<ROLE-DEFINITION-ID>",
    "properties": {
        "roleName": "<ROLE-NAME>",
        "description": "",
        "assignableScopes": [
            "/subscriptions/<SUBSCRIPTION-ID>/resourceGroups/<RG-Name>"
        ],
        "permissions": [
            {
                "Actions": [
                    "Microsoft.Authorization/roleAssignments/read",
                    "Microsoft.Authorization/roleAssignments/write",
                    "Microsoft.Authorization/roleDefinitions/read",
                    "Microsoft.Authorization/roleDefinitions/write",
                    "Microsoft.ContainerService/managedClusters/read",
                    "Microsoft.ContainerService/managedClusters/write",
                    "Microsoft.KeyVault/vaults/read",
                    "Microsoft.KeyVault/vaults/write",
                    "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action",
                    "Microsoft.ManagedIdentity/userAssignedIdentities/read",
                    "Microsoft.Network/virtualNetworks/read",
                    "Microsoft.Network/virtualNetworks/subnets/join/action",
                    "Microsoft.Network/virtualNetworks/subnets/read",
                    "Microsoft.Resources/subscriptions/resourceGroups/read",
                    "Microsoft.Storage/locations/checknameavailability/read",
                    "Microsoft.Storage/storageAccounts/blobServices/containers/read",
                    "Microsoft.Storage/storageAccounts/blobServices/containers/write",
                    "Microsoft.Storage/storageAccounts/blobServices/read",
                    "Microsoft.Storage/storageAccounts/blobServices/write",
                    "Microsoft.Storage/storageAccounts/fileServices/read",
                    "Microsoft.Storage/storageAccounts/fileServices/write",
                    "Microsoft.Storage/storageAccounts/listKeys/action",
                    "Microsoft.Storage/storageAccounts/read",
                    "Microsoft.Storage/storageAccounts/write",
                    "Microsoft.Network/privateDnsZones/read",
                    "Microsoft.Network/privateDnsZones/A/read",
                    "Microsoft.Network/privateDnsZones/A/write",
                    "Microsoft.Network/privateDnsZones/write",
                    "Microsoft.Network/privateDnsZones/join/action",
                    "Microsoft.Network/privateDnsZones/virtualNetworkLinks/read",
                    "Microsoft.Network/privateDnsZones/virtualNetworkLinks/write",
                    "Microsoft.ContainerService/managedClusters/listClusterUserCredential/action",
                    "Microsoft.ContainerService/managedClusters/agentPools/read",
                    "Microsoft.ContainerService/managedClusters/agentPools/write",
                    "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials/write",
                    "Microsoft.KeyVault/vaults/read"
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ]
    }
}

6. Click Save after updating the permissions.
7. Click Review + update to finalise the changes.

Jump Box or Local Machine

A jump box serves as a secure, controlled access point for executing installation commands and managing cluster resources. It ensures that all operations originate from a trusted environment with direct network access to the PPC cluster. This avoids connectivity issues that may arise from local machines with restricted network paths or inconsistent tooling.

• Use a dedicated Debian or Red Hat jump box created in Microsoft Azure. Do not use a jump box hosted on any other cloud.

• The jump box must be provisioned in the same Azure region where the PPC cluster will be deployed. This ensures proper connectivity and access to regional resources.

  For example, if the PPC cluster is deployed in eastus, the jump box must also be created in eastus. Placing the jump box in a different region, such as westeurope, may result in network access failures. It may also cause latency issues when connecting to cluster endpoints.

Microsoft Azure Region

For automated installation

Identify the Azure region where the cluster is to be deployed.

The deployment region is automatically detected from the resource group’s location during the bootstrap process. Ensure that the resource group is created in the intended deployment region before running the installer.

All resources must be in the same region.
For more information about Microsoft Azure resources, refer to Microsoft Azure Resource IDs from Infrastructure Team.

For component-based installation

Identify the Azure region where the cluster is to be deployed.

Region must be specified as azure_location in the terraform.tfvars file during the 00_backup_storage and 02_aks_cluster stages.

All resources must be in the same region.
For more information about Microsoft Azure resources, refer to Microsoft Azure Resource IDs from Infrastructure Team.

Microsoft Azure Resource IDs from Infrastructure Team

Deployment Resource Group

Before proceeding with the installation, identify the Azure Resource Group where the cluster is to be deployed.

• For automated deployment, specify this resource group name at the input prompt when running the ./bootstrap.sh script.
• For component-based deployment, set the resource_group_name field in the terraform.tfvars files, wherever required.

The following resources are provisioned within the resource group specified during deployment.

Pre-existing Resources

The following resources must be provisioned by the IT team before installation.

They can reside in any resource group in the same region. The installer references each resource by its entire Azure resource ID.

Ensure the deploying identity, such as, service principal or managed identity, has the appropriate permissions on these resources.

AKS User-Assigned Managed Identity Permissions

The AKS User-Assigned Managed Identity (id-aks-applianceframework) must be granted a custom role with the following permissions. Grant these permissions on the resource group that contains the Private DNS Zone and Virtual Network. These permissions enable AKS to manage private DNS records and join virtual networks during cluster operations.

To configure the User-Assigned Managed Identity, perform the following steps. Use a custom Azure role that contains the permissions required for AKS deployment and management operations within the specified resource group.

1. Creating a Custom Role

1. In the Azure portal, navigate to Resource Groups.
2. Select the resource group that contains the AKS resources.
3. Open Access Control (IAM).
4. Select Add > Add custom role.
5. Provide a name and description for the custom role.
6. Select JSON and add the following permissions.

{
  "Name": "<ROLE-NAME>",
  "Description": "",
  "AssignableScopes": [
    "/subscriptions/<SUBSCRIPTION-ID>/resourceGroups/<RESOURCE-GROUP>"
  ],
  "Actions": [
    "Microsoft.Network/privateDnsZones/read",
    "Microsoft.Network/privateDnsZones/A/read",
    "Microsoft.Network/privateDnsZones/A/write",
    "Microsoft.Network/privateDnsZones/A/delete",
    "Microsoft.Network/privateDnsZones/virtualNetworkLinks/read",
    "Microsoft.Network/privateDnsZones/virtualNetworkLinks/write",
    "Microsoft.Network/privateDnsZones/virtualNetworkLinks/delete",
    "Microsoft.Network/virtualNetworks/subnets/read",
    "Microsoft.Network/virtualNetworks/subnets/join/action",
    "Microsoft.Network/privateDnsZones/write",
    "Microsoft.Network/virtualNetworks/join/action"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": []
}

7. Review the permissions and create the custom role.

Note: These permissions are required when using a private AKS cluster with a pre-existing Private DNS Zone (private_dns_zone_id). Without them, cluster provisioning and DNS resolution will fail.

2. Assigning the custom role to the Managed Identity

1. On the Azure portal, navigate to Managed Identities.

2. Select Create.

3. Specify the following:

   • Subscription
   • Resource group
   • Managed identity name
   • Region

4. Select Review + Create and then Create.

   Wait for the User-Assigned Managed Identity (UAMI) to be provisioned.

5. Open the newly created User-Assigned Managed Identity.

6. Select Azure role assignments.

7. Select Add role assignment.

8. Set the scope to the target resource group.

9. Select the custom role created in the previous section.

10. Assign the role to the User-Assigned Managed Identity.

11. Verify that the role assignment appears under the managed identity’s role assignments.

Zone Requirements

The cluster requires a minimum of two availability zones for high availability. Three-zone cluster deployments are supported and recommended for production.

Ensure the following requirements are met before deploying:

The bootstrap script does not prompt for zone selection, it uses the default three zone configuration. The default zone configuration is ["1", "2", "3"]. Not all Azure regions support three availability zones, and not all VM SKUs are available in every zone. Using a zone that does not support your VM SKU causes cluster creation to fail.

To verify the zone that is supported in the required region for PPC deployment, run the following command:

# List availability zones for your region
az account list-locations \
  --query "[?name=='<region>'].availabilityZoneMappings[].logicalZone" \
  -o table

Replace <region> with your Azure region, for example eastus.

Perform the following steps to modify the number of zones

1. Navigate to iac/azure/cluster/modules.

2. Enter the value of the supported zones in both terraform.tfvars files for 02_aks_cluster and 03_node_pool modules.

   # 02_aks_cluster/terraform.tfvars
   system_node_pool_zones = ["<value of supported zone 1>", "<value of supported zone 2>"]    # adjust to the zones your region supports
   
   # 03_node_pool/terraform.tfvars
   node_pool_zones = ["<value of supported zone 1>", "<value of supported zone 2>"]           # must match system_node_pool_zones exactly
   

   where <value of supported zone 1> and <value of supported zone 2> are the supported zones in the required Azure region.

   For more information on editing the 02_aks_cluster, and 03_node_pool modules, refer to Manual component-based installation.

Node pool sizing

The step [1b] Select Node Architecture in the bootstrap script prompts to select the node architecture interactively during deployment.

For arm64 and amd64, the following are the default system and user node pool configurations.

amd64 (x86-64)

arm64

Before creating the cluster, verify that your target Azure region provides the required availability zones. Also confirm that your subscription can launch the required VM sizes in those zones.

# System node pool SKU
az vm list-skus \
  --subscription <subscription ID> \
  --location <region>\
  --size <VM Size>\
  --output table

where

• subscription ID is the subscription ID for the Microsoft Azure account.
• <region> is the name of the region where PPC is to be deployed.
• <VM Size> is one of the supported amd64 or arm64 VM sizes listed above. Run the command once for each size. Ensure that the access to launch both, system and user node pool, are available.

A sample output is as follows:

ResourceType     Locations    Name              Zones    Restrictions
---------------  -----------  ----------------  -------  --------------
virtualMachines  eastus       Standard_D8as_v5  1,2,3    NotAvailableForSubscription type: Zone, locations: eastus zones: 3,1

where,

• Zones are the availability zones in which the VM size can be deployed. At least two zones must be available. If the Zones column is empty, then the region does not offer availability zones for that size. In such scenarios, select a different region.
• Restrictions If the value is None, no action is required. If any restriction is listed, take the relevant action before proceeding. For example, choose a different region, or request access or increase quota.

AKS cluster tier

The sku_tier setting controls the AKS API server uptime SLA, available node capacity, and supported features.

Set sku_tier = "Standard" for all production deployments. Use "Premium" if your organization requires long-term support (LTS) guarantees.

In 02_aks_cluster/terraform.tfvars, edit the following value:

sku_tier = "Standard"

For more information on editing the 02_aks_cluster module, refer to Manual component-based installation.

2 - Preparing for PPC deployment

The PCT is a pre-packaged deployment archive. It contains the infrastructure-as-code scripts, Helm charts, and bootstrap tooling. These are required to provision a PPC on your target cloud platform. It automates the creation of the Kubernetes cluster, networking, identity configuration, and installation of Protegrity microservices. Download and extract the PCT on your jump box before starting the deployment process.

Note: If there is an existing cluster from a previous install, clean up your local registry on the jump box. Also clean up any existing clusters by running ./bootstrap.sh --cloud azure destroy from /deployment before proceeding.

During installation, the system may prompt for the system password and require sign-in to Microsoft Azure. If the Azure CLI is not already logged in, the bootstrap script automatically runs az login --use-device-code. A device-code prompt similar to the following appears.

[YYYY-MM-DD HH:MM:SS] Azure CLI not logged in. Triggering az login...
To sign in, use a web browser to open the page https://login.microsoft.com/device and enter the code XXXXXXXX to authenticate.

To sign-in to Microsoft Azure, perform the following steps:

1. Open the displayed URL in a browser, and enter the code shown in the terminal.
2. Complete the SSO sign-in and follow the on-screen instructions.
3. After successful authentication, the script continues automatically.

To download and extract PCT, perform the following steps:

1. Log in to the My.Protegrity portal.

2. Navigate to Product Management > Explore Products > AI Team Edition > Platform Installation.

3. From the Actions column for Protegrity Provisioned Cluster, click the Download Product icon. This downloads the PPC 1.2 archive.

4. Create a deployment_120 directory on the jumpbox.

   mkdir deployment_120 && cd deployment_120
   

5. Copy the PCT to the deployment_120 directory on the jump box.

6. Extract the PCT.

   tar -xvf PPC-K8S-ALL_1.2.0.x.tar
   

   Note: For more information about the PCT, refer to My.Protegrity or the release notes.

3 - Deploying PPC

This section provides the steps to deploy the Protegrity Provisioned cluster (PPC) cluster. Review the prerequisites and choose the installation method that best fits your environment before you begin.

The PPC cluster can be deployed using one of the following methods:

• Automated script-based installation: This method requires the bootstrap.sh script to deploy the PPC cluster. The script installs the required software and dependencies, prompts to provide the required information, and deploys the cluster automatically.

• Manual component-based installation: This method requires to perform the deployment of each component to install the PPC cluster. The configuration files are edited to provide the required information and then deploy the cluster.

• In-cluster deployment: This method is intended for users who already have an AKS cluster provisioned and managed outside of the PPC installer. Instead of creating a new cluster, the installer deploys PPC components onto the existing cluster. Cluster details must be provided to the installer, which uses them during Stage 05 to configure and deploy the PPC Helm charts.

Note: A PPC can be deployed in regions where minimum two zones are present.

3.1 - Automated script-based installation

Before you begin

• Ensure that all the required resources are in the same resource-group. If the resources are in different resource groups, then ensure to move the resources to the same group before proceeding for PPC deployment.

• The repository provides a bootstrap script that automatically installs or updates the following tools on the jump box:

  • Azure CLI - Required to communicate with your Microsoft Azure account.
  • Helm - Required to manage Kubernetes packages.
  • jq - Required to parse JSON.
  • kubectl - Required to communicate with the Kubernetes cluster.
  • OpenTofu - Required to manage infrastructure as code.
  • oras: Required to pull non‑container, generic OCI artifacts from the registry that are not handled by standard container tooling.

Using a Standard Deployment

By default, the PCT is configured to deploy a cluster using secure settings. To deploy a standard cluster, the configuration files must be modified accordingly. For the additional configurations, refer to Configuring for a Standard Deployment.

Architecture Selection

The step [1b] Select Node Architecture in the bootstrap script prompts to select the node architecture interactively during deployment.

• amd64 (x86-64)

• arm64

The bootstrap script prompts you to select the node architecture interactively during deployment (step 1b).

Deploying the PPC

The bootstrap script prompts for variables to be set to complete the deployment. Run the following command and follow the instructions on the screen:

./bootstrap.sh --cloud azure

The script prompts for the following variables.

1. Enter AKS Cluster Name

   The following characters are allowed:

   • Lowercase letters: a-z
   • Numbers: 0-9
   • Hyphens: -

   The following characters are not allowed:

   • Uppercase letters: A-Z
   • Underscores: _
   • Spaces
   • Any special characters such as: / ? * + % ! @ # $ ^ & ( ) = [ ] { } : ; , .
   • Leading or trailing hyphens
   • The cluster name must be 40 characters or fewer

   Note: Ensure that the cluster name does not exceed 40 characters. Cluster names longer than this limit can cause the bootstrap script to fail in subsequent installation steps. If the installation fails because the cluster name exceeds the 40-character limit, correct the name and re-run the script.
   

   • Correction: Choose a cluster name with 40 characters or fewer.
     
   • Retry: Execute the installation command again with the updated name. The script will automatically handle the update and proceed with the bootstrap process.

   After the cluster name is accepted, the script prompts you to select the node architecture.

   [1b] Select Node Architecture

   [1b] Select Node Architecture
     1) amd64 (x86_64) — e.g. Standard_D8as_v5
     2) arm64 (ARM/Ampere) — e.g. Standard_D8ps_v5
   

   Enter 1 to select amd64 or 2 to select arm64.

   Note: Select amd64 for standard Intel/AMD 64-bit environments. Select arm64 for ARM-based environments such as AWS Graviton instances.

2. Querying for available Resource Groups

   The script queries for the available Resource Groups.

   Enter the Resource Group name from the table []

   The script then automatically detects the location and subscription ID of the resource group.

3. Enter UAMI Resource ID

   Provide the complete Azure resource ID for the UAMI used by AKS in the following format:

   /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
   

   The UAMI client ID is detected automatically.

4. Enter AKS Subnet Resource ID

   Provide the complete resource ID of the pre-existing subnet used for AKS nodes in the following format:

   /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/<subnet-name>
   

5. Enter Private DNS Zone Resource ID

   Provide the Private DNS zone ID used by the AKS private cluster in the following format:

   /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/privateDnsZones/privatelink.<region>.azmk8s.io
   

   The script attempts to automatically detect network settings:

   • Virtual network address space
   • Service CIDR
   • DNS service IP
   • Pod CIDR

   If the detection fails, then default values configured in the terraform.tfvars file are used.

6. Enter FQDN [name.domain.com]

   This is the Fully Qualified Domain Name for the ingress.

   Warning: Ensure that the FQDN does not exceed 50 characters and only the following characters are used:

   • Lowercase letters: a-z
   • Numbers: 0-9
   • Special characters: - .

7. Storage Account and Key Vault provisioning

   Choose whether to use existing resources or create resources:

   1) Use existing
   2) Provision new via Tofu
   

   • Enter 1 if an encrypted Storage Account and Key Vault are already provisioned for this cluster. The installer prompts for the Storage Account name, Key Vault name, backup container, Key Vault key name, and the Velero UAMI Resource ID.

   • Enter 2 to allow the installer to create a Storage Account and Key Vault with the velero container, the pty-backup-key encryption key, and a Velero UAMI automatically. Only the new resource names are required.
     a. Enter new Storage Account Name - Enter the Storage Account name. It must be globally unique, 3-24 chars, lowercase letters and digits only. b. Enter Blob Container Name - The default container is velero. Leave blank to use the default container.
     c. Enter new Key Vault Name - Enter the Key Vault name. It supports only alphanumeric and hyphen characters.

8. Enter Velero UAMI Resource ID (required)

   Enter the resource ID of the dedicated Velero User-Assigned Managed Identity (UAMI) in the format:

   /subscriptions/<subscription-id>/resourceGroups/<velero-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>
   

   The script automatically validates the UAMI and detects the UAMI Client ID.

9. Enter OpenSearch UAMI Resource ID (required)

   Enter the resource ID of the OpenSearch Velero User-Assigned Managed Identity (UAMI) in the format:

   /subscriptions/<subscription-id>/resourceGroups/<opensearch-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>
   

   The script automatically validates the UAMI and detects the UAMI Client ID.

10. Enter Image Registry Endpoint

    Enter <Container_Registry_Path>, the container registry endpoint from where the container images are retrieved.

    Note: If deploying from the Protegrity Container Registry, use registry.protegrity.com:9443. Specify the local registry endpoint if a local registry is used.

    Expected format: <hostname>[:port].

    Do not include ‘https://’

11. Enter Registry Username

    Enter the username for the registry mentioned in the previous step. Leave this entry blank if the registry does not require authentication.

12. Enter Registry Password or Access Token

    Enter Password or Access Token for the registry.

    Input is masked with * characters. Press Enter to keep the current value.

    Leave this entry blank if the registry does not require authentication.

13. Enter Owner Email (for cluster tagging)

    Enter email address in the format name@domain.tld. This email is used for the cluster ‘Owner’ tag and the platform owner contact.

    Note: The cluster creation process can take 10-15 minutes.

    If the session is terminated during installation due to network issues, power outage, and so on, then the installation stops. To restart the installation, run the script again:

    # Navigate to setup directory 
    ./bootstrap.sh --cloud azure
    

After the bootstrap script is completed, verify the cluster and workloads using the following commands:

# Confirm nodes are Ready
kubectl get nodes

# Confirm PPC workloads are Running
kubectl get pods -A

Configuring for a Standard Deployment

Note: The following instructions are optional and only required for configuring a standard PPC deployment on Azure. Skip these steps if you have already installed the secure settings.

By default, the PCT is configured to deploy a cluster using secure settings. To deploy a standard cluster, the configuration files must be modified.

The following files require changes:

For a standard PPC deployment on Azure AKS, perform the following steps:

1. Ensure that you have downloaded and extracted the PCT. For more information, refer to Preparing for PPC deployment.

2. Update the settings in the AKS Cluster Module.

a. Navigate to the 02_aks_cluster module.

cd iac/azure/cluster/modules/02_aks_cluster/

b. Edit the terraform.tfvars file. Locate the fips_enabled parameter and set it to false.

fips_enabled                  = false

c. Save the file and exit the editor.

3. Update the settings in the Node Pool Module.

a. Navigate to the 03_node_pool module.

cd iac/azure/cluster/modules/03_node_pool/

b. Edit the terraform.tfvars file. Locate the fips_enabled parameter and set it to false.

fips_enabled                  = false

c. Save the file and exit the editor.

4. After completing all these configuration changes, proceed to deploy the cluster.

Note: The steps provided here update the security settings during installation. When following the installation method, do not revert or overwrite the values configured in this section. Keep fips_enabled set to false in 02_aks_cluster and 03_node_pool.

3.2 - Manual component-based installation

This section is intended for enterprise customers who need full control over each stage of the AKS cluster deployment. Use this path when individual infrastructure stages must be reviewed or approved separately. Also use it when integration with an existing CI/CD pipeline is required. Use it when corporate change-management controls prevent running an all-in-one automated script. Each stage is self-contained and can be executed by different teams on the same jump box.

Review the Deploying PPC section to override settings for high availability, data safety, and security compliance before running tofu apply.

Note: If you are performing a standard deployment, ensure you completed Configuring PPC for a Standard Deployment before proceeding. Do not revert fips_enabled to true when performing the following steps.

Deploying PPC using component-based installation

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

Before you begin

Ensure to have the following prerequisites before proceeding with the installation.

Access and permissions

Required Roles

The Azure principal must have AKS cluster admin access.

The required Azure RBAC Roles are listed in the following table:

Deployment Resource Group

All resources created by the installer are provisioned in a single Azure resource group. Specify this group using resource_group_name in each terraform.tfvars file. This resource group must exist before running the installer.

The following resources are created inside this resource group.

Values to collect before starting

Gather the following values before populating each stage terraform.tfvars in Step 5.

Optional: Using a Standard Deployment

By default, the PCT is configured to deploy a cluster using secure settings. To deploy a standard cluster, the configuration files must be modified accordingly. For the additional configurations, refer to Configuring for a Standard Deployment.

Deploying PPC

To deploy PPC using component-based installation, perform the following 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. Authenticating with Azure CLI

To authenticate with the Azure CLI on the jump box, run the following command:

az login
az account show

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

Ensure the target subscription, resource group, managed identities, subnet, and private DNS zone are accessible before continuing.

3. Downloading and extracting the release PCT

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

4. Installing required tools

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

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

5. Provisioning backup storage and key vault

This is an optional step.

Note: Skip this step if an Azure Storage Account, backup container, Key Vault, and key already exist for this cluster. Note these values. They will be needed in next steps.

1. Navigate to the 00_backup_storage directory.

export PPC_DEPLOY_DIR=<path to PPC deployment directory>
cd "$PPC_DEPLOY_DIR/iac/azure/cluster/modules/00_backup_storage"

2. Open terraform.tfvars and fill in the required values.

    resource_group_name    = "<resource-group-name>"
    aks_cluster_name       = "<cluster-name>"
    storage_account_name   = "<storage-account-name>"
    storage_container_name = "velero"
    key_vault_name         = "<key-vault-name>"
    key_name               = "pty-backup-key"

    azure_subscription_id = "<subscription-id>"
    azure_location        = "<region>"        # e.g. eastus

3. Save the file and exit the editor.

4. To apply the terraform configuration, run the following command:

    tofu init
    tofu plan          # review the proposed changes before applying
    tofu apply         # when prompted with "Enter a value:", type "yes"

5. Note the Storage Account, container, Key Vault, and key values for future steps.

6. Filling in each module’s terraform.tfvars

Each module under iac/azure/cluster/modules/ contains its own terraform.tfvars file. There is no single shared configuration file. The terraform.tfvars file in every module must be updated before running the deployment.

Verify that the following values are the same across all modules:

• resource_group_name
• aks_cluster_name
• azure_subscription_id
• storage_account_name
• storage_container_name

01_identity module

This stage creates RBAC role assignments for the pre-existing User-Assigned Managed Identities (UAMIs) required by AKS, Velero, and OpenSearch.

To update the 01_identity module, perform the following steps:

a. Navigate to the iac/azure/cluster/modules/01_identity/ directory.

    export PPC_DEPLOY_DIR=<path to PPC deployment directory>
    cd "$PPC_DEPLOY_DIR/iac/azure/cluster/modules/01_identity/"

b. Edit the terraform.tfvars file to provide the required values.

    # -------------------------------------------------
    # Common (backend + provider — same value in all stages)
    # -------------------------------------------------
    resource_group_name    = "<resource-group-name>" # e.g. "aks-rg-prod"
    aks_cluster_name       = "<cluster-name>" # e.g. "prod-aks-cluster"
    azure_subscription_id  = "<subscription-id>" # e.g. "1e9ef7b6-cdc4-4a6b-98f7-a408ac1e19e0"
    storage_account_name   = "<storage-account-name>" # e.g. "myclusterstateaccount"
    storage_container_name = "velero"

    # -------------------------------------------------
    # Pre-existing managed identities (provided by IT)
    # -------------------------------------------------
    uami_id = "</subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>>"

    velero_uami_id = "</subscriptions/<subscription-id>/resourceGroups/<velero-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<velero-managed-identity-name>>" # required  

    opensearch_uami_id = "</subscriptions/<subscription-id>/resourceGroups/<opensearch-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<opensearch-managed-identity-name>>" # required

    # -------------------------------------------------
    # Key Vault (leave empty to skip KV role assignment)
    # -------------------------------------------------
    key_vault_name = "<key-vault-name>" # e.g. "my-key-vault"

c. Save the file and exit the editor.

d. To initialize, plan, and apply the changes, run the following commands:

    tofu init
    tofu plan          # review the proposed changes before applying
    tofu apply         # when prompted with "Enter a value:", type "yes"

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

• Verify Resources:
• AKS UAMI
• Velero UAMI
• OpenSearch UAMI

az identity show \
  --ids "<uami-resource-id>" \
  --query principalId \
  --output tsv

az role assignment list \
  --assignee "<aks-uami-principal-id>" \
  --output table

az identity show \
  --ids "<velero-uami-resource-id>" \
  --query principalId \
  --output tsv

az role assignment list \
  --assignee "<velero-uami-principal-id>" \
  --output table

az identity show \
  --ids "<opensearch-uami-resource-id>" \
  --query principalId \
  --output tsv

az role assignment list \
  --assignee "<opensearch-uami-principal-id>" \
  --output table

02_aks_cluster module

This stage provisions the private AKS cluster with a system node pool. It configures networking using Azure CNI Overlay and Cilium, and enables Workload Identity. It also creates federated identity credentials for Velero and OpenSearch.

To update the 02_aks_cluster module, perform the following steps:

a. Navigate to the iac/azure/cluster/modules/02_aks_cluster/ directory.

   export PPC_DEPLOY_DIR=<path to PPC deployment directory>
   cd "$PPC_DEPLOY_DIR/iac/azure/cluster/modules/02_aks_cluster/"

Note (standard deployment): If you are deploying a standard cluster, ensure fips_enabled remains false. For more information, refer to Configuring PPC for a Standard Deployment. Do not change this value to true.

b. Edit the terraform.tfvars file to provide the required values.

    # -------------------------------------------------
    # Common (backend + provider — same value in all stages)
    # -------------------------------------------------
    resource_group_name    = "<resource-group-name>" # e.g. "aks-rg-prod"
    aks_cluster_name       = "<cluster-name>" # e.g. "prod-aks-cluster"
    azure_subscription_id  = "<subscription-id>" # e.g. "1e9ef7b6-cdc4-4a6b-98f7-a408ac1e19e0"
    storage_account_name   = "<storage-account-name>" # e.g. "myclusterstateaccount"
    storage_container_name = "velero"

    # -------------------------------------------------
    # Identity (UAMI for kubelet and federated credentials)
    # -------------------------------------------------
    uami_id            = "</subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>>" # full UAMI resource ID (same as Stage 01)
    velero_uami_id     = "</subscriptions/<subscription-id>/resourceGroups/<velero-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<velero-managed-identity-name>>" # full Velero UAMI resource ID (for federated credential)
    opensearch_uami_id = "</subscriptions/<subscription-id>/resourceGroups/<opensearch-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<opensearch-managed-identity-name>>" # full OpenSearch UAMI resource ID (for federated credential)

    # -------------------------------------------------
    # Cluster
    # -------------------------------------------------
    azure_location      = "<region>" # e.g. "eastus"  (auto-detected from resource group)
    subnet_id           = "</subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/<subnet-name>>" # e.g. "/subscriptions/.../subnets/snet-aks-applianceframework"
    private_dns_zone_id = "</subscriptions/<subscription-id>/resourceGroups/<dns-resource-group>/providers/Microsoft.Network/privateDnsZones/privatelink.eastus.azmk8s.io>" # e.g. "/subscriptions/.../privateDnsZones/privatelink.eastus.azmk8s.io"

    # -------------------------------------------------
    # Networking (service CIDR + DNS IP)
    # -------------------------------------------------
    service_cidr   = "<10.0.0.0/16>" # auto-derived by updatevartf.sh (non-overlapping with the VNet)
    dns_service_ip = "<10.220.0.10>" # auto-derived: the .10 host of the chosen service_cidr
    pod_cidr       = "<10.0.0.0/16>" # auto-derived: non-overlapping with the VNet and service_cidr

    # -------------------------------------------------
    # System node pool
    # -------------------------------------------------
    architecture                  = "amd64" # amd64 or arm64
    system_node_pool_vm_size      = ""      # leave empty to auto-select based on architecture
    system_node_pool_node_count   = 2
    system_node_pool_disk_size_gb = 50
    system_node_pool_os_sku       = "AzureLinux"
    system_node_pool_zones        = ["1", "2", "3"]
    fips_enabled                  = true # set false for a non-FIPS node OS image (immutable)

    # -------------------------------------------------
    # Ownership / tagging
    # -------------------------------------------------
    owner_email                   = "<name@domain.tld>" # optional; blank = auto-detect from the Azure CLI identity

c. Save the file and exit the editor.

d. To initialize, plan, and apply the changes, run the following commands:

    tofu init
    tofu plan          # review the proposed changes before applying
    tofu apply         # when prompted with "Enter a value:", type "yes"

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

# Confirm the AKS cluster is in Succeeded state
az aks show --name <cluster-name> --resource-group <resource-group> \
  --query "{Name:name, State:provisioningState, Version:kubernetesVersion, Fqdn:privateFqdn}" \
  --output table

A sample output is displayed below:

Name              State      Version    Fqdn
----------------  ---------  ---------  -----------------------------------------------
<cluster-name>    Succeeded  1.35       <cluster-name>.privatelink.<region>.azmk8s.io

# Verify kubectl can reach the cluster
kubectl get nodes    # expect 2 system nodes in Ready state

# Verify federated credentials exist
az identity federated-credential list \
  --identity-name <velero-uami-name> \
  --resource-group <velero-uami-resource-group> --output table

az identity federated-credential list \
  --identity-name <opensearch-uami-name> \
  --resource-group <opensearch-uami-resource-group> --output table

03_node_pool module

This stage creates a user-managed node pool for application workloads. Node Auto Provisioning (NAP) handles autoscaling; no cluster autoscaler is configured on this pool.

To update the 03_node_pool module, perform the following steps:

a. Navigate to the iac/azure/cluster/modules/03_node_pool/ directory.

   export PPC_DEPLOY_DIR=<path to PPC deployment directory>
   cd "$PPC_DEPLOY_DIR/iac/azure/cluster/modules/03_node_pool/"

Note (standard deployment): If you are deploying a standard cluster, ensure fips_enabled remains false as configured in Configuring PPC for a Standard Deployment. Do not change this value to true.

b. Edit the terraform.tfvars file to provide the required values.

    # -------------------------------------------------
    # Common (backend + provider — same value in all stages)
    # -------------------------------------------------
    resource_group_name    = "<resource-group-name>" # e.g. "aks-rg-prod"
    aks_cluster_name       = "<cluster-name>" # e.g. "prod-aks-cluster"
    azure_subscription_id  = "<subscription-id>" # e.g. "1e9ef7b6-cdc4-4a6b-98f7-a408ac1e19e0"
    storage_account_name   = "<storage-account-name>" # e.g. "myclusterstateaccount"
    storage_container_name = "velero"

    # -------------------------------------------------
    # Node pool
    # -------------------------------------------------
    subnet_id              = "</subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/<subnet-name>>"      # same subnet as AKS nodes (Stage 02)
    architecture           = "amd64" # amd64 or arm64
    vm_size                = ""      # leave empty for architecture default
    node_pool_disk_size_gb = 120
    node_pool_desired_size = 3
    node_pool_zones        = ["1", "2", "3"]
    fips_enabled           = true # set false for a non-FIPS node OS image (immutable)

c. Save the file and exit the editor.

d. To initialize, plan, and apply the changes, run the following commands:

    tofu init
    tofu plan          # review the proposed changes before applying
    tofu apply         # when prompted with "Enter a value:", type "yes"

Expected time for this stage is approximately 5 to 10 minutes for node pool provisioning.

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

# Confirm the user node pool exists and is Succeeded
az aks nodepool show --cluster-name <cluster-name> \
  --resource-group <resource-group> --name userpool \
  --query "{Name:name, State:provisioningState, Count:count, VmSize:vmSize, OsSku:osSku}" \
  --output table

A sample output is displayed below:

Name      State      Count    VmSize      OsSku
--------  ---------  -------  ----------  ----------
userpool  Succeeded  <count>  <vm-size>   AzureLinux

# Verify all nodes are Ready (system + user nodes)
kubectl get nodes -o wide

# Confirm user pool nodes have the expected label
kubectl get nodes -l agentpool=userpool

04_aks_addons module

This stage creates the default and backup Kubernetes storage classes using Azure Managed Disks (Premium LRS). It also removes the built-in default storage class annotation.

To update the 04_aks_addons module, perform the following steps:

a. Navigate to the iac/azure/cluster/modules/04_aks_addons/ directory.

   export PPC_DEPLOY_DIR=<path to PPC deployment directory>
   cd "$PPC_DEPLOY_DIR/iac/azure/cluster/modules/04_aks_addons/"

b. Edit the terraform.tfvars file to provide the required values.

    # -------------------------------------------------
    # Common (backend + provider — same value in all stages)
    # -------------------------------------------------
    resource_group_name    = "<resource-group-name>" # e.g. "aks-rg-prod"
    aks_cluster_name       = "<cluster-name>" # e.g. "prod-aks-cluster"
    azure_subscription_id  = "<subscription-id>" # e.g. "1e9ef7b6-cdc4-4a6b-98f7-a408ac1e19e0"
    storage_account_name   = "<storage-account-name>" # e.g. "myclusterstateaccount"
    storage_container_name = "velero"

    # -------------------------------------------------
    # Storage classes (must match Stage 05's terraform.tfvars)
    # -------------------------------------------------
    storage_class_name        = "<storage-class-name>"
    backup_storage_class_name = "<backup-storage-class-name>"

c. Save the file and exit the editor.

d. To initialize, plan, and apply the changes, run the following commands:

    tofu init
    tofu plan          # review the proposed changes before applying
    tofu apply         # when prompted with "Enter a value:", type "yes"

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

# List storage classes and confirm ebs-sc is the default
kubectl get storageclass

# Verify ebs-sc details
kubectl describe storageclass ebs-sc

# Confirm the built-in 'default' storage class is no longer the default
kubectl get storageclass default -o jsonpath='{.metadata.annotations.storageclass\.kubernetes\.io/is-default-class}'
# expected output: empty or "false"

A sample output is displayed below:

storage_class_names = {
  "backup" = "ebs-bkp"
  "default" = "ebs-sc"
}

05_helm_releases module

This stage deploys all application Helm charts and configures Velero backup with the Azure plugin. It also bootstraps the NFA platform and Insight analytics stack.

To update the 05_helm_releases module, perform the following steps:

a. Navigate to the iac/azure/cluster/modules/05_helm_releases/ directory.

   export PPC_DEPLOY_DIR=<path to PPC deployment directory>
   cd "$PPC_DEPLOY_DIR/iac/azure/cluster/modules/05_helm_releases/"

b. Run the following commands and note the values:

# Get the Velero Client ID
az identity show \
  --name <velero-managed-identity-name> \
  --resource-group <resource-group-name> \
  --query clientId \
  -o tsv

# Get the OpenSearch Client ID
az identity show \
  --name <opensearch-managed-identity-name> \
  --resource-group <resource-group-name> \
  --query clientId \
  -o tsv

c. Edit the terraform.tfvars file to provide the required values.

Important: The value for harbor_secret field must always be harbor-secret.

Note: If deploying from the Protegrity Container Registry, use registry.protegrity.com:9443. Specify the local registry endpoint if a local registry is used.

    # -------------------------------------------------
    # Common (backend + provider — same value in all stages)
    # -------------------------------------------------
    resource_group_name    = "<resource-group-name>" # e.g. "aks-rg-prod"
    aks_cluster_name       = "<cluster-name>" # e.g. "prod-aks-cluster"
    azure_subscription_id  = "<subscription-id>" # e.g. "1e9ef7b6-cdc4-4a6b-98f7-a408ac1e19e0"
    storage_account_name   = "<storage-account-name>" # e.g. "myclusterstateaccount"
    storage_container_name = "velero"
    check_prev_stage       = true # set false to skip verifying Stage 04 was applied before Stage 05
    
    # -------------------------------------------------
    # Storage classes (must match Stage 04's terraform.tfvars)
    # -------------------------------------------------
    storage_class_name        = "<storage-class-name>"
    backup_storage_class_name = "<backup-storage-class-name>"
    
    # -------------------------------------------------
    # Networking
    # -------------------------------------------------
    subnet_id    = "</subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/<subnet-name>>" # same subnet as Stages 02/03 (for VNet address space lookup)
    pod_cidr     = ""  # optional override; empty = auto-detected from the live AKS network profile
    architecture = "amd64" # amd64 or arm64
    node_os      = "AzureLinux_FIPS" # should mirror stage-03 user node pool os_sku + fips_enabled
    node_pool_name = "<node-pool-name>" # must match node_pool_name in Stage 03's terraform.tfvars

    # -------------------------------------------------
    # Registry
    # -------------------------------------------------
    global_image_reg = "<Container_Registry_Path>"
    harbor_secret    = "harbor-secret"
    ingress_fqdn     = "<FQDN>" # e.g. "apps.example.com"

    # -------------------------------------------------
    # Ownership / tagging
    # -------------------------------------------------
    owner_email = "<name@domain.tld>" # optional; blank = auto-detect from the Azure CLI identity

    # -------------------------------------------------
    # CLI users (enrolled via bootstrap.sh access add-cli-user)
    # -------------------------------------------------
    cli_user_public_keys = {} # e.g. { "jane.doe" = "ssh-rsa AAAA... jane.doe@host" } — on FIPS clusters only RSA (>=2048 bits) and ECDSA keys are accepted, not Ed25519/DSA

    # cli_user_public_keys is an optional map of additional CLI users
    # who should be granted SSH access to the cluster. Add entries
    # as username-to-public-key pairs, for example: {"jane.doe" = "ssh-rsa AAAA... jane.doe@host"}

    # This is used to enroll additional users through bootstrap.sh access add-cli-user.
    # On FIPS-enabled clusters, only RSA keys with a minimum length of 2048 bits
    # and ECDSA keys are accepted. Ed25519 and DSA keys are not supported.


    # -------------------------------------------------
    # Restore / backup
    # -------------------------------------------------
    restore             = false                               # set to true to restore from a previous backup
    backup_name         = "authnz-postgresql-schedule-backup" # Velero backup name used when restore = true
    insight_backup_name = ""                                  # Insight Velero backup name (K8s resources only); leave empty to auto-resolve latest

    # -------------------------------------------------
    # Workload Identity
    # -------------------------------------------------
    velero_uami_client_id     = "<velero_uami_client_id>" # client ID of the Velero UAMI 
    opensearch_uami_client_id = "<opensearch_uami_client_id>" # client ID of the OpenSearch UAMI    

c. Save the file and exit the editor.

d. This step must be performed only if registry needs an authentication. Do not put them in the tfvars file.

To enter registry credentials using the environment variables, run the following commands:

export TF_VAR_username="<registry-username>"
export TF_VAR_password="<registry-password>"

e. To initialize, plan, and apply the changes, run the following commands:

    tofu init
    tofu plan          # review the proposed changes before applying
    tofu apply         # when prompted with "Enter a value:", type "yes"

Expected time for this stage is approximately 15 to 20 minutes.

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

# Confirm all Helm releases are deployed
helm list -A

# Verify Velero is running
kubectl get pods -n pty-backup-recovery

# Verify NFA platform pods
kubectl get pods -A

# Verify Insight pods
kubectl get pods -n pty-insight

# Verify Envoy Gateway
kubectl get pods -n api-gateway

# Verify VolumeSnapshotClass exists
kubectl get volumesnapshotclass

# Check all pods across the cluster are healthy
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded

# Confirm the ingress gateway has an IP
kubectl get gateway -A

A sample output is displayed below:

nfa_release_status = "deployed"
user_svc_private_key = <sensitive>
velero_release_status = "deployed"

All the nodes must be in the Ready state. All the pods must be in the Running or Completed state.

Verifying the installation

To verify the installation, run the following command:

kubectl get nodes
kubectl get pods -A

Configuring for a Standard Deployment

Note: The following instructions are optional and only required for configuring a standard PPC deployment on Azure. Skip these steps if you have already installed the secure settings.

By default, the PCT is configured to deploy a cluster using secure settings. To deploy a standard cluster, the configuration files must be modified.

The following files require changes:

For a standard PPC deployment on Azure AKS, perform the following steps:

1. Ensure that you have downloaded and extracted the PCT. For more information, refer to Preparing for PPC deployment.

2. Update the settings in the AKS Cluster Module.

a. Navigate to the 02_aks_cluster module.

cd iac/azure/cluster/modules/02_aks_cluster/

b. Edit the terraform.tfvars file. Locate the fips_enabled parameter and set it to false.

fips_enabled                  = false

c. Save the file and exit the editor.

3. Update the settings in the Node Pool Module.

a. Navigate to the 03_node_pool module.

cd iac/azure/cluster/modules/03_node_pool/

b. Edit the terraform.tfvars file. Locate the fips_enabled parameter and set it to false.

fips_enabled                  = false

c. Save the file and exit the editor.

4. After completing all these configuration changes, proceed to deploy the cluster.

Note: The steps provided here update the security settings during installation. When following the installation method, do not revert or overwrite the values configured in this section. Keep fips_enabled set to false in 02_aks_cluster and 03_node_pool.

3.3 - 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.