DEV Community: Rahimah Sulayman

Inside the AWS Default VPC (and Why You'll Want Your Own)

Rahimah Sulayman — Sun, 15 Nov 2026 19:30:23 +0000

Introduction: A guided tour of the default VPC that comes with every AWS account: subnets, route table, internet gateway, NACL and security group. Then how to create your own VPC.

Every AWS account comes with a network you never asked for. It's already there, already wired to the internet, and it's the reason your first EC2 instance "just worked." It's called the default VPC.

Before building a VPC from scratch, it helps to know what AWS builds for you. So this article is a tour: first the default VPC and everything attached to it, then how to create your own. By the end, you'll know what each piece does and how they connect.

What's a VPC?

A Virtual Private Cloud (VPC) is your own isolated network inside AWS. You choose its IP range, split it into subnets, and control what can talk to what. A VPC lives in one region, and mine is in Europe (Stockholm) eu-north-1.

Coming from Azure? A VPC is the equivalent of a VNet, and both live in a single region. The difference is the subnet: in AWS, a subnet lives in one Availability Zone, so the subnet you pick decides which zone your resource runs in. In Azure, a subnet spans the whole region and you choose the zone per resource.

Meet the default VPC

In the console, search for VPC and open Your VPCs. My account lists exactly one, and the Default VPC column says Yes.

A few things stand out:

IPv4 CIDR 172.31.0.0/16: the range of private IP addresses this network can hand out. The /16 means 65,536 addresses.
Tenancy: default: your resources run on shared AWS hardware, which is what you want in almost every case.
Main route table and Main network ACL: two IDs we'll visit shortly.

Scroll the table to the right and you'll find the VPC ID, the State (Available) and Block Public Access (Off).

Select the row and a details panel opens at the bottom. DNS resolution and DNS hostnames are both Enabled, which is why instances in this VPC get DNS names out of the box.

For the big picture, click the VPC ID and open the Resource map tab. It shows 3 subnets, 1 route table and 1 network connection, which is an internet gateway. Everything below is just us zooming into this map.

Subnets: one per Availability Zone

Open Subnets in the left menu. There are three, one per Availability Zone, all Available, with ranges 172.31.0.0/20, 172.31.16.0/20 and 172.31.32.0/20. Each /20 holds 4,096 addresses.

Open one and check its details:

Availability Zone: eu-north-1b. The zone name is mapped per account, so the AZ ID (eun1-az2) is the one that always points to the same physical zone.
Available IPv4 addresses: 4091. AWS reserves 5 addresses in every subnet.
Default subnet: Yes and Auto-assign public IPv4 address: Yes. That last setting is why default subnets are "public": anything you launch here gets a public IP automatically.

The route table: how traffic finds its way

Still inside the subnet, click the Route table tab. There are only two routes:

172.31.0.0/16 → local: traffic inside the VPC stays inside the VPC.
0.0.0.0/0 → igw-...: everything else goes to the internet gateway.

That second route is what makes a subnet public. Open Route tables in the left menu to see the table itself. It's marked Main: Yes, and it has no explicit subnet associations. Subnets without an explicit association automatically use the main route table.

The internet gateway: the door

Under Internet gateways, you'll find one, with its state set to Attached to our VPC. Think of it this way: the gateway is the door, and the route is the sign pointing to it. Without both, nothing reaches the internet.

Two layers of firewall: NACL and security group

Back on the subnet, the Network ACL tab says this subnet uses the VPC's default network ACL. Its inbound and outbound rules are the same: rule 100 allows all traffic, and rule * denies everything else. Rules are checked from the lowest number up, so the allow always wins and the deny never triggers.

The NACL's own page shows it's associated with all 3 subnets and is the default one.

Then there's the default security group. Its outbound rule allows all traffic to anywhere (0.0.0.0/0), so anything inside can reach out freely.

The difference between the two:

A network ACL works at the subnet level and is stateless: return traffic needs its own rule.
A security group works at the resource level (like an instance) and is stateful: return traffic is allowed automatically.

Azure comparison: both roles are played by Network Security Groups (NSGs), which can be attached to a subnet or to a network interface.

Create your own VPC

Now the fun part. Here are the steps:

Open VPC > Your VPCs and click Create VPC.

Under Resources to create, pick one of two options:
- VPC and more: a wizard that builds the VPC, subnets, route tables and more in one go. The preview shows project-vpc, 4 subnets across 2 AZs and 3 route tables, with a default range of 10.0.0.0/16. It's quick and convenient.
- VPC only: just the network itself, with nothing else. I chose this one, because I want to build each piece by hand.

Fill in the form. I set the Name tag to test, chose IPv4 CIDR manual input with 192.168.0.0/16, selected No IPv6 CIDR block, and kept Tenancy on Default. I left VPC encryption control on None, because the other modes carry additional charges.
Click Create VPC.

Picking a CIDR: the block size must be between /16 and /28. Choose a range that doesn't overlap with your other networks (this is why I avoided 172.31.0.0/16), because overlapping ranges make peering or VPN connections painful later.

What you actually get

AWS confirms with a green banner, and the details tell the story. Compared to the default VPC, Default VPC is now No, and DNS hostnames is Disabled.

The Resource map is nearly empty:

Subnets (0)
Route tables (1): the main route table AWS creates automatically
Network connections (0)

There are no subnets and no internet gateway, so nothing can run in this VPC yet and nothing can reach the internet. To prove the new VPC didn't sneak any subnets in, I opened Subnets again: the list still shows only the 3 default ones.

Conclusion

The default VPC is a ready-made network: one subnet per AZ, a route to an internet gateway, and permissive default rules.
A subnet is public because its route table points to an internet gateway, not because of its name.
NACLs guard subnets (stateless), and security groups guard resources (stateful).
VPC only gives you an empty shell, while VPC and more builds a full layout for you.
A new VPC starts with no subnets, so nothing can be deployed into it yet.

NOTE: The number of default subnets equals the number of Availability Zones in the region, so it varies by region.
My region is Stockholm (eu-north-1), which has 3 AZs, so you get 3 default subnets.
N. Virginia (us-east-1) has 6 AZs, so its default VPC has 6 default subnets. Most tutorials and screenshots use that region.
Other regions have 2, 3 or 4 AZs, so the count differs again.
A default VPC is per region. Every region has its own, each with its own 172.31.0.0/16 range. If you switch the region selector in the top bar, you’ll see a different default VPC and a different set of default subnets.
You can check this by switching to N. Virginia and opening Subnets. You should see 6, one for each AZ.

Next up in this series, I'll create subnets inside this new VPC and start turning an empty network into a working one.

Which would you rather see after that: an internet gateway and public subnet, or a private subnet with a NAT gateway? Let me know in the comments.

Building an Automated CI/CD Pipeline with GitHub Actions: From Testing to Continuous Deployment

Rahimah Sulayman — Tue, 10 Nov 2026 08:17:51 +0000

Introduction

Modern software delivery requires more than writing code and pushing it to a repository. Applications need reliable processes for testing, building, and deploying changes with minimal manual intervention.

In this project, I built an automated CI/CD pipeline using GitHub Actions. What started as a basic workflow evolved into a multi-stage pipeline that validates repository changes, executes a custom reusable composite action, generates a dynamic status card, and deploys a website to GitHub Pages.

During implementation, I encountered and resolved several issues, including a Bash syntax error, an intentional CI validation failure, a temporary GitHub Actions server error, and a YAML configuration mistake.

This article documents the implementation, troubleshooting process, and final deployment.

Project Overview

The objective was to build a working CI/CD pipeline that automates repository validation, website generation, and deployment.

The project covered five major areas:

Creating a GitHub repository and configuring a basic workflow.
Implementing automated repository checks.
Building and integrating a custom GitHub composite action.
Creating a multi-stage CI/CD pipeline.
Deploying the generated website to GitHub Pages.

Technologies used:

Git and GitHub
GitHub Actions
YAML
Bash
HTML and CSS
GitHub Pages

1. Repository Setup and the First GitHub Actions Workflow

I started by creating a public GitHub repository named pipeit-tutorial.

The first task was to establish a basic GitHub Actions workflow and understand how workflow execution is triggered by repository events.

I created .github/workflows/hello.yml:

name: hello

on:
  push:
  workflow_dispatch:

jobs:
  say-hello:
    runs-on: ubuntu-latest
    steps:
      - name: Say hello
        run: echo "Hello! My first robot is working."

      - name: Show the date and time
        run: date

The workflow runs whenever code is pushed to the repository. I also included workflow_dispatch, which allows it to be started manually from the GitHub Actions interface.

After committing and pushing the file, GitHub Actions detected the workflow and executed its job on an Ubuntu runner.

The workflow successfully printed the greeting and displayed the execution date and time.

This established the foundation for the automation that followed.

In addition to automatic execution on code pushes, I tested the pipeline using GitHub Actions' manual trigger (workflow_dispatch).

Steps followed:

Opened the pipeit-tutorial repository on GitHub.
Navigated to the Actions tab.
Selected the hello workflow from the workflow list.
Clicked Run workflow.
Selected the main branch.
Clicked Run workflow to initiate execution.

Opened the resulting workflow run to inspect the execution logs.

Verified that all steps completed successfully, displaying the greeting message and execution date and time.

This confirmed that the workflow could be triggered on demand without requiring a new code push.

The workflow_dispatch event provides flexibility by allowing workflows to be executed manually whenever needed, alongside their automated triggers.

2. Implementing Continuous Integration Checks

The next objective was to introduce a basic validation process.

A CI pipeline should not simply execute commands, it should also verify that repository changes meet defined requirements.

For this project, I created a Bash script to check whether the README file contained a Markdown heading.

I created tests/check.sh:

#!/usr/bin/env bash

set -e

if grep -q '^#' README.md; then
    echo "✅ README has a title"
else
    echo "❌ README.md needs a title line that starts with #"
    exit 1
fi

The script checks whether the README contains a Markdown heading. If the heading exists, the check passes. Otherwise, the script prints an error message and exits with a non-zero status.

I then created .github/workflows/ci.yml:

name: ci

on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Get my code
        uses: actions/checkout@v4

      - name: Run my checks
        run: bash tests/check.sh

This workflow runs on both pushes and pull requests.

The actions/checkout step retrieves the repository contents so that the runner can access the files. The next step executes the Bash validation script.

Testing the Failure Scenario

To verify that the validation was meaningful, I deliberately removed the Markdown heading from the README file and pushed the change.

The workflow failed as expected.

The log displayed:

❌ README.md needs a title line that starts with #

This confirmed that the pipeline was enforcing the condition defined in the test script.

I restored the README heading and pushed the correction. The next CI execution passed successfully.

A useful CI pipeline must be capable of detecting invalid changes rather than simply reporting success.

3. Creating a Custom GitHub Composite Action

After establishing the CI checks, I moved on to reusable automation.

GitHub Actions supports custom actions, allowing teams to package repeated workflow steps into reusable components.

For this project, I created a custom composite action that generates a dynamic HTML status card.

The action was created in .github/actions/build-card/action.yml.

It accepts a name and an optional message, generates a website inside the site directory, and writes a summary to the GitHub Actions run page.

The generated page includes information about the build, such as the commit reference, workflow run number, triggering event, and build time.

The action uses a Bash script and an HTML template to generate the page dynamically. One important implementation detail was the use of an unquoted heredoc (<<EOF) so that shell variables could be expanded while generating the HTML.

I also configured the action to expose the generated page path as an output.

Integrating the Custom Action into the CI Workflow

Once the composite action was created, I integrated it into the existing CI workflow.

The additional step was:

- name: Try my own action
  uses: ./.github/actions/build-card
  with:
    name: Rahimah Sulayman

This allowed the workflow to invoke the action directly from the repository.

After pushing the changes, the CI workflow executed successfully. The custom action generated the HTML status card and displayed its summary in the workflow run.

I also corrected the generated page footer to:

<p>Built with GitHub Actions</p>

This demonstrated how reusable composite actions can simplify workflows and package related operations into a single component.

4. Building the Complete CI/CD Pipeline

With the validation script and custom action working, I moved on to the main pipeline.

The goal was to combine testing, website generation, and deployment into a single automated workflow.

Before configuring deployment, I enabled GitHub Pages in the repository settings and selected GitHub Actions as the deployment source.

I then created .github/workflows/pipeline.yml.

The workflow was configured with three jobs:

test: checks the repository.
build: generates the website and packages it for deployment.
deploy: publishes the website to GitHub Pages.

The pipeline also included a scheduled trigger and a manual trigger.

Pipeline Configuration

The workflow uses the following structure:

name: pipeline

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 8 * * *'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Run my checks
        run: bash tests/check.sh

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Build my status card with my own action
        uses: ./.github/actions/build-card
        with:
          name: Rahimah Sulayman
          message: Updated automatically through continuous deployment

      - name: Package the website
        uses: actions/upload-pages-artifact@v5
        with:
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Publish to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Understanding the Job Dependencies

One important feature of this pipeline is the use of the needs keyword.

The build job depends on the successful completion of the test job:

build:
  needs: test

Similarly, deployment depends on the build job:

deploy:
  needs: build

This establishes the execution order:

Test → Build → Deploy

The deployment process cannot proceed unless the preceding stages complete successfully.

The workflow also defines permissions required for GitHub Pages deployment:

permissions:
  contents: read
  pages: write
  id-token: write

The concurrency configuration ensures that only the relevant Pages deployment workflow runs at a time, cancelling an older in-progress run when a newer one takes its place.

The scheduled trigger runs the pipeline daily at 08:00 UTC, while workflow_dispatch allows manual execution.

5. Deploying the Website to GitHub Pages

After configuring the pipeline, I pushed the workflow to the repository.

GitHub Actions executed the three jobs in sequence.

The test job validated the repository, the build job generated the website and packaged the site directory, and the deploy job published the artifact to GitHub Pages.

The workflow completed successfully.

The deployed website was available at:

https://rahimahisah17.github.io/pipeit-tutorial/

At this point, the project had moved beyond basic CI automation. It now had a workflow that could validate changes, generate a website, and deploy the result.

6. Verifying Automatic Deployment

A successful initial deployment was not enough. I also needed to confirm that subsequent changes would automatically reach the live website.

To test this, I updated the custom action's message input in the pipeline:

message: Updated automatically through continuous deployment

I committed and pushed the change to the main branch.

This triggered the pipeline automatically.

GitHub Actions executed the test, build, and deployment jobs again. After the deployment completed, I refreshed the live website and confirmed that the updated content was visible.

This verified the continuous deployment process.

The final workflow supported both initial publication and automatic updates whenever changes were pushed to the configured branch.

7. Troubleshooting and Lessons Learned

The implementation was not entirely error-free. Several issues occurred during development, and resolving them was an important part of completing the project.

Issue 1: Bash Syntax Error

During the initial implementation of tests/check.sh, the conditional statement contained a syntax error.

The script did not execute as expected because the if statement was not structured correctly.

I corrected the conditional block and ensured that the then, else, and fi keywords were properly placed.

The corrected script subsequently executed successfully.

Lesson: Shell scripts require careful attention to syntax. A small structural mistake can cause an entire CI job to fail.

Issue 2: Deliberate README Validation Failure

I intentionally removed the heading from the README to test whether the CI workflow could detect an invalid repository change.

The workflow failed and displayed the expected validation message.

This was not an unexpected pipeline defect. It was a controlled test to confirm that the validation script was working.

After restoring the heading, the workflow passed.

Lesson: Testing failure conditions is just as important as testing successful execution. A pipeline should fail when its defined requirements are not met.

Issue 3: GitHub Actions Internal Server Error

During the execution of the initial workflow, GitHub Actions returned a temporary internal server error.

The issue was not caused by the repository's workflow configuration.

I reran the failed jobs, and the workflow completed successfully.

Lesson: Not every CI/CD failure originates from application code or configuration. External platform issues can also affect workflow execution, so it is important to inspect the error details before changing working code.

Issue 4: Duplicate YAML Key

While updating the message passed to the custom action, I accidentally introduced a duplicate key:

message: message: Updated automatically through continuous deployment

This resulted in a YAML configuration error.

I corrected the line to:

message: Updated automatically through continuous deployment

After committing the correction, the pipeline executed successfully.

Lesson: YAML configuration must be structured carefully. Duplicate or incorrectly formatted keys can prevent a workflow from being parsed and executed.

8. Repository Structure

The completed repository is organized as follows:

pipeit-tutorial/
│
├── .github/
│   ├── actions/
│   │   └── build-card/
│   │       └── action.yml
│   │
│   └── workflows/
│       ├── hello.yml
│       ├── ci.yml
│       └── pipeline.yml
│
├── tests/
│   └── check.sh
│
├── README.md
└── site/
    └── index.html

The site/index.html file is generated by the custom action during the build process.

The repository structure separates workflow definitions, reusable actions, validation scripts, documentation, and generated website content.

9. Project Release and Documentation

After completing the implementation, I updated the repository documentation to explain the project, its architecture, technologies, and deployment process.

I also published a GitHub release:

Release: v1.0.0

This release marks the completed version of the project and provides a reference point for the implementation.

The repository includes the workflow definitions, custom composite action, validation script, and documentation required to understand how the pipeline works.

10. What This Project Demonstrates

The project provided practical experience with several important DevOps and CI/CD concepts:

Continuous Integration: Automatically validating repository changes through GitHub Actions.
Workflow Triggers: Running automation in response to pushes, scheduled events, and manual requests.
Reusable Automation: Packaging repeated operations into a custom composite action.
Job Dependencies: Controlling pipeline execution using needs.
Artifact Management: Packaging generated website content for deployment.
Continuous Deployment: Automatically publishing updates to GitHub Pages.
Troubleshooting: Diagnosing shell script errors, YAML configuration issues, validation failures, and external platform errors.

It also reinforced the importance of designing pipelines that provide clear feedback and stop execution when validation requirements are not satisfied.

Conclusion

Building this CI/CD pipeline was a practical exercise in bringing together the essential stages of automated software delivery.

What started as a simple GitHub Actions workflow evolved into a multi-stage pipeline capable of validating repository changes, executing reusable automation, generating dynamic website content, and deploying updates automatically.

One of the most valuable aspects of the project was troubleshooting the issues encountered during implementation. Understanding why a workflow fails, identifying whether the problem comes from the script, configuration, or external platform, and applying the appropriate correction are important parts of working with automation.

The completed project demonstrates how GitHub Actions can be used to build structured and reusable CI/CD workflows without requiring a complex deployment environment.

It also provides a foundation for future improvements, such as introducing more comprehensive automated tests, adding security and dependency scanning, and extending the deployment process to a containerized application.

The pipeline is built, tested, and deployed.

Project Links

GitHub Repository: https://github.com/rahimahisah17/pipeit-tutorial
Live Website: https://rahimahisah17.github.io/pipeit-tutorial/
GitHub Release: https://github.com/rahimahisah17/pipeit-tutorial/releases/tag/v1.0.0

Summary

This project demonstrates how GitHub Actions can automate a complete software delivery workflow, from code validation to deployment.

By the end of the implementation, I had:

Created GitHub Actions workflows for basic automation and continuous integration.
Implemented a Bash script to validate repository documentation.
Built a reusable custom composite action to generate a dynamic HTML status card.
Configured a multi-job pipeline with testing, building, and deployment stages.
Enabled automated deployment to GitHub Pages.
Verified that changes pushed to the main branch triggered a new deployment.
Documented troubleshooting experiences and published the project as a GitHub release.

The result is a working CI/CD implementation that demonstrates workflow automation, reusable actions, pipeline dependencies, and continuous deployment using GitHub Actions.

From Zero to Live: Containerise a Python App, Deploy It to Azure Container Apps and Automate It with GitHub Actions

Rahimah Sulayman — Mon, 02 Nov 2026 14:25:20 +0000

Introduction

I recently completed the ShipIt Weekend: Deploy Your First App to Azure lab. It has three missions:

Build it: write a small web app, package it in a Docker image and run it locally.
Ship it: publish the image to GitHub Container Registry (GHCR) and run it on Azure Container Apps with a public HTTPS URL.
Automate it: add a GitHub Actions pipeline that builds, pushes and deploys on every push to main.

I worked through everything from a Linux terminal (Ubuntu on WSL, on a Windows laptop). This is not a polished "everything worked first time" tutorial. I made a few mistakes along the way: I named my repository differently from what the lab expected, my pipeline failed on its first run, and my first credential claim was rejected. I've kept those moments in, because that is where most of the learning happens.

What you'll need:

A GitHub account
An Azure account with an active subscription
Docker, Git and the Azure CLI installed in a Linux-style terminal (WSL works well on Windows)

Mission 1: Build it, containerise a web app

Step 1: Create the project and a Git repository

mkdir -p ~/shipit-app && cd ~/shipit-app
git init -b main

mkdir -p creates the folder (and doesn't complain if it already exists), and && runs cd only if that succeeded.
git init -b main turns the folder into a Git repository and names the first branch main.

Step 2: Write the web app

The app uses only Python's standard library, so there is nothing to install and less that can break.

cat > app.py << 'EOF'
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

MESSAGE = "Hello from ShipIt Weekend!"


class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = f"<h1>{MESSAGE}</h1><p>Built with Docker, shipped to Azure, automated with GitHub Actions.</p>".encode()
        self.send_response(200)
        self.send_header("Content-Type", "text/html; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


HTTPServer(("0.0.0.0", int(os.environ.get("PORT", "8080"))), Handler).serve_forever()
EOF

The cat > app.py << 'EOF' pattern is a here-document: everything up to the EOF line is written into app.py. The quotes around 'EOF' stop the shell from interpreting anything inside. The server listens on port 8080 (or whatever PORT says) and answers every request with a small HTML page.

Step 3: Write the Dockerfile

cat > Dockerfile << 'EOF'
FROM python:3.12-slim
WORKDIR /app
COPY app.py .
ENV PORT=8080
EXPOSE 8080
USER nobody
CMD ["python", "app.py"]
EOF

FROM python:3.12-slim starts from a small official Python image.
WORKDIR /app and COPY app.py . put the app in the container.
ENV PORT=8080 and EXPOSE 8080 set and document the port.
USER nobody runs the app as an unprivileged user instead of root. This is a small but important security habit.
CMD is the command that runs when the container starts.

Step 4: Build and run it locally

docker build -t shipit-app .

docker build reads the Dockerfile in the current folder (the .) and -t shipit-app names the image. The first build downloads the Python base image, so it took about 16 seconds for me.

docker run -d --rm -p 8080:8080 --name shipit shipit-app
curl http://localhost:8080
docker stop shipit

-d runs the container in the background, --rm deletes it when it stops, -p 8080:8080 maps the port to your machine, and --name shipit gives it a name.
curl fetches the page, and docker stop shuts the container down.

The app answered with the HTML heading, so the container worked.

Step 5: Commit, create a GitHub repository and push

git add app.py Dockerfile
git commit -m "feat: containerised web app"

Before pushing, I created an empty repository on GitHub. This is where I made my first mistake: I named it shipit, but the lab expects shipit-app. I didn't notice until much later, and it caused a confusing problem at the end (more on that in Mission 3). I connected my local repo to it like this:

git remote add origin git@github.com:rahimahisah17/shipit.git
git push -u origin main

git remote add origin <url> registers the GitHub repo under the nickname origin. I used the SSH URL because I already had SSH keys set up.
git push -u origin main uploads the main branch and links it to origin/main, so a plain git push works from now on.

Tip: If you follow the lab, name your GitHub repository shipit-app from the start. The final credential check expects that name.

Mission 2: Ship it, GHCR and Azure Container Apps

Step 1: Set your GitHub username and link the image to the repo

export GH_USER=rahimahisah17
echo "LABEL org.opencontainers.image.source=https://github.com/$GH_USER/shipit" >> Dockerfile
git commit -am "chore: link image to repository" && git push

export GH_USER=... stores your username in a variable, so later commands don't need it typed out. It must be lowercase.
The LABEL line adds the repo's URL to the image as metadata, so GitHub can link the package to the repository. >> appends to the file (a single > would overwrite it).
git commit -am stages and commits changes to tracked files in one step.

Small mistake #1: When I first ran echo $GH_USER it printed nothing. I had opened a new terminal session, and environment variables don't survive that. I ran export again and it was fine. If a command suddenly produces strange image names or URLs, check that your variables are still set.

Step 2: Log in to GitHub Container Registry

GHCR is free for public images. Docker needs a personal access token to log in:

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Generate a token with only the write:packages scope and a short expiry.

echo YOUR_TOKEN | docker login ghcr.io -u $GH_USER --password-stdin

--password-stdin makes Docker read the token from the pipe instead of from the command line, which is safer. I got Login Succeeded.

Security note: Treat the token like a password. Don't share it, don't screenshot it unblurred, and delete it when you've finished.

Step 3: Build, tag and push the image

docker build -t ghcr.io/$GH_USER/shipit-app:v1 .
docker push ghcr.io/$GH_USER/shipit-app:v1

The tag has four parts: the registry (ghcr.io), the owner (your username), the image name (shipit-app) and the version (v1). Because the layers were cached, the build took 2.6 seconds.

The push uploaded each layer and ended with the image digest.

Step 4: Make the package public

A new GHCR package is private by default, as the badge on its page shows.

Azure has to pull the image without a password, so it must be public. In the package's Package settings, go to the Danger Zone, click Change visibility, choose Public and type the package name to confirm.

Afterwards the Danger Zone says "This package is currently public."

Step 5: Sign in to Azure and prepare the subscription

az login --use-device-code

--use-device-code gives you a code and a URL to open in a browser, which works well in WSL, where a browser often can't open automatically. You'll see a couple of yellow warnings ("Attempted too soon" and a note about a tenant without subscriptions). They look alarming but are harmless: the login still completes and lists your subscription.

az extension add --name containerapp --upgrade
az provider register --namespace Microsoft.App --wait
az provider register --namespace Microsoft.OperationalInsights --wait

The first command installs the CLI extension that provides the az containerapp commands. Mine was already installed and up to date, which is fine.
The provider register commands switch on the services Container Apps needs (the Container Apps service itself and Log Analytics for logs). A new subscription must do this once. With --wait they print nothing when they succeed, and the prompt simply returns.

Step 6: Create a resource group

az group create --name shipit-rg --location westeurope

A resource group is a folder-like container for everything in this lab, which makes cleanup easy at the end. The JSON output showed "provisioningState": "Succeeded".

Step 7: Deploy to Azure Container Apps

az containerapp up \
  --name shipit-app \
  --resource-group shipit-rg \
  --location westeurope \
  --image ghcr.io/$GH_USER/shipit-app:v1 \
  --ingress external \
  --target-port 8080

This one command creates a Container Apps environment, a Log Analytics workspace and the app itself.

--image points at the image in GHCR (this works because the package is public).
--ingress external gives the app a public address.
--target-port 8080 tells Azure which port inside the container receives traffic.

It's slow. Mine ran for over five minutes on a spinner while Azure created the environment and workspace. Don't press Ctrl+C: stopping halfway can leave half-created resources behind. When it finished, it printed the public URL.

Step 8: Test the live app

export APP_URL=https://$(az containerapp show --name shipit-app --resource-group shipit-rg --query properties.configuration.ingress.fqdn -o tsv)
echo $APP_URL
curl $APP_URL

az containerapp show fetches the app's details, and --query ... -o tsv picks out only the hostname as plain text.
$(...) drops that result into the variable.

The warning about the extension altering the command's behaviour is harmless. curl returned my page from the public internet.

Mission 3: Automate it, CI/CD with GitHub Actions

Step 1: Give GitHub Actions access, with least privilege

The pipeline needs permission to update the app, but only that app's resource group.

export SUB_ID=$(az account show --query id -o tsv)
az ad sp create-for-rbac --name shipit-github --role contributor \
  --scopes /subscriptions/$SUB_ID/resourceGroups/shipit-rg --json-auth

az ad sp create-for-rbac creates a service principal, an identity for automation (like a robot account).
--role contributor lets it create and update resources.
--scopes ... limits that to the shipit-rg resource group only. This is the least-privilege idea in practice.
--json-auth prints the credentials in the JSON format the GitHub login action expects.

The output contains a clientSecret. You'll see a warning about it, plus a deprecation notice for --json-auth (it still worked for me).

Copy the whole JSON and save it as a GitHub secret: your repo → Settings → Secrets and variables → Actions → New repository secret, with the name AZURE_CREDENTIALS.

Step 2: Write the pipeline

mkdir -p .github/workflows

The folder must be named exactly .github/workflows, because that's where GitHub looks for workflows.

cat > .github/workflows/deploy.yml << 'EOF'
name: deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  packages: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push the image
        run: |
          IMAGE=ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/shipit-app:${GITHUB_SHA::7}
          docker build -t "$IMAGE" .
          docker push "$IMAGE"
          echo "IMAGE=$IMAGE" >> "$GITHUB_ENV"

      - name: Log in to Azure
        uses: azure/login@v2
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

      - name: Deploy to Azure Container Apps
        run: az containerapp update --name shipit-app --resource-group shipit-rg --image "$IMAGE"
EOF

What the workflow does:

on: runs it on every push to main, and lets you start it manually (workflow_dispatch).
permissions: lets it read the code and write packages.
Log in to GHCR: uses a temporary built-in token, GITHUB_TOKEN, so no personal token is needed in the pipeline.
Build and push: tags the image with the first 7 characters of the commit ID, so every deployment is traceable to a commit.
Log in to Azure: uses the AZURE_CREDENTIALS secret.
Deploy: az containerapp update points the app at the new image.

The terminal in this screenshot looks jumbled because of how it displayed my paste, but the file itself was fine, as the workflow runs below prove.

Step 3: Change the app and push

I changed the app's message so the pipeline had something new to deploy:

sed -i.bak 's/Hello from ShipIt Weekend!/Shipped automatically by GitHub Actions!/' app.py && rm app.py.bak
grep MESSAGE app.py
git add .github/workflows/deploy.yml app.py
git commit -m "ci: deploy to Azure on every push"
git push

sed -i.bak 's/old/new/' does an in-place find-and-replace and keeps a backup, which rm then deletes.
grep MESSAGE app.py confirms the change before I committed.

Step 4: The first pipeline run fails

I opened the Actions tab and the run had failed after just 19 seconds.

I opened the failing job and found the red step: Build and push the image. The image had built fine, but the log ended with:

denied: permission_denied: write_package
Error: Process completed with exit code 1.

Why it happened: I had first pushed the shipit-app image from my laptop using my personal token, so the package belongs to my account. The workflow's built-in GITHUB_TOKEN is a different identity, and it had no permission to write to that existing package.

Step 5: The fix, give the repository write access to the package

In the package's Package settings → Manage Actions access, I clicked Add Repository, chose my repo and gave it the Write role. That grants only this one repository permission to push to this one package.

Then I clicked Re-run all jobs on the failed run, and this time it passed in 45 seconds.

Step 6: Verify the deployment

curl $APP_URL

The response now showed the new heading, "Shipped automatically by GitHub Actions!", which proves the pipeline built, pushed and deployed the change without me touching Azure.

And in the browser:

Step 7: The repository name problem and claiming the credential

The lab ends by asking you to claim a verified credential, using your live URL and the repository https://github.com/<your-username>/shipit-app.

My repository was called shipit, not shipit-app. My first claim attempt failed with the message "We couldn't reach your live URL". The app was up and curl returned the page, so I first suspected Azure had scaled the app to zero while idle and the checker gave up before it woke. I checked the app with curl and got a successful response.

The real problem turned out to be the repository name. The form still contained .../shipit. After I renamed the repository to shipit-app and submitted the matching URL, the claim worked. The error message pointed at the wrong thing, so the lesson is: when a validation message doesn't make sense, re-check every input against the instructions, not just the one the message mentions.

[Screenshot placeholder: the failed claim showing "We couldn't reach your live URL"]

To rename the repo, I went to the repo's Settings → General → Repository name, entered shipit-app and clicked Rename. GitHub redirects the old name, and the secret, workflow and Actions history all move with the repo. Then I updated my local remote:

git remote set-url origin git@github.com:rahimahisah17/shipit-app.git

git remote set-url changes the address stored for origin, so future pushes go to the renamed repo.

Step 8: Clean up

Deleting what you no longer need is how you make sure nothing is ever charged:

az group delete --name shipit-rg --yes --no-wait
az ad sp delete --id $(az ad sp list --display-name shipit-github --query "[0].id" -o tsv)
az group exists --name shipit-rg

az group delete removes the resource group and everything in it: the app, its environment and the logs. --yes skips the prompt and --no-wait returns immediately while Azure deletes in the background.
az ad sp delete removes the service principal. Deleting the resource group does not remove it.
az group exists prints true while the group is still there and false once it's gone.

Deletion takes a few minutes. I got true twice, then Deleting from az group show, then finally false. I also deleted the AZURE_CREDENTIALS secret and the personal access token.

Troubleshooting summary

What happened	Cause	Fix
`echo $GH_USER` printed nothing	I opened a new terminal, and variables don't persist between sessions	Run `export GH_USER=...` again
Package couldn't be pulled by Azure	GHCR packages are private by default	Set the package visibility to Public
`az containerapp up` seemed stuck	Creating the environment and Log Analytics workspace takes several minutes	Wait, and don't press Ctrl+C
Pipeline failed with `permission_denied: write_package`	The package was first pushed with my personal token, so the workflow's `GITHUB_TOKEN` couldn't write to it	Add the repo under Manage Actions access with the Write role, then re-run
Credential claim said "couldn't reach your live URL"	My repo was named `shipit`, not `shipit-app`	Rename the repo to `shipit-app` and use the matching URL

Lessons learned

Follow naming conventions in guided labs. My shipit vs shipit-app mismatch caused the longest detour.
Read the failing step, not just the red X. The Actions log told me exactly what was wrong: write_package.
Least privilege pays off. The service principal can only touch one resource group, and the repo has write access to only one package.
No secrets in code. The Azure credentials live in an encrypted GitHub secret, and the pipeline's registry login uses a temporary token.
Clean up. Deleting the resource group, the service principal, the secret and the token means nothing keeps running or stays exposed.

One thing I'd still tidy up: my Dockerfile's LABEL line still points at the old repository name (shipit). GitHub redirects the old name, so nothing broke, but updating it would be cleaner.

Summary

In one weekend-sized lab I went from an empty folder to a live HTTPS app on Azure with a working CI/CD pipeline:

I wrote a tiny Python web server and packaged it in a Docker image that runs as a non-root user.
I pushed the image to GitHub Container Registry, made it public, and deployed it to Azure Container Apps with the Azure CLI.
I created a least-privilege service principal and a GitHub Actions workflow, so every push to main builds, pushes and deploys automatically.
I debugged a package permission error and a repository naming mismatch, then cleaned up all the Azure resources.

The app itself is simple, but the workflow behind it is the real thing: containers, a registry, cloud hosting, least-privilege access and automated deployment. If you're learning DevOps or cloud, I'd recommend trying it yourself, mistakes included.

The code is on GitHub: rahimahisah17/shipit-app

Thanks for reading! If you've hit similar errors in your own pipelines, I'd love to hear how you solved them in the comments.

Kubernetes on AKS: From Zero to Production Workloads - Publishing to GitHub and Cleaning Up Azure Resources (Part 9/9)

Rahimah Sulayman — Mon, 26 Oct 2026 20:50:19 +0000

Introduction

Building a cloud-native environment is only part of the engineering process. A complete project also needs version-controlled implementation artifacts, a reproducible record of the work, and a deliberate cleanup strategy that prevents unused cloud resources from continuing to incur charges.

In this final mission, I published the Kubernetes manifests to GitHub, verified that the lab namespace could be removed, deleted the Azure resource group, checked the status of the associated resource groups, and removed the obsolete Kubernetes context from the local kubeconfig.

The objective was to preserve the implementation as portfolio evidence while ensuring that the temporary Azure environment was decommissioned.

What This Part Covers

Committing the Kubernetes manifests to Git.
Publishing the repository to GitHub.
Verifying namespace removal.
Deleting the Azure resource group.
Checking that the AKS-managed resource group was removed.
Deleting the obsolete Kubernetes context.
Confirming what remains available after the cloud environment is deleted.

1. Review the Kubernetes Manifests

The project contains nine Kubernetes manifest files covering the workloads and resources implemented throughout the lab.

The files are organized under the manifests/ directory:

ls manifests

The output showed:

01-pod.yaml
02-deployment.yaml
03-service-clusterip.yaml
04-service-loadbalancer.yaml
05-configmap.yaml
06-statefulset.yaml
07-daemonset.yaml
08-job.yaml
09-cronjob.yaml

The manifests capture the main resources from the project:

Manifest	Resource
`01-pod.yaml`	Standalone Pod
`02-deployment.yaml`	Deployment
`03-service-clusterip.yaml`	Internal ClusterIP Service
`04-service-loadbalancer.yaml`	LoadBalancer Service
`05-configmap.yaml`	ConfigMap
`06-statefulset.yaml`	Headless Service and StatefulSet with persistent storage
`07-daemonset.yaml`	DaemonSet
`08-job.yaml`	Batch Job
`09-cronjob.yaml`	Scheduled CronJob

Keeping these resources in version control preserves the configuration used throughout the lab. The manifests provide a reference for the implementation and can be reviewed independently of the Azure environment in which they were deployed.

2. Commit the Manifests to Git

I committed the workload manifests with a message describing the implementation:

git commit -m "feat: AKS workloads (pods, deployment, services, config, statefulset, daemonset, job, cronjob)"

Git confirmed the commit:

[main 610883d] feat: AKS workloads (pods, deployment, services, config, statefulset, daemonset, job, cronjob)
9 files changed, 206 insertions(+)

The commit created the nine manifest files in the repository.

A descriptive commit message makes the change easier to identify in the project history. It also establishes a clear record of the implementation being preserved for the portfolio.

3. Configure the GitHub Remote

I configured the local repository to use the GitHub repository:

https://github.com/rahimahisah17/aks-kubernetes-lab.git

The command used was:

git remote add origin https://github.com/rahimahisah17/aks-kubernetes-lab.git 2>/dev/null || git remote set-url origin https://github.com/rahimahisah17/aks-kubernetes-lab.git

This command adds origin when it does not already exist or updates its URL when the remote has already been configured.

Using a remote allows the local Git repository to publish commits to GitHub and maintain a shared record of the implementation.

4. Push the Project to GitHub

With the remote configured, I pushed the main branch:

git push -u origin main

The command completed successfully:

Enumerating objects: 19, done.
Counting objects: 100% (19/19), done.
Compressing objects: 100% (18/18), done.
Writing objects: 100% (19/19), 3.70 KiB | 84.00 KiB/s, done.
Total 19 (delta 2), reused 0 (delta 0), pack-reused 0

To https://github.com/rahimahisah17/aks-kubernetes-lab.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

The push published the branch and configured it to track origin/main.

The project repository is available here:

GitHub — aks-kubernetes-lab

Publishing the manifests ensures that the configuration remains accessible even after the cluster and its cloud resources have been deleted.

The repository also serves as portfolio evidence of the project implementation, including the manifest structure and version-control history.

5. Delete the Kubernetes Lab Namespace

After the GitHub push succeeded, I removed the namespace containing the lab workloads:

kubectl delete namespace k8s-lab

Kubernetes returned:

namespace "k8s-lab" deleted

I then inspected the remaining namespaces:

kubectl get namespaces

The output listed the remaining namespaces:

NAME              STATUS   AGE
default           Active   5h9m
kube-node-lease   Active   5h9m
kube-public       Active   5h9m
kube-system       Active   5h9m

The k8s-lab namespace was no longer present.

Deleting a namespace removes the Kubernetes resources contained in it, subject to their deletion and finalization behavior. This removed the dedicated lab namespace and its namespaced workloads from the cluster.

However, deleting a Kubernetes namespace does not itself decommission the AKS cluster or remove every Azure resource associated with it. The Azure resource group therefore needed to be deleted separately.

6. Delete the Azure Resource Group

The Azure environment used the following configuration:

RESOURCE_GROUP=rg-aks-lab
CLUSTER_NAME=aks-lab
LOCATION=westeurope
NODE_SIZE=Standard_D2s_v3

I first attempted to delete the resource group using the environment variable:

az group delete --name $RESOURCE_GROUP --yes --no-wait

The command returned an error:

argument --name/-n/--resource-group/-g: expected one argument

The variable was not populated in that shell because I switched to another terminal, so Azure CLI did not receive a resource group name.

I then supplied the resource group name explicitly:

az group delete --name rg-aks-lab --yes --no-wait

This issued the resource group deletion request.

The --yes option skips the interactive confirmation, while --no-wait returns without waiting for the deletion operation to finish. As a result, the command's return does not, on its own, establish that the resources have already disappeared.

For cleanup operations, verification is essential because Azure resource deletion can continue asynchronously after the command returns.

7. Verify the Azure Resource Group Cleanup

The AKS deployment had a primary resource group and an AKS-managed resource group. I checked for both using:

az group list --query "[?starts_with(name, 'rg-aks-lab') || starts_with(name, 'MC_rg-aks-lab')].name" --output tsv

An initial check still showed:

rg-aks-lab
MC_rg-aks-lab_aks-lab_westeurope

This indicated that the deletion process had not yet removed both resource groups from the listing.

I repeated the check after the deletion process had progressed:

az group list --query "[?starts_with(name, 'rg-aks-lab') || starts_with(name, 'MC_rg-aks-lab')].name" --output tsv

The subsequent output was empty, confirming that neither matching resource group remained in the returned list.

The verification covered both the main lab resource group and the resource group created by AKS to manage supporting infrastructure.

This distinction matters because AKS can create Azure resources outside the visible workload definitions in the Kubernetes manifests. A complete cleanup check should account for the managed infrastructure, rather than checking only the primary resource group.

8. Remove the Obsolete Kubernetes Context

With the AKS environment decommissioned, I removed its local Kubernetes context:

kubectl config delete-context aks-lab

The command returned:

warning: this removed your active context, use "kubectl config use-context" to select a different one
deleted context aks-lab from /home/rahimahisah/.kube/config

The context had stored the connection configuration used by kubectl to access the aks-lab cluster.

Removing it cleans up the local kubeconfig after the cluster has been deleted. The warning also notes that the removed context had been active, so another context would need to be selected before using kubectl against a different cluster.

This step removes the local connection entry; it does not delete the local repository, manifests, or GitHub project.

9. What Remains After Cleanup?

The cleanup separates the cloud environment from the project artifacts.

Component	Final state
`k8s-lab` namespace	Deleted
Main Azure resource group `rg-aks-lab`	No longer present in the verification listing
AKS-managed resource group	No longer present in the verification listing
Local `aks-lab` kubeconfig context	Deleted
Local project directory	Preserved
Kubernetes YAML manifests	Preserved locally
Git commit history	Preserved in the repository
GitHub repository	Published and available

This separation is important for cloud labs. The resources used to demonstrate the implementation can be removed without discarding the configuration, documentation, and version-control history that make the work reproducible and useful as portfolio evidence.

Although the Azure resource groups were removed from the verification listing, the final Azure bill remains the authoritative source for confirming any outstanding or previously accrued charges. Deletion stops the continued use of the deleted resources, but it does not erase charges already incurred.

10. Operational Takeaways

This final mission brought together version control, cloud resource lifecycle management, and verification.

The main takeaways were:

Version-controlled infrastructure: Kubernetes manifests provide a durable record of the resource configuration used in the lab.
Repository publishing: Pushing the project to GitHub preserves the implementation beyond the lifetime of the AKS cluster.
Namespace cleanup: Removing the lab namespace deletes its dedicated Kubernetes workloads and resources.
Azure resource cleanup: Deleting the primary resource group initiates removal of the cluster and related Azure resources.
Asynchronous deletion: Commands using --no-wait require a separate verification step to confirm the resources have disappeared.
Managed-resource awareness: AKS can create a separate managed resource group that should be included in cleanup verification.
Local configuration hygiene: Removing an obsolete kubeconfig context prevents local configuration from retaining an unnecessary connection entry.
Cost awareness: Cloud cleanup should be verified rather than assumed, and actual billed amounts should be checked independently.

Conclusion: From Cluster Provisioning to Decommissioning

The nine-part series brought together AKS provisioning, Kubernetes workloads, networking, configuration, persistent storage, batch processing, scheduled automation, and cost optimization.

In this final mission, I committed the nine workload manifests, pushed the project to GitHub, deleted the k8s-lab namespace, issued the Azure resource group deletion request, verified that the primary and AKS-managed resource groups were no longer listed, and removed the obsolete Kubernetes context.

The result is a preserved project repository without the temporary cloud infrastructure used to run it.

The central operational principle is straightforward: infrastructure work is not complete until its implementation has been preserved and its temporary resources have been deliberately decommissioned. Version-controlled manifests retain the engineering evidence, while verified cleanup helps prevent unnecessary ongoing resource consumption.

This article is Part 9 of the nine-part series, “Kubernetes on AKS: From Zero to Production Workloads.”

Kubernetes on AKS: From Zero to Production Workloads - FinOps: Measure, Price and Cut Cluster Costs (Part 8/9)

Rahimah Sulayman — Mon, 26 Oct 2026 20:26:27 +0000

Introduction

Cloud-native infrastructure is not production-ready simply because its workloads are running. It must also be measurable, cost-aware, and configured to avoid paying for unnecessary capacity.

In this mission, I evaluated the resource consumption of my Azure Kubernetes Service (AKS) cluster, examined Kubernetes resource requests and limits, queried the Azure Retail Prices API to estimate compute costs, and implemented workload and node-pool scaling controls. I also removed an externally exposed LoadBalancer Service, tested the AKS stop/start lifecycle, and documented the findings and optimization actions in COST-REPORT.md.

The objective was to connect Kubernetes resource telemetry with Azure pricing and practical cost-control measures, while distinguishing observed utilization from requested capacity, configured limits, and estimated charges.

What This Part Covers

Measuring node and Pod resource usage.
Inspecting CPU and memory requests and limits.
Installing jq to process Azure pricing data.
Querying the Azure Retail Prices API for the VM size used by the cluster.
Estimating the monthly compute cost.
Configuring workload autoscaling with a Horizontal Pod Autoscaler (HPA).
Enabling cluster autoscaling for the AKS node pool.
Removing the public LoadBalancer Service.
Testing AKS stop/start operations.
Creating and committing a cost report.

1. Measure Actual Resource Utilization

I started with the node-level metrics:

kubectl top nodes

The output showed:

NAME                                CPU(cores)   CPU(%)   MEMORY(bytes)   MEMORY(%)
aks-nodepool1-33590657-vmss000000   242m         12%      1479Mi          25%

At the time of measurement, the node was using approximately 12% of its reported CPU capacity and 25% of its memory capacity.

These figures provide a snapshot of actual resource consumption. They are useful for identifying whether the node is under pressure or operating with substantial unused capacity, although a single observation does not establish the workload's peak or long-term requirements.

Inspect the Pods consuming CPU

I then inspected the Pods across namespaces, sorted by CPU usage:

kubectl top pods -A --sort-by=cpu | head -15

The output included system components in kube-system and application workloads in k8s-lab, including:

csi-azurefile-node
azure-cns
metrics-server
konnectivity-agent
coredns
kube-proxy
web Deployment Pods
node-agent
store-0 and store-1

The displayed CPU consumption of the application Pods was low at the time of measurement. This helped establish that the cluster's workloads were not consuming a substantial share of the node's available CPU during the observed interval.

The distinction matters because a Kubernetes cluster can have a relatively low current workload while still reserving significant capacity through its configured resource requests.

2. Compare Resource Requests, Limits and Actual Usage

To understand how much capacity the workloads had requested or been permitted to use, I inspected the node's allocated resources:

kubectl describe nodes | grep -A 8 "Allocated resources"

The output showed:

Allocated resources:
  (Total limits may be over 100 percent, i.e., overcommitted.)
  Resource           Requests       Limits
  --------           --------       ------
  cpu                1187m (62%)    10692m (562%)
  memory             1330Mi (22%)   13443360Ki (226%)

The figures reveal three different aspects of resource management.

Metric	CPU	Memory
Observed node utilization	12%	25%
Allocated requests	62%	22%
Allocated limits	562%	226%

Actual utilization represents observed consumption at the time of measurement.

Requests represent the capacity declared by workloads for scheduling purposes. CPU requests of 62% indicate that workloads had reserved a significant proportion of the node's allocatable CPU capacity, even though observed CPU utilization was only 12%.

Limits define upper resource boundaries for individual containers. Their aggregated percentages can exceed 100% because Kubernetes permits resource overcommitment. The reported CPU limit of 562% therefore does not mean that the node was actually using more than five times its CPU capacity.

These measurements should not be interpreted interchangeably. Low current utilization can indicate an opportunity to review requests, but reducing them requires an understanding of the workload's peak behavior, performance requirements, and reliability objectives.

Verify the Deployment's resource settings

I inspected the container configuration for the web Deployment:

kubectl get deployment web -n k8s-lab -o json \
  | jq '.spec.template.spec.containers[] |
        {name: .name, requests: .resources.requests, limits: .resources.limits}'

The result showed:

{
  "name": "nginx",
  "requests": {
    "cpu": "50m",
    "memory": "64Mi"
  },
  "limits": {
    "cpu": "200m",
    "memory": "128Mi"
  }
}

Each NGINX container requested 50m CPU and 64Mi memory, with limits of 200m CPU and 128Mi memory.

With three replicas, those declared requests contribute to the Deployment's aggregate resource reservations. Repeating this comparison across workloads helps identify where requests may be substantially higher than typical consumption or where capacity may be constrained.

The goal is not to minimize requests indiscriminately. It is to align resource allocation with actual workload requirements while preserving sufficient headroom for bursts and normal operating variation.

3. Install jq for Pricing Data Analysis

To process the JSON returned by Azure's pricing endpoint, I installed jq in the Linux environment:

sudo apt-get install -y jq

The package manager installed jq and its required dependencies successfully.

This utility made it easier to filter the Azure Retail Prices API response and extract fields such as the product name, meter, price, unit of measure, region, and price type.

4. Retrieve VM Pricing from the Azure Retail Prices API

The cluster configuration identified the following environment values:

RESOURCE_GROUP=rg-aks-lab
CLUSTER_NAME=aks-lab
LOCATION=westeurope
NODE_SIZE=Standard_D2s_v3

I queried the Azure Retail Prices API for virtual machine pricing matching the region and VM size:

curl -sG "https://prices.azure.com/api/retail/prices" \
  --data-urlencode "\$filter=serviceName eq 'Virtual Machines' and armRegionName eq '$LOCATION' and armSkuName eq '$NODE_SIZE' and priceType eq 'Consumption'" \
  | jq -r '.Items[]
    | select(.meterName | test("Spot|Low Priority"; "i") | not)
    | [.productName, .skuName, .meterName, .retailPrice, .unitOfMeasure, .armRegionName, .priceType]
    | @tsv'

The response contained multiple pricing records for the requested VM SKU. The available records included different operating-system products and pricing types, so the SKU alone was not sufficient to select the correct rate.

I compared the returned fields to distinguish the applicable consumption rate from Windows-specific, DevTest, Spot, and Low Priority entries.

For the cost report, I used an observed public retail consumption rate of $0.12 per hour for the Standard_D2s_v3 VM in westeurope.

Estimate the monthly VM compute cost

Using a simplified month of 730 hours, the calculation was:

[
\text{Estimated monthly cost} =
\text{Hourly rate} \times 730
]

[
\$0.12 \times 730 = \$87.60
]

The resulting estimate was:

Item	Estimate
VM size	`Standard_D2s_v3`
Region	`westeurope`
Hourly rate used	$0.12
Assumed monthly hours	730
Estimated monthly VM compute cost	$87.60

This is a price-based estimate, not a confirmed Azure invoice amount. The calculation covers the VM rate used in the report and excludes additional AKS and Azure resource charges. Actual billing can also depend on the applicable pricing record, subscription or purchasing terms, usage duration, and associated resources.

For that reason, the estimate provides a useful baseline for cost planning, but it should not be presented as the complete operating cost of the cluster.

5. Identify and Remove Unnecessary Public Exposure

I reviewed the Services across namespaces:

kubectl get services -A

The output showed the internal web-svc ClusterIP Service, the headless store Service, and the web-public LoadBalancer Service.

The public Service was exposing NGINX using this external IP:

20.61.154.190

I inspected its configuration and endpoints:

kubectl describe service web-public -n k8s-lab

The Service used the selector app=web, exposed port 80, and routed traffic to the NGINX Pods. Its type was LoadBalancer, and the external IP had been assigned.

The lab no longer required this public endpoint for its remaining work, so I removed the Service:

kubectl delete service web-public -n k8s-lab

Kubernetes confirmed:

service "web-public" deleted from k8s-lab namespace

Removing the Service eliminated that Kubernetes-managed public exposure. The internal Service remained available for cluster-internal access.

This action also removed the LoadBalancer Service configuration that was no longer needed by the lab. Deleting the Service should not be treated as proof that every associated Azure charge disappears immediately; the resulting Azure resources and billing records still need to be considered when validating actual savings.

6. Configure Horizontal Pod Autoscaling

The web Deployment had been configured with three replicas. Rather than permanently fixing it at that count, I created a Horizontal Pod Autoscaler (HPA) to allow Kubernetes to adjust the number of Pods based on CPU utilization.

I configured the HPA as follows:

kubectl autoscale deployment web -n k8s-lab \
  --cpu-percent=70 \
  --min=1 \
  --max=5

Kubernetes returned:

horizontalpodautoscaler.autoscaling/web autoscaled

The command displayed a deprecation notice for --cpu-percent, recommending the newer --cpu option with a percentage or resource quantity format.

I verified the resulting HPA:

kubectl get hpa web -n k8s-lab

The output showed:

NAME   REFERENCE      TARGETS   MINPODS   MAXPODS   REPLICAS
web    Deployment/web cpu: 2%/70%  1      5         3

At the time of the check, the observed CPU utilization was approximately 2% against a 70% target. The HPA was configured to maintain between one and five replicas, with three replicas currently reported.

This configuration allows the replica count to respond to CPU utilization rather than requiring manual scaling for every workload fluctuation.

The HPA does not guarantee that replicas immediately scale down whenever usage is low, nor does it remove the need for appropriate resource requests and metrics. It evaluates workload metrics against its configuration and adjusts the desired replica count as conditions warrant.

7. Enable AKS Node-Pool Autoscaling

Pod autoscaling changes the number of application replicas, but it does not automatically increase the number of virtual machines in the cluster unless cluster-level scaling is configured.

I enabled the cluster autoscaler for nodepool1, allowing the node count to vary between one and three:

az aks nodepool update \
  --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" \
  --name nodepool1 \
  --enable-cluster-autoscaler \
  --min-count 1 \
  --max-count 3

The command updated the node-pool configuration. Azure CLI also displayed a notice that the command behavior had been altered by the aks-preview extension.

I then queried the effective settings:

az aks nodepool show \
  --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" \
  --name nodepool1 \
  --query "{Pool:name,Count:count,Autoscaling:enableAutoScaling,Min:minCount,Max:maxCount}" \
  --output table

The output showed:

Pool       Count   Autoscaling   Min   Max
nodepool1  1       True          1     3

This verified that cluster autoscaling was enabled and that the configured minimum and maximum node counts were one and three.

The node pool was currently at one node. With autoscaling enabled, Kubernetes can request additional node capacity when scheduling demand requires it, subject to the configured limits and Azure's ability to provision the capacity.

HPA and cluster autoscaling serve different purposes

These settings control separate layers of the environment:

Horizontal Pod Autoscaler: adjusts the number of application Pods.
Cluster autoscaler: adjusts the number of AKS nodes when cluster capacity needs to change.

The HPA was configured for one to five web replicas, while the node pool was configured for one to three nodes. The two mechanisms work at different levels and should be configured together with appropriate resource requests, scheduling requirements, and capacity limits.

The maximum node count is a limit, not a target. Enabling autoscaling does not mean the cluster will remain at three nodes.

8. Test the AKS Stop/Start Lifecycle

I also exercised the AKS cluster's stop/start commands.

To stop the cluster, I ran:

az aks stop \
  --resource-group "$RESOURCE_GROUP" \
  --name "$CLUSTER_NAME"

I then started it again:

az aks start \
  --resource-group "$RESOURCE_GROUP" \
  --name "$CLUSTER_NAME"

Finally, I checked its reported power state:

az aks show \
  --resource-group "$RESOURCE_GROUP" \
  --name "$CLUSTER_NAME" \
  --query powerState.code \
  --output tsv

The resulting state was:

Running

This confirmed that the cluster was running after the stop/start sequence.

For a lab or development environment that is not needed continuously, stopping the cluster during idle periods can be part of a cost-control strategy. However, the cluster must first be checked for active workloads, scheduled operations, dependencies, and service availability requirements.

The stop/start exercise demonstrates the control operation; it is not, on its own, a measured comparison of the before-and-after Azure bill. Actual savings should be verified against the applicable billing records and the resources that continue to incur charges.

9. Document the Findings in COST-REPORT.md

To capture the analysis and decisions, I created COST-REPORT.md in the project repository:

cat << 'EOF' > COST-REPORT.md
# AKS FinOps Cost Report

## Cluster Configuration
- Resource Group: rg-aks-lab
- Cluster: aks-lab
- Region: westeurope
- Node Pool: nodepool1
- VM Size: Standard_D2s_v3
- Node Count: 1

## Resource Utilization
- Node CPU usage: 12%
- Node memory usage: 25%
- CPU requests: 62%
- Memory requests: 22%

## Cost Estimate
- Estimated VM rate: $0.12/hour
- Estimated monthly VM cost (730 hours): $87.60
- Estimate excludes additional AKS and Azure resource charges.

## Cost Optimization Actions
- Configured web deployment autoscaling between 1 and 5 replicas.
- Enabled cluster autoscaling for nodepool1 between 1 and 3 nodes.
- Reduced the node pool to 1 node.
- Removed the web-public LoadBalancer service.
- Stopped the AKS cluster when not in use.

## Notes
The VM price is a public retail-price estimate, not a confirmed invoice amount. Actual costs depend on billing rates and associated Azure resources.
EOF

The report consolidated the cluster configuration, observed utilization, VM price estimate, and optimization actions into a version-controlled artifact.

A concise cost report is useful because it distinguishes the measurements from the actions taken and documents what remains outside the estimate. In this case, it explicitly records that the $87.60 figure excludes additional AKS and Azure resource charges.

10. Commit the Cost Report

I checked the repository state:

git status

The report appeared as an untracked file. I staged it:

git add COST-REPORT.md

Then I committed it:

git commit -m "docs: AKS cost review and optimisation"

Git confirmed the commit:

[main 2725349] docs: AKS cost review and optimisation
1 file changed, 30 insertions(+)
create mode 100644 COST-REPORT.md

This committed the cost report to the main branch, preserving the analysis and optimization decisions alongside the lab's other project documentation.

11. Summary of Cost Optimization Decisions

The main findings and actions were:

Area	Finding or action	Operational purpose
Node utilization	12% CPU and 25% memory usage observed	Establish a snapshot of actual resource consumption
Resource requests	CPU requests at 62%; memory requests at 22%	Identify declared capacity reservations for further review
Resource limits	Aggregated CPU and memory limits above 100%	Understand configured overcommitment rather than actual usage
VM pricing	$0.12/hour used for the estimate	Establish a public retail-price baseline
Monthly estimate	$87.60 for 730 hours of VM compute	Quantify an illustrative compute cost
Workload scaling	HPA configured for one to five replicas	Match the `web` replica count to CPU demand
Node scaling	Cluster autoscaler configured for one to three nodes	Allow node capacity to adjust to scheduling demand
Public networking	`web-public` Service deleted	Remove an external endpoint no longer required by the lab
Cluster lifecycle	Stop/start operations tested	Establish an option for managing idle lab capacity
Documentation	`COST-REPORT.md` committed	Preserve the findings and optimization actions

These actions address different aspects of cost management. Autoscaling controls capacity, removing an unnecessary Service eliminates unneeded exposure, resource measurements inform future tuning, and stopping an idle cluster provides a lifecycle control. The retail-price estimate supports planning but does not replace actual cost analysis.

Conclusion

This FinOps review combined Kubernetes telemetry with Azure pricing data to establish a practical baseline for the AKS lab.

The observed node utilization was 12% CPU and 25% memory, while resource requests and limits revealed how declared capacity differed from current consumption. A public VM consumption rate of $0.12 per hour was used to estimate $87.60 for 730 hours of VM compute, excluding additional AKS and Azure resource charges.

I configured the web HPA to scale between one and five replicas, enabled node-pool autoscaling between one and three nodes, removed the public web-public Service, tested the AKS stop/start workflow, and committed the findings in COST-REPORT.md.

The key principle is that cost optimization should be based on measured usage, explicit assumptions, and deliberate trade-offs. Reducing infrastructure cost is valuable only when the resulting capacity and availability remain appropriate for the workload.

In Part 9, the series will conclude with the final mission, bringing the lab's implementation, documentation, and cleanup together.

This article is Part 8 of the nine-part series, “Kubernetes on AKS: From Zero to Production Workloads.”

Kubernetes on AKS: From Zero to Production Workloads -DaemonSets, Jobs and CronJobs (Part 7/9)

Rahimah Sulayman — Mon, 26 Oct 2026 19:25:12 +0000

Introduction

Kubernetes supports more than continuously running application workloads. It also provides controllers for node-level agents, one-off batch processing, and scheduled tasks.

In this mission, I implemented a DaemonSet to run a lightweight agent on each eligible AKS node, scaled the node pool to verify that the agent was scheduled on a newly added node, and then returned the pool to one node. I also configured a batch Job with three completions and a CronJob that runs every minute, verifying their execution through Job status and container logs.

These workload types address different operational requirements: DaemonSets distribute workloads across nodes, Jobs manage finite tasks, and CronJobs create Jobs on a recurring schedule.

What This Part Covers

Creating and validating a DaemonSet.
Injecting the node name into a container through the Downward API.
Scaling the AKS node pool and verifying DaemonSet placement.
Defining a batch Job with three successful completions.
Inspecting Job status and logs.
Scheduling recurring work with a CronJob.
Verifying scheduled executions and reviewing the resulting cluster resources.

1. Deploy a DaemonSet

A DaemonSet ensures that a copy of a specified Pod runs on each eligible node. This makes it suitable for node-level agents that need to operate wherever workloads are scheduled.

I defined the DaemonSet in manifests/07-daemonset.yaml:

cat << 'EOF' > manifests/07-daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: node-agent
spec:
  selector:
    matchLabels:
      app: node-agent
  template:
    metadata:
      labels:
        app: node-agent
    spec:
      containers:
        - name: agent
          image: busybox:1.36
          command: ["sh", "-c", "while true; do echo \"$(date) agent running on node $NODE_NAME\"; sleep 30; done"]
          env:
            - name: NODE_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
          resources:
            requests:
              cpu: 10m
              memory: 16Mi
            limits:
              cpu: 50m
              memory: 32Mi
EOF

Configuration details

The manifest defines a DaemonSet named node-agent with a single container using busybox:1.36.

The container runs a loop that writes a timestamp and the node name to its output every 30 seconds. This provides a lightweight way to confirm which node is hosting each agent.

The node name is injected through the Kubernetes Downward API:

env:
  - name: NODE_NAME
    valueFrom:
      fieldRef:
        fieldPath: spec.nodeName

This avoids hardcoding a node name into the container command. Each Pod receives the name of the node on which it is running.

The resource configuration also defines explicit requests and limits:

Resource	Request	Limit
CPU	`10m`	`50m`
Memory	`16Mi`	`32Mi`

These values keep the agent's resource requirements small while making its resource boundaries explicit.

I applied the manifest:

kubectl apply -f manifests/07-daemonset.yaml

Kubernetes returned:

daemonset.apps/node-agent created

I then monitored the rollout:

kubectl rollout status daemonset/node-agent

The output confirmed:

daemon set "node-agent" successfully rolled out

2. Verify DaemonSet Placement and Logs

To inspect the DaemonSet's status, I ran:

kubectl get daemonset node-agent

The output showed:

NAME         DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE
node-agent   1         1         1       1            1

At this stage, the cluster had one node, and the DaemonSet had one desired and ready Pod.

I checked the Pod's placement with:

kubectl get pods -l app=node-agent -o wide

The output identified the Pod as node-agent-rdmcq, running on:

aks-nodepool1-33590657-vmss000000

The Pod was in the Running state and had the internal IP 10.244.0.172.

To confirm that the agent was reporting the correct node, I inspected its recent logs:

kubectl logs -l app=node-agent --prefix --tail=1

The output included:

[pod/node-agent-rdmcq/agent] Mon Oct 26 10:02:52 UTC 2026 agent running on node aks-nodepool1-33590657-vmss000000

This verified that the agent was running and that the node name supplied through the Downward API was available inside the container.

3. Scale the AKS Node Pool to Verify DaemonSet Behavior

To verify how the DaemonSet responds when the cluster gains another node, I scaled the AKS node pool from one node to two:

az aks scale \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --nodepool-name nodepool1 \
  --node-count 2

The Azure CLI returned the node pool configuration. Its output also displayed a notice that the command's behavior had been altered by the aks-preview extension.

Once the second node was available, I checked the cluster:

kubectl get nodes

The output showed two nodes in the Ready state:

NAME                                STATUS   ROLES    VERSION
aks-nodepool1-33590657-vmss000000   Ready    <none>   v1.36.4
aks-nodepool1-33590657-vmss000001   Ready    <none>   v1.36.4

I then checked the DaemonSet Pods again:

kubectl get pods -l app=node-agent -o wide

The output showed one agent Pod on each node:

Pod	Status	Node
`node-agent-rdmcq`	Running	`aks-nodepool1-33590657-vmss000000`
`node-agent-mdscg`	Running	`aks-nodepool1-33590657-vmss000001`

The second agent was running on the newly added node, demonstrating the DaemonSet's node-level placement behavior.

Unlike a Deployment, where the replica count is explicitly configured, a DaemonSet aims to maintain a Pod on every eligible node. As the eligible node count changes, the number of agent Pods changes accordingly.

Return the node pool to one node

After verifying the two-node behavior, I scaled the node pool back to one:

az aks scale \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --nodepool-name nodepool1 \
  --node-count 1

This returned the lab environment to its previous node count. Scaling a node pool affects the cluster's compute capacity and is also relevant when managing cloud costs for a lab environment.

4. Create a Batch Job

A Kubernetes Job manages Pods that perform finite work and are expected to complete successfully. Unlike a continuously running Deployment, a Job tracks successful task completion.

I defined the Job in manifests/08-job.yaml:

cat << 'EOF' > manifests/08-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: report
spec:
  completions: 3
  parallelism: 3
  backoffLimit: 2
  ttlSecondsAfterFinished: 3600
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: report
          image: busybox:1.36
          command: ["sh", "-c", "echo \"Report part generated by $(hostname)\"; sleep 5"]
EOF

Job configuration

The Job is named report and uses busybox:1.36 to print a message identifying the Pod that generated each report part.

The important settings are:

completions: 3 specifies that three successful completions are required.
parallelism: 3 allows up to three Job Pods to run concurrently.
backoffLimit: 2 sets the permitted retry count for failed Pods before the Job is considered failed.
ttlSecondsAfterFinished: 3600 allows the completed Job to be eligible for automatic cleanup one hour after it finishes.
restartPolicy: Never prevents a failed container from being restarted within the same Pod.

This configuration models a small batch operation with three successful executions. Each Pod prints its own hostname, making it possible to distinguish the individual task executions in the logs.

I applied the Job:

kubectl apply -f manifests/08-job.yaml

The initial output confirmed:

job.batch/report created

My first verification attempt returned a NotFound error when waiting for the Job to complete, and the immediate Job listing showed no resources. I reapplied the manifest and checked the resulting Job again.

kubectl apply -f manifests/08-job.yaml

The subsequent execution completed successfully.

5. Verify Job Completion and Inspect the Logs

I checked the Job status:

kubectl get job report

The output showed:

NAME     STATUS     COMPLETIONS   DURATION
report   Complete   3/3           10s

The 3/3 completion count confirmed that the Job had achieved its three required successful completions.

To inspect the output from all the Job's Pods, I ran:

kubectl logs -l job-name=report --prefix

The logs included messages such as:

[pod/report-2v8b5/report] Report part generated by report-2v8b5
[pod/report-bxzps/report] Report part generated by report-bxzps
[pod/report-plnqc/report] Report part generated by report-plnqc

Each execution produced a message containing its own Pod hostname. This confirmed that the Job's three task executions ran and completed.

The logs also demonstrate why Job status and application output are complementary checks. The completion count confirms the controller's recorded outcome, while the logs show what the containers actually executed.

6. Schedule Recurring Work with a CronJob

A CronJob creates Jobs according to a schedule. It is useful for recurring operations such as periodic reporting, cleanup tasks, and scheduled maintenance.

I defined the CronJob in manifests/09-cronjob.yaml:

cat << 'EOF' > manifests/09-cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: heartbeat
spec:
  schedule: "*/1 * * * *"
  successfulJobsHistoryLimit: 2
  failedJobsHistoryLimit: 1
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: heartbeat
              image: busybox:1.36
              command: ["sh", "-c", "echo \"Heartbeat at $(date)\""]
EOF

The CronJob is named heartbeat and uses the schedule:

*/1 * * * *

This cron expression requests execution every minute.

The Job template uses a BusyBox container that prints a timestamp. Unlike the report Job, which required three successful completions, this CronJob creates a new Job each time its schedule is triggered.

The history settings control how many finished Jobs are retained by the CronJob controller:

successfulJobsHistoryLimit: 2 retains up to two successful Jobs.
failedJobsHistoryLimit: 1 retains up to one failed Job.

The Pod template uses restartPolicy: OnFailure, allowing a failed container to be restarted within its Pod according to Kubernetes' restart behavior.

I applied the manifest:

kubectl apply -f manifests/09-cronjob.yaml

Kubernetes confirmed:

cronjob.batch/heartbeat created

7. Verify Scheduled Executions

I inspected the CronJob:

kubectl get cronjob heartbeat

The output showed the every-minute schedule and the CronJob's status fields, including its suspension state, active Job count, and last scheduled execution.

The initial check occurred before the first scheduled run had been recorded, so the LAST SCHEDULE field was still empty.

After subsequent checks, I listed Jobs in creation order:

kubectl get jobs --sort-by=.metadata.creationTimestamp

The output included the completed report Job and a completed Job created by the heartbeat CronJob.

To inspect the latest scheduled Job's output, I ran:

kubectl logs job/$(kubectl get jobs --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}')

The output was:

Heartbeat at Mon Oct 26 12:34:01 UTC 2026

This confirmed that the scheduled workload had executed and produced its expected message.

The naming pattern also makes the controller relationship visible: the CronJob is named heartbeat, while the Jobs it creates include a generated suffix.

8. Inspect the Combined Cluster State

After deploying the DaemonSet, Job, and CronJob, I inspected the broader set of resources:

kubectl get all,configmap,secret,pvc

ls manifests

The manifests folder contains nine yaml files.

The output showed the different workload types operating in the k8s-lab namespace.

The relevant resources included:

Resource	Observed state
`node-agent` DaemonSet	One desired and ready agent Pod after returning the node pool to one node
`report` Job	Complete, with `3/3` successful completions
`heartbeat` CronJob	Configured to run every minute
`heartbeat` Jobs	Completed executions recorded
`store` StatefulSet	`2/2` Pods ready
`web` Deployment	`3/3` replicas available
`web-svc` Service	Internal `ClusterIP`
`web-public` Service	`LoadBalancer` with external IP `20.61.154.190`
`store` Service	Headless Service with no cluster IP
StatefulSet PVCs	Two claims bound, each with `1Gi` capacity

9. DaemonSets, Jobs and CronJobs: Key Differences

Although all three resources can create and manage Pods, they serve distinct purposes.

Resource	Primary behavior	Typical use
DaemonSet	Maintains a Pod on each eligible node	Node-level agents, monitoring, logging, and other node-scoped services
Job	Runs Pods until a finite task reaches its required successful completion count	Batch processing, report generation, and one-off operations
CronJob	Creates Jobs according to a recurring schedule	Scheduled reports, periodic maintenance, and recurring automation

The choice depends on the execution model.

A DaemonSet follows the eligible node count. A Job tracks successful completion of finite work. A CronJob adds a time-based schedule for creating those Jobs.

These resources are complementary rather than interchangeable.

10. Operational Takeaways

This mission demonstrated several useful Kubernetes operations:

Node-level coverage: A DaemonSet automatically placed an agent on each eligible node, including the second node added during the test.
Runtime visibility: The Downward API supplied the node name to the agent without hardcoding infrastructure details into the container command.
Finite task execution: The report Job completed three successful tasks and exposed their outputs through logs.
Recurring automation: The heartbeat CronJob created scheduled Jobs that printed timestamps.
Execution verification: Job completion counts and container logs provided separate ways to verify task outcomes.
Compute management: Scaling the AKS node pool demonstrated the relationship between node count and DaemonSet placement.
Resource awareness: The final resource listing showed how node-level, batch, scheduled, stateless, and stateful workloads coexist in the same cluster.

Conclusion

The node-agent DaemonSet was deployed and verified on the AKS node pool. Scaling the pool to two nodes resulted in one agent Pod on each node, and the pool was subsequently returned to one node.

The report Job completed all three required executions, with logs confirming that each Pod generated its report message. The heartbeat CronJob also ran successfully on its configured every-minute schedule, producing timestamped output.

Together, these implementations demonstrate how Kubernetes handles node-scoped agents, finite batch work, and recurring tasks through dedicated controllers.

In Part 8, the series will continue with the next mission, building on the workload and operational capabilities established here.

This article is Part 7 of the nine-part series, “Kubernetes on AKS: From Zero to Production Workloads.”

Kubernetes on AKS: From Zero to Production Workloads - StatefulSets and Persistent Storage (Part 6/9)

Rahimah Sulayman — Mon, 26 Oct 2026 18:38:17 +0000

Introduction

Applications that maintain data need more than a reliable way to run containers. They also need predictable identities, stable network addresses, and storage that remains available when Pods are replaced.

In this mission, I deployed a StatefulSet on Azure Kubernetes Service (AKS), paired it with a headless Service, and provisioned persistent Azure Disk volumes for its replicas. I then wrote data from inside a Pod, deleted that Pod, and verified that the replacement could still access the data. Finally, I tested the StatefulSet's DNS identity from another Pod in the cluster.

The objective was to demonstrate how Kubernetes supports stateful workloads whose identity and data must survive individual Pod replacement.

What This Part Covers

Inspecting the available Kubernetes StorageClasses.
Creating a headless Service.
Defining a StatefulSet with two replicas.
Provisioning persistent storage through managed-csi.
Verifying Pod identities and PersistentVolumeClaims.
Writing data to a Pod's persistent volume.
Deleting and waiting for a StatefulSet Pod to return.
Verifying that data survives Pod replacement.
Testing stable DNS access through the headless Service.

1. Inspect the Available StorageClasses

Before defining the StatefulSet, I inspected the StorageClasses available in the cluster:

kubectl get storageclass

The output showed several StorageClasses for Azure Files and Azure Disk. The managed-csi StorageClass was available for persistent disk provisioning.

Its relevant properties included:

Property	Value
StorageClass	`managed-csi`
Provisioner	`disk.csi.azure.com`
Reclaim policy	`Delete`
Volume binding mode	`WaitForFirstConsumer`
Volume expansion	Enabled

The managed-csi StorageClass uses the Azure Disk Container Storage Interface (CSI) driver. It allows Kubernetes to provision Azure-managed disks for workloads that request persistent storage.

The WaitForFirstConsumer binding mode delays volume binding and provisioning until a Pod using the claim is scheduled. This allows storage provisioning to account for the Pod's scheduling requirements.

The reclaim policy is also important. Delete means that a dynamically provisioned volume can be deleted when its PersistentVolume is released, depending on the lifecycle of the associated storage resources. Deleting an individual StatefulSet Pod does not, by itself, release its PersistentVolumeClaim.

2. Define a Headless Service and StatefulSet

I created manifests/06-statefulset.yaml to define both the headless Service and the StatefulSet.

cat << 'EOF' > manifests/06-statefulset.yaml
apiVersion: v1
kind: Service
metadata:
  name: store
spec:
  clusterIP: None
  selector:
    app: store
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: store
spec:
  serviceName: store
  replicas: 2
  selector:
    matchLabels:
      app: store
  template:
    metadata:
      labels:
        app: store
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
          volumeMounts:
            - name: data
              mountPath: /usr/share/nginx/html
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes:
          - ReadWriteOnce
        storageClassName: managed-csi
        resources:
          requests:
            storage: 1Gi
EOF

Why use a headless Service?

The Service is configured with:

clusterIP: None

This makes it a headless Service. Instead of providing a conventional cluster IP, it enables DNS records to resolve directly to the endpoints of the selected Pods.

The Service selects Pods labelled app: store and exposes port 80. It also provides the network identity associated with the StatefulSet.

Why use a StatefulSet?

The StatefulSet is named store and declares two replicas:

serviceName: store
replicas: 2

Unlike ordinary Deployment-managed Pods, StatefulSet Pods have stable ordinal identities. The two replicas use these names:

store-0
store-1

The StatefulSet also uses the store headless Service as its governing Service, allowing the Pods to have predictable DNS identities.

Persistent storage

The manifest defines a volumeClaimTemplates entry named data. Each replica receives its own PersistentVolumeClaim requesting 1Gi of storage from the managed-csi StorageClass.

The important settings are:

accessModes:
  - ReadWriteOnce
storageClassName: managed-csi
resources:
  requests:
    storage: 1Gi

The container mounts the volume at:

/usr/share/nginx/html

This is the directory NGINX serves as its default document root. Writing a file there allows the test to demonstrate whether the contents remain available after a Pod is replaced.

Because each StatefulSet replica receives its own claim, store-0 and store-1 do not share the same per-replica volume.

3. Deploy the StatefulSet

I applied the manifest:

kubectl apply -f manifests/06-statefulset.yaml

Kubernetes confirmed that both resources were created:

service/store created
statefulset.apps/store created

I then monitored the StatefulSet rollout:

kubectl rollout status statefulset/store

The command reported:

Waiting for 1 pods to be ready...
partitioned roll out complete: 2 new pods have been updated...

After the rollout, I inspected the StatefulSet, Pods, and PersistentVolumeClaims:

kubectl get statefulset,pods,pvc -l app=store

The two Pods were running:

NAME        READY   STATUS    RESTARTS
pod/store-0 1/1     Running   0
pod/store-1 1/1     Running   0

The PersistentVolumeClaims were also bound:

NAME                    STATUS   CAPACITY   ACCESS MODES   STORAGECLASS
persistentvolumeclaim/data-store-0   Bound   1Gi   RWO   managed-csi
persistentvolumeclaim/data-store-1   Bound   1Gi   RWO   managed-csi

This verified that the StatefulSet had created both replicas and Kubernetes had provisioned a separate 1Gi persistent volume claim for each one.

The stable Pod names and individual claims are central to the StatefulSet model: a replacement for store-0 is associated with the identity and storage claim belonging to store-0, rather than being treated as an entirely unrelated replica.

4. Write Data to the Persistent Volume

To test persistence, I wrote a message to the NGINX document root inside store-0:

kubectl exec store-0 -- sh -c 'echo "Hello from $(hostname), written at $(date)" > /usr/share/nginx/html/index.html'

The command writes a message containing the Pod's hostname and the current date into index.html.

Because the document root is backed by the persistent volume mounted at /usr/share/nginx/html, the test data is stored on the volume rather than only in the container's writable layer.

This creates a clear verification point: after the Pod is replaced, the file should still contain the original message if the same persistent claim is attached successfully.

5. Delete the Pod and Wait for Replacement

I deleted store-0 to test the StatefulSet's recovery behavior:

kubectl delete pod store-0

Kubernetes confirmed that the Pod had been deleted from the k8s-lab namespace.

The StatefulSet controller then worked to restore the desired replica count. Because store-0 is part of a StatefulSet, Kubernetes recreates the Pod with the same ordinal identity and reuses its associated PersistentVolumeClaim.

I waited for the replacement Pod to become ready:

kubectl wait --for=condition=Ready pod/store-0 --timeout=180s

The command returned:

pod/store-0 condition met

This confirmed that store-0 had returned to the Ready state.

6. Verify That the Data Survived

With store-0 ready again, I inspected the file:

kubectl exec store-0 -- cat /usr/share/nginx/html/index.html

The output was:

Hello from store-0, written at Mon Oct 26 09:56:05 UTC 2026

The message remained available after the original Pod had been deleted and replaced.

This confirmed the key behavior being tested: the replacement Pod retained access to the data stored on the PersistentVolume associated with store-0.

The Pod itself is replaceable, but its identity and associated persistent storage allow the application to recover without losing the file created during the test.

This does not mean that every storage configuration automatically survives every failure scenario. Data persistence depends on the volume lifecycle, reclaim policy, storage backend, and how the claims and volumes are managed. In this test, the StatefulSet's per-replica claim remained available through Pod replacement.

7. Verify Stable DNS from Another Pod

The headless Service also provides predictable network identities for the StatefulSet Pods.

To verify DNS access, I launched a temporary BusyBox Pod and requested the content through the hostname store-0.store:

kubectl run dns-test --rm -i --restart=Never \
  --image=busybox:1.36 -- wget -qO- http://store-0.store

The response contained:

Hello from store-0, written at Mon Oct 26 09:56:05 UTC 2026

The temporary Pod returned the same content written before store-0 was deleted.

This verified two aspects of the implementation:

The name store-0.store resolved and allowed access to the NGINX endpoint.
The endpoint served the data that persisted across the Pod replacement.

The store-0.store hostname is derived from the StatefulSet Pod identity and its governing headless Service. This predictable naming is particularly useful for applications that need to communicate with specific replicas.

The temporary dns-test Pod was configured with --rm, so Kubernetes removed it when the command completed.

8. StatefulSet vs. Deployment

StatefulSets and Deployments both manage replicated workloads, but they address different operational requirements.

Capability	Deployment	StatefulSet
Pod identity	Typically interchangeable Pod names	Stable ordinal names such as `store-0`
Stable per-replica storage	Not provided automatically through a Deployment's usual model	Supported through `volumeClaimTemplates`
Common use cases	Stateless web applications and APIs	Stateful applications requiring stable identity or storage
Scaling and replacement	Reconciles desired replica count	Reconciles replicas while preserving ordinal identity
Networking	Commonly accessed through a Service	Can use a headless Service for per-Pod DNS identities

A StatefulSet is not automatically the right choice for every application that writes files. The appropriate workload resource depends on whether the application needs stable identity, ordered operations, or persistent storage tied to individual replicas.

In this mission, those features made the StatefulSet a suitable way to demonstrate data persistence across Pod replacement.

9. Operational Takeaways

This mission demonstrated how StatefulSets, headless Services, and persistent storage work together on AKS.

The main takeaways were:

Stable workload identity: StatefulSet replicas have predictable names that remain associated with their ordinals when Pods are replaced.
Persistent storage: Each replica receives its own PersistentVolumeClaim through volumeClaimTemplates.
Dynamic provisioning: The managed-csi StorageClass allows Kubernetes to provision Azure Disk storage for the claims.
Pod recovery: Deleting store-0 caused the StatefulSet controller to recreate the same logical replica.
Data continuity: The file written before deletion remained available after the replacement Pod became ready.
Stable DNS: A headless Service enables per-Pod DNS identities, allowing another Pod to access store-0 through store-0.store.
Storage lifecycle awareness: Persistent volume behavior depends on the claim and volume lifecycle, access modes, storage class, and reclaim policy—not only on the Pod resource.

Conclusion

The store StatefulSet was deployed with two replicas, a headless Service, and separate 1Gi persistent volume claims backed by the managed-csi StorageClass.

I wrote a file to store-0, deleted the Pod, waited for the replacement to become ready, and verified that the original file content remained available. A request to http://store-0.store from a temporary Pod returned the same content, confirming that the stable DNS identity and persistent storage were working together as intended.

This is the primary distinction between simply recreating a container and managing a stateful workload: the replacement can recover with its expected identity and retain access to its data.

In Part 7, the series will continue with the next mission, building on the workload and storage capabilities established here.

This article is Part 6 of the nine-part series, “Kubernetes on AKS: From Zero to Production Workloads.”

Kubernetes on AKS: From Zero to Production Workloads - Services, ConfigMaps and Secrets (Part 5/9)

Rahimah Sulayman — Mon, 26 Oct 2026 18:12:33 +0000

Introduction

A running application needs more than healthy Pods. It also needs a reliable way to receive traffic and a secure, maintainable approach to handling configuration.

In this mission, I extended the NGINX Deployment on Azure Kubernetes Service (AKS) by creating internal and external Services, testing application access, and separating configuration values from the container image. I also created a Kubernetes Secret, verified its stored value, and injected both ConfigMap and Secret data into the running Deployment as environment variables.

The implementation demonstrates how Kubernetes networking and configuration resources work together to make workloads accessible and configurable without rebuilding their images.

What This Part Covers

Creating a ClusterIP Service for internal application access.
Testing the NGINX application inside the cluster.
Exposing the Deployment through a LoadBalancer Service.
Verifying the public endpoint.
Creating a ConfigMap from literal values.
Creating a Secret for a sensitive configuration value.
Injecting ConfigMap and Secret values into the Deployment.
Verifying the environment variables inside a running container.

1. Create a ClusterIP Service

I started by defining an internal Service in manifests/03-service-clusterip.yaml.

cat << 'EOF' > manifests/03-service-clusterip.yaml
apiVersion: v1
kind: Service
metadata:
  name: web-svc
spec:
  type: ClusterIP
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80
EOF

The manifest defines a Service named web-svc with the following configuration:

type: ClusterIP creates an internal Service address that is reachable from within the cluster.
selector: app: web identifies the Pods that receive traffic through the Service.
port: 80 specifies the port exposed by the Service.
targetPort: 80 specifies the destination port on the selected Pods.

The selector connects the Service to the web Deployment's Pods, which carry the app: web label.

This is an important distinction: clients communicate with the Service rather than depending on an individual Pod IP address. Kubernetes maintains the Service's routing to the eligible backend Pods as the workload changes.

I applied the manifest:

kubectl apply -f manifests/03-service-clusterip.yaml

The Service provides a stable internal endpoint for the application. It does not, by itself, expose the application directly to the public internet.

2. Test Internal Application Access

After configuring the internal Service, I tested access to the NGINX application from inside the Kubernetes environment.

kubectl run curl-test --rm -i --restart=Never --image=busybox:1.36 -- wget -qO- http://web-svc

It starts a temporary Pod called curl-test inside the cluster, using the small busybox image. The Pod runs wget to fetch http://web-svc, and the Service’s name resolves through CoreDNS. --rm deletes the Pod afterwards, -i shows the output, and --restart=Never stops Kubernetes from restarting it once it finishes. The command returned the default “Welcome to nginx!” HTML, which showed the app was reachable through the ClusterIP Service from inside the cluster.

<title>Welcome to nginx!</title>

The response also contained the page's standard message confirming that the NGINX web server was installed and running.

This verified that the application could respond to an HTTP request from within the cluster.

Testing internal connectivity before exposing a workload externally is useful because it separates application and internal networking checks from the additional configuration required for public access.

3. Expose the Application with a LoadBalancer Service

For external access, I created a second Service in manifests/04-service-loadbalancer.yaml.

cat << 'EOF' > manifests/04-service-loadbalancer.yaml
apiVersion: v1
kind: Service
metadata:
  name: web-public
spec:
  type: LoadBalancer
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80
EOF

The Service uses the same app: web selector as the internal Service, so it routes traffic to the Pods managed by the Deployment.

The key difference is:

type: LoadBalancer

On AKS, this Service type requests an Azure load balancer configuration that can expose the application through an external IP address.

I applied the manifest:

kubectl apply -f manifests/04-service-loadbalancer.yaml

Kubernetes confirmed that the Service was created:

service/web-public created

I then watched the Service status:

kubectl get service web-public --watch

The output showed:

NAME         TYPE           CLUSTER-IP   EXTERNAL-IP      PORT(S)
web-public   LoadBalancer   10.0.73.23   20.61.154.190   80:31236/TCP

The assigned addresses and port information were:

Cluster IP: 10.0.73.23
External IP: 20.61.154.190
Service port: 80
NodePort: 31236

The external IP made the NGINX application reachable through the load balancer.

Verify the public endpoint

I tested the external endpoint using curl:

curl -s http://$(kubectl get service web-public -o jsonpath='{.status.loadBalancer.ingress[0].ip}') | grep title

The response was:

<title>Welcome to nginx!</title>

This confirmed that the request reached the NGINX application through the public Service endpoint.

A LoadBalancer Service is useful when an application needs an externally reachable endpoint. However, public exposure should be deliberate: production workloads may also require network restrictions, TLS termination, ingress routing, and appropriate access controls.

4. Create a ConfigMap

Application configuration should not always be embedded in a container image. Kubernetes ConfigMaps provide a way to store non-sensitive configuration separately from application code and image builds.

I generated a ConfigMap manifest from literal values:

kubectl create configmap web-config \
  --from-literal=APP_ENV=production \
  --from-literal=WELCOME_MSG="Hello from AKS" \
  --dry-run=client -o yaml > manifests/05-configmap.yaml

The command generated the YAML locally rather than immediately creating the resource in the cluster. The output was saved to manifests/05-configmap.yaml.

The configuration contained two values:

Key	Value
`APP_ENV`	`production`
`WELCOME_MSG`	`Hello from AKS`

I then applied the generated manifest:

kubectl apply -f manifests/05-configmap.yaml

Kubernetes confirmed:

configmap/web-config created

To inspect the stored configuration, I ran:

kubectl get configmap web-config -o yaml

The output included:

data:
  APP_ENV: production
  WELCOME_MSG: Hello from AKS

This verified that the ConfigMap contained the expected configuration values.

Because the ConfigMap is separate from the container image, these values can be managed independently of the image build. ConfigMaps are intended for non-sensitive data and should not be used to store credentials or other confidential values.

5. Create a Kubernetes Secret

For the next configuration value, I created a Kubernetes Secret named web-secret.

kubectl create secret generic web-secret \
  --from-literal=API_KEY=change-me-123

Kubernetes returned:

secret/web-secret created

The Secret contains the key API_KEY, with a placeholder value used in this lab.

Unlike a ConfigMap, a Secret is designed for sensitive configuration data. However, creating a Kubernetes Secret does not automatically make the value safe: access controls, encryption at rest, and appropriate secret-management practices still matter.

Verify the stored value

I verified the value using:

kubectl get secret web-secret -o jsonpath='{.data.API_KEY}' | base64 --decode; echo

The output was:

change-me-123

Kubernetes stores Secret data in a base64-encoded representation in the API object. Base64 is an encoding mechanism, not encryption. Anyone authorized to retrieve and decode the value can read it.

The value used here is only a lab placeholder. Real API keys and production credentials should not be committed to a repository or exposed in terminal output, screenshots, or documentation.

6. Inject the ConfigMap into the Deployment

With the ConfigMap and Secret created, I configured the web Deployment to consume their values as environment variables.

First, I added the ConfigMap values:

kubectl set env deployment/web --from=configmap/web-config

Kubernetes confirmed:

deployment.apps/web env updated

This added the ConfigMap's key-value pairs to the container environment defined by the Deployment.

The values supplied by web-config were:

APP_ENV=production
WELCOME_MSG=Hello from AKS

7. Inject the Secret into the Deployment

I then added the Secret value to the Deployment:

kubectl set env deployment/web --from=secret/web-secret

Kubernetes returned:

deployment.apps/web env updated

This configured the container environment to include API_KEY from web-secret.

Changing the Deployment's Pod template triggered a rollout. I verified that the rollout completed:

kubectl rollout status deployment/web

The output confirmed:

deployment "web" successfully rolled out

The new Pods were created using the updated Deployment configuration.

Verify the environment variables

To verify that the values were available inside a running container, I executed:

kubectl exec deploy/web -- printenv APP_ENV WELCOME_MSG API_KEY

The output was:

production
Hello from AKS
change-me-123

This confirmed that the container received the values from both Kubernetes configuration resources.

The ConfigMap supplied the non-sensitive application configuration, while the Secret supplied the placeholder API key. Both were injected into the container environment without rebuilding the NGINX image.

For real workloads, avoid printing secrets to logs or terminal output unnecessarily. When applications support it, mounting secrets as files or retrieving credentials from an external secret manager may be more appropriate, depending on the security requirements.

8. ClusterIP vs. LoadBalancer

The two Services created in this mission serve different networking purposes.

Feature	`ClusterIP`	`LoadBalancer`
Primary purpose	Internal application access	External application access
Default reachability	Within the cluster	Through an external load balancer when provisioned
Stable Service endpoint	Yes	Yes
Typical use	Internal APIs and service-to-service traffic	Applications that require a public or externally reachable endpoint

Both Services use label selectors to route traffic to the appropriate Pods. The choice of Service type depends on where the clients are located and how the application should be exposed.

9. Operational Takeaways

This mission brought together Kubernetes networking and configuration management.

The main operational takeaways were:

Stable internal networking: A ClusterIP Service provides an internal endpoint independent of individual Pod IP addresses.
External access: A LoadBalancer Service can expose an application through an Azure-managed external endpoint.
Separation of configuration: ConfigMaps allow non-sensitive settings to be managed separately from the container image.
Secret handling: Kubernetes Secrets provide a dedicated resource for sensitive values, but they still require appropriate security controls.
Environment injection: ConfigMap and Secret values can be supplied to containers through the Deployment's environment configuration.
Rollout verification: Updating the Deployment's Pod template triggers a rollout, which can be monitored with kubectl rollout status.
Connectivity testing: Testing both internal and external access verifies different parts of the application networking path.

Conclusion

The web Deployment was made accessible through an internal ClusterIP Service and an external LoadBalancer Service. The public endpoint returned the NGINX welcome page, confirming that external access was working.

I also created web-config and web-secret, injected their values into the Deployment, and verified the resulting environment variables inside a running container.

The result is a workload with a stable networking interface and configuration managed independently of its container image. These patterns form an important foundation for applications that need controlled connectivity and maintainable configuration on AKS.

In Part 6, the series will continue with the next mission, building on the networking and configuration resources established here.

This article is Part 5 of the nine-part series, “Kubernetes on AKS: From Zero to Production Workloads.”

Kubernetes on AKS: From Zero to Production Workloads -Deployments, Self-Healing, Scaling and Rolling Updates (Part 4/9)

Rahimah Sulayman — Mon, 26 Oct 2026 17:05:48 +0000

Introduction

Running a container in Kubernetes is only the starting point. Production workloads also need mechanisms for maintaining the desired number of replicas, recovering from Pod failures, scaling with demand, and updating application versions without unnecessary disruption.

In this mission, I used a Kubernetes Deployment to manage an NGINX workload on Azure Kubernetes Service (AKS). I configured three replicas, added health probes and resource constraints, verified the rollout, deleted a Pod to observe self-healing, scaled the Deployment, updated the container image, inspected rollout history, and rolled back to the previous version.

What This Part Covers

Defining a Deployment with three NGINX replicas.
Configuring resource requests, limits, and health probes.
Verifying the rollout and associated ReplicaSet.
Observing automatic Pod replacement after deletion.
Scaling the Deployment from three replicas to five and back.
Updating the NGINX image.
Inspecting rollout history and recording the change cause.
Rolling back to the previous Deployment revision.

1. Define the Deployment Manifest

I created the Deployment manifest at manifests/02-deployment.yaml.

cat << 'EOF' > manifests/02-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
              memory: 128Mi
          readinessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 3
            periodSeconds: 10
EOF

The manifest defines a Deployment named web, using the apps/v1 API and the app: web label to identify its Pods.

Replica management

replicas: 3
selector:
  matchLabels:
    app: web

The Deployment declares three desired replicas. Its selector matches Pods labelled app: web, while the Pod template applies that label to each replica it creates.

This relationship allows the Deployment controller to manage the workload through a ReplicaSet, which maintains the required number of Pods.

Rolling update strategy

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1
    maxUnavailable: 0

The update strategy controls how Kubernetes replaces old Pods during an update.

maxSurge: 1 allows one additional Pod above the desired replica count during a rollout.
maxUnavailable: 0 prevents the Deployment from intentionally reducing the number of available replicas below the desired count during the rolling update.

These settings prioritize availability during updates, provided the cluster has sufficient capacity and the replacement Pods can become ready.

Container resources and health checks

The NGINX container uses the nginx:1.27 image and exposes container port 80.

Its resource settings are:

Resource	Request	Limit
CPU	`50m`	`200m`
Memory	`64Mi`	`128Mi`

The manifest also defines a readiness probe that sends an HTTP request to / on port 80. It begins checking after three seconds and repeats every ten seconds.

A readiness probe helps Kubernetes determine whether a container is ready to receive traffic. The configuration also establishes resource boundaries for each replica, making resource expectations explicit.

2. Apply the Deployment and Verify the Rollout

I applied the manifest to the cluster:

kubectl apply -f manifests/02-deployment.yaml

Kubernetes returned:

deployment.apps/web created

I then monitored the rollout:

kubectl rollout status deployment/web

The command confirmed:

deployment "web" successfully rolled out

To inspect the Deployment, ReplicaSet, and Pods together, I ran:

kubectl get deployment,replicaset,pods -l app=web

The results showed:

NAME                 READY   UP-TO-DATE   AVAILABLE
deployment.apps/web  3/3     3            3

NAME                     DESIRED   CURRENT   READY
replicaset.apps/web-5b77b547f8  3   3         3

NAME                          READY   STATUS
pod/web-5b77b547f8-5jwm5       1/1     Running
pod/web-5b77b547f8-5tzd h      1/1     Running
pod/web-5b77b547f8-qpzqh       1/1     Running

The important result was that the Deployment had three available replicas, the ReplicaSet maintained three Pods, and all three Pods were running.

The Deployment and ReplicaSet provide different levels of workload management. The Deployment manages rollout and revision history, while the ReplicaSet maintains the required number of matching Pods.

Together, they provide more control over application availability than a standalone Pod.

3. Verify Self-Healing by Deleting a Pod

To test the Deployment controller's reconciliation behavior, I deleted one of the Pods selected by the app=web label.

I used the following command to identify a Pod and pass its name to kubectl delete:

kubectl delete pod $(kubectl get pods -l app=web -o jsonpath='{.items[0].metadata.name}')

Kubernetes confirmed that the selected Pod had been deleted from the k8s-lab namespace.

I then checked the Pods again:

kubectl get pods -l app=web

The output showed three running Pods. A replacement had been created to maintain the Deployment's desired replica count.

This is the Deployment controller's reconciliation behavior in action. The desired state remained three replicas, so Kubernetes worked to restore that state after one Pod was removed.

The replacement Pod did not need to retain the deleted Pod's name. Kubernetes created a new Pod from the Deployment's template through its ReplicaSet.

Operational takeaway: Deleting a Pod managed by a Deployment does not normally reduce the workload's desired replica count. The controller works to maintain that count.

4. Scale the Deployment

The next step was to change the desired replica count.

I scaled the Deployment from three replicas to five:

kubectl scale deployment web --replicas=5

Kubernetes returned:

deployment.apps/web scaled

To verify the result and inspect the Pod placement, I ran:

kubectl get pods -l app=web -o wide

The output showed five running Pods, each with a Pod IP and placement on the AKS node.

I then scaled the Deployment back to three replicas:

kubectl scale deployment web --replicas=3

This returned:

deployment.apps/web scaled

Scaling changes the number of Pod replicas managed by the Deployment. Scaling out from three to five increased the number of running instances, while scaling back to three reduced the desired replica count.

This operation was performed manually with kubectl scale. It was not an automatic response to CPU utilization or incoming traffic; automatic scaling requires additional configuration, such as a Horizontal Pod Autoscaler.

5. Update the NGINX Container Image

After verifying replica management, I updated the Deployment to use the nginx:1.27-alpine image:

kubectl set image deployment/web nginx=nginx:1.27-alpine

Kubernetes confirmed:

deployment.apps/web image updated

The new image uses the Alpine-based NGINX image variant. Changing the image in a Deployment triggers a rollout, allowing Kubernetes to replace Pods according to the configured update strategy.

I then annotated the Deployment with the reason for the change:

kubectl annotate deployment/web kubernetes.io/change-cause="switch to nginx 1.27-alpine"

The output confirmed:

deployment.apps/web annotated

Recording the change cause makes the intention behind a revision easier to identify when reviewing rollout history.

6. Verify the Rollout and Inspect Revision History

I checked the status of the updated Deployment:

kubectl rollout status deployment/web

The rollout completed successfully:

deployment "web" successfully rolled out

I then inspected the revision history:

kubectl rollout history deployment/web

The output showed two revisions:

deployment.apps/web

REVISION  CHANGE-CAUSE
1         <none>
2         switch to nginx 1.27-alpine

Revision 1 represented the original Deployment configuration, while revision 2 recorded the change to the Alpine image.

The history provides an operational record of Deployment revisions and their associated change causes. This can help identify which version is currently deployed and which revision to restore if an update needs to be reversed.

7. Roll Back to the Previous Revision

To demonstrate rollback, I reverted the Deployment to its previous revision:

kubectl rollout undo deployment/web

Kubernetes returned:

deployment.apps/web rolled back

The command also displayed a warning explaining that the Deployment had previously been managed with kubectl apply. A rollback does not update the kubectl.kubernetes.io/last-applied-configuration annotation, which can affect the behavior of future kubectl apply operations. Kubernetes recommended applying the previous configuration file when appropriate.

This warning is worth noting when mixing imperative changes, such as kubectl set image, with declarative manifest management. The live Deployment, its rollout history, and the last-applied configuration annotation are related, but they are not interchangeable.

To verify the image configured in the Deployment after the rollback, I ran:

kubectl get deployment web -o jsonpath='{.spec.template.spec.containers[0].image}'; echo

The output was:

nginx:1.27

This confirmed that the Deployment's Pod template had returned to the original image.

The rollback demonstrated how Deployment revision history can be used to reverse a change without manually recreating the entire workload.

8. Operational Takeaways

This mission demonstrated several core capabilities used to manage Kubernetes applications:

Desired-state management: A Deployment maintains the declared number of replicas through its controller and ReplicaSet.
Self-healing: When a managed Pod is deleted, Kubernetes creates a replacement to restore the desired replica count.
Scaling: The replica count can be increased or reduced to change the number of running application instances.
Health checks: Readiness probes help Kubernetes determine whether a container is ready to receive traffic.
Rolling updates: A Deployment can replace Pods gradually according to its update strategy.
Revision history: Rollout history provides a record of Deployment revisions and their recorded change causes.
Rollback: A previous Deployment revision can be restored when an update needs to be reversed.
Configuration management: Mixing imperative updates with declarative kubectl apply requires attention to the last-applied configuration and future changes.

These capabilities provide a stronger operational foundation than managing individual Pods directly. They make application changes more controlled and help maintain the intended state of a workload.

Conclusion

The web Deployment was successfully created with three NGINX replicas, and its rollout was verified. I confirmed that Kubernetes replaced a deleted Pod, scaled the Deployment to five replicas and back to three, updated the image to nginx:1.27-alpine, reviewed the rollout history, and restored the original nginx:1.27 image through rollback.

The key distinction is that a Deployment manages the desired state of an application rather than relying on individual Pods to remain unchanged. Replica management, health checks, rolling updates, and rollback together provide essential tools for operating workloads reliably on AKS.

In Part 5, the series will continue with the next mission, building on the workload-management capabilities established here.

This article is Part 4 of the nine-part series, “Kubernetes on AKS: From Zero to Production Workloads.”

Kubernetes on AKS: From Zero to Production Workloads - Pods, the Smallest Unit (Part 3/9)

Rahimah Sulayman — Mon, 26 Oct 2026 16:42:24 +0000

Introduction

A Kubernetes Pod is the smallest deployable unit in Kubernetes. It provides the execution environment for one or more containers, along with shared networking and storage resources.

In this mission, I deployed a standalone NGINX Pod to my Azure Kubernetes Service (AKS) cluster, defined its resource requirements, inspected its runtime state, reviewed its logs, accessed the application locally, and examined what happens when a standalone Pod is deleted.

The focus was on the Pod lifecycle and the operational details that matter when running containerized workloads on Kubernetes.

What This Part Covers

Defining a Pod using a Kubernetes YAML manifest.
Deploying the Pod to the k8s-lab namespace.
Verifying its status, IP address, and assigned node.
Inspecting container configuration and resource constraints.
Reviewing NGINX logs and verifying its version.
Accessing the application through port forwarding.
Observing the behavior of a standalone Pod after deletion.

1. Define the Pod Manifest

I created the manifest at manifests/01-pod.yaml in the project repository.

cat << 'EOF' > manifests/01-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: web-pod
  labels:
    app: web-pod
spec:
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80
      resources:
        requests:
          cpu: 50m
          memory: 64Mi
        limits:
          cpu: 200m
          memory: 128Mi
EOF

The manifest defines a Pod named web-pod containing one NGINX container.

Key configuration details

apiVersion: v1 specifies the Kubernetes API version for the Pod resource.
kind: Pod identifies the resource being created.
metadata.name assigns the name web-pod.
metadata.labels attaches the app: web-pod label, which can be used to identify and select the Pod.
image: nginx:1.27 specifies the NGINX container image.
containerPort: 80 documents the port on which the container is expected to receive HTTP traffic.
CPU request: 50m declares 50 millicores of CPU as the container's requested compute capacity.
Memory request: 64Mi declares 64 mebibytes of requested memory.
CPU limit: 200m sets the container's CPU usage limit.
Memory limit: 128Mi sets the container's memory limit.

Resource requests and limits serve different purposes. Requests influence scheduling decisions, while limits constrain the resources a container can consume. CPU limits can result in throttling, whereas exceeding a container's memory limit can lead to termination.

Defining these values makes the workload's resource expectations explicit rather than leaving them entirely unspecified.

2. Deploy the Pod

With the manifest in place, I applied it to the cluster:

kubectl apply -f manifests/01-pod.yaml

Kubernetes confirmed that the resource had been created:

pod/web-pod created

I then checked the Pod's status and placement:

kubectl get pods -o wide

The output showed:

NAME      READY   STATUS    RESTARTS   AGE   IP           NODE
web-pod   1/1     Running   0          25s   10.244.0.139 aks-nodepool1-33590657-vmss000000

The important observations were:

Ready: 1/1 — the Pod's single container was ready.
Status: Running — the Pod had started successfully.
Restarts: 0 — no container restarts had occurred at the time of inspection.
Pod IP: 10.244.0.139 — Kubernetes assigned the Pod an internal IP address.
Node: aks-nodepool1-33590657-vmss000000 — the scheduler placed the Pod on this AKS worker node.

The -o wide option exposes additional placement and networking information beyond the default Pod listing.

This verified that the manifest had been accepted and the NGINX workload was running in the k8s-lab namespace.

3. Inspect the Pod Configuration and Runtime State

To examine the Pod in more detail, I ran:

kubectl describe pod web-pod

The output confirmed that web-pod was running in the k8s-lab namespace, with the nginx container using the nginx:1.27 image.

The inspection also exposed the container's runtime information, resource configuration, readiness conditions, assigned node, and recent events.

Container readiness

The Pod reported the following conditions as true:

Initialized
Ready
ContainersReady
PodScheduled

These conditions provide useful operational information. A Pod's existence alone does not guarantee that its application is ready to serve traffic. Checking readiness and container state helps distinguish a successfully scheduled workload from one that is actually running and ready.

Resource configuration

The container's reported resource settings matched the manifest:

Resource	Request	Limit
CPU	`50m`	`200m`
Memory	`64Mi`	`128Mi`

The events also recorded the scheduling, image-pulling, container-creation, and container-start operations.

The image was pulled successfully, and Kubernetes started the container without reporting a restart.

This inspection connected the desired configuration in the YAML manifest with the state Kubernetes was reporting for the running workload.

4. Review the NGINX Logs

I retrieved the container logs with:

kubectl logs web-pod

The output showed the NGINX container entrypoint initializing its configuration and launching the NGINX process.

The logs included messages indicating that configuration was complete and that NGINX was ready to start up. They also showed the NGINX worker processes starting.

Reviewing logs is an important part of troubleshooting containerized applications. They can reveal startup failures, configuration problems, and application-level errors that may not be obvious from the Pod status alone.

In this case, the startup output was consistent with a successfully initialized NGINX container.

5. Verify the NGINX Version

To inspect the NGINX version from inside the running container, I executed:

kubectl exec web-pod -- nginx -v

The command returned:

nginx version: nginx/1.27.5

This verified the version of NGINX running inside the container.

The manifest specified the nginx:1.27 image tag, while the running binary reported version 1.27.5. This illustrates why inspecting the runtime can provide useful information beyond the image tag declared in a manifest.

6. Access the Application with Port Forwarding

The Pod was running NGINX on container port 80. To access it from my local machine without creating a Kubernetes Service or exposing the application publicly, I used port forwarding:

kubectl port-forward pod/web-pod 8080:80

The terminal reported:

Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

This forwarded local port 8080 to port 80 on the Pod.

With the port-forwarding process running, I opened the following address in my browser:

http://localhost:8080

The browser displayed the default Welcome to nginx! page, confirming that the NGINX web server was accessible through the local port-forwarding connection.

Port forwarding provided a convenient way to test the application without creating a public endpoint. The connection remained dependent on the kubectl port-forward process, so it was useful for this verification rather than as a production traffic-routing solution.

Important: The port-forwarding command occupies the terminal while it is running. I kept that process active while accessing the page in the browser.

7. Delete the Standalone Pod

After verifying the application, I deleted the Pod:

kubectl delete pod web-pod

Kubernetes confirmed:

pod "web-pod" deleted from k8s-lab namespace

I then checked the namespace for remaining Pods:

kubectl get pods

The result was:

No resources found in k8s-lab namespace.

This confirmed that the standalone Pod had been removed and that no Pods remained in the namespace at the time of the check.

Why the Pod was not recreated

A standalone Pod does not have a higher-level workload controller responsible for maintaining a desired number of replicas.

Deleting it therefore removed the workload without automatically creating a replacement.

This behavior is an important distinction between running a Pod directly and managing workloads through resources such as Deployments or StatefulSets. Controllers can reconcile the actual state with the declared desired state, including replacing Pods when necessary.

For this mission, deleting the standalone Pod demonstrated its lifecycle and the absence of automatic replacement.

8. Operational Takeaways

This mission established a complete workflow for deploying and inspecting a basic Kubernetes workload.

The key operational points were:

Declarative configuration: A YAML manifest defines the desired Pod configuration and can be stored alongside the rest of the project.
Resource management: CPU and memory requests and limits establish explicit resource expectations for the container.
Runtime inspection: kubectl get pods -o wide and kubectl describe pod expose different levels of information about scheduling, readiness, networking, and container state.
Log inspection: kubectl logs helps reveal what happens during application startup.
Container-level verification: kubectl exec can be used to inspect the running container, including its software version.
Local application access: Port forwarding provides a practical way to test a Pod without creating a public endpoint.
Pod lifecycle: A standalone Pod is not automatically recreated after deletion because no higher-level controller manages its desired state.

Conclusion

The web-pod workload was successfully deployed to AKS, inspected at both the Kubernetes and container levels, accessed through local port forwarding, and subsequently deleted.

The exercise demonstrated how Kubernetes manifests translate into running workloads and how the Kubernetes CLI supports verification throughout the Pod lifecycle.

A standalone Pod is useful for understanding the fundamentals and performing targeted tests. For workloads that require resilience, scaling, and automatic replacement, higher-level controllers provide the management capabilities needed to maintain the desired state.

In the next part of this series, I will continue building on the AKS environment and explore the next workload-management concept in the lab.

This article is Part 3 of the nine-part series, “Kubernetes on AKS: From Zero to Production Workloads.”

Kubernetes on AKS: From Zero to Production Workloads -Creating the AKS Cluster (Part 2/9)

Rahimah Sulayman — Mon, 26 Oct 2026 16:13:41 +0000

Introduction

Provisioning a Kubernetes cluster is the next step after preparing the development environment. In this part of the series, I moved from local tooling setup to creating an Azure Kubernetes Service (AKS) cluster, connecting kubectl to it, verifying the cluster, and preparing a dedicated namespace for workloads.

The objective was to establish a working Kubernetes environment on Azure that could support the deployments and experiments in the missions that follow.

What This Part Covers

Loading the lab configuration.
Creating an Azure resource group.
Provisioning an AKS cluster.
Retrieving cluster credentials and configuring kubectl.
Verifying the cluster and its system components.
Creating and selecting a Kubernetes namespace.

1. Load the Lab Configuration

I started from the project directory created in Part 1:

cd /mnt/c/Users/Admin/Desktop/labs/aks-kubernetes-lab

Before provisioning any Azure resources, I loaded the environment variables defined in lab.env:

source lab.env

The environment file provides the configuration used by the commands in this mission, including the resource group name, cluster name, Azure region, and node size.

Using variables instead of repeatedly hardcoding resource names makes the commands easier to maintain and reuse throughout the lab.

2. Check the Resource Group and Create It

Before creating the resource group, I checked whether it already existed:

az group show --name $RESOURCE_GROUP --query location --output tsv 2>/dev/null

The command queries the resource group's location. Redirecting standard error to /dev/null suppresses error messages if the resource group does not exist.

I then created the resource group:

az group create --name $RESOURCE_GROUP --location $LOCATION --output table

The command returned the following result:

Location    Name
----------  ----------
westeurope  rg-aks-lab

This confirmed that the resource group rg-aks-lab was available in westeurope.

An Azure resource group provides a logical container for related resources. In this lab, it serves as the main resource group for the AKS environment.

3. Provision the AKS Cluster

With the resource group created, I provisioned the AKS cluster using the Azure CLI:

az aks create \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --location $LOCATION \
  --tier free \
  --node-count 1 \
  --node-vm-size $NODE_SIZE \
  --generate-ssh-keys \
  --output table

Here is what the main options do:

--resource-group specifies the Azure resource group that will contain the cluster.
--name sets the AKS cluster name.
--location specifies the Azure region.
--tier free selects the Free tier for AKS cluster management.
--node-count 1 configures one initial worker node.
--node-vm-size specifies the virtual machine size for the node.
--generate-ssh-keys generates SSH keys if required.
--output table presents the returned information in a table format.

The command displayed a notice that the aks-preview extension had altered its behavior. It also warned that the new node pool would enable SSH access and recommended using --ssh-access disabled to disable SSH access for better security.

The command subsequently returned cluster information, including the Kubernetes version, provisioning state, resource group, and cluster name.

The key result was:

ProvisioningState: Succeeded
ResourceGroup:     rg-aks-lab
Name:              aks-lab
Location:          westeurope

The provisioning state of Succeeded confirmed that Azure had completed the cluster creation operation.

4. Connect kubectl to the AKS Cluster

Creating the cluster is only part of the process. I also needed to configure my local Kubernetes client to communicate with it.

I retrieved the cluster credentials with:

az aks get-credentials \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --overwrite-existing

The command returned:

Merged "aks-lab" as current context in /home/rahimahisah/.kube/config

This merged the AKS cluster credentials into the local kubeconfig file and selected the aks-lab context.

To confirm the active context, I ran:

kubectl config current-context

The output was:

aks-lab

This confirmed that kubectl was configured to use the AKS cluster context.

Kubernetes contexts allow a single kubeconfig file to hold connection details for multiple clusters. Checking the active context before running commands is a useful habit because it helps prevent accidentally targeting the wrong environment.

5. Verify the Kubernetes Cluster

After connecting kubectl, I checked the cluster's node status:

kubectl get nodes -o wide

The output showed:

NAME                                STATUS   ROLES    AGE     VERSION
aks-nodepool1-33590657-vmss000000   Ready    <none>   3m18s   v1.36.4

The node was in the Ready state, indicating that Kubernetes considered it ready to accept workloads.

The wider output also included information about the node's internal IP address, operating system image, kernel version, and container runtime.

The node was running Ubuntu 24.04.5 LTS, and the Kubernetes version shown was v1.36.4.

Inspect the cluster components

Next, I checked the cluster information:

kubectl cluster-info

The output confirmed that the Kubernetes control plane was running and displayed the endpoints for CoreDNS and the metrics server.

I then inspected the system pods in the kube-system namespace:

kubectl get pods --namespace kube-system

The output showed system components in the Running state, including:

azure-cns
azure-ip-masq-agent
cloud-node-manager
coredns
coredns-autoscaler
csi-azuredisk-node
csi-azurefile-node
kube-proxy
metrics-server
konnectivity-agent

These components support the operation of the cluster. For example, CoreDNS provides cluster DNS services, the CSI node components support storage integration, and the metrics server provides resource metrics used by Kubernetes tools and autoscaling components.

Checking the node, cluster information, and system pods provided an initial verification that the cluster was accessible and its core components were running.

Screenshot 4: Node status, cluster information, and system pods.

6. Create a Dedicated Kubernetes Namespace

With the cluster verified, I created a namespace for the lab workloads:

kubectl create namespace k8s-lab

Kubernetes confirmed the operation:

namespace/k8s-lab created

I then configured the current context to use the new namespace by default:

kubectl config set-context --current --namespace=k8s-lab

The output confirmed that the aks-lab context had been modified.

To verify the namespace configured in the current context, I ran:

kubectl config view --minify --output 'jsonpath={..namespace}'; echo

The result was:

k8s-lab

This means that subsequent kubectl commands that do not explicitly specify a namespace will use k8s-lab by default.

Namespaces provide a way to organize Kubernetes resources within a cluster. Creating a dedicated namespace keeps the lab workloads separate from system components running in kube-system.

7. What Learned

This mission connected the local tooling setup from Part 1 to a working Kubernetes environment hosted on Azure.

The key takeaways were:

Azure resource organization: Resource groups provide a logical boundary for related Azure resources.
Cluster provisioning: The Azure CLI can provision an AKS cluster using a repeatable set of configuration options.
Kubernetes authentication and context: Retrieving credentials allows kubectl to communicate with the selected cluster.
Cluster verification: Checking node readiness, cluster information, and system pods helps establish whether the environment is operational.
Namespace management: A dedicated namespace helps organize lab workloads and avoid mixing them with system resources.

One important habit I reinforced was verifying the active Kubernetes context before working with cluster resources. It is a small check that can help prevent mistakes when managing multiple environments.

Conclusion

The AKS cluster was provisioned successfully, the local Kubernetes client was connected to it, and the k8s-lab namespace was created and selected as the default namespace for the current context.

The environment is now ready for the next stage of the series, where I will begin working with Kubernetes resources and workloads.

In Part 3, the series will continue with the next mission in the lab, building on the cluster and namespace established here.

This article is part of the nine-part series, “Kubernetes on AKS: From Zero to Production Workloads.”

Kubernetes on AKS: From Zero to Production Workloads -Setting Up the Foundation (Part 1/9)

Rahimah Sulayman — Mon, 26 Oct 2026 15:31:25 +0000

Series: Kubernetes on AKS: From Zero to Production Workloads

Part 1: Workspace, Tools and Azure Sign-In

Environment: Ubuntu on WSL, VS Code terminal, Azure CLI, kubectl and Git

Before deploying workloads to Kubernetes, there is some groundwork to do. A reliable environment needs more than a cluster: it needs a structured project directory, version control, the right command-line tools, authenticated access to Azure, and the necessary resource providers.

In this first part of my nine-part series, I'll walk through how I prepared the environment for a hands-on Azure Kubernetes Service (AKS) lab. I'll cover the project workspace, Git initialization, Azure CLI installation, Azure authentication, Kubernetes command-line tools, and Azure resource provider registration. I'll also share an installation error I encountered, how I investigated it, and the workaround that allowed me to continue.

1. Creating the project workspace

I started by creating a dedicated directory for the lab and navigating into it.

mkdir -p /mnt/c/Users/Admin/Desktop/labs/aks-kubernetes-lab
cd /mnt/c/Users/Admin/Desktop/labs/aks-kubernetes-lab
pwd

Here's what each command does:

mkdir -p creates the project directory, including any missing parent directories.
cd moves into the directory.
pwd prints the current working directory so we can verify the location.

The terminal returned:

/mnt/c/Users/Admin/Desktop/labs/aks-kubernetes-lab

Confirming the working directory matters because subsequent commands create files and perform Git operations relative to that location.

A dedicated workspace keeps the project's documentation, Kubernetes manifests, and configuration organized as the lab grows.

2. Initializing Git

With the workspace ready, I initialized a Git repository using main as the initial branch.

git init -b main

The terminal confirmed:

Initialized empty Git repository in /mnt/c/Users/Admin/Desktop/labs/aks-kubernetes-lab/.git/

Git provides version control, allowing us to track changes, review previous versions, and maintain a history of the files created throughout the project.

The -b main option establishes main as the initial branch.

At this point, the repository existed locally. It had not yet been connected to a remote GitHub repository.

3. Creating the initial project structure

Next, I created a directory to hold the Kubernetes manifests.

mkdir -p manifests

I then created an initial README.md file:

printf '# Kubernetes on AKS\n\nProduction Kubernetes workloads on Azure Kubernetes Service, built as a hands-on lab.\n' > README.md

To inspect the file, I ran:

cat README.md

The output was:

# Kubernetes on AKS

Production Kubernetes workloads on Azure Kubernetes Service, built as a hands-on lab.

This README was intentionally minimal. It established the repository's entry point, while the manifests/ directory provided a dedicated location for Kubernetes YAML files.

The initial project structure looked like this:

aks-kubernetes-lab/
├── manifests/
└── README.md

This represents the initial structure, not the final repository layout.

4. Staging the README

Before creating the first commit, I staged the README and checked the repository status.

git add README.md
git status

Git reported:

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   README.md

The output confirmed that README.md was staged and ready to be included in a commit.

Git's staging area lets us choose which changes belong in a commit. This is useful when a project contains multiple modifications but we want to record only a specific set of changes.

5. Adding `.gitignore` and creating the first commit

Before committing the initial files, I created a .gitignore file.

printf 'lab.env\n*.log\n' > .gitignore

Its contents were:

lab.env
*.log

The lab.env rule tells Git to ignore a file named lab.env, while *.log ignores files ending in .log.

This is a useful precaution when working with cloud infrastructure. Environment files may contain configuration values that should not be published, and log files can add unnecessary clutter to a repository.

Important: .gitignore does not remove files that have already been committed or staged. It is a preventive measure, not a replacement for proper secret management.

I staged the files and created the initial commit:

git add README.md .gitignore
git commit -m "chore: initialise AKS lab workspace"

Git confirmed the commit:

[main (root-commit) 7bdb9aa] chore: initialise AKS lab workspace
2 files changed, 5 insertions(+)
create mode 100644 .gitignore
create mode 100644 README.md

This established the first checkpoint in the repository's history. Subsequent changes could now be recorded as separate commits.

6. Installing Azure CLI

The next step was to install the Azure command-line interface (Azure CLI).

Azure CLI allows us to manage Azure resources from a terminal. It is particularly useful for repeatable infrastructure workflows, where commands can be documented and reused instead of relying exclusively on the Azure portal.

I ran the installation command provided by the lab:

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

The command downloads and executes Microsoft's installation script for Debian-based Linux environments. Because it runs with elevated privileges, it is important to use a trusted installation source and understand what the command does.

The terminal showed the package repositories being updated and Azure CLI being installed.

I then verified the installation:

az version

The output included:

{
  "azure-cli": "2.91.0",
  "azure-cli-core": "2.91.0",
  "azure-cli-telemetry": "1.1.0"
}

This confirmed that Azure CLI was installed and available from the terminal.

7. Signing in to Azure

With Azure CLI installed, I authenticated using device-code sign-in.

az login --use-device-code

The CLI instructed me to open Microsoft's device-login page in a browser and enter the displayed code. After completing the browser authentication, I selected the available subscription.

The terminal showed the selected subscription as Azure subscription 1 under Default Directory.

Device-code authentication is useful when the terminal cannot conveniently open a browser or when authentication needs to be completed in a separate browser session.

Verifying the active account

I checked the active Azure account using:

az account show --output table

The output displayed account information, including the subscription name, state, and tenant details.

This verification is important because the subscription selected in Azure CLI determines where subsequent Azure commands will operate. Accidentally using the wrong subscription can result in resources being created in the wrong environment.

Security note: Before publishing terminal screenshots, redact device codes, access tokens, credentials, and any identifiers you don't want to expose.

8. Installing Kubernetes command-line tools

Azure CLI manages Azure resources, but we also need kubectl to interact with Kubernetes.

kubectl is the Kubernetes command-line client. It allows us to inspect resources, apply manifests, examine workload status, and communicate with the Kubernetes API when a cluster is available and the appropriate credentials and permissions are configured.

The lab's initial installation command was:

sudo az aks install-cli

Troubleshooting: The default installation path failed

The command encountered an error:

Connection error while attempting to download client
([Errno 2] No such file or directory: '/usr/local/bin/kubectl')

The terminal also showed that /usr/local/bin existed.

This was a useful reminder that an installation command can fail at its target path even when Azure CLI itself is working. Rather than repeatedly retrying the same command, I inspected the directory and switched to a user-local installation location.

First, I checked the directory:

ls -ld /usr/local/bin

Then I created a directory under my home folder:

mkdir -p ~/.local/bin

I reran the installation with explicit paths:

az aks install-cli \
  --install-location ~/.local/bin/kubectl \
  --kubelogin-install-location ~/.local/bin/kubelogin

This instructed the installer to place kubectl and kubelogin in my user-local binary directory.

The installer completed the downloads and advised that ~/.local/bin needed to be included in PATH so the shell could find the commands.

Adding the installation directory to `PATH`

I added the directory to my Bash configuration:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Then I reloaded the configuration:

source ~/.bashrc

Finally, I verified the Kubernetes client installation:

kubectl version --client

The terminal returned:

Client Version: v1.37.1
Kustomize Version: v5.8.1

This confirmed that the kubectl client was installed and available from the shell.

What resolved the problem?

The workaround used a directory within my home folder rather than the original default installation location. Updating PATH then allowed the shell to locate the downloaded binaries.

The failure occurred during local tooling setup, before a Kubernetes cluster was involved. Distinguishing local installation problems from cluster or workload problems makes troubleshooting more systematic.

9. Registering Azure resource providers

Before creating Azure resources, the subscription may need the relevant resource providers registered.

A resource provider exposes the management operations for a category of Azure resources. For this lab, I registered four providers:

az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.Compute
az provider register --namespace Microsoft.Network
az provider register --namespace Microsoft.Storage

These providers correspond to the services used throughout the lab:

Resource provider	Purpose
`Microsoft.ContainerService`	AKS and related container-service management
`Microsoft.Compute`	Virtual machines and compute resources
`Microsoft.Network`	Networking resources, including virtual networks and load balancers
`Microsoft.Storage`	Azure storage resources

Registering a provider does not create an AKS cluster or provision the associated resources. It enables the subscription to use the relevant provider's operations.

Verifying registration

I checked the registration state of the AKS provider:

az provider show \
  --namespace Microsoft.ContainerService \
  --query registrationState \
  --output tsv

The result was:

Registered

This confirmed that Microsoft.ContainerService was registered. The screenshot documents the verification of this provider; it does not independently confirm the registration state of all four providers.

10. Preparing the lab environment

The lab used an environment file to keep its configuration values consistent across subsequent commands.

cat << 'EOF' > lab.env
export RESOURCE_GROUP=rg-aks-lab
export LOCATION=westeurope
export CLUSTER_NAME=aks-lab
export NODE_SIZE=Standard_D2s_v3
EOF

I loaded the variables into the current shell:

source lab.env

Then I checked their values:

echo "$RESOURCE_GROUP $LOCATION $CLUSTER_NAME $NODE_SIZE"

The terminal returned:

rg-aks-lab westeurope aks-lab Standard_D2s_v3

Using variables avoids repeatedly typing the same resource names and configuration values throughout a lab. It also reduces the chance of accidentally using inconsistent names in later commands.

The values describe the intended lab configuration; they do not mean the AKS cluster has already been created.

Security reminder: lab.env is included in .gitignore. Keep credentials and secrets out of source control, and check the repository's status before committing changes.

Key takeaways

A dedicated workspace and Git history provide a maintainable starting point for infrastructure projects.
.gitignore helps prevent selected local files from being added to the repository, but it does not replace proper secret management.
Azure CLI and kubectl have different roles: one manages Azure resources, while the other interacts with Kubernetes.
When an installer fails at its default path, inspecting the environment and selecting a suitable installation location can provide a practical workaround.
Always verify the active Azure account and subscription before creating or modifying resources.
Registering a resource provider enables its operations; it does not create resources by itself.

What's next?

In Part 2, I'll continue with the next stage of the lab: provisioning and configuring the Azure Kubernetes Service infrastructure, following the lab guide.

We'll move from preparing the local environment to establishing the Azure infrastructure on which the Kubernetes workloads will run.

This is the foundation for the remaining parts of the series, covering Kubernetes workloads, networking, configuration, storage, automation, scaling, cost optimization, and cleanup.

This article documents the commands and outcomes captured during the lab. Installation results and version numbers reflect the recorded environment and may differ on other systems. Review commands, permissions, and potential Azure charges before running them in your own subscription.