keeper-k8s-injector

README

Keeper Kubernetes Secrets Injector

Automatically inject secrets from Keeper Secrets Manager into your Kubernetes pods at runtime.

Features

• No Kubernetes Secrets created - Secrets are written directly to pod tmpfs
• Pod-scoped lifetime - Secrets are removed when pod terminates
• Automatic rotation - Sidecar refreshes secrets without pod restarts
• Simple configuration - Just two annotations to get started
• Title-based lookup - Reference secrets by name, not UIDs
• Keeper Notation - Use keeper://UID/field/password for precise extraction
• File Attachments - Download files from Keeper records
• Folder Support - Fetch all secrets from a Keeper folder
• Production-ready - HA, metrics, leader election

Installation

Option 1: Helm (OCI Registry) - Recommended

helm install keeper-injector oci://registry-1.docker.io/keeper/keeper-injector \
  --namespace keeper-system \
  --create-namespace

Option 2: Helm (Repository)

helm repo add keeper https://keeper-security.github.io/keeper-k8s-injector
helm repo update
helm install keeper-injector keeper/keeper-injector \
  --namespace keeper-system \
  --create-namespace

Option 3: kubectl (Direct YAML)

kubectl apply -f https://github.com/Keeper-Security/keeper-k8s-injector/releases/latest/download/install.yaml

Quick Start

1. Create KSM Auth Secret

# From your Keeper Secrets Manager config file
kubectl create secret generic keeper-auth \
  --from-file=config=ksm-config.json \
  --namespace default

2. Annotate Your Pod

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  annotations:
    keeper.security/inject: "true"
    keeper.security/auth-secret: "keeper-auth"
    keeper.security/secret: "database-credentials"
spec:
  containers:
    - name: app
      image: my-app:latest

Secrets are now available at /keeper/secrets/database-credentials.json.

Examples

Try these working examples to see the injector in action:

Example	Description	Time
Hello Secrets	Web page displaying secret values	5 min
PostgreSQL	Real database credential injection	10 min
Rotation Dashboard	Live secret rotation visualization	5 min

Try It Now

# Clone the repo
git clone https://github.com/Keeper-Security/keeper-k8s-injector.git
cd keeper-k8s-injector

# Run the hello-secrets example
kubectl apply -f examples/01-hello-secrets/
kubectl port-forward svc/hello-secrets 8080:80

# Open http://localhost:8080

Documentation

• Overview - Architecture and concepts
• Quick Start - 5-minute setup guide
• Annotations Reference - All configuration options
• Advanced Configuration - Helm, OIDC, multi-cluster
• Troubleshooting - Common issues and solutions

Annotation Examples

Multiple Secrets

keeper.security/secrets: "database-creds, api-keys, tls-cert"

Custom Paths

keeper.security/secret-db: "/app/config/database.json"
keeper.security/secret-api: "/etc/myapp/api.json"

With Rotation

keeper.security/refresh-interval: "5m"
keeper.security/signal: "SIGHUP"

Keeper Notation (Specific Fields)

keeper.security/secret-password: "keeper://QabbPIdM8Unw4hwVM-F8VQ/field/password:/app/secrets/db-pass"

File Attachments

keeper.security/file-cert: "Database Credentials:cert.pem:/app/certs/server.pem"

Comparison with External Secrets Operator (ESO)

Feature	Keeper Injector	External Secrets Operator
Creates K8s Secrets	No	Yes
Secret storage	Pod tmpfs (memory)	etcd
Secrets in etcd backups	No	Yes
Configuration	Annotations	CRDs
Runtime rotation	Yes (sidecar)	Sync interval
Pod isolation	Yes	Shared secrets

Use Keeper Injector when: Security is paramount, you need secrets out of etcd, or require per-pod isolation.

Use ESO when: You need secrets as K8s Secret objects, or apps require environment variables only.

Docker Images

Image	Description
keeper/injector-webhook	Mutating admission webhook
keeper/injector-sidecar	Sidecar container for secret fetching

Images are available on Docker Hub with multi-arch support (amd64, arm64).

Requirements

• Kubernetes 1.25+
• Keeper Secrets Manager application

Links

• ArtifactHub
• Docker Hub - Webhook
• Docker Hub - Sidecar
• Keeper Secrets Manager

Contributing

Contributions are welcome! Please open an issue or pull request.

License

MIT License - see LICENSE for details.

Support

• GitHub Issues
• Keeper Support