Azure AKS Cluster Setup

This guide covers setting up an Azure Kubernetes Service (AKS) cluster for CIVITAS/CORE remote deployment.

Overview

Azure Kubernetes Service (AKS) provides a managed Kubernetes environment that simplifies cluster management while providing the scalability and reliability needed for production CIVITAS/CORE deployments.

Prerequisites

Azure Account Requirements

• Azure Subscription: Active Azure subscription with sufficient credits/budget
• Permissions: Subscription Contributor or Owner role to create resources
• Resource Limits: Ensure subscription limits allow for required VM sizes
• Regional Availability: Verify AKS availability in your preferred region

Control System Requirements

Your local machine needs:

• Azure CLI: For managing Azure resources
• kubectl: Kubernetes command-line tool
• helm: Package manager for Kubernetes
• Internet Access: For downloading tools and accessing Azure services

Azure Environment Setup

Install Azure CLI

Windows:

winget install -e --id Microsoft.AzureCLI

macOS:

brew update
brew install azure-cli

Linux (Ubuntu/Debian):

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Authenticate with Azure

Login to your Azure account:

az login

This opens a browser window for authentication. After successful login, verify your subscription:

az account show
az account list --output table

Set the correct subscription if you have multiple:

az account set --subscription "your-subscription-id"

Register Required Resource Providers

Azure resource providers must be registered for AKS and compute resources:

# Check current registration status
az provider show --namespace Microsoft.ContainerService --query "registrationState"
az provider show --namespace Microsoft.Compute --query "registrationState"

# Register if not already registered
az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.Compute

# Wait for registration to complete
az provider show --namespace Microsoft.ContainerService --query "registrationState"

AKS Cluster Creation

Create Resource Group

Create a resource group to organize your Azure resources:

# Choose an appropriate location near your users
az group create --name civitas-core --location germanywestcentral

Available regions include:

• germanywestcentral - Germany West Central
• westeurope - West Europe
• eastus - East US
• westus2 - West US 2

Create AKS Cluster

Create the AKS cluster with appropriate sizing:

Development/Testing Cluster:

az aks create \
  --resource-group civitas-core \
  --name civitas-core-dev \
  --node-count 2 \
  --node-vm-size Standard_D8s_v3 \
  --generate-ssh-keys \
  --enable-managed-identity \
  --network-plugin azure

Production Cluster:

az aks create \
  --resource-group civitas-core \
  --name civitas-core-prod \
  --node-count 3 \
  --node-vm-size Standard_D16s_v3 \
  --generate-ssh-keys \
  --enable-managed-identity \
  --network-plugin azure \
  --enable-cluster-autoscaler \
  --min-count 3 \
  --max-count 10

VM Size Recommendations:

Use Case	VM Size	vCPUs	Memory	Description
Development	Standard_D8s_v3	8	32 GB	Minimal for testing
Production	Standard_D16s_v3	16	64 GB	Recommended for production
High Memory	Standard_E16s_v3	16	128 GB	Memory-intensive workloads
Compute Intensive	Standard_F16as_v6	16	64 GB	CPU-intensive workloads

Add Additional Node Pools (Optional)

For workload separation or specialized requirements:

az aks nodepool add \
  --resource-group civitas-core \
  --cluster-name civitas-core-prod \
  --name workerpool \
  --node-count 2 \
  --node-vm-size Standard_D8s_v3

Cluster Configuration

Configure kubectl Access

Download cluster credentials and configure kubectl:

az aks get-credentials --resource-group civitas-core --name civitas-core-prod

Verify cluster access:

kubectl get nodes
kubectl cluster-info

Install NGINX Ingress Controller

Add the ingress-nginx Helm repository:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

Install the ingress controller:

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.allowSnippetAnnotations=true \
  --set controller.publishService.enabled=true \
  --set controller.service.externalTrafficPolicy=Local \
  --set controller.replicaCount=2

Wait for the external IP to be assigned:

kubectl get svc -n ingress-nginx --watch

Install Cert-Manager

Add the cert-manager Helm repository:

helm repo add jetstack https://charts.jetstack.io
helm repo update

Install cert-manager:

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.17.0 \
  --set crds.enabled=true

Verify cert-manager installation:

kubectl get pods -n cert-manager

DNS and SSL Configuration

Configure DNS

Get the external IP address of your ingress controller:

kubectl get svc -n ingress-nginx ingress-nginx-controller

Update your DNS provider to create an A record:

• Record Type: A
• Name: *.your-domain.com (wildcard recommended)
• Value: External IP from above command
• TTL: 300 (5 minutes)

SSL Certificate Setup

Let's Encrypt cluster issuers will be configured automatically by the CIVITAS/CORE platform deployment. Ensure your domain is internet-accessible for certificate validation.

Verification

Test Cluster Readiness

Verify all components are running:

# Check node status
kubectl get nodes

# Verify ingress controller
kubectl get pods -n ingress-nginx

# Check cert-manager
kubectl get pods -n cert-manager

# Test DNS resolution
nslookup your-domain.com

Resource Verification

Check available resources:

kubectl top nodes
kubectl describe nodes

Troubleshooting

Common Issues

Cluster Creation Fails

• Verify subscription limits and quotas
• Check resource provider registration
• Ensure sufficient permissions

Ingress Controller Issues

• Verify LoadBalancer service has external IP
• Check Azure Load Balancer in Azure Portal
• Ensure network security groups allow traffic

DNS Resolution Problems

• Verify A record points to correct external IP
• Check DNS propagation with online tools
• Confirm domain is internet-accessible

Certificate Issues

• Ensure domain is publicly accessible
• Check Let's Encrypt rate limits
• Verify cert-manager logs: kubectl logs -n cert-manager deployment/cert-manager

Cost Optimization

Development Environments

• Use smaller VM sizes (Standard_D8s_v3)
• Enable cluster autoscaler with low minimum
• Consider Azure Dev/Test pricing
• Stop clusters when not in use

Production Environments

• Use Reserved Instances for predictable workloads
• Enable cluster autoscaler for dynamic scaling
• Monitor and optimize resource requests/limits
• Consider spot instances for non-critical workloads

Security Considerations

Network Security

• Enable network policies for pod-to-pod communication
• Use Azure Private Link for enhanced security
• Configure appropriate network security groups

Access Control

• Enable Azure AD integration for RBAC
• Use managed identities for service access
• Implement least privilege access principles

Next Steps

Once your AKS cluster is ready and verified:

1. Configure Settings: Use Inventory Configuration Guide with local preset
2. Install Platform: Follow Platform Installation Guide
3. Set Domain: Configure your domain in the cc_cli wizard
4. Deploy: Execute cc_cli exec to deploy the platform

Your AKS cluster is now ready for CIVITAS/CORE platform deployment using the unified cc_cli workflow.

Azure-Specific Configuration Notes

When using the cc_cli wizard, use these Azure-specific settings:

• Domain: Your internet-accessible domain
• Environment: prod, dev, or custom identifier
• Ingress Class: nginx
• Storage Class: default or managed-premium
• Let's Encrypt: Enable for automatic SSL certificates