Skip to main content

Azure Setup Guide

This guide walks you through setting up Orchestr8 on Microsoft Azure using Azure Kubernetes Service (AKS).

Prerequisites​

CLI Tool Requirements​

Before deploying to Azure, ensure you have the required command-line tools. See the Prerequisites Guide for complete installation instructions for all tools.

Required for Azure:

  • Core tools: kubectl, helm, git (required for all providers)
  • Azure-specific: az CLI for authentication and management
  • Optional: terraform (required for infrastructure provisioning)

Quick Verification:

# Verify all required tools are installed
o8 doctor --verbose

# Show installation instructions for missing tools
o8 doctor --fix

Azure Requirements​

  • Active Azure subscription
  • Sufficient quota for:
    • AKS cluster (minimum 2 system nodes + 3 user nodes)
    • Virtual Network and subnets
    • Azure Key Vault
    • Azure Container Registry (optional)
    • Public IP addresses (for load balancers)

Quick Start​

1. Run the Setup Script​

For Windows PowerShell:

.\scripts\setup-azure-auth.ps1

This script will:

  • Check Azure CLI installation
  • Authenticate with Azure
  • Create a resource group
  • Create an Azure Key Vault
  • Set up environment variables
  • Optionally create a service principal

2. Bootstrap AKS Cluster​

Create an AKS cluster with O8:

o8 bootstrap create azure \
  --cluster-name orchestr8-cluster \
  --resource-group orchestr8-resources \
  --location eastus2

This command will:

  • Create a Virtual Network with proper subnets
  • Deploy an AKS cluster with system and user node pools
  • Enable Azure AD RBAC
  • Enable Workload Identity for secure pod authentication
  • Create an Azure Container Registry
  • Set up Azure Key Vault for secrets management

3. Install O8 Platform​

Once the cluster is ready, install the O8 platform:

o8 setup --provider azure --domain your-domain.com

Manual Setup​

Step 1: Azure Authentication​

Login to Azure:

az login

Set your subscription:

az account set --subscription <SUBSCRIPTION_ID>

Step 2: Create Resource Group​

az group create \
  --name orchestr8-resources \
  --location eastus2 \
  --tags managed-by=orchestr8 environment=production

Step 3: Create AKS Cluster with Terraform​

O8 uses Terraform to provision Azure infrastructure. The configuration includes:

# terraform/infrastructure/azure/aks/main.tf
resource "azurerm_kubernetes_cluster" "main" {
  name                = var.cluster_name
  location            = var.location
  resource_group_name = var.resource_group_name
  dns_prefix          = var.cluster_name

  # Workload Identity for pod authentication
  oidc_issuer_enabled       = true
  workload_identity_enabled = true

  # Azure AD integration
  azure_active_directory_role_based_access_control {
    managed            = true
    azure_rbac_enabled = true
  }
}

Apply the Terraform configuration:

cd terraform/infrastructure/azure
terraform init
terraform plan
terraform apply

Step 4: Get AKS Credentials​

az aks get-credentials \
  --name orchestr8-cluster \
  --resource-group orchestr8-resources \
  --overwrite-existing

Step 5: Create Azure Key Vault​

az keyvault create \
  --name orchestr8-kv-$RANDOM \
  --resource-group orchestr8-resources \
  --location eastus2 \
  --enable-rbac-authorization true \
  --enable-soft-delete true \
  --retention-days 7

Azure-Specific Configuration​

Workload Identity​

O8 uses Azure AD Workload Identity for secure pod-to-Azure resource authentication:

  1. ArgoCD Identity: For GitOps operations
  2. External Secrets Identity: For Key Vault access
  3. Cert Manager Identity: For DNS challenges

Each identity is automatically configured during bootstrap.

Networking Architecture​

The default network configuration:

  • VNet CIDR: 10.0.0.0/16
  • AKS Subnet: 10.0.1.0/22 (1024 IPs)
  • Application Gateway Subnet: 10.0.5.0/24 (optional)
  • Service CIDR: 10.0.0.0/16
  • DNS Service IP: 10.0.0.10

Storage​

O8 on Azure uses:

  • Azure Disks: For persistent volumes (managed disks)
  • Azure Files: For shared storage (optional)
  • Azure Blob Storage: For Terraform state and backups

Secrets Management​

Using Azure Key Vault​

Initialize secrets management:

o8 secrets init --provider azure --key-vault <YOUR_KEY_VAULT_NAME>

Create a secret:

o8 secrets create database-password \
  --provider azure \
  --data '{"password": "secure-password-123"}'

List secrets:

o8 secrets list --provider azure

Get a secret:

o8 secrets get database-password --provider azure

External Secrets Integration​

O8 automatically configures External Secrets Operator to sync Azure Key Vault secrets to Kubernetes:

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: azure-vault
spec:
  provider:
    azurekv:
      vaultUrl: "https://<KEY_VAULT_NAME>.vault.azure.net"
      authType: WorkloadIdentity
      serviceAccountRef:
        name: external-secrets

Cost Optimization​

Recommendations​

  1. Use Spot Instances: For non-critical workloads

    o8 bootstrap create azure --use-spot-instances

  2. Auto-scaling: Configured by default (2-10 nodes)

  3. Reserved Instances: For production workloads

  4. Resource Tagging: All resources are tagged for cost tracking

Cost Estimation​

Typical monthly costs (East US 2):

  • AKS Cluster: Free (pay only for nodes)
  • Nodes (D4s_v3 x 5): ~$350-500
  • Load Balancer: ~$25
  • Key Vault: ~$5
  • Storage: ~$20-50

Total: ~$400-600/month for a basic setup

Troubleshooting​

Common Issues​

1. Authentication Failures​

# Refresh Azure CLI credentials
az login --tenant <TENANT_ID>

# Check current context
az account show

2. Insufficient Quota​

# Check quota usage
az vm list-usage --location eastus2 --output table

# Request quota increase via Azure Portal

3. Network Connectivity​

# Test cluster connectivity
kubectl cluster-info

# Check AKS diagnostics
az aks show --name orchestr8-cluster --resource-group orchestr8-resources

4. Key Vault Access​

# Check Key Vault permissions
az keyvault show --name <KEY_VAULT_NAME>

# Verify managed identity
az identity show --name orchestr8-cluster-external-secrets-identity \
  --resource-group orchestr8-resources

Getting Help​

# Check O8 status
o8 doctor --provider azure

# View AKS cluster logs
az aks get-credentials --name orchestr8-cluster --resource-group orchestr8-resources
kubectl logs -n kube-system -l component=kube-apiserver

# Azure support
az feedback

Clean Up​

To remove all Azure resources:

# Destroy the cluster
o8 bootstrap destroy azure

# Or manually delete the resource group
az group delete --name orchestr8-resources --yes --no-wait

Next Steps​

  1. Configure DNS for your domain
  2. Deploy your first module
  3. Set up monitoring and observability
  4. Configure backups and disaster recovery

Additional Resources​