Skip to content

Init Azure credentials with hyops init azure

Purpose: Initialise Azure runtime credentials so Terraform/Terragrunt stacks can run non-interactively. Owner: Platform operations Trigger: First-time environment bootstrap, new workstation/runner, or credential rotation. Impact: Without Azure credentials, Azure stacks cannot apply. Severity: P3 Pre-reqs: az and ansible-vault installed; Azure subscription access. Rollback strategy: Remove the generated credentials file under <root>/credentials/ and re-run init.

Context

hyops init azure writes:

  • Non-secret config: <root>/config/azure.conf
  • Sensitive credentials: <root>/credentials/azure.credentials.tfvars (mode 0600)
  • Readiness marker: <root>/meta/azure.ready.json

It can bootstrap or rotate a service principal in interactive mode, and can run in --non-interactive mode when the required secrets are already present.

Preconditions and safety checks

  • Ensure you are targeting the correct environment: 

    echo "HYOPS_ENV=$HYOPS_ENV"

  • Confirm required tools exist: 

    command -v az ansible-vault

  • If you want to use the local vault provider (recommended for workstations): 

    hyops vault status-verbose
    Notes:

  • After hyops vault bootstrap, HyOps remembers the provider command at ~/.hybridops/config/vault-password-command.

  • In a fresh shell, you may need to unlock once: 

    hyops vault password >/dev/null

  • Interactive bootstrap requires that the Azure CLI identity is a user (not a service principal): 

    az account show --query user.type -o tsv

  • Avoid sharing the same AZ_SP_NAME across multiple HyOps environments on the same tenant/subscription. HyOps may rotate the bootstrap client secret during init; if two envs share the same service principal name, rotating the secret in one env will invalidate the other env until it re-runs init.

Steps

1) Generate the config template (first run only)

  • Command: 

    hyops init azure --env dev

  • Expected result:

  • If the config does not exist, HyOps writes a template and exits with guidance.
  • Edit <root>/config/azure.conf and re-run the command.
  • The template defaults AZ_SP_NAME to an environment-scoped value (for example sp-hybridops-terraform-bootstrap-dev).

2) Interactive bootstrap (recommended on workstations)

  • Action: authenticate with your operator identity, then allow HyOps to bootstrap/rotate the service principal.

  • Commands: 

    az login
# If a browser cannot open, use device-code login:
# az login --use-device-code
hyops init azure --env dev --with-cli-login

  • Expected result:

  • HyOps prints the active Azure identity and asks for confirmation.
  • If HyOps detects AZ_SP_NAME is shared with other local envs, it warns and prompts before rotating secrets.
  • target=azure status=ready and azure.credentials.tfvars is written.

3) Non-interactive mode (recommended for CI/runners)

  • Action: ensure the runtime vault contains the required keys:
  • AZ_CLIENT_ID
  • AZ_CLIENT_SECRET
  • AZ_TENANT_ID

  • AZ_SUBSCRIPTION_ID

  • Command: 

    hyops init azure --env dev --non-interactive

  • Notes:
  • Provide vault password source via environment (recommended: HYOPS_VAULT_PASSWORD_COMMAND) or pre-bootstrap the persisted provider command.
  • If this is a fresh shell and vault is locked, unlock once: 
    hyops vault password >/dev/null

Verification

  • Confirm readiness marker exists: 

    cat ~/.hybridops/envs/dev/meta/azure.ready.json

  • Confirm credentials file exists and is protected: 

    ls -la ~/.hybridops/envs/dev/credentials/azure.credentials.tfvars

Troubleshooting

ERR: Azure CLI login required ... --with-cli-login

  • Remediation: 
    az login
hyops init azure --env dev --with-cli-login

ERR: Azure CLI is not logged in as a user (user.type != user)

  • Meaning: you are logged into az as a service principal (or other non-user identity). Interactive bootstrap cannot safely proceed.

  • Remediation: 

    az logout
az login
hyops init azure --env dev --with-cli-login

AADSTS7000215: Invalid client secret provided

  • Meaning: the service principal secret used for az login --service-principal ... is not valid (wrong secret value, expired secret, or propagation delay right after rotation).

  • Remediation:

  • Re-run init (HyOps may retry and/or rotate the secret as part of bootstrap): 
    hyops init azure --env dev --with-cli-login
  • If it still fails, use the printed evidence: path to inspect the run envelope.

ERR: credentials file already exists (use --force ...)

  • Remediation: 
    hyops init azure --env dev --with-cli-login --force

vault password command timed out while waiting for unlock

  • Meaning: vault provider exists, but GPG unlock was not completed before timeout.

  • Remediation: 

    hyops vault password >/dev/null
export HYOPS_VAULT_PASSWORD_COMMAND_TIMEOUT_S=300
hyops init azure --env dev --with-cli-login

WARNING: AZ_SP_NAME=... is also configured for env(s): ...

  • Meaning: multiple HyOps envs on this workstation are configured to use the same Azure bootstrap service principal name. If HyOps rotates the client secret, it will invalidate the other env(s) until they re-run init.

  • Remediation (recommended):

  • set a unique AZ_SP_NAME per env in <root>/config/azure.conf (env-scoped names are the default for new templates)

  • re-run: 

    hyops init azure --env dev --with-cli-login

  • If you intentionally share one service principal across envs: 

    hyops init azure --env dev --with-cli-login --allow-shared-sp

References

Maintainer: HybridOps.Studio License: MIT-0 for code, CC-BY-4.0 for documentation