Managed Azure HostedClusters Identity Flow

This document provides a high-level overview of how Azure identities flow through the managed Azure HostedClusters architecture, from HostedCluster configuration to Azure API authentication.

The diagrams below show the key aspects of the identity flow. For detailed information on each component, see the linked documentation at the bottom of this page.

Sequence Diagram

The following diagram shows the identity flow using the Control Plane Operator (CPO) as an example. Other control plane pods that need to authenticate with Azure follow a similar pattern, using their respective SecretProviderClass and credential file.

sequenceDiagram
    participant HC as HostedCluster CR
    participant HO as HyperShift Operator
    participant CPO as Control Plane Operator
    participant SPC as SecretProviderClass
    participant CSI as CSI Driver
    participant KV as Azure Key Vault
    participant SDK as Azure SDK
    participant AAD as Azure AD
    participant ARM as Azure ARM API

    Note over HC,ARM: Setup Phase
    HC->>HO: HostedCluster created with ManagedIdentities config
    HO->>SPC: Creates SecretProviderClasses (managed-azure-cpo, etc.)
    HO->>CPO: Deploys Control Plane Operator

    Note over HC,ARM: Pod Startup Phase
    CPO->>CSI: Pod starts with CSI volume mount
    CSI->>SPC: Reads SecretProviderClass configuration
    CSI->>KV: Authenticates with ARO_HCP_KEY_VAULT_USER_CLIENT_ID managed identity
    KV-->>CSI: Returns UserAssignedIdentityCredentials JSON
    CSI->>CPO: Mounts credential file at /mnt/certs

    Note over HC,ARM: Runtime Authentication
    CPO->>SDK: Loads credential file
    SDK->>SDK: Parses JSON, decodes PEM certificate
    SDK->>AAD: Client certificate authentication
    AAD-->>SDK: Returns Azure Access Token
    SDK->>ARM: API call with Bearer token
    ARM-->>CPO: Azure resource operation result

Component Identity Mapping

graph LR
    subgraph HC_CR[HostedCluster CR]
        CP[ControlPlaneManagedIdentities]
    end

    subgraph SPC_RESOURCES[SecretProviderClasses]
        SPC1[managed-azure-cloud-provider]
        SPC2[managed-azure-cpo]
        SPC3[managed-azure-nodepool-management]
        SPC4[managed-azure-ingress]
        SPC5[managed-azure-network]
        SPC6[managed-azure-disk-csi]
        SPC7[managed-azure-file-csi]
        SPC8[managed-azure-image-registry]
        SPC9[managed-azure-kms]
    end

    subgraph CP_PODS[Control Plane Pods]
        CCM[Cloud Controller Manager]
        CPO2[Control Plane Operator]
        CAPZ[CAPZ]
        ING[Ingress Operator]
        CNO[Network Operator]
        DISK[Disk CSI Driver]
        FILE[File CSI Driver]
        REG[Image Registry]
        KAS[Kube API Server]
    end

    CP -->|cloudProvider| SPC1 --> CCM
    CP -->|controlPlaneOperator| SPC2 --> CPO2
    CP -->|nodePoolManagement| SPC3 --> CAPZ
    CP -->|ingress| SPC4 --> ING
    CP -->|network| SPC5 --> CNO
    CP -->|disk| SPC6 --> DISK
    CP -->|file| SPC7 --> FILE
    CP -->|imageRegistry| SPC8 --> REG
    KMS_ID[secretEncryption.kms.azure.kms] -->|kms| SPC9 --> KAS

Key Vault Secret Structure

graph TB
    subgraph KV_VAULT[Azure Key Vault]
        KV[(Key Vault)]
    end

    subgraph SECRET_JSON[Secret Content - JSON]
        JSON[UserAssignedIdentityCredentials]
        JSON --> F1[authentication_endpoint]
        JSON --> F2[client_id]
        JSON --> F3[client_secret]
        JSON --> F4[tenant_id]
        JSON --> F5[not_before / not_after]
    end

    subgraph PEM_BUNDLE[Decoded client_secret - PEM]
        PEM[PEM Bundle]
        PEM --> CERT[X.509 Certificate]
        PEM --> KEY[Private Key]
    end

    KV --> JSON
    F3 -->|base64 decode| PEM

Detailed Documentation

Each stage of the identity flow is documented in detail:

Additional References

• SecretProviderClass Configuration - Deep dive into ReconcileManagedAzureSecretProviderClass function and all SecretProviderClass resources created by HO/CPO