CNE Azure Ready: Getting Started

CNE Azure Ready: Prerequisites

Before running the bootstrap scripts for Cloud Native Experience (CNE) on Microsoft Azure, install the needed command-line tools, prepare your Azure subscription, and create an Azure Key Vault and a GitOps repository. Argo CD deploys your Liferay DXP environments from the GitOps repository, so the repository’s contents define what runs on the cluster.

The bootstrap runs from your local machine and provisions a GitOps-based platform using Terraform, Helm, Argo CD, and Azure Kubernetes Service (AKS).

Installing the Command-Line Tools

The bootstrap scripts check for these tools before they do anything else. Install them and make sure they are available in your system’s PATH.

ToolRequired ByPurpose
Azure CLI (az)setup_azure.sh and teardown_azure.shSign in to Azure and create the Terraform state storage, role assignments, and cluster credentials.
TerraformLauncher, setup_azure.sh, and teardown_azure.shProvision the AKS cluster and the platform.
Helm CLIsetup_azure.sh and teardown_azure.shValidate config.json against the infrastructure provider chart and install the liferay-platform chart in setup_azure.sh, and uninstall it in teardown_azure.sh.
jqLauncher, setup_azure.sh, and teardown_azure.shRead config.json in the bootstrap scripts.
curlLauncherDownload the bootstrap release.
tarLauncherExtract the bootstrap release.
sha256sum or shasumLauncherVerify the bootstrap release against its checksum.
kubectl CLIteardown_azure.shRemove the platform’s Kubernetes resources before Terraform destroys the infrastructure.

If a tool is missing, the run stops with The utility <name> is not installed. If neither checksum tool is installed, the launcher stops with Neither sha256sum nor shasum is installed.

Terraform must be version 1.10.0 or later. Both Azure Terraform stacks enforce this version when Terraform initializes. OpenTofu is not supported.

Setup pulls the liferay-azure-infrastructure-provider and liferay-platform charts from oci://us-central1-docker.pkg.dev/external-assets-prd/liferay-helm-chart, so your machine must be able to reach that registry. Your machine also reaches these endpoints during the run:

  • https://storage.googleapis.com, where the launcher lists the published bootstrap releases
  • https://cdn.liferay.cloud, where the launcher downloads the bootstrap release and its checksum
  • https://argoproj.github.io/argo-helm, where the platform stack gets the Argo CD chart

Preparing Your Azure Subscription

The bootstrap reads your subscription and tenant from config.json and creates every Azure resource the platform uses, except the Key Vault.

Setting Up Your Azure Account

Find your subscription and tenant IDs, confirm your roles, choose a deployment name, and sign in with the account that runs the bootstrap:

  1. Find the IDs of the subscription you deploy to and of its tenant. Sign in with az login, then list the subscriptions your account can use:

    az account list --query "[].{name: name, subscription_id: id, tenant_id: tenantId}" --output table
    

    You set the two IDs in config.json as subscription_id and tenant_id.

  2. Make sure the account that runs the bootstrap holds Owner on the subscription, or Contributor together with Role Based Access Control Administrator. The bootstrap creates resources and assigns roles, including on your Key Vault and on any container registries you configure, so these roles must cover those scopes too. To grant a missing role, see Assign Azure roles using Azure CLI.

    The bootstrap creates a resource group named after deployment_name, a virtual network, a subnet, a NAT gateway, a public IP address, a network security group, the AKS cluster, and user-assigned managed identities. It also assigns these roles to those identities:

    RoleScope
    Network ContributorThe virtual network
    AcrPullEach container registry
    ContributorThe resource group
    Managed Identity ContributorThe resource group
    Role Based Access Control Administrator, with a conditionThe resource group
    Key Vault Secrets UserThe Key Vault
    Monitoring roles, when observability is enabledThe monitoring resources and the resource group
  3. Choose a deployment_name. It becomes the resource group name, the AKS DNS prefix, and the prefix of every resource name, and the AKS cluster is named <deployment_name>-aks. Use only lowercase letters, digits, and hyphens. Start the name with a letter, end it with a letter or digit, and keep it to 29 characters or fewer.

  4. Sign in to the tenant you deploy to:

    az login --tenant <tenant-id>
    

    If the browser sign-in stalls, sign in with a device code instead:

    az login --tenant <tenant-id> --use-device-code
    

    If your account can use more than one subscription, select the one you set in config.json, so the checks in this article run against it:

    az account set --subscription <subscription-id>
    

    When setup finds an active login that can get a token for the subscription, it reuses it and prints Reusing the active Azure login for the subscription <id>. Otherwise, it prints Attempting to login to your Azure account. and runs az login --tenant <tenant_id> itself. Either way, it then selects the subscription with az account set. Sign in with a user account rather than a service principal: when your account cannot list the Terraform state container, setup grants the signed-in user a role on it, and it assigns that role to a user.

