Kubernetes is great for orchestrating containerized applications, but there's a common challenge: when you update a ConfigMap or Secret, pods don't automatically restart to pick up the new configuration. This means you often need to manually trigger a rollout or restart pods after configuration changes - which can be cumbersome in production environments.

Enter Stakater Reloader: a simple but powerful Kubernetes controller that watches for changes in ConfigMaps and Secrets and automatically triggers deployments to restart when their configurations change. Let's explore how to set this up.

Prerequisites

• Kubernetes cluster

• Git (to clone the repository)

• New to Kubernetes? Check out our Kubernetes Training course

Getting Started

Clone the repository containing the complete example:

git clone https://github.com/rslim087a/reloader-kubernetes-tutorial
cd

Understanding the Demo Setup

This demo includes:

1. A PostgreSQL deployment that reads configuration from ConfigMaps and Secrets

2. A client application that connects to PostgreSQL

3. The Stakater Reloader that watches for configuration changes

4. Updated configurations that will trigger automatic reloads

Let's examine each part of the setup and its role in the demonstration.

Step 1: Setting Up the Namespace

First, we'll create a dedicated namespace for our demo:

kubectl apply -f 00-namespace

# 00-namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name

Step 2: Setting Up Reloader with RBAC

Reloader needs proper permissions to watch resources and trigger updates:

kubectl apply -f 01-rbac

Key elements of the RBAC configuration:

# 01-rbac.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: reloader-role
rules:
  - apiGroups: [""]
    resources: ["secrets", "configmaps"]
    verbs: ["list", "get", "watch"]  # Permissions to watch ConfigMaps and Secrets
  - apiGroups: ["apps"]
    resources: ["deployments", "daemonsets", "statefulsets"]
    verbs: ["list", "get", "update", "patch"]  # Permissions to update workloads

Step 3: Deploying the Reloader

Now we deploy the Reloader controller:

kubectl apply -f 02-reloader

# 02-reloader.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: reloader
  namespace: demo-reloader
spec:
  replicas: 1
  selector:
    matchLabels:
      app: reloader
  template:
    metadata:
      labels:
        app: reloader
    spec:
      serviceAccountName: reloader  # Uses the ServiceAccount we created
      containers:
      - image: "ghcr.io/stakater/reloader:v1.0.71"
        name

Step 4: Creating Initial Configuration

Let's set up the initial PostgreSQL configuration:

kubectl apply -f 03-postgres-config

# 03-postgres-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: postgres-config
  namespace: demo-reloader
  annotations:
    reloader.stakater.com/auto: "true"  # This annotation tells Reloader to watch this ConfigMap
data:
  POSTGRES_DB: demoapp
  POSTGRES_USER: demouser
---
apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
  namespace: demo-reloader
  annotations:
    reloader.stakater.com/auto: "true"  # This annotation tells Reloader to watch this Secret
type: Opaque
data:
  POSTGRES_PASSWORD: ZGVtbzEyMw==  # base64 encoded "demo123"

The key part here is the reloader.stakater.com/auto: "true" annotation on both the ConfigMap and Secret. This tells Reloader to watch these resources for changes.

Step 5: Deploying PostgreSQL

Now we deploy PostgreSQL with configuration from our ConfigMap and Secret:

kubectl apply -f 04-postgres-deployment

Key elements of the PostgreSQL deployment:

# 04-postgres-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  namespace: demo-reloader
spec:
  # ...
  template:
    metadata:
      labels:
        app: postgres
      annotations:
        configmap.reloader.stakater.com/reload: "postgres-config"  # Explicit annotation
        secret.reloader.stakater.com/reload: "postgres-secret"     # Explicit annotation
    spec:
      containers:
      - name: postgres
        # ...
        env:
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: postgres-secret  # Reference to our Secret
              key: POSTGRES_PASSWORD
        - name: POSTGRES_USER
          valueFrom:
            configMapKeyRef:
              name: postgres-config  # Reference to our ConfigMap
              key: POSTGRES_USER
        - name: POSTGRES_DB
          valueFrom:
            configMapKeyRef:
              name: postgres-config
              key

