Configuration Management on Azure AKS: Decoupling Apps with ConfigMaps & Secrets

A production container image should never hardcode configuration values, API endpoints, or database passwords. Following the Twelve-Factor App methodology, modern cloud-native applications must strictly decouple code from configuration so the exact same container image can run reliably across Development, Staging, and Production environments without rebuilds.

In this hands-on guide, you will master enterprise Kubernetes configuration management on Azure Kubernetes Service (AKS):

• ConfigMaps: Externalize non-sensitive application settings, feature flags, and API endpoints.
• Kubernetes Secrets: Safely store, base64-encode, and manage confidential passwords, tokens, and credentials.
• Environment Variable Injection: Dynamically pass configuration keys directly into running container processes.
• Volume Mounts: Mount complete configuration files (such as NGINX or database configs) into container directories in real time.
• Production Hardening: Enforce immutability and understand enterprise secrets management with Azure Key Vault.

📌 Lab Prerequisites: To follow along, you need an active Azure Subscription (Free Trial, Student Credits, or Pay-As-You-Go) and a running AKS cluster with Azure CLI and kubectl connected locally. If you need to spin up a cluster first, refer to our foundational guide: Deploy Your First Containerized App on Azure Kubernetes Service (AKS).

📦 Prefer Declarative YAML Manifests?

While this guide focuses on hands-on imperative CLI commands for fast learning and diagnostics, the complete, production-ready declarative YAML manifests (01-configmap.yaml, 02-secret.yaml, 03-deployment.yaml, and 04-service.yaml) are available in our official GitHub repository:
👉 StackLayerOfficially/azure-aks-hands-on-labs (03-configmaps-secrets)

⚠️ Disclaimer & Cloud Cost Notice

This tutorial is built strictly for hands-on educational and lab purposes. The configurations shown here are simplified demonstrations and should not be used directly in live production environments without independent security reviews. Stack Layer and its technical team assume no responsibility or liability for any issues, outages, or data loss resulting from applying these commands. Always follow Step-06 to pause or delete your cluster when finished to protect your cloud balance.

Understanding the Core Concepts

1. What is a ConfigMap (and Why Do We Need It)?

A ConfigMap is a native Kubernetes API object used to store non-confidential configuration data in key-value pairs.

Why use it? Without ConfigMaps, changing an application setting (such as an API endpoint, port, or debug flag) would require modifying your source code, rebuilding the container image, and redeploying it. With ConfigMaps, your application image remains generic and decoupled from the environment, allowing it to adapt dynamically between dev, staging, and production.

2. What is a Kubernetes Secret (and How Does It Differ)?

A Kubernetes Secret is an object designed specifically to hold confidential data such as passwords, API tokens, TLS certificates, and SSH keys.

Why use it? Unlike ConfigMaps, Secrets are base64-encoded and decoupled from container images. This prevents credentials from being exposed in source code repositories (like GitHub) and allows cluster administrators to enforce strict Role-Based Access Control (RBAC) to limit who can view or modify sensitive data.

Connect Your Local CLI to AKS

Authenticate your local terminal to your running AKS cluster:

[code] # Connect Azure CLI to your running AKS cluster az aks get-credentials --resource-group stacklayer-aks-rg --name stacklayer-aks-cluster --overwrite-existing # Verify that cluster worker nodes are in a Ready state kubectl get nodes [/code]

Command Breakdown:

• az aks get-credentials: Downloads the access certificates for your AKS cluster and automatically updates your local ~/.kube/config file.
• --resource-group stacklayer-aks-rg: Specifies the Azure resource group hosting your cluster.
• --name stacklayer-aks-cluster: Identifies your target AKS cluster name.
• --overwrite-existing: Overwrites any expired or conflicting local kubeconfig contexts.
• kubectl get nodes: Confirms that worker nodes are reporting a healthy Ready state.

Step-01: Create and Inspect a Kubernetes ConfigMap

You can create ConfigMaps quickly via the command line to store non-sensitive environment variables.

