Troubleshooting

Accessing the PPC CLI

• Permission denied for publickey: Ensure the correct private key ~/.ssh/<cluster_name>_user_svc is used and matches the authorized_keys in the pod.

• Connection refused: Verify the load balancer IP and hosts file configuration.

• Key format issues: Ensure the private key is in the correct format . For example, OpenSSH format for Linux or macOS, .ppk for PuTTY.

Component installation issues

• Helm chart not found: Run helm repo update to refresh the repository cache.

• Namespace already exists: Drop the --create-namespace flag if the namespace is already created.

• CRD conflicts: If cert-manager CRDs already exist, skip the CRD installation step.

• Pod not starting: Inspect logs with kubectl logs <pod> -n <namespace> and kubectl describe pod <pod> -n <namespace>.

State lock error after interrupted installation

Issue: When an installation is interrupted mid-apply (Ctrl+C, network drop, SSH disconnect, or jump box crash), subsequent installation attempts fail with the following error:

Error: Error acquiring the state lock
Error message: state blob is already locked
Lock Info:
  ID:        9377a903-94d1-4b19-3e57-1ee92b18bed5
  Path:      https://<storage>.blob.core.windows.net/velero/infrastructure-manifest%2F<cluster>%2Fstates%2F01_identity.tfstate
  Operation: OperationTypeApply

Description: OpenTofu acquires a lease on the state blob in Azure Blob Storage before applying changes. If the process is terminated without a graceful shutdown, the lease is not released automatically. This can occur due to Ctrl+C, network disconnection, SSH session timeout, or a jump box reboot.

Resolution: Force-unlock the state using the lock ID from the error message, then re-run the installation.

cd iac/azure/cluster/modules/<failed-stage>
tofu init
tofu force-unlock <lock-id>

Replace <failed-stage> with the module directory that failed (for example, 01_identity) and <lock-id> with the ID shown in the error output.