The crucial part here is the annotations in the pod template metadata section:

• configmap.reloader.stakater.com/reload: "postgres-config"

• secret.reloader.stakater.com/reload: "postgres-secret"

These explicit annotations tell Reloader exactly which deployments to restart when the specified ConfigMap or Secret changes.

Step 6: Deploying the Client Application

Let's deploy a simple client that connects to PostgreSQL:

kubectl apply -f 05-client

# 05-client.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pg-client
  namespace: demo-reloader
spec:
  # ...
  template:
    # ...
    spec:
      containers:
      - name: pg-client
        image: postgres:15-alpine
        command: ["/bin/sh", "-c"]
        args:
        - |
          while true; do
            echo "Attempting to connect to PostgreSQL...";
            PGPASSWORD=$(POSTGRES_PASSWORD) psql -h postgres -U $(POSTGRES_USER) -d $(POSTGRES_DB) -c "SELECT 'Successfully connected to PostgreSQL!'";
            sleep 10;
          done
        env:
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: postgres-secret
              key: POSTGRES_PASSWORD
        # ... other environment variables

The client will continuously attempt to connect to PostgreSQL, making it easy to see when configuration changes affect connectivity.

Demonstration: Updating Configuration

Let's see Reloader in action by updating the ConfigMap:

kubectl apply -f 06-config-update

# 06-config-update.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: postgres-config
  namespace: demo-reloader
  annotations:
    reloader.stakater.com/auto: "true"
data:
  POSTGRES_DB: newdatabase  # Changed from demoapp
  POSTGRES_USER: demouser   # Unchanged

Watch the pods to see automatic restarting:

kubectl get pods -n demo-reloader -w

You should see the PostgreSQL pod terminate and a new pod start with the updated configuration.

Next, let's update a Secret:

kubectl apply -f 07-secret-update

# 07-secret-update.yaml
apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
  namespace: demo-reloader
  annotations:
    reloader.stakater.com/auto: "true"
type: Opaque
data:
  # Password is "newpassword" in base64
  POSTGRES_PASSWORD

Again, watch the pods to see the PostgreSQL pod restart automatically:

kubectl get pods -n demo-reloader -w

You can verify the client connections by checking its logs:

kubectl logs -n demo-reloader deployment/pg-client -f

How It Works

Stakater Reloader works through a simple mechanism:

1. It continuously watches resources annotated with reloader.stakater.com/auto: "true"

2. When changes are detected in these resources, it finds all deployments, statefulsets, and daemonsets that use them

3. It then triggers a rollout of these workloads by updating an annotation in their pod template

4. This causes Kubernetes to create new pods with the updated configuration

You can also explicitly tell Reloader which deployments to update when a specific ConfigMap or Secret changes using annotations like:

• configmap.reloader.stakater.com/reload: "name-of-configmap"

• secret.reloader.stakater.com/reload: "name-of-secret"

Benefits of Using Reloader

• Automation: No need to manually restart deployments after config changes

• Simplicity: Minimal setup required (just add annotations)

• Flexibility: Works with any type of Kubernetes deployment

• Increased Productivity: Configuration changes take effect immediately

• No Downtime: Rolling updates ensure continuous service

Cleanup

When you're done with the demo, clean up the resources:

Conclusion

Stakater Reloader solves a common pain point in Kubernetes: the need to manually restart pods when configurations change. By automating this process, it simplifies operations and ensures your applications always use the most up-to-date configurations.

This approach is especially valuable in environments with frequent configuration changes or where configuration is managed through GitOps pipelines.

Try integrating Reloader into your Kubernetes workflows and see how it can simplify your configuration management!

Kubernetes Training

If you find these guides helpful, check out our Kubernetes Training course