Azure

Prerequisites #

To manage any Cloud Account using the instructions below, you need:

• The humctl CLI installed

• Authentication against the Platform Orchestrator via humctl login

• The Azure CLI installed

• These environment variables set:

  export HUMANITEC_ORG=<your-humanitec-org-id>
  

Azure workload identity federation #

Credentials: temporary

Available Inputs/Outputs: see the Cloud Account types reference

How it works #

Azure temporary credentials make use of Azure workload identity federation .

The setup involves the Humanitec Platform Orchestrator OIDC provider .

Create a managed identity #

1. Define the naming of the managed identity you are going to create for the Cloud Account:

   export MANAGED_IDENTITY_NAME=my-azure-temp-cloud-account
   

2. Define the naming of the new Cloud Account:

   export CLOUD_ACCOUNT_NAME="My Azure Temporary Cred Account"
   export CLOUD_ACCOUNT_ID=my-azure-temp-cloud-account
   

3. Create a managed identity:

   Define the resource group for the identity:

   export MANAGED_IDENTITY_RESOURCE_GROUP=<my-resource-group>
   

   Create the managed identity and capture its client ID:

   export MANAGED_IDENTITY_CLIENT_ID=$(az identity create \
     --name ${MANAGED_IDENTITY_NAME} \
     --resource-group ${MANAGED_IDENTITY_RESOURCE_GROUP} \
     --query clientId -o tsv)
   

4. Configure a federated credential for the Humanitec OIDC Provider on this managed identity:

   If you haven’t already done so (see Prerequisites ), define these environment variables:

   export HUMANITEC_ORG=<your-humanitec-org-id>
   

   Create the federated credential:

   az identity federated-credential create \
     --name AccessFromHumanitec \
     --identity-name ${MANAGED_IDENTITY_NAME} \
     --resource-group ${MANAGED_IDENTITY_RESOURCE_GROUP} \
     --issuer https://idtoken.humanitec.io \
     --subject ${HUMANITEC_ORG}/${CLOUD_ACCOUNT_ID} \
     --audience api://AzureADTokenExchange
   

Create the Cloud Account for temporary credentials #

5. Create a Cloud Account in the Platform Orchestrator.

   Set the Azure tenant id. For the currently logged on user, you can use this command:

   export AZURE_TENANT_ID=$(az account show --query tenantId -o tsv)
   

   Create the Cloud Account:

   • CLI
   • Terraform

   Create a file defining the Cloud Account you want to create:

   cat << EOF > azure-identity-cloudaccount.yaml
   apiVersion: entity.humanitec.io/v1b1
   kind: Account
   metadata:
     id: ${CLOUD_ACCOUNT_ID}
   entity:
     name: ${CLOUD_ACCOUNT_NAME}
     type: azure-identity
     credentials:
       azure_identity_tenant_id: ${AZURE_TENANT_ID}
       azure_identity_client_id: ${MANAGED_IDENTITY_CLIENT_ID}
   EOF
   

   Use the humctl create command to create the Cloud Account in the Organization defined by your configured context:

   humctl apply -f azure-identity-cloudaccount.yaml
   rm azure-identity-cloudaccount.yaml
   

   Using the Humanitec Terraform Provider :

   resource "humanitec_resource_account" "azure-identity" {
     id   = var.cloud_account_id
     name = var.cloud_account_name
     type = "azure-identity"
     credentials = jsonencode({
       azure_identity_tenant_id = var.azure_identity_tenant_id
       azure_identity_client_id = var.azure_identity_client_id
     })
   }
   

   Inside the API, Cloud Accounts are called Resource Accounts, both represent the same entity.

6. Assign the required roles to the managed identity.

   The Cloud Account is now ready for use by any Drivers supporting the azure-identity Account type. Remember to assign the required permissions to the managed identity on the target Azure services depending on the kind of operations it needs to perform.

   For access to an AKS cluster, refer to the Kubernetes page for guidance.

7. Test the Cloud Account.

   The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account. For accounts of type azure-identity, the Azure tenant and app IDs will be displayed.

   • CLI

   The check operation can be called using the specific CLI command.

   humctl resources check-account ${CLOUD_ACCOUNT_ID}
   

   Note that this check does not validate roles assigned to the managed identity that may be used to provision or connect infrastructure during deployments.

Example: connect to an AKS cluster using temporary credentials #

This example Resource Definition uses the AKS cluster Driver to connect to an AKS cluster. It includes a Cloud Account of type azure-identity via the driver_account setting. The Cloud Account credentials will be automatically picked up by the Driver with no further configuration required.

aks-temporary-credentials.yaml ( view on GitHub ) :