1. Create the ConfigMap via CLI

Run the following command to create a ConfigMap named stacklayer-app-config with four application settings:

[code] # Create a ConfigMap with key-value pairs kubectl create configmap stacklayer-app-config \ --from-literal=APP_ENV=production \ --from-literal=APP_PORT=80 \ --from-literal=LOG_LEVEL=debug \ --from-literal=FEATURE_FLAG_ANALYTICS=true [/code]

Command Breakdown:

• kubectl create configmap stacklayer-app-config: Creates a new ConfigMap resource named stacklayer-app-config in your current namespace.
• --from-literal=KEY=VALUE: Tells Kubernetes to store a raw key-value string pair directly from your command line without requiring an external file.

2. Inspect and Verify Stored Keys

Inspect the ConfigMap to confirm the keys and values are stored:

[code] # List existing ConfigMaps in the cluster kubectl get configmaps # View detailed key-value contents and metadata kubectl describe configmap stacklayer-app-config [/code]

Step-02: Create and Inspect a Kubernetes Secret

Now, let's create a Secret to securely store sensitive database credentials and an API token.

1. Create the Secret via CLI

Create a secret named stacklayer-app-secret containing confidential credentials:

[code] # Create a generic Secret containing sensitive credentials kubectl create secret generic stacklayer-app-secret \ --from-literal=DB_USERNAME=stacklayer_admin \ --from-literal=DB_PASSWORD="VaultPassword@2026!Azure" \ --from-literal=API_AUTH_TOKEN=sec_live_948271039472619 [/code]

Command Breakdown:

• kubectl create secret generic stacklayer-app-secret: Creates a generic (Opaque) Secret named stacklayer-app-secret.
• --from-literal=...: Ingests sensitive strings directly. Kubernetes automatically base64-encodes these values in etcd to protect them from casual observation.

2. Inspect and Decode Secret Data

When you query a secret's raw data, Kubernetes returns base64-encoded strings. Decode the stored password directly in your terminal:

[code] # Retrieve and decode the DB_PASSWORD key in real-time kubectl get secret stacklayer-app-secret -o jsonpath="{.data.DB_PASSWORD}" | base64 --decode echo "" [/code]

Step-03: Inject Configuration & Secrets into a Running Container

To see how containers consume these settings in real time without creating complex YAML files, run a lightweight test pod that directly loads environment variables from your ConfigMap and Secret:

[code] # Spin up an interactive test pod with injected environment variables kubectl run stacklayer-test-app \ --image=stacklayer/kubernetes:nginx-v1 \ --restart=Never \ --env="APP_ENV=production" \ --env="DB_USER=stacklayer_admin" # Verify the pod is running kubectl get pod stacklayer-test-app [/code]

Command Breakdown:

• kubectl run stacklayer-test-app: Rapidly creates and runs a single test pod without requiring deployment manifest boilerplate.
• --image=stacklayer/kubernetes:nginx-v1: Runs the official Stack Layer NGINX container image.
• --restart=Never: Instructs Kubernetes to create a standalone Pod instead of a Deployment controller.

Step-04: Verify Injected Variables Inside the Live Container

Verify that the configuration settings are accessible inside the running container process:

[code] # Query the live container environment directly kubectl exec stacklayer-test-app -- printenv | grep -E "APP_ENV|DB_USER" [/code]

Command Breakdown:

• kubectl exec stacklayer-test-app -- printenv: Executes the standard Linux printenv binary inside the active container.
• | grep -E "APP_ENV|DB_USER": Confirms that your configurations are loaded directly into process memory, ready for backend application code to consume.

Step-05: Mount Configurations as Live Files (Volume Mounts)

Some applications (such as NGINX web servers, HAProxy, or database engines) require complete configuration files (e.g., nginx.conf, index.html) loaded from a specific filesystem path rather than environment variables.

1. Create a ConfigMap from a Local File

Create a sample HTML configuration file locally and import it into Kubernetes:

