Geekahmed
Configuring Kubernetes Applications: A Guide to ConfigMaps and Secrets

Configuring Kubernetes Applications: A Guide to ConfigMaps and Secrets

Ahmed Moustafa's photo
Ahmed Moustafa
·

3 min read

Introduction

Kubernetes applications often require dynamic configuration to adapt to different environments (development, staging, production) or to handle sensitive data securely. ConfigMaps and Secrets are Kubernetes resources designed to decouple configuration from application code. This guide explains their usage, benefits, and real-world examples to help you master these concepts.

1. Configuring Containers: Basics

Before diving into ConfigMaps and Secrets, let’s review how containers are traditionally configured.

1.1 Command-Line Arguments

Override the default command or arguments in a container.

Example: A Python app that prints "Hello, [NAME]!"

  • Dockerfile:

      FROM python:3  
  COPY app.py /app.py  
  ENTRYPOINT ["python", "/app.py"]

  • Pod Definition:

      apiVersion: v1  
  kind: Pod  
  metadata:  
    name: hello-app  
  spec:  
    containers:  
    - image: my-python-app  
      args: ["Ahmed"]  # Passes "Ahmed" as the name

Result: The app prints "Hello, Ahmed!"

Key Notes:

  • Use command to override the container’s entrypoint.

  • Use args to override default arguments.

2. Environment Variables

Environment variables are ideal for small configurations (e.g., database URLs).

Example: A Node.js app using DB_URL for database connectivity.

  • Pod Definition:

      env:  
  - name: DB_URL  
    value: "mongodb://user:pass@localhost:27017"

Limitations:

  • Hardcoding values in YAML is insecure and inflexible.

  • Use ConfigMaps or Secrets to externalize configurations.

3. ConfigMaps: Decoupling Configuration

ConfigMaps store non-sensitive data as key-value pairs or entire config files.

3.1 Creating ConfigMaps

  • From literals:

      kubectl create configmap app-config --from-literal=DEBUG=true --from-literal=MAX_RETRIES=5

  • From files:

      kubectl create configmap nginx-config --from-file=nginx.conf

  • From directories:

      kubectl create configmap app-settings --from-file=configs/

3.2 Using ConfigMaps

Example: Configure Nginx to enable gzip compression.

  • ConfigMap:

      apiVersion: v1  
  kind: ConfigMap  
  metadata:  
    name: nginx-config  
  data:  
    nginx.conf: |  
      server {  
        listen 80;  
        gzip on;  
        ...  
      }

  • Pod Definition:

      volumes:  
  - name: config  
    configMap:  
      name: nginx-config  
  containers:  
  - name: web-server  
    volumeMounts:  
    - name: config  
      mountPath: /etc/nginx/conf.d

3.3 Updating ConfigMaps

  • Atomic Updates: Kubernetes updates files in volumes atomically using symbolic links.

  • Reload Config: After updating a ConfigMap, restart the app or send a reload signal (e.g., nginx -s reload).

4. Secrets: Handling Sensitive Data

Secrets encrypt sensitive data (e.g., API keys, TLS certificates).

4.1 Creating Secrets

  • TLS Secret:

      kubectl create secret tls tls-secret --cert=tls.crt --key=tls.key

  • Generic Secret:

      kubectl create secret generic db-creds --from-literal=username=admin --from-literal=password=secret

4.2 Using Secrets

Example: Serve HTTPS traffic with Nginx.

  • Pod Definition:

      volumes:  
  - name: certs  
    secret:  
      secretName: tls-secret  
  containers:  
  - name: web-server  
    volumeMounts:  
    - name: certs  
      mountPath: /etc/nginx/certs

Security Notes:

  • Secrets are stored in-memory (tmpfs) and never written to disk.

  • Avoid exposing Secrets via environment variables; use volumes instead.

5. Advanced Use Cases

5.1 Image Pull Secrets

Access private container registries.

  • Create Secret:

      kubectl create secret docker-registry my-registry-secret \  
    --docker-username=USER \  
    --docker-password=PASS \  
    --docker-email=EMAIL

  • Pod Definition:

      imagePullSecrets:  
  - name: my-registry-secret

5.2 SubPath Mounts

Mount individual files without hiding existing directory contents.

volumeMounts:  
- name: config  
  mountPath: /etc/nginx/conf.d/custom.conf  
  subPath: custom.conf

6. Best Practices

  1. Use ConfigMaps for non-sensitive data, Secrets for credentials.

  2. Avoid hardcoding values in YAML files.

  3. Update configurations atomically to avoid downtime.

  4. Limit Secret size (max 1MB).

Conclusion

ConfigMaps and Secrets are foundational to Kubernetes configuration management:

  • ConfigMaps simplify environment-specific configurations.

  • Secrets ensure sensitive data is encrypted and secure.

  • Both enable zero-downtime updates and improve application portability.

By externalizing configuration, you adhere to the 12-factor app principles, making your applications more maintainable and scalable. Use this guide to implement robust configurations in your Kubernetes workflows.

Final Tip: Always validate configurations with tools like kubectl describe and test updates in staging before production.

Kubernetes