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 you use --force on an existing environment, HyOps also reviews the current effective defaults before continuing. That includes values already present in azure.conf, not just values discovered from the active Azure CLI session.
  • 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 run record: path to inspect the run envelope.

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

  • Remediation:

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

--with-cli-login --force keeps the wrong subscription, tenant, or location

  • Meaning: the environment already had values in azure.conf, and you want to repair them instead of silently carrying them forward.

  • Current behaviour:

  • HyOps now pauses and asks you to keep or override the effective values for:
    • AZ_LOCATION
    • AZ_SP_NAME
    • AZ_SUBSCRIPTION_ID
    • AZ_TENANT_ID

  • This review step applies to values that came from the existing config file as well as values derived from the active Azure CLI context.

  • Recommended repair path:

    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

License: MIT-0 for code, CC-BY-4.0 for documentation