[code] # Write sample configuration content to a local file cat < custom-site.html

Hello from AKS ConfigMap Volume Mount!

Environment: Production Cluster (Stack Layer AKS)

EOF # Create a ConfigMap directly from the local file kubectl create configmap stacklayer-site-content --from-file=custom-site.html [/code]

Command Breakdown:

• --from-file=custom-site.html: Automatically creates a ConfigMap entry where the key is the filename (custom-site.html) and the value is the full text content of that file.

2. How Volume Mounts Work in Production

In production manifests, you mount this ConfigMap directly into the container filesystem (such as /usr/share/nginx/html) as a read-only directory volume. This allows you to update web content or configuration files dynamically without changing or rebuilding the underlying container image!

To review the complete volume mount YAML manifest, visit our companion GitHub repository (03-deployment.yaml).

Step-06: Production Best Practices & Cost Cleanup

When deploying configurations in production enterprise environments, cloud engineers adopt these security practices:

1. Immutable ConfigMaps (Prevent Accidental Configuration Drift)

In Kubernetes 1.21+, you can add immutable: true to the specification of a ConfigMap or Secret. This protects production workloads from unexpected mid-cycle changes and substantially reduces load on the Kubernetes API server by disabling cache watches.

2. Azure Key Vault Integration (Secrets Store CSI Driver)

While native Kubernetes Secrets are base64-encoded, enterprise architectures on Azure typically enable the AKS Azure Key Vault Secrets Store CSI Driver. This allows AKS pods to sync encryption keys, certificates, and passwords stored securely in Azure Key Vault directly into memory without storing them as plain Kubernetes Secret objects.

Clean Up Demonstration Resources

Delete the test pod and configurations to keep your cluster clean:

[code] # Delete the test pod kubectl delete pod stacklayer-test-app # Delete test ConfigMaps and Secrets kubectl delete configmap stacklayer-app-config stacklayer-site-content kubectl delete secret stacklayer-app-secret [/code]

Option A: Stop the Cluster (Recommended If Practicing Later Labs)

If you plan to follow additional hands-on guides, you can stop the cluster to pause VM compute billing while keeping all cluster configurations intact:

[code] # Stop the AKS cluster to pause compute billing az aks stop --resource-group stacklayer-aks-rg --name stacklayer-aks-cluster # When you are ready to resume, start it back up: az aks start --resource-group stacklayer-aks-rg --name stacklayer-aks-cluster [/code]

Command Breakdown:

• az aks stop: Powers down all virtual machine worker nodes and halts hourly compute billing immediately. All cluster configurations and network topologies are preserved.
• az aks start: Resumes cluster operations and wakes up worker nodes in approximately 2–3 minutes.

Option B: Delete the Cluster Completely (Permanent Teardown)

If you are finished experimenting and want to ensure 100% zero future charges:

[code] # Permanently delete the resource group and all contained resources az group delete --name stacklayer-aks-rg --yes --no-wait [/code]

Command Breakdown:

• az group delete --name stacklayer-aks-rg: Permanently deletes the resource group stacklayer-aks-rg, cluster, virtual networks, and managed disks.
• --yes: Bypasses interactive confirmation prompts.
• --no-wait: Executes asynchronously in the Azure background so you can close your terminal immediately.

Summary

In this guide, you learned how to manage configuration like a seasoned cloud engineer on Azure AKS:

• Decoupled application configuration from container images adhering to the Twelve-Factor App methodology.
• Created and inspected non-sensitive configuration keys using ConfigMaps.
• Secured passwords and credentials using base64-encoded Kubernetes Secrets.
• Injected settings dynamically into live container processes via environment variables.
• Explored mounting configuration files directly as read-only directory volumes using volumeMounts.
• Safeguarded your cloud budget with az aks stop and az group delete.

“Did you successfully practice ConfigMaps and Secrets on your AKS cluster?”

If yes, leave a comment below! If you ran into any issues or have questions, feel free to drop them below as well.