kubeseal

Encrypt a Kubernetes secret from a YAML file into a SealedSecret (default JSON output)

$ kubeseal < [secret.yaml] > [sealedsecret.json]

$ kubeseal [[-o|--format]] [yaml|json] --token [my-bearer-token] < [secret.yaml] > [sealedsecret.yaml]

$ kubeseal --controller-namespace [controller-namespace] --controller-name [controller-name] < [secret.yaml] > [sealedsecret.yaml]

$ kubeseal --raw --from-file [path/to/secret.txt] --name [my-secret] --scope [strict|namespace-wide|cluster-wide] > [sealedsecret.yaml]

$ kubeseal --fetch-cert --username [username] --password [password] > [cert.pem]

$ kubeseal --cert [cert.pem] < [secret.yaml] > [sealedsecret.yaml]

$ kubeseal --merge-into [sealedsecret.yaml] < [secret.yaml]

$ kubeseal --validate < [sealedsecret.yaml]

kubeseal [options] [input_file]
cat <secret.yaml> | kubeseal [options] > <sealedsecret.yaml>
kubeseal --raw --from-literal=<key>=<value> [--from-literal=...] > <sealedsecret.yaml>

--cert <path>
    Specifies the path to the public key certificate for sealing. If not provided, kubeseal attempts to fetch it from the controller.

--controller-name <name>
    Sets the name of the sealed-secrets controller deployment (default: sealed-secrets).

--controller-namespace <namespace>
    Sets the namespace of the sealed-secrets controller (default: kube-system).

--dry-run
    Prints the sealed secret to stdout without actually writing it to the specified output file.

--from-file <path>
    Reads secret data from a file, similar to kubectl create secret generic --from-file.

--from-literal <key=value>
    Provides secret data as a literal key-value pair, similar to kubectl create secret generic --from-literal.

--from-env <env_var_name>
    Reads secret data from an environment variable.

--json
    Outputs the sealed secret in JSON format instead of YAML.

--name <name>
    Specifies the name for the generated SealedSecret object.

--namespace <namespace>
    Specifies the target namespace for the SealedSecret object.

--output <path>
    Writes the sealed secret to the specified file instead of stdout.

--raw
    Indicates that the input is a raw secret value (e.g., from --from-literal), not a full Kubernetes Secret YAML.

--scope <cluster-wide|namespace-wide|strict>
    Controls the secrecy scope, determining how restricted the secret is (e.g., to a specific namespace or cluster-wide).

--re-encrypt
    Re-encrypts an existing SealedSecret with the latest public key. Useful for key rotations.

--allow-empty-data
    Allows sealing of secrets with empty data values.

--merge-into <file>
    Merges the generated SealedSecret into an existing YAML file, typically a Kubernetes manifest.

--recovery-unseal-key <path>
    Path to a private key for emergency unsealing (advanced usage, typically not for sealing).

--recovery-cert <path>
    Path to a public certificate for emergency unsealing (advanced usage, typically not for sealing).

kubeseal is a command-line utility for encrypting Kubernetes Secret objects into SealedSecret objects. It is an integral part of the sealed-secrets ecosystem, which provides a controller to decrypt these SealedSecret objects back into standard Secret objects within a Kubernetes cluster. The primary purpose of kubeseal is to allow users to safely commit sensitive data, such as database passwords or API keys, into version control systems (like Git) without exposing the plain-text values.

It achieves this by encrypting the secret data using the sealed-secrets controller's public key. Only the controller, holding the corresponding private key, can decrypt the data within the cluster, making it a secure and practical solution for managing secrets in a GitOps workflow.

kubeseal requires the sealed-secrets controller to be running in your Kubernetes cluster to fetch its public key for encryption. Without the controller, or if the key is not explicitly provided via --cert, kubeseal cannot function.

The SealedSecret objects generated by kubeseal can only be decrypted by the specific sealed-secrets controller instance that holds the corresponding private key. This ensures strong security but means portability of sealed secrets across distinct clusters requires careful management of controller keys.

While kubeseal encrypts secrets, it does not decrypt them. Decryption is solely handled by the sealed-secrets controller within the cluster when a SealedSecret is applied.

kubeseal leverages asymmetric encryption. It fetches the public key from the sealed-secrets controller running in your Kubernetes cluster (or you can provide it via --cert). It then uses this public key to encrypt the secret data. The resulting SealedSecret can be safely committed to Git. When this SealedSecret is applied to the cluster, the sealed-secrets controller, possessing the corresponding private key, decrypts it into a standard Kubernetes Secret object.

• Storing sensitive configuration in public or private Git repositories without exposing plain-text values.
• Implementing GitOps workflows where all application configurations, including secrets, are version-controlled.
• Ensuring that secrets are only accessible by the Kubernetes cluster they are intended for, even if the Git repository is compromised.
• Enabling safe collaboration on infrastructure-as-code that includes secret definitions.

kubeseal is a core component of the sealed-secrets project, originally developed by Bitnami (now VMware). It emerged as a solution to a common challenge in Kubernetes: how to safely store sensitive information like passwords and API keys in Git repositories while maintaining a GitOps workflow. The project addresses this by providing a robust public-key encryption mechanism for Kubernetes Secrets, making it possible to commit secrets safely to version control.

kubectl(1), sops(1)