Chapter 20 · Azure Kubernetes App Deploy

Subchapter 20.12

Deploy

Python

Rust

Deploy

templates/k8s/11 files

12 more in the appendix

Next Configmap

Source

templates/github-actions/deploy.yml

YAML194 lines7 KB

1# GitHub Actions workflow: Deploy to AKS
2#
3# This workflow builds a container image, pushes it to Azure Container Registry,
4# and deploys it to an Azure Kubernetes Service cluster.
5#
6# Authentication uses OIDC federation (workload identity) — no stored passwords.
7# Required GitHub secrets: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID
8#
9# Placeholders to replace (uses __DOUBLE_UNDERSCORE__ style; K8s templates use angle-bracket style):
10#   __ACR_NAME__    — Azure Container Registry name (e.g. myappacr)
11#   __AKS_CLUSTER__ — AKS cluster name (e.g. myapp-aks)
12#   __RG_NAME__     — Azure resource group containing ACR and AKS
13#   __APP_NAME__    — Application / deployment name in Kubernetes
14#   __NAMESPACE__   — Kubernetes namespace to deploy into

deploy.yml on GitHub

name: Deploy to AKS

on:

# Trigger on push to main branch (app code changes only)

push:

branches:

- main

paths-ignore:

- 'docs/**'

- '*.md'

- '.github/**'

- '.vscode/**'

# Allow manual trigger from the Actions tab

workflow_dispatch:

# OIDC federation requires these permissions so GitHub can issue

# an ID token that Microsoft Entra ID will accept.

permissions:

id-token: write # Required for requesting the JWT

contents: read # Required for actions/checkout

# Prevent parallel deployments on the same branch.

# Uses workflow + ref so staging and production runs can proceed independently.

# cancel-in-progress: false ensures the running deploy finishes

# before the queued deploy starts (avoids mid-rollout conflicts).

# Note: env context is not available here — use github or vars contexts only.

concurrency:

group: ${{ github.workflow }}-${{ github.ref_name }}

cancel-in-progress: false

env:

ACR_NAME: __ACR_NAME__

AKS_CLUSTER: __AKS_CLUSTER__

RESOURCE_GROUP: __RG_NAME__

APP_NAME: __APP_NAME__

NAMESPACE: __NAMESPACE__

defaults:

run:

shell: bash

jobs:

build-and-deploy:

runs-on: ubuntu-latest

steps:

- name: Checkout repository

uses: actions/checkout@v4

# -----------------------------------------------------------

# Validate that no placeholders remain unreplaced

#

# Checks for __PLACEHOLDER__ and <placeholder> patterns in

# env vars and k8s/ directory. Fails fast with clear error

# if any found.

# -----------------------------------------------------------

- name: Validate — no unreplaced placeholders

run: |

PLACEHOLDERS_FOUND=0

# Check env variables

for VAR in ACR_NAME AKS_CLUSTER RESOURCE_GROUP APP_NAME NAMESPACE; do

VALUE="${!VAR}"

if [[ "$VALUE" =~ __[A-Z_]+__ ]]; then

echo "❌ Placeholder found in \$${VAR}: ${VALUE}"

PLACEHOLDERS_FOUND=1

fi

done

# Check k8s/ directory if it exists

if [ -d k8s ]; then

# __PLACEHOLDER__ style (env var style used in this workflow)

if grep -rq '__[A-Z_]\+__' k8s/; then

echo "❌ Placeholders found in k8s/ manifests:"

grep -rn '__[A-Z_]\+__' k8s/ || true

PLACEHOLDERS_FOUND=1

fi

# <placeholder> style (angle-bracket style used in K8s manifest templates).

# Exclude <image>: it is intentionally left in place here and replaced

# with the SHA-tagged image in the "Substitute image tag" step below.

if grep -rnP '<[a-z][a-z0-9-]*>' k8s/ | grep -vq '<image>'; then

echo "❌ Angle-bracket placeholders found in k8s/ manifests:"

grep -rnP '<[a-z][a-z0-9-]*>' k8s/ | grep -v '<image>' || true

PLACEHOLDERS_FOUND=1

fi

if [ $PLACEHOLDERS_FOUND -eq 1 ]; then

echo ""

echo "⚠️ Workflow failed: unreplaced placeholders detected."

echo "Replace the following in your deploy.yml:"

echo " - __ACR_NAME__ → Your Container Registry name"

echo " - __AKS_CLUSTER__ → Your AKS cluster name"

echo " - __RG_NAME__ → Your resource group name"

echo " - __APP_NAME__ → Your application name"

echo " - __NAMESPACE__ → Your Kubernetes namespace"

exit 1

fi

echo "✓ All placeholders replaced"

# -----------------------------------------------------------

# Authenticate to Azure using OIDC (workload identity)

#

# This exchanges the GitHub-issued OIDC token for an Azure

# access token — no client secret required.

# -----------------------------------------------------------

- name: Azure Login (OIDC)

uses: azure/login@v2

with:

client-id: ${{ secrets.AZURE_CLIENT_ID }}

tenant-id: ${{ secrets.AZURE_TENANT_ID }}

subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

# -----------------------------------------------------------

# Build container image and push to ACR

#

# `az acr build` runs the Docker build remotely on ACR,

# so no local Docker daemon is needed. The image is tagged

# with the commit SHA for traceability.

# -----------------------------------------------------------

- name: Build and push image to ACR

run: |

az acr build \

--registry ${{ env.ACR_NAME }} \

--image ${{ env.APP_NAME }}:${{ github.sha }} \

.

- name: Set AKS context

uses: azure/aks-set-context@v4

with:

resource-group: ${{ env.RESOURCE_GROUP }}

cluster-name: ${{ env.AKS_CLUSTER }}

# -----------------------------------------------------------

# Deploy to AKS

#

# Applies all K8s resources (with substituted image tag),

# then waits for the rollout to complete successfully.

# Sets a step output flag used to gate the rollback step.

# -----------------------------------------------------------

- name: Substitute image tag in manifests

env:

IMAGE: ${{ env.ACR_NAME }}.azurecr.io/${{ env.APP_NAME }}:${{ github.sha }}

run: |

if [ ! -d k8s ]; then

echo "❌ k8s/ directory not found — cannot deploy without manifests"

exit 1

fi

# Use xargs to preserve sed exit codes (find|while swallows them)

find k8s -name "*.yaml" -o -name "*.yml" \

| xargs -I{} sed -i "s|<image>|${IMAGE}|g" "{}"

echo "✓ Image tag substituted in all manifests"

- name: Deploy to AKS

id: deploy

run: |

# Ensure the namespace exists before applying manifests

kubectl create namespace ${{ env.NAMESPACE }} --dry-run=client -o yaml \

| kubectl apply -f -

kubectl apply -f k8s/ --namespace ${{ env.NAMESPACE }}

kubectl rollout status deployment/${{ env.APP_NAME }} \

--namespace ${{ env.NAMESPACE }} \

--timeout=300s

# Signal that the deployment was applied — used to gate rollback

echo "deployed=true" >> "$GITHUB_OUTPUT"

- name: Rollback on failure

if: failure() && steps.deploy.outputs.deployed == 'true'

run: |

kubectl rollout undo deployment/${{ env.APP_NAME }} \

--namespace ${{ env.NAMESPACE }}

kubectl rollout status deployment/${{ env.APP_NAME }} \

--namespace ${{ env.NAMESPACE }} \

--timeout=120s

echo "⚠️ Rolled back to previous revision"