ksp

KSP - Kubernetes Secret Proxy

KSP does annotation based secret data injection and decryption.

It runs locally and acts as proxy to your kubernetes api server. This means it integrates seamless with kubectl and tools that build on it.

Table of Contents

• Installation
  • Go
  • Binary (Recommended)
  • Docker (In Development)
• Getting started
  • GPG
• Injectors
  • GPG
    • Annotations
    • Notes
• Rationale
  • POST
  • PATCH

Installation

Go

export GO111MODULE=on
go get github.com/clstb/ksp

Binary (Recommended)

Download the latest binary here.

Docker (In Development)

Docker images are available here.

Getting started

GPG

1. Start the ksp proxy with enabled gpg injector.

ksp proxy --port 8000 --config $HOME/.kube/config --injector-gpg

1. Verify kubectl is still working.

kubectl version

1. Encrypt a file.

ksp g e --keys {YOUR_KEY_ID} --file ./secret.env

# secret.env
BAR=foo
FOO=bar

1. Set annotations.

apiVersion: v1
kind: Secret
metadata:
  annotations:
    'ksp/inject': gpg
data:
  BAR: .....

Either add encrypted data manually to the secret or use other tooling to import it. For example kustomize supports it with the .env secret generator.

1. Apply it.

kubectl apply -f secret.yaml

Injectors

Injectors modify secrets passed to them based on annotations.
They use following interface:

type Injector interface {
    Inject(*corev1.Secret) (*corev1.Secret, error)
}

GPG

The GPG injector decrypts all data fields of the secret using the local gpg cli.

Annotations

• ksp/inject: gpg

Notes

• You can use ksp gpg encrypt to encrypt basic JSON files.
• You can encrypt the secret data with multiple public keys. That way it is possible to have a seperate keys for CI/CD or other developers.

Rationale

Following API endpoints need to be handled:

• POST /api/v1/namespaces/{namespace}/secrets
• PATCH /apis/v1/namespaces/{namespace}/secrets/{name}

POST

This endpoint handles secret creation.

The proxy applies following steps:

1. Read secret from request body
2. Call configured injectors with secret
3. Rewrite request body with injected secret
4. Forward request to the kubernetes API server

PATCH

This endpoint handles secret modification.
If a secret already exists kubectl pulls it from the cluster and computes a diff between the local and cluster state.
This diff is incorrect because the local state contains encrypted or no secret data.

The proxy applies following steps to solve this problem:

1. Read patch from request body
2. Retrieve cluster state of the secret
3. Compute local state by patching the cluster state
4. Call configured injectors with secret
5. Compute fixed patch from injected secret and cluster state
6. Rewrite request body with fixed patch
7. Forward request to the kubernetes API server