Kubernetes Provider

The Kubernetes provider reads from and writes to Kubernetes ConfigMaps or Secrets.

At a glance

Quick start

# Set a secret$ secretspec set DATABASE_URL --provider k8s+secret://secret-nameEnter value for DATABASE_URL: postgresql://localhost/mydb✓ Secret DATABASE_URL saved to kubernetes
# Get a secret$ secretspec get DATABASE_URL --provider k8s+secret://secret-namepostgresql://localhost/mydb
# Run with secrets$ secretspec run --provider k8s+secret://secret-name -- npm start

Terminal window

Setup

Prerequisites

• A Kubernetes cluster
• Cluster connection configured in $KUBECONFIG (or $HOME/.kube/config as fallback)
• Build with --features kubernetes

Authentication

Uses whatever authentication method is configured in the cluster configuration used by kubectl.

Configuration

URI format

k8s+KIND://NAME[@NAMESPACE]

• NAME: Name of the Kubernetes object
• KIND: Kind of the Kubernetes object. Only supports configmap or secret.
• NAMESPACE: Optional namespace where the Kubernetes object exists in. If omitted, will use the cluster’s default namespace.

URI examples

k8s+configmap://db-config@db-postgresk8s+configmap://db-configk8s+secret://db-credentials@db-postgres

Project configuration

[providers]kube = "k8s+configmap://db-config@db-postgres"
[profiles.default]DATABASE_URL = { description = "Database URL", providers = ["kube"] }

secretspec.toml

Storage model

Each secret is stored as a key in the Kubernetes ConfigMap or Secret. Each secret is stored as secretspec--{project}--{profile}--{key} under .data. A key cannot exceed 253 characters. Each component can only contain alphanumeric characters, underscores, periods, and internal hyphens. SecretSpec joins the project, profile, and key with validated -- boundaries. Distinct logical addresses therefore cannot collapse onto one GCSM secret when a project or profile contains a single internal hyphen. As a consequence, a component cannot start or end with - or contain --, because those forms could overlap a boundary.

Use existing secrets

A secret’s ref field names an existing secret instead: item is the secret name stored in .data.item of the Kubernetes object. Reads and writes target that entry in place.

[profiles.default]API_TOKEN = { description = "Token", ref = { item = "com.example.app" }, providers = ["k8s+secret://app-config"] }

Last updated Oct 08, 2026