qseal is a CLI tool that simplifies the process of sealing and unsealing Kubernetes secrets using kubeseal. It uses a declarative configuration file (qsealrc.yaml) to manage your secrets.
- Declarative configuration of sealed secrets
- Sealing and unsealing via a single
syncoperation - Conflict detection for sealed paths
If your GOPATH is set up, you can install qseal using the following command:
go install github.com/42paris/qseal@latestYou can also download the latest release from the releases page.
-
Initialize the configuration file: After installing
qseal, navigate to your project directory and run:qseal init
This will create a
qsealrc.yamlfile in your project root. -
Edit the configuration file: Open
qsealrc.yamland edit namespace and the controller values. You can add your secrets in thesecretssection. Each secret should have the following structure:- name: my-secret sealed: "secrets/my-secret.env.sealed.yaml" the path of the sealed secrets (optional) default to {{secret_name}}.sealed.yaml env: "secrets/my-secret.env" the path of the env file (optional) files: # the list of files to be sealed (optional) - "secrets/config.yaml" - "secrets/my-secret2.yaml" type: "kubernetes.io/dockerconfigjson" # the type of the secret (optional) default to Opaque
-
Run
qsealorqseal sync: After editing the configuration file, you can runqsealto created the sealed secrets. The command will automatically detect the changes and seal or unseal the secrets as needed.qseal
-
Check the status: You can check the status of your secrets by running:
qseal status
This will show you the current state of your secrets and whether they will have to get sealed or unsealed.
-
Autocompletion: You can enable autocompletion for your shell by running:
qseal completion --help
qseal [flags]
qseal [command]
qseal # without any command will run `qseal sync`| Command | Description |
|---|---|
init |
Initialize the qsealrc.yaml configuration file |
sync |
Seal or unseal secrets based on the configuration file |
status |
Will show the status of the secrets and whether they will have to get sealed or unsealed |
seal-all |
Seal all secrets defined in the config file (not recommended, use qseal sync or qseal) |
unseal-all |
Unseal all secrets defined in the config file (not recommended, use qseal sync or qseal) |
completion |
Generate autocompletion script for your shell |
help |
Display help for any command |
-h,--help: Show help information
Use qseal [command] --help for detailed information about a specific command.
qseal expects a qsealrc.yaml file at the root of your project. This file defines all secrets to be managed. Each secret must include:
- A name
- The path to the sealed file
- Then the path to the secret file (env file, files)
- The type of secret (e.g.,
kubernetes.io/dockerconfigjson,kubernetes.io/tls, etc.)
The core of qseal is the Sync operation, which:
- Parses the secrets listed in
qsealrc.yaml - Groups them by sealed output path
- Determines whether each group needs to be sealed, unsealed, or skipped
- Detects conflicts (e.g. multiple actions for the same sealed path)
- Applies sealing or unsealing as needed
Example log output:
[2025-04-16 10:00:00] SEALING secrets.yaml (3 secret(s))
[2025-04-16 10:00:00] SKIP secrets.yaml (up-to-date)
[2025-04-16 10:00:00] UNSEALING secrets.yaml (2 secret(s))If multiple secrets reference the same sealed file path but require different actions (seal vs unseal), qseal will raise an e
5CC9
rror. You can resolve this by explicitly running either:
qseal seal-allor
qseal unseal-all