How to Manage Application Configuration in Kubernetes Using Configmaps and Secrets

ByAkensai

Learning how to manage application configuration in Kubernetes using ConfigMaps and Secrets is one of the most important skills for any DevOps engineer or system administrator. Kubernetes separates configuration from container images. This keeps your apps portable and easier to maintain. Without this separation, you’d have to rebuild images every time a config value changes. In this tutorial, you’ll learn how to create ConfigMaps and Secrets, mount them into pods, and update them safely. By the end, you’ll have a solid, practical understanding of how Kubernetes handles sensitive and non-sensitive configuration data. This approach works whether you’re running a simple web app or a complex microservices stack.

Prerequisites for Managing Kubernetes ConfigMaps and Secrets

Before you start, make sure you have the following in place.

Required tools and access:

  • A running Kubernetes cluster (local with Minikube or a cloud provider like GKE, EKS, or AKS)
  • kubectl installed and configured on your local machine
  • Basic familiarity with YAML syntax
  • A terminal with shell access (Linux or macOS recommended)

Assumed knowledge:

  • You understand what a Kubernetes pod is
  • You’ve run basic kubectl commands before
  • You know what environment variables are

Estimated time: 30–45 minutes

You don’t need to be a Kubernetes expert. This tutorial is written for intermediate users who want to handle configuration properly. If you’re new to Kubernetes, check out the official Kubernetes documentation to get familiar with the basics first.

How to Manage Application Configuration in Kubernetes Using ConfigMaps

See also: How to Monitor Linux Server Performance Using Command-line Tools

ConfigMaps store non-sensitive configuration data as key-value pairs. Think of them as a way to inject settings into your containers without hardcoding anything.

Step 1: Create a ConfigMap from a literal value

Run this command to create a simple ConfigMap:

kubectl create configmap app-config 
  --from-literal=APP_ENV=production 
  --from-literal=APP_PORT=8080

This creates a ConfigMap named app-config with two key-value pairs. Kubernetes stores this in the cluster’s etcd database.

Step 2: Verify the ConfigMap was created

kubectl get configmap app-config
kubectl describe configmap app-config

You’ll see both keys listed under the Data section. This confirms the ConfigMap exists and is ready to use.

Step 3: Create a ConfigMap from a file

First, create a config file locally:

cat < app.properties
APP_ENV=production
APP_PORT=8080
LOG_LEVEL=info
EOF

Now create the ConfigMap from that file:

kubectl create configmap app-config-file --from-file=app.properties

This is useful when you have many config values. You don’t have to type each one individually.

Step 4: Mount the ConfigMap as environment variables in a pod

Create a YAML file called pod-configmap.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: configmap-demo
spec:
  containers:
    - name: app-container
      image: busybox
      command: ["sh", "-c", "echo $APP_ENV && sleep 3600"]
      envFrom:
        - configMapRef:
            name: app-config

Apply it with:

kubectl apply -f pod-configmap.yaml

The pod will read all keys from app-config as environment variables. This keeps your container image clean and reusable.

Step 5: Mount the ConfigMap as a volume

Sometimes you need config files inside the container, not just environment variables. Update your pod spec:

apiVersion: v1
kind: Pod
metadata:
  name: configmap-volume-demo
spec:
  containers:
    - name: app-container
      image: busybox
      command: ["sh", "-c", "cat /etc/config/app.properties && sleep 3600"]
      volumeMounts:
        - name: config-volume
          mountPath: /etc/config
  volumes:
    - name: config-volume
      configMap:
        name: app-config-file

Apply it:

kubectl apply -f pod-volume-demo.yaml

Kubernetes mounts each key as a separate file inside /etc/config. Your app can read the file directly.

How to Manage Application Configuration in Kubernetes Using Secrets

Secrets work similarly to ConfigMaps, but they store sensitive data like passwords, API keys, and tokens. Kubernetes base64-encodes Secrets by default. For production use, always enable encryption at rest. You can learn more about that in the Kubernetes Secrets documentation.

Step 6: Create a Secret from literal values

kubectl create secret generic db-credentials 
  --from-literal=DB_USER=admin 
  --from-literal=DB_PASSWORD=SuperSecretPass123

Kubernetes stores this data base64-encoded. It’s not encrypted by default, but it’s kept separate from your code.

Step 7: Verify the Secret

kubectl get secret db-credentials
kubectl describe secret db-credentials

The describe command won’t show the actual values. That’s intentional. To decode a value manually, run:

kubectl get secret db-credentials -o jsonpath='{.data.DB_PASSWORD}' | base64 --decode

Step 8: Inject the Secret into a pod as environment variables

Create a file called pod-secret.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: secret-demo
spec:
  containers:
    - name: app-container
      image: busybox
      command: ["sh", "-c", "echo $DB_USER && sleep 3600"]
      envFrom:
        - secretRef:
            name: db-credentials

Apply it:

kubectl apply -f pod-secret.yaml

Your app can now read DB_USER and DB_PASSWORD as environment variables. No hardcoded credentials in your image.

Step 9: Update a ConfigMap or Secret

To update a ConfigMap, edit it directly:

kubectl edit configmap app-config

This opens the resource in your default editor. Make your changes and save. Pods using volume mounts will pick up the changes automatically within a few minutes. Pods using environment variables won’t update until they restart.

Troubleshooting Common ConfigMap and Secret Issues

Even experienced engineers run into problems here. These are the most common ones.

Problem: Pod can’t find the ConfigMap or Secret

If your pod fails to start with an error like configmap "app-config" not found, check that the ConfigMap exists in the same namespace:

kubectl get configmap -n your-namespace

Always make sure your pod and ConfigMap are in the same namespace.

Problem: Environment variables aren’t updating

Environment variables are set at pod startup. If you update a ConfigMap, you must restart the pod:

kubectl rollout restart deployment your-deployment-name

Problem: Secret values look garbled

Secrets are base64-encoded. If you create a Secret manually in YAML, you must encode the values first:

echo -n "mypassword" | base64

Use the output as the value in your Secret manifest. Don’t paste plain text directly into the data field.

Warning: Never commit Secret manifests to version control. Use tools like Sealed Secrets or HashiCorp Vault for production environments. You can find more guidance at the HashiCorp Vault documentation.

Problem: Volume-mounted config files not updating

Volume-mounted ConfigMaps update automatically, but there’s a sync delay. It can take up to 60 seconds. Wait a moment and check again before assuming something is broken.

Conclusion

You’ve now seen exactly how to manage application configuration in Kubernetes using ConfigMaps and Secrets. You created both resource types, mounted them as environment variables and volumes, and learned how to update them safely. This approach keeps your container images clean and your sensitive data out of your codebase. As a next step, explore Role-Based Access Control (RBAC) to restrict who can read your Secrets. You should also look into encrypting Secrets at rest using a KMS provider. These practices are essential in any production Kubernetes environment. Managing configuration this way scales well and keeps your infrastructure organized.

Similar Posts