CNE Azure Ready: Bootstrapping Your Initial Environment
After you complete CNE Azure Ready: Prerequisites, run the Cloud Native Experience (CNE) bootstrap process to create an Azure Kubernetes Service (AKS) cluster, the Liferay platform, and your Liferay DXP environments in an Azure subscription.
The bootstrap is one command. It reads a config.json file, downloads the bootstrap release that the file names, creates the AKS cluster and the platform with Terraform, and installs the Liferay platform root application. Argo CD then uses that application to deploy everything in your GitOps repository.
Preparing the Bootstrap Directory
Create a working directory for the bootstrap process. The script reads config.json from the current directory and extracts the bootstrap release into it.
mkdir cne-bootstrap
cd cne-bootstrap
touch config.json
Keep this directory after the run. Without remote Terraform state, it holds the state that reruns and teardown use.
Configuring the Bootstrap
The config.json file defines the deployment. This example creates a deployment named clarity that uses PostgreSQL and stores its Terraform state in an Azure storage account:
{
"deployment_name": "clarity",
"options": {
"auto_approve": false,
"parallelism": 10,
"provider": "azure",
"version": "0.3.0"
},
"platformComponents": {
"values": {
"gitops": {
"repository": {
"url": "https://github.com/clarity-vision-solutions/liferay-gitops.git"
}
}
}
},
"region": "eastus2",
"setup": {
"database": {
"engine": "postgresql"
}
},
"subscription_id": "your-azure-subscription-id",
"tenant_id": "your-azure-tenant-id",
"terraform": {
"platform": {
"cluster_secret_store": {
"key_vault": {
"name": "your-key-vault-name",
"resource_group_name": "your-key-vault-resource-group"
}
},
"keda_config": {
"enabled": true
},
"observability_config": {
"enabled": true
}
}
},
"tfstate": {
"container_name": "tfstate",
"resource_group_name": "clarity-tfstate",
"storage_account_name": "claritytfstate"
}
}
Replace subscription_id, tenant_id, deployment_name, the Key Vault’s name and resource_group_name, and the GitOps repository url with the values from the prerequisites. Then choose your own region and tfstate names. Setup creates the tfstate resource group, storage account, and container when they don’t exist, and the storage account name must be unique across Azure.
The example also turns on KEDA (keda_config) and observability (observability_config), so the bootstrap sets up KEDA and the Azure Monitor resources that autoscaling and Grafana monitoring use. To use those features after the bootstrap, see CNE Azure Ready: Configuring Autoscaling and CNE Azure Ready: Monitoring With Grafana. For every key config.json accepts, see CNE Azure Ready: Bootstrap Configuration Reference.
For your first deployment, run the bootstrap with the configuration in this article before you change other Terraform or Helm values. When you finish evaluating that deployment, clean up the environment as CNE Azure Ready: Cleaning Up the Environment describes, then deploy again with your own configuration.
Required Keys
Every config.json file must set these keys, except the tfstate keys, which only a tfstate object requires. The example sets all of them:
| Key | Description |
|---|---|
deployment_name | Identifies the deployment. It names the resource group and the AKS cluster (<deployment_name>-aks). |
region | Sets the Azure region for all resources, such as eastus2. |
subscription_id | Names the Azure subscription where the resources are created. |
tenant_id | Names the Microsoft Entra ID tenant that the subscription belongs to. |
options.provider | Selects the infrastructure provider. Set it to azure. |
setup.database.engine | Sets the database engine for the deployment. Set it to postgresql. |
terraform.platform.cluster_secret_store.key_vault | Names the Key Vault, with name and resource_group_name, that the platform reads secrets from. |
platformComponents.values.gitops.repository.url | Names the GitOps repository that Argo CD deploys from. |
tfstate.container_name, tfstate.resource_group_name, tfstate.storage_account_name | Name the blob container, resource group, and storage account that hold the Terraform state. They are required when a tfstate object is present. |
Where the run stops depends on which key is missing:
- When
deployment_name,region,subscription_id,tenant_id, or atfstatekey is missing, the run stops withThe configuration JSON file must contain a key named "<key>". - When
options.provideris missing, the launcher stops withNo provider is specified in <file>. - When
setup.database.engineis missing, setup stops with a Helm values schema error from the infrastructure provider chart, andteardown_azure.shstops withsetup.database.engine is missing. - When
terraform.platform.cluster_secret_storeis missing, the Terraform apply of the platform stack stops, because the variable has no default.
Bootstrap Options
The options object in config.json controls how the bootstrap runs:
| Option | Description |
|---|---|
provider | Selects the infrastructure provider. Set it to azure. |
version | Selects the bootstrap release to download, such as 0.3.0. When it is omitted, the script uses latest, the newest published release. |
auto_approve | Adds -auto-approve to every Terraform apply and destroy when it is true. The default is false. |
parallelism | Sets the Terraform -parallelism flag, the maximum number of concurrent Terraform operations. |
Set version to a specific release. The script extracts each release to its own liferay-azure-bootstrap-<version> directory. Without tfstate, a later run with latest that downloads a newer release works in a new directory that does not hold the Terraform state of the earlier runs.
Choosing the Terraform State Location
The tfstate object determines where the Terraform state is stored:
-
With
tfstate, the script creates the resource group, storage account, and container if they do not exist. If your Azure user cannot list the container, the script grants your user theStorage Blob Data Contributorrole on the container and waits up to five minutes for the role to take effect. Each stack’s state is the blob<deployment_name>/<region>/<aks|platform>/terraform.tfstate, read with Microsoft Entra ID authentication. -
Without
tfstate, the state stays on your machine underliferay-azure-bootstrap-<version>/cloud/terraform/azure/aksandliferay-azure-bootstrap-<version>/cloud/terraform/azure/platformin the bootstrap directory. Keep that directory for reruns and teardown.
Running the Bootstrap Script
From the bootstrap directory, run the bootstrap process:
bash <(curl -sL https://raw.githubusercontent.com/liferay/liferay-portal/master/cloud/scripts/bootstrap.sh)
The script reads config.json from the current directory. To use a file elsewhere, pass its path as an argument. The script downloads liferay-azure-bootstrap-<version>.tar.gz from https://cdn.liferay.cloud/bootstrap/, verifies it against its .sha256 checksum, extracts it to liferay-azure-bootstrap-<version> in the current directory, and runs the Azure setup with your configuration.
With tfstate, a first run can fail with 403 AuthorizationPermissionMismatch. See Rerunning the Bootstrap Process for the fix.
As it runs, the script goes through these stages in order:
-
The script generates a
config.auto.tfvars.jsonfile for each Terraform stack. -
The script signs in to Azure. When an active Azure CLI login already covers the subscription, it prints
Reusing the active Azure login for the subscription <subscription_id>.Otherwise, it printsAttempting to login to your Azure account.and runsaz loginfor the tenant inconfig.json. Sign in if the script asks you to. -
With
tfstate, lines that start with[Tfstate storage configuration]report that the state storage was created or already exists. -
Setting up the Kubernetes cluster.starts the Terraform apply of the AKS stack, andKubernetes cluster setup complete.reports that it finished. -
Connecting to the Kubernetes cluster.runsaz aks get-credentials --overwrite-existing, which replaces the cluster’s entry in~/.kube/config. -
Setting up the Liferay platform.starts the Terraform apply of the platform stack, which installs Argo CD, andLiferay platform setup complete.reports that it finished. -
Applying the Liferay platform root application.installs theliferay-platformHelm release into theargocd-systemnamespace.
The script exports TF_INPUT=0 and runs terraform apply on the AKS stack, then on the platform stack, without a saved plan.
With options.auto_approve set to false, the default, Terraform shows each stack’s plan and asks you to approve it, first for the AKS stack and then for the platform stack. Enter yes at each prompt. TF_INPUT=0 turns off only Terraform’s prompts for variable values. To run without prompts, set auto_approve to true.
Argo CD keeps deploying the platform components and your environments from the GitOps repository after the script exits. Watch their progress in the Argo CD UI, as Accessing Argo CD describes.
Rerunning the Bootstrap Process
If provisioning fails, fix the cause and run the bootstrap again from the same directory with the same config.json. The rerun reuses the Terraform state and the existing state storage, and reports each storage resource that exists with a line such as Storage account <name> already exists. Skipping creation process.
In 0.3.0, the first run with tfstate can fail with 403 AuthorizationPermissionMismatch while Terraform locks the state, because the script stops waiting for the new role assignment after one successful read. The next run then fails with state blob is already locked. Break the lease on the state blob, then run the bootstrap again:
az storage blob lease break \
--account-name <storage_account_name> \
--auth-mode login \
--blob-name <deployment_name>/<region>/aks/terraform.tfstate \
--container-name <container_name> \
--lease-break-period 0
If failures persist, see CNE Azure Ready: Troubleshooting, or clean up the environment as CNE Azure Ready: Cleaning Up the Environment describes before you retry.
Accessing Argo CD
The platform stack installs Argo CD as the argocd release in the argocd-system namespace. The bootstrap then installs the liferay-platform root application, which deploys liferay-platform-components: External Secrets, Crossplane, Envoy Gateway, Argo Workflows, the ECK operator, the Liferay DXP Operator, KEDA and observability when enabled, and one set of applications for each environment folder in your GitOps repository.
The script does not print Argo CD credentials or start a port-forward. Follow these steps to open the Argo CD UI:
-
Forward a local port to the Argo CD server:
kubectl -n argocd-system port-forward svc/argocd-server 8080:80The Argo CD server runs without TLS, so the forward targets port
80. The command keeps running until you stop it, so leave it open while you use the Argo CD UI. -
In another terminal, get the
adminpassword from theargocd-initial-admin-secretsecret:kubectl -n argocd-system get secret argocd-initial-admin-secret \ -o jsonpath="{.data.password}" | base64 --decode -
Open
http://localhost:8080in your browser and sign in asadminwith that password. -
Check that each application shows Healthy and Synced.
An application shows Progressing until its resources report a status. A LiferayInfrastructure resource shows The system is initializing., then Still <reason>: <message>, and then The LiferayInfrastructure is healthy. When its Synced condition is False, the LiferayInfrastructure is Degraded and shows that condition’s message.
Verifying the Deployment
Each environment folder in the GitOps repository produces two Argo CD applications, <project>-<environment>-infra and <project>-<environment>-app, in the namespace liferay-<project>-<environment>. In a GitOps repository created from the boilerplate and not yet changed, these are default-dev-infra and default-dev-app in the namespace liferay-default-dev.
Argo CD reports the LiferayInfrastructure Healthy only when its Ready condition is True and its managed services are ready: the database is bootstrapped, and the document library connection is ready.
Check the Liferay pods in the environment’s namespace:
kubectl get pods --namespace liferay-default-dev
When the Liferay pod is ready, its STATUS is Running and its READY column counts every container as ready. While its init containers run, its STATUS starts with Init:.
The Liferay pod waits for these dependencies, among others, before Liferay DXP starts:
-
The
wait-for-elasticsearchinit container runs until Elasticsearch reports green or yellow health. -
The
database-server-detailsConfigMap appears once the database server has an address and its bootstrap job is ready.
The Liferay pod shows CreateContainerConfigError while the database is provisioned, because the database-server-details ConfigMap does not exist yet. If the pod stays in CreateContainerConfigError because that ConfigMap is not found, the database was not provisioned. See CNE Azure Ready: Troubleshooting.
Liferay DXP on Azure starts with the trial license disabled, so you must add a license. See CNE Azure Ready: Managing Secrets and Licenses. To reach Liferay DXP at a domain, see CNE Azure Ready: Configuring Liferay Domains and TLS.
Continue with CNE Azure Ready: Configuring the Cloud Native Experience to customize the environment and platform components.