# Self-Managed Azure HyperShift Overview

!!! note "Developer Preview in OCP 4.21"

    Self-managed Azure HostedClusters are available as a Developer Preview feature in OpenShift Container Platform 4.21.

## Introduction

Self-managed Azure HyperShift enables you to deploy and manage OpenShift hosted control planes on an OpenShift management cluster running in Azure. The key difference from managed Azure HyperShift deployments is the management cluster platform: self-managed uses an OpenShift cluster you provision and manage, while managed Azure uses Azure Kubernetes Service (AKS).

## Architecture Overview

Self-managed Azure HyperShift deployments consist of three key layers:

1. **Management Cluster**: An existing Azure OpenShift cluster that hosts the HyperShift operator and control planes for your hosted clusters
2. **Control Plane**: Kubernetes control plane components running as pods on the management cluster
3. **Data Plane**: Worker nodes running as Azure Virtual Machines in your Azure subscription

The architecture uses [Azure Workload Identity](https://azure.github.io/azure-workload-identity/docs/) for secure, credential-free authentication between OpenShift components and Azure services. This eliminates the need to manage long-lived service principal credentials and provides better security through federated identity credentials.

### Key Differences from Managed Azure

Unlike managed Azure HyperShift deployments, self-managed Azure:

- Uses an OpenShift cluster as the management platform instead of AKS
- Requires you to provision and manage the lifecycle of the management cluster

## DNS Management Options

Self-managed Azure HyperShift supports two DNS management approaches, and both are documented in the same guides:

| Aspect | With External DNS | Without External DNS |
|--------|------------------|---------------------|
| **Best For** | Production, multi-cluster | Development, testing |
| **API Server DNS** | Custom (e.g., `api-cluster.example.com`) | Azure LoadBalancer (e.g., `abc123.region.cloudapp.azure.com`) |
| **Setup Complexity** | Higher (requires DNS zones, service principal) | Lower (minimal configuration) |
| **Management** | Fully automatic | Manual or Azure-provided |

!!! tip "Both Approaches in One Guide"

    Our setup guides include instructions for both approaches. Simply follow the sections that match your choice:

    - **With External DNS**: Follow all sections including DNS Zone Configuration and External DNS Service Principal Setup
    - **Without External DNS**: Skip DNS sections and use the simplified operator installation command

## Deployment Workflow

Setting up self-managed Azure HyperShift is a three-phase process that must be completed in order:

### Phase 1: Azure Workload Identity Setup

**Purpose**: Establish secure authentication infrastructure for OpenShift components to access Azure services.

This phase creates the foundational security infrastructure required for your hosted clusters:

- **Managed Identities**: Creates Azure managed identities for each OpenShift component (image registry, ingress, CSI drivers, cloud provider, network operator, etc.)
- **OIDC Issuer**: Configures an OIDC issuer in Azure Blob Storage for service account token validation
- **Federated Credentials**: Establishes trust relationships between Azure Entra ID and OpenShift service accounts

You can create workload identities using either:

- **HyperShift CLI** (recommended): `hypershift create iam azure` - automates identity and federated credential creation
- **Azure CLI**: Manual `az identity` and `az identity federated-credential` commands

**Why This Matters**: Without these identities and federated credentials, your hosted cluster components cannot authenticate with Azure APIs to provision storage, manage load balancers, configure networking, or perform other essential cloud operations. Using workload identities instead of traditional service principals provides better security, automatic credential rotation, and follows Azure's modern authentication best practices.

**When to Complete**: This is a one-time setup that can be reused across multiple hosted clusters. Complete this before proceeding to Phase 2.

👉 **Guide**: [Create Azure IAM Resources](create-iam-separately.md) - OIDC issuer configuration and workload identity creation

### Phase 2: Management Cluster Setup

**Purpose**: Prepare your Azure OpenShift management cluster to host and manage HyperShift control planes.

This phase installs the HyperShift operator with optional External DNS configuration:

- **DNS Zone Configuration** (Optional): Creates Azure DNS zones for automatic DNS record management
- **External DNS** (Optional): Sets up a service principal and deploys ExternalDNS operator
- **HyperShift Operator**: Installs the HyperShift operator

**Why This Matters**: The HyperShift operator orchestrates the entire lifecycle of hosted control planes. If you choose External DNS, it automatically provisions DNS records for each hosted cluster's endpoints.

**When to Complete**: After Phase 1 is complete, but before creating any hosted clusters.

👉 **Guide**: [Setup Azure Management Cluster for HyperShift](setup-management-cluster.md) - Includes both DNS approaches

### Phase 3: Create Hosted Clusters

**Purpose**: Deploy self-managed Azure hosted clusters with custom networking and configuration.

This phase creates your actual hosted OpenShift clusters:

- **Infrastructure Provisioning**: Creates resource groups, VNets, subnets, and network security groups
- **HostedCluster Creation**: Deploys the control plane on the management cluster and worker nodes in your Azure subscription
- **Workload Identity Integration**: Links the hosted cluster to the workload identities created in Phase 1
- **Private Endpoint Access** (Optional): Configures Azure Private Link for private API server connectivity

**Why This Matters**: This is where you deploy the actual OpenShift clusters that your applications will run on. Each hosted cluster gets its own control plane running on the management cluster and its own set of worker node VMs in Azure. The cluster uses the workload identities from Phase 1 to securely access Azure services without storing credentials.

**When to Complete**: After Phases 1 and 2 are fully configured and verified.

👉 **Guide**: [Create a Self-Managed Azure HostedCluster](create-self-managed-azure-cluster.md) - Includes both DNS approaches

## Prerequisites Summary

Before beginning the deployment process, ensure you have:

- **Azure Resources**:

    - An existing Azure OpenShift management cluster
    - Azure subscription with appropriate permissions (Contributor + User Access Administrator)
    - (Optional) A parent DNS zone in Azure DNS for delegating cluster DNS records (required only if using External DNS)

- **Tools and Access**:

    - Azure CLI (`az`) configured with your subscription
    - OpenShift CLI (`oc`) or Kubernetes CLI (`kubectl`)
    - HyperShift CLI binary
    - `jq` command-line JSON processor
    - Cloud Credential Operator (CCO) tool
    - Valid OpenShift pull secret

- **Permissions**:

    - Subscription-level Contributor and User Access Administrator roles
    - Microsoft Graph API permissions (Application.ReadWrite.OwnedBy) for creating service principals

## Resource Group Strategy

Self-managed Azure deployments use multiple resource groups with different lifecycles:

- **Persistent Resource Group** (e.g., `os4-common`): Long-lived resources shared across multiple clusters

    - Workload identities (managed identities)
    - OIDC issuer storage account
    - Azure DNS zones (if using External DNS)
    - External DNS service principal (if using External DNS)

- **Cluster-Specific Resource Groups**: Created and destroyed with each hosted cluster

    - Managed resource group for cluster infrastructure
    - VNet resource group (if using custom networking)
    - NSG resource group (if using custom networking)

!!! tip "Resource Reuse"

    By placing workload identities and OIDC issuer in a persistent resource group, you can:

    - Reuse the same identities across multiple hosted clusters
    - Avoid recreating federated credentials for each cluster
    - Reduce cluster creation time
    - Simplify cleanup when deleting individual clusters

## Security Considerations

Self-managed Azure HyperShift implements several security best practices:

1. **Workload Identity Federation**: Eliminates long-lived credentials by using OIDC-based authentication
2. **Least Privilege Access**: Each component gets its own managed identity with minimal required permissions
3. **Network Isolation**: Custom VNets and NSGs allow you to implement network segmentation and security policies
4. **Federated Credentials**: Trust relationships are scoped to specific service accounts, preventing unauthorized access
5. **Private Connectivity** (Optional): Azure Private Link provides private API server access, ensuring control plane traffic never traverses the public internet. See [Deploy Azure Private Clusters](deploy-azure-private-clusters.md)

## Next Steps

Begin your self-managed Azure HyperShift deployment by following the guides in order:

1. **[Create Azure IAM Resources](create-iam-separately.md)** - Set up OIDC issuer, managed identities, and workload identity federation
2. **[Setup Azure Management Cluster for HyperShift](setup-management-cluster.md)** - Install HyperShift operator (with or without External DNS)
3. **[Create a Self-Managed Azure HostedCluster](create-self-managed-azure-cluster.md)** - Deploy your first hosted cluster
4. **[Deploy Azure Private Clusters](deploy-azure-private-clusters.md)** (Optional) - Configure private endpoint access with Azure Private Link
5. **[Autoscaling](autoscaling-self-managed.md)** - Configure node pool and cluster autoscaling
6. **[Etcd Snapshot Backup](backup-and-restore-etcd-snapshot.md)** (Optional) - Configure etcd backup with Azure Blob Storage

Each guide includes sections for both DNS approaches - simply follow the sections that match your choice.

## Additional Resources

- [Azure Workload Identity Documentation](https://azure.github.io/azure-workload-identity/docs/)
- [HyperShift Architecture Reference](../../reference/architecture/index.md)
- [Managed Azure Documentation](../azure/create-azure-cluster-on-aks.md) - For comparison with AKS-based deployments