Securing Enough Compute Quota

The AKS system node pool runs system_node_count nodes (default 2) of the machine_type VM size (default Standard_D8s_v3). The general-purpose Node Auto Provisioning pool provisions workload nodes of the same size on demand. Before the first run, confirm that the region has vCPU quota for that VM size and offers it:

az vm list-usage --location <region> --output table
az vm list-skus --location <region> --size Standard_D8s_v3

az vm list-usage lists each vCPU quota in the region with its current usage and its limit. The quota for the VM size’s family must leave room for the system nodes and for the workload nodes the environments add. If it doesn’t, request a quota increase. az vm list-skus lists the VM size when the region offers it, along with any zone restrictions on it.

To use a different VM size, set terraform.aks.machine_type in config.json. See CNE Azure Ready: Bootstrap Configuration Reference.

Making Sure the Database Service Is Available

The platform provisions Azure Database for PostgreSQL Flexible Server in your region. The subscription must be allowed to create it there. Nothing checks this before the run: the cluster and the platform install, the database fails afterward, and Liferay DXP never starts.

Check whether the region offers the service to your subscription:

az postgres flexible-server list-skus --location <region> --query "[0].reason" --output tsv

An empty result means the service is available in the region.

The default PostgreSQL server size is GP_Standard_D2s_v3. Confirm that the region offers it, or set database.instanceType for each environment. See CNE Azure Ready: Helm Values Reference.

Setting Up Remote Terraform State (Optional)

By default, Terraform keeps its state on your local machine. To keep it in Azure Storage, add a tfstate object to config.json with resource_group_name, storage_account_name, and container_name. All three keys are required once the tfstate object is present. Setup creates each named resource that does not exist yet: the resource group, a StorageV2 storage account with Standard_LRS redundancy, and the container.

On every run with tfstate, setup also configures the storage account: it turns off public blob access, requires TLS 1.2, and turns on blob versioning and 90 days of blob delete retention.

The storage account name must be 3 to 24 characters of lowercase letters and numbers, and it must be unique across Azure.

If your account cannot list the state container, setup assigns your signed-in user the Storage Blob Data Contributor role on the container and waits up to five minutes for the assignment to take effect.

Creating an Azure Key Vault

The platform reads its secrets, including the GitOps repository credentials, from an Azure Key Vault that you create.

  1. Create an Azure Key Vault that uses the Azure role-based access control (RBAC) permission model. The bootstrap reads the vault but never creates it, and a vault that uses the access policy permission model stops the run. Create the vault in the subscription that subscription_id names, because the bootstrap reads the vault through that subscription.

  2. Note the vault’s name and resource group. You set them in config.json as terraform.platform.cluster_secret_store.key_vault.name and terraform.platform.cluster_secret_store.key_vault.resource_group_name.

  3. Make sure the account that stores secrets in the vault holds the Key Vault Secrets Officer or Key Vault Administrator role on the vault.

Creating a GitOps Repository

Create the repository from Liferay’s template, and give Argo CD a token to read it:

  1. Create a repository using the LiferayCloud/cloud-native-gitops-boilerplate template. Its liferay/projects/default/environments/dev/ folder matches the layout the platform expects.

  2. Generate a personal access token with read-only access to the GitOps repository’s contents. The platform only reads the repository.

  3. Save this JSON document to a file, such as gitops-credentials.json, with your own values:

    {
        "git_machine_user_id": "your-github-username",
        "git_access_token": "ghp_abc...WxYZ"
    }
    
    FieldDescription
    git_machine_user_idGitHub username (or organization machine-account login) that owns the token
    git_access_tokenThe personal access token you generated
  4. Create a secret named liferay-credentials-gitops in the Key Vault from that file:

    az keyvault secret set \
        --file gitops-credentials.json \
        --name liferay-credentials-gitops \
        --vault-name <vault-name>
    

Verifying Your Setup

Before continuing, run each command and confirm that its output matches the expected output:

CommandExpected Output
az version"azure-cli": "2.90.0" or a later version
az account show --query "{subscription_id: id, tenant_id: tenantId}" --output tableThe subscription and tenant IDs you set in config.json
az keyvault show --name <vault-name> --query properties.enableRbacAuthorizationtrue
az keyvault secret show --name liferay-credentials-gitops --output tsv --query name --vault-name <vault-name>liferay-credentials-gitops
terraform -versionTerraform v1.10.0 or a later version
helm version, kubectl version --client, jq --version, curl --version, and tar --versionA version number from each
sha256sum --version or shasum --versionA version number from either

If a result doesn’t match, return to the section that covers that prerequisite before continuing.

Next Steps

After completing these prerequisites, continue to CNE Azure Ready: Bootstrapping Your Initial Environment.