kubemirror/examples/README.md

KubeMirror Examples

This directory contains example manifests for testing KubeMirror functionality.

Overview

The examples create 5 namespaces with various resources to demonstrate different mirroring scenarios:

Namespace Structure

• namespace-1: Source namespace containing:

  • shared-credentials Secret → mirrors to ALL namespaces
  • database-credentials Secret → mirrors to namespace-3 and namespace-4
  • local-secret Secret → NO mirroring (stays local)
  • app-config ConfigMap → mirrors to ALL namespaces
  • nginx-config ConfigMap → mirrors to namespace-2 and namespace-5

• namespace-2: Traefik middleware source namespace containing:

  • compression Middleware → mirrors to namespace-4 and namespace-5
  • rate-limit Middleware → mirrors to ALL namespaces
  • headers Middleware → mirrors to namespace-3 only

• namespace-3: Target namespace (receives mirrors)

• namespace-4: Target namespace (receives mirrors + Traefik middleware)

• namespace-5: Target namespace (receives mirrors + Traefik middleware)

Prerequisites

1. KubeMirror controller must be deployed and running
2. Traefik CRDs must be installed (for middleware examples)

# Install official Traefik CRDs (latest)
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/master/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

Note: If you don't want to test Traefik middleware mirroring, you can skip the CRD installation and just exclude traefik-middleware.yaml from your apply command.

Quick Start

Apply all examples using kustomize:

# Apply all examples
kubectl apply -k examples/

# Or apply individually
kubectl apply -f examples/namespaces.yaml
kubectl apply -f examples/source-secret.yaml
kubectl apply -f examples/source-configmap.yaml
kubectl apply -f examples/traefik-middleware.yaml

Verification

Check Namespaces

# List all example namespaces
kubectl get namespaces -l app=kubemirror-example

# Verify allow-mirrors label
kubectl get namespaces -l kubemirror.raczylo.com/allow-mirrors=true

Check Mirrored Secrets

# Check shared-credentials (should exist in all namespaces)
kubectl get secret shared-credentials -n namespace-1
kubectl get secret shared-credentials -n namespace-2
kubectl get secret shared-credentials -n namespace-3
kubectl get secret shared-credentials -n namespace-4
kubectl get secret shared-credentials -n namespace-5

# Check database-credentials (only in namespace-3 and namespace-4)
kubectl get secret database-credentials -n namespace-3
kubectl get secret database-credentials -n namespace-4

# Check local-secret (should ONLY exist in namespace-1)
kubectl get secret local-secret -n namespace-1
kubectl get secret local-secret -n namespace-2 # Should NOT exist

Check Mirrored ConfigMaps

# Check app-config (should exist in all namespaces)
kubectl get configmap app-config --all-namespaces

# Check nginx-config (only in namespace-2 and namespace-5)
kubectl get configmap nginx-config -n namespace-2
kubectl get configmap nginx-config -n namespace-5

Check Mirrored Traefik Middlewares

# Check compression middleware (should be in namespace-4 and namespace-5)
kubectl get middleware compression -n namespace-2
kubectl get middleware compression -n namespace-4
kubectl get middleware compression -n namespace-5

# Check rate-limit middleware (should be in all namespaces)
kubectl get middleware rate-limit --all-namespaces

# Check headers middleware (should be in namespace-3)
kubectl get middleware headers -n namespace-3

Check Mirror Ownership

Verify that mirrored resources have the correct ownership labels:

# Check labels on a mirrored secret
kubectl get secret shared-credentials -n namespace-3 -o yaml | grep -A 5 labels

# Should include:
# kubemirror.raczylo.com/mirrored: "true"
# kubemirror.raczylo.com/source-namespace: namespace-1
# kubemirror.raczylo.com/source-name: shared-credentials

Testing Update Propagation

Test that updates to source resources propagate to mirrors:

# Update the shared-credentials secret
kubectl patch secret shared-credentials -n namespace-1 \
  --type='json' \
  -p='[{"op": "replace", "path": "/data/password", "value": "'$(echo -n "new-password" | base64)'"}]'

# Wait a few seconds, then verify the change propagated
kubectl get secret shared-credentials -n namespace-3 -o jsonpath='{.data.password}' | base64 -d
# Should output: new-password

Testing Deletion Behavior

Test that deleting source resources deletes mirrors:

# Delete a source secret
kubectl delete secret database-credentials -n namespace-1

# Wait a few seconds, verify mirrors are also deleted
kubectl get secret database-credentials -n namespace-3 # Should not exist
kubectl get secret database-credentials -n namespace-4 # Should not exist

Test that deleting a mirror recreates it (if source still exists):

# Delete a mirrored resource
kubectl delete secret shared-credentials -n namespace-4

# Wait a few seconds, verify it's recreated
kubectl get secret shared-credentials -n namespace-4 # Should exist again

Cleanup

Remove all examples:

# Delete all resources
kubectl delete -k examples/

# Or delete individually
kubectl delete -f examples/traefik-middleware.yaml
kubectl delete -f examples/source-configmap.yaml
kubectl delete -f examples/source-secret.yaml
kubectl delete -f examples/namespaces.yaml

Troubleshooting

View KubeMirror Logs

# View controller logs
kubectl logs -n kubemirror-system -l app.kubernetes.io/name=kubemirror -f

Check Controller Events

# View events in a specific namespace
kubectl get events -n namespace-3 --sort-by='.lastTimestamp'

# Look for mirror-related events
kubectl get events --all-namespaces | grep -i mirror

Verify Controller is Running

# Check controller deployment
kubectl get deployment -n kubemirror-system

# Check controller pods
kubectl get pods -n kubemirror-system

Common Issues

1. Mirrors not created: Ensure target namespaces have the kubemirror.raczylo.com/allow-mirrors: "true" label
2. Updates not propagating: Check controller logs for errors or rate limiting
3. Traefik resources not mirroring: Ensure Traefik CRDs are installed in the cluster
4. Permission errors: Verify the controller has proper RBAC permissions

Advanced Examples

Mirror to All Except Specific Namespaces

apiVersion: v1
kind: Secret
metadata:
  name: almost-all
  namespace: namespace-1
  annotations:
    kubemirror.raczylo.com/sync: "true"
    kubemirror.raczylo.com/target-namespaces: "all"
    kubemirror.raczylo.com/excluded-namespaces: "namespace-3"
  labels:
    kubemirror.raczylo.com/enabled: "true"
data:
  key: dmFsdWU=  # "value" in base64

Pattern-Based Mirroring

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: namespace-1
  annotations:
    kubemirror.raczylo.com/sync: "true"
    kubemirror.raczylo.com/target-namespaces: "all"
    kubemirror.raczylo.com/namespace-pattern: "app-.*"
  labels:
    kubemirror.raczylo.com/enabled: "true"
data:
  config: "value"