Skip to content

SOPS

CLI tool for encrypting structured files (YAML, JSON, ENV) in-place — the GitOps standard for secrets-in-Git.

Overview

SOPS (Secrets OPerationS) encrypts values only in structured files, leaving keys/structure intact for Git diffability. It supports multiple key backends (age, AWS KMS, GCP KMS, Azure KV, Vault Transit) and is the standard way to store encrypted secrets in Git for GitOps workflows (Flux, ArgoCD). It is a CNCF Sandbox project.

Key Facts

Attribute Detail
Repository github.com/getsops/sops
Stars ~17k+ ⭐
Language Go
License MPL 2.0
Governance CNCF Sandbox
Recommended Backend age (over PGP)

Evaluation

Pros Cons
Encrypts values only — Git-diffable No centralized secret management
Multiple KMS backends (age, AWS, GCP, Azure) Key distribution is manual
Perfect for GitOps (Flux kustomize-controller) No dynamic secrets
In-place editing (decrypt → edit → re-encrypt) No audit logging
.sops.yaml for path-based rules No access control beyond key possession
CNCF Sandbox, wide adoption

How It Works

flowchart LR
    subgraph Encrypt["Encryption"]
        Plain["secrets.yaml\n(plaintext)"]
        SOPS_E["sops --encrypt"]
        Enc["secrets.yaml\n(values encrypted,\nkeys visible)"]
    end

    subgraph Git_S["Git Repository"]
        Stored["secrets.yaml\n(encrypted)"]
    end

    subgraph Decrypt["Decryption"]
        SOPS_D["sops --decrypt"]
        Decrypted["secrets.yaml\n(plaintext)"]
    end

    Plain --> SOPS_E --> Enc --> Stored
    Stored --> SOPS_D --> Decrypted

    style Enc fill:#2e7d32,color:#fff
    style Stored fill:#1565c0,color:#fff

Supported Backends

Backend Use Case
age ✅ Recommended — simple, modern, no keyring complexity
AWS KMS Cloud-native, IAM-integrated
GCP KMS Cloud-native, IAM-integrated
Azure Key Vault Cloud-native, Azure AD-integrated
HashiCorp Vault Transit Vault-managed key encryption
PGP Legacy — complex keyring management

Notes

Sources

Questions

Answered

  • Q: age or PGP? -- age is recommended. It provides simpler key management (single X25519 key pair), a smaller attack surface (no keyring, no keyserver), and modern cryptography (ChaCha20-Poly1305). PGP is considered legacy and should only be retained for backward compatibility with existing encrypted files.

  • Q: What is the difference between updatekeys and rotate? -- sops updatekeys syncs the encrypted file with the current .sops.yaml creation rules by adding or removing master keys. It does not re-encrypt the data (the data key stays the same). sops rotate generates a completely new data key and re-encrypts all values. Use rotate for true cryptographic rotation after a suspected key compromise; use updatekeys for onboarding new team members or removing stale keys.

  • Q: Can SOPS encrypt binary files? -- Yes. When encrypting binary files, SOPS encrypts the entire file content as a single blob using the same envelope encryption mechanism (data key encrypted by master keys). Binary encryption produces a .sops metadata sidecar or embeds metadata in the output format.

  • Q: How does .sops.yaml path matching work? -- Rules are evaluated sequentially from top to bottom. The first rule whose path_regex matches the filename is used. If no rule matches, SOPS falls back to command-line-specified keys. Use a catchall rule at the end of the file for default encryption behavior.

  • Q: Can I use SOPS with Terraform? -- Yes. The carlpett/sops Terraform provider decrypts SOPS-encrypted files and makes the values available as Terraform variables. It supports ephemeral blocks to prevent plaintext secrets from being stored in Terraform state.

  • Q: How do key groups work? -- Key groups enforce quorum-based decryption. When key groups are configured, decryption requires at least one valid master key from each group. This provides separation of duty, ensuring that no single team or key backend can decrypt files alone.

Open

  • Q: How does SOPS handle large files with many keys? -- SOPS encrypts each leaf value individually with its own IV. For files with thousands of keys, this produces a large sops metadata block. Performance remains acceptable for typical configuration files (tens to hundreds of keys), but very large files may experience slower encrypt/decrypt operations.

  • Q: What is the recommended pattern for SOPS in a GitOps workflow? -- Encrypt files in the repository using SOPS with .sops.yaml for automatic key selection. In the CI/CD or GitOps pipeline, decrypt using age keys or KMS credentials available as CI secrets. Some teams use SOPS in combination with Flux or ArgoCD SOPS plugins to decrypt secrets at deploy time.