MeteorOps | DevOps Dictionary | Kubernetes Secret

Kubernetes Secret

Kubernetes Secret is a Kubernetes API object used to store sensitive data such as passwords, API tokens, TLS certificates, SSH keys, and registry credentials. In practical terms, it lets your pods consume sensitive values without hardcoding them into container images, application code, or plain deployment manifests.

What a Kubernetes Secret does

A Secret separates sensitive configuration from your workload definition. Instead of putting a database password directly in a Deployment, you create a Secret and reference it from the pod.

Applications usually consume Secrets in one of two ways:

As environment variables, such as DATABASE_PASSWORD.
As mounted files, such as /etc/secrets/api-key or /etc/tls/tls.crt.

This keeps sensitive values outside the container image and makes it easier to rotate credentials without rebuilding the application.

How Kubernetes Secrets work

A Secret is stored in the Kubernetes API server and persisted in the cluster backing store, usually etcd. Secret values are base64-encoded in the object definition, but base64 is encoding, not encryption.

A simplified Secret looks like this:

apiVersion: v1
kind: Secret
metadata:
  name: app-database-secret
type: Opaque
data:
  username: YXBwdXNlcg==
  password: c3VwZXItc2VjcmV0

A pod can then reference the Secret:

env:
  - name: DATABASE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: app-database-secret
        key: password

When the pod starts, Kubernetes makes the selected Secret value available to the container. If the Secret is mounted as a volume, Kubernetes can update the mounted file after the Secret changes. If the Secret is used as an environment variable, the pod usually needs a restart to pick up the new value.

Common use cases

Database credentials: usernames, passwords, connection strings, and application-specific tokens.
API keys: credentials for external services such as payment providers, observability tools, or internal APIs.
TLS assets: certificates and private keys used by ingress controllers, services, or workloads.
Container registry credentials: pull secrets for private images.
Service account tokens: credentials used by pods to authenticate to the Kubernetes API.
Application secrets: signing keys, encryption keys, session secrets, and webhook tokens.

Common Secret types

Kubernetes supports several Secret types. The type helps Kubernetes and tools understand what the Secret contains.

Opaque: the default generic Secret type for arbitrary key-value data.
kubernetes.io/tls: used for TLS certificates and private keys, commonly with keys named tls.crt and tls.key.
kubernetes.io/dockerconfigjson: used for Docker registry authentication.
kubernetes.io/service-account-token: used for service account tokens, though newer Kubernetes setups often use projected, short-lived tokens instead.
basic-auth: used for username and password pairs.
ssh-auth: used for SSH private keys.

Kubernetes Secret vs ConfigMap

A Secret and a ConfigMap are both Kubernetes API objects used to separate configuration from application code, but they serve different purposes.

Use a Secret for sensitive data, such as passwords, tokens, private keys, and certificates.
Use a ConfigMap for non-sensitive data, such as feature flags, log levels, service URLs, and application settings.

The distinction matters for access control, auditing, and operational habits. Engineers should treat Secrets with stricter permissions and avoid storing them in plain text Git repositories.

Security considerations

Kubernetes Secrets are useful, but they are not a complete secrets management system by themselves.

Base64 is not encryption: anyone who can read the Secret object can decode the values.
Use RBAC carefully: restrict who and what can read, list, watch, or update Secrets.
Encrypt Secrets at rest: configure Kubernetes encryption at rest for etcd where possible.
Avoid committing raw Secrets to Git: use sealed secrets, external secret operators, SOPS, or a secrets manager workflow.
Rotate credentials: plan how pods will reload updated values, especially when Secrets are consumed as environment variables.
Limit namespace access: Secrets are namespaced, but broad namespace permissions can still expose many credentials.

If you manage Kubernetes manifests with infrastructure as code, be careful not to place real secret values directly in state files or repositories. For example, when you deploy Kubernetes resources using Terraform, you should account for where sensitive values are stored, who can read the state, and how rotation will work.

Real-world example

Suppose you run a Node.js API in Kubernetes and it needs to connect to PostgreSQL. You can store the database password in a Secret named api-db-secret. Your Deployment references that Secret as an environment variable called DATABASE_PASSWORD.

The container image stays the same across development, staging, and production. Each environment gets its own Secret value. If the production password changes, you update the Secret and restart the affected pods instead of rebuilding the image.

Secrets and external systems

Many teams use Kubernetes Secrets as the final delivery mechanism to pods, while storing the source of truth in a dedicated secrets system such as AWS Secrets Manager, HashiCorp Vault, Google Secret Manager, or Azure Key Vault.

In that setup, an operator or controller syncs external secret values into Kubernetes Secrets. This pattern works well when teams need centralized rotation, audit logs, and cloud IAM integration. It is also common in clusters that manage cloud resources through Kubernetes APIs, such as when teams deploy AWS resources using Crossplane on Kubernetes.

Key limitations

Size limit: a single Kubernetes Secret is limited to 1 MiB.
Namespace scope: a Secret belongs to one namespace and is not shared globally by default.
Access risk: any pod or user with permission to read the Secret can access its value.
Operational complexity: rotation, reload behavior, Git workflows, and audit requirements need clear processes.

A Kubernetes Secret is best understood as a Kubernetes-native way to pass sensitive values to workloads. It improves separation of concerns, but you still need strong access control, encryption at rest, safe deployment workflows, and a clear rotation strategy.

DevOps Dictionary