# Connect to an AKS cluster using temporary credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: aks-temporary-credentials
entity:
  name: aks-temporary-credentials
  type: k8s-cluster
  # The driver_account references a Cloud Account of type "azure-identity"
  # which needs to be configured for your Organization.
  driver_account: azure-temporary-creds
  driver_type: humanitec/k8s-cluster-aks
  driver_inputs:
    values:
      loadbalancer: 20.10.10.10
      name: demo-123
      resource_group: my-resources
      subscription_id: 12345678-aaaa-bbbb-cccc-0987654321ba
      # Add this exact server_app_id for a cluster using AKS-managed Entra ID integration
      server_app_id: 6dae42f8-4368-4678-94ff-3960e28e3630

Azure service principal client ID & password #

Credentials: static

Available Inputs/Outputs: see the Cloud Account types reference

This Cloud Account type uses static credentials. For superior security , we recommend using the Azure workload identity federation Cloud Account type with temporary credentials instead.

Create the Cloud Account #

1. Create a service principal which will be used by the Humanitec Platform Orchestrator.

   export ROLE_NAME=humanitec-spn
   export SPN_OUTPUT=$(az ad sp create-for-rbac --display-name $ROLE_NAME)
   

   Export the values, needed for the Cloud Account:

   export SPN_APP_ID=$(echo $SPN_OUTPUT | jq -rM .appId )
   export SPN_PASSWORD=$(echo $SPN_OUTPUT | jq -rM .password )
   export SPN_TENANT=$(echo $SPN_OUTPUT | jq -rM .tenant )
   

2. Create a Cloud Account in the Platform Orchestrator.

   Define the name and id of the new Cloud Account:

   export CLOUD_ACCOUNT_NAME="My Azure Cred Account"
   export CLOUD_ACCOUNT_ID=my-azure-cred
   

   If you haven’t already done so (see Prerequisites ), define these environment variables:

   export HUMANITEC_ORG=<your-humanitec-org-id>
   

   Create the Cloud Account:

   • CLI
   • Terraform

   Create a file defining the Cloud Account you want to create:

   cat << EOF > azure-cloudaccount.yaml
   apiVersion: entity.humanitec.io/v1b1
   kind: Account
   metadata:
     id: ${CLOUD_ACCOUNT_ID}
   entity:
     name: ${CLOUD_ACCOUNT_NAME}
     type: azure
     credentials:
       appId: ${SPN_APP_ID}
       password: ${SPN_PASSWORD}
       tenant: ${SPN_TENANT}
   EOF
   

   Use the humctl create command to create the Cloud Account in the Organization defined by your configured context:

   humctl apply -f azure-cloudaccount.yaml
   rm azure-cloudaccount.yaml
   

   Using the Humanitec Terraform Provider :

   resource "humanitec_resource_account" "azure" {
     id   = var.cloud_account_id
     name = var.cloud_account_name
     type = "azure"
     credentials = jsonencode({
       "appId"    = var.azure_client_id
       "password" = var.azure_client_secret
       "tenant"   = var.azure_tenant_id
     })
   }
   

   Inside the API, Cloud Accounts are called Resource Accounts, both represent the same entity.

3. Assign the required roles to the service principal.

   The Cloud Account is now ready for use by any Drivers supporting the azure Account type. Remember to assign the required permissions to the service principal on the target Azure services depending on the kind of operations it needs to perform.

   For access to an AKS cluster, refer to the Kubernetes page for guidance.

4. Test the Cloud Account.

   The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account. For accounts of type azure, the Azure tenant and app IDs will be displayed.

   • CLI

   The check operation can be called using the specific CLI command.

   humctl resources check-account ${CLOUD_ACCOUNT_ID}
   

   Note that this check does not validate permissions assigned to the service principal that may be used to provision or connect infrastructure during deployments.

Example: connect to an AKS cluster using static credentials #

This example Resource Definition uses the AKS cluster Driver to connect to an AKS cluster. It includes a Cloud Account of type azure via the driver_account setting. The Cloud Account credentials will be automatically picked up by the Driver with no further configuration required.

aks-static-credentials-cloudaccount.yaml ( view on GitHub ) :

# Connect to an AKS cluster using static credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: aks-static-credentials-cloudaccount
entity:
  name: aks-static-credentials-cloudaccount
  type: k8s-cluster
  # The driver_account references a Cloud Account of type "azure"
  # which needs to be configured for your Organization.
  driver_account: azure-static-creds
  driver_type: humanitec/k8s-cluster-aks
  driver_inputs:
    values:
      loadbalancer: 20.10.10.10
      name: demo-123
      resource_group: my-resources
      subscription_id: 12345678-aaaa-bbbb-cccc-0987654321ba
      # Add this exact server_app_id for a cluster using AKS-managed Entra ID integration
      server_app_id: 6dae42f8-4368-4678-94ff-3960e28e3630