API Reference

Complete reference for Replizieren annotations and behavior.

Annotations

All Replizieren annotations use the replizieren.dev/ prefix.

replizieren.dev/replicate

Type: String Required: Yes (for replication to occur, unless replicate-all is used) Applies to: Secrets, ConfigMaps

Controls whether and where a resource should be replicated.

Values

Behavior

• Whitespace handling: Spaces around namespace names are automatically trimmed
• Empty entries: Empty entries in comma-separated lists are ignored ("ns1,,ns2" = "ns1, ns2")
• Source exclusion: The source namespace is always excluded from targets
• Non-existent namespaces: Replication to non-existent namespaces will log an error but continue processing other targets

Examples

# Single namespace
annotations:
  replizieren.dev/replicate: "production"

# Multiple namespaces
annotations:
  replizieren.dev/replicate: "staging, production, testing"

# All namespaces (legacy - prefer replicate-all)
annotations:
  replizieren.dev/replicate: "true"

# Disabled
annotations:
  replizieren.dev/replicate: "false"

replizieren.dev/replicate-all

Type: String (boolean) Required: No Applies to: Secrets, ConfigMaps

Controls replication to all namespaces. This is the preferred way to replicate to all namespaces as it removes ambiguity around namespace names.

Values

Precedence Rules

When both replicate-all and replicate are set:

1. If replicate-all: "true", replicate to all namespaces (ignores replicate)
2. If replicate-all: "false", use replicate for namespace list
3. If replicate-all: "false" and replicate: "true", “true” is treated as a namespace name

Examples

# All namespaces (recommended)
annotations:
  replizieren.dev/replicate-all: "true"

# Target a namespace literally named "true"
annotations:
  replizieren.dev/replicate-all: "false"
  replizieren.dev/replicate: "true"

# replicate-all takes precedence (ignores namespace list)
annotations:
  replizieren.dev/replicate-all: "true"
  replizieren.dev/replicate: "ns1, ns2"  # This is ignored

replizieren.dev/rollout-on-update

Type: String (boolean) Required: No Default: "false" Applies to: Secrets, ConfigMaps

Controls whether Deployments should be restarted when the resource is updated.

Values

Behavior

When enabled and the resource is updated:

1. Detection: Finds all Deployments in affected namespaces that use the resource
2. Annotation: Adds/updates a timestamp annotation on the Pod template
3. Restart: Kubernetes performs a rolling restart due to the template change

Affected Namespaces

Rollouts are triggered in:

• The source namespace (where the original resource lives)
• All target namespaces (where the resource is replicated)

Detection Methods

A Deployment is considered to “use” a Secret if:

• It has a volume with secret.secretName matching the Secret name
• It has a container with envFrom[].secretRef.name matching the Secret name

A Deployment is considered to “use” a ConfigMap if:

• It has a volume with configMap.name matching the ConfigMap name
• It has a container with envFrom[].configMapRef.name matching the ConfigMap name

Annotations Added

For Secrets:

spec:
  template:
    metadata:
      annotations:
        secret.restartedAt: "2024-01-15T10:30:00Z"

For ConfigMaps:

spec:
  template:
    metadata:
      annotations:
        configmap.restartedAt: "2024-01-15T10:30:00Z"

Examples

# Enable rollout
annotations:
  replizieren.dev/replicate: "production"
  replizieren.dev/rollout-on-update: "true"

# Replicate without rollout
annotations:
  replizieren.dev/replicate: "production"
  replizieren.dev/rollout-on-update: "false"

Supported Resources

Secrets

All Secret types are supported:

ConfigMaps

All ConfigMaps are supported, including those with:

• data (string key-value pairs)
• binaryData (binary data)

Replicated Resource Properties

When a resource is replicated, the following properties are preserved:

The following are NOT preserved (set by Kubernetes):

• metadata.namespace (set to target namespace)
• metadata.uid
• metadata.resourceVersion
• metadata.creationTimestamp
• metadata.ownerReferences

Controller Behavior

Reconciliation

The controller reconciles on:

• Resource creation
• Resource update
• Resource deletion (no action taken on replicated copies)

Error Handling

Leader Election

The controller uses leader election for high availability. Only one instance is active at a time, ensuring no duplicate processing.

Rate Limiting

The controller uses Kubernetes’ standard rate limiting:

• Initial retry: 5ms
• Max retry: 1000s
• Exponential backoff between retries

RBAC Requirements

The controller requires the following ClusterRole permissions:

rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "patch"]

Metrics

The controller exposes standard controller-runtime metrics on port 8080 (configurable):

Health Endpoints

Environment Variables

The controller does not require any environment variables. All configuration is done through command-line flags set in the Deployment manifest.

Command-Line Flags

Compatibility

Kubernetes Versions

Replizieren is tested against multiple Kubernetes versions in CI. The following table shows the compatibility status:

Note: We test against the latest patch version of each minor release. Older patch versions should work but are not explicitly tested.

Version Support Policy

• Actively tested: Last 5 Kubernetes minor versions
• Minimum supported: Kubernetes 1.28+
• CI tested on every PR: v1.32, v1.31, v1.30, v1.29, v1.28

Build Requirements