Skip to content

SOPS

Summary

SOPS (Secrets OPerationS) is a CLI and Go library that encrypts the values of YAML, JSON, ENV and INI files (and whole BINARY files) while leaving keys readable, so encrypted secrets can live in Git with meaningful diffs. A random data key encrypts the values. That data key is wrapped by one or more master keys: age (including SSH, plugin and post-quantum keys), PGP, AWS KMS, GCP Cloud KMS, Azure Key Vault, HashiCorp Vault/OpenBao Transit, or HuaweiCloud KMS. Flux decrypts SOPS natively. Argo CD needs a plugin. The latest release is 3.13.3 (2026-07-23). SOPS is a CNCF Sandbox project under MPL-2.0, and has been under a CNCF TOC health review since 2026-03.

Key Facts

Attribute Detail
Latest Version 3.13.3 (2026-07-23). Minor line 3.13 started 2026-05-08
Release cadence About two minor releases per year (3.10 Mar 2025, 3.11 Sep 2025, 3.12 Feb 2026, 3.13 May 2026) plus patches. No published support window
Repository github.com/getsops/sops (moved from mozilla/sops in 2023)
Docs getsops.io/docs (docs moved out of the README in 3.13.1)
Language Go (build needs Go >= 1.25). Library github.com/getsops/sops/v3
License MPL-2.0
Governance CNCF Sandbox (accepted 2023-05-17). TOC health review open since 2026-03-17 over MPL-2.0 licensing (cncf/toc#2098)
Origin Mozilla, 2015
Formats YAML, JSON, ENV (dotenv), INI, BINARY
Key backends age, PGP, AWS KMS, GCP KMS, Azure Key Vault, Vault/OpenBao Transit, HuaweiCloud KMS (3.12.0+)
Recommended backend age (docs: "recommended to use age over PGP, if possible"). PGP is not deprecated
Stars ~17k+ (2026-07 figure)

How It Works

SOPS uses envelope encryption: each value is AES-256-GCM-encrypted with a per-file data key, and each master key stores its own encrypted copy of that data key in the file's sops metadata block.

flowchart LR
    Dev["Developer<br/>sops edit / encrypt"] --> Cfg[".sops.yaml<br/>creation_rules"]
    Dev --> File["secrets.yaml<br/>keys plaintext,<br/>values ENC[AES256_GCM,...]"]
    File --> Meta["sops metadata<br/>encrypted data keys + MAC"]
    Meta --- Age["age / PGP<br/>(offline)"]
    Meta --- KMS["AWS / GCP / Azure /<br/>HuaweiCloud KMS"]
    Meta --- Transit["Vault / OpenBao<br/>Transit"]
    File --> Git["Git repository"]
    Git --> Flux["Flux kustomize-controller<br/>(native decryption)"]
    Git --> Argo["Argo CD repo-server<br/>(KSOPS / helm-secrets)"]
    Git --> CI["CI job<br/>sops decrypt"]

Details: Explanation: Architecture, Envelope Encryption Model and Message Authentication Code.

Evaluation

Pros Cons
Encrypts values only, so Git diffs and merges stay meaningful Not a secret manager: no dynamic secrets, leases or automatic rotation
Many master-key backends in one file, including offline age and post-quantum age Revocation needs updatekeys + rotate. Git history stays decryptable with old keys
No server to run. Single static binary and Go library Key distribution to people and CI is up to you
Native Flux support. Plugins for Argo CD, Helm and Terraform Argo CD integration puts keys and plaintext in the repo-server
.sops.yaml path rules, key groups (Shamir quorum), partial encryption No built-in access control beyond key possession. Auditing depends on the backend (optional PostgreSQL decrypt log)
Stable v3 file format, CNCF Sandbox, active maintainers (4 releases in 2026-05 to 07) Governance uncertainty: CNCF health review over MPL-2.0 (relicense, archive or move)

When It Fits

  • GitOps repositories that need Kubernetes Secrets, Helm values or app config in Git (especially with Flux).
  • Small and medium teams that want secrets versioned with code and no new infrastructure.
  • IaC repositories (Terraform/OpenTofu via carlpett/sops) and config files decrypted at deploy time with sops exec-env.

When to Look Elsewhere

  • You need dynamic or short-lived credentials, leasing, or central audit of every read: use HashiCorp Vault (or OpenBao).
  • Secrets already live in a cloud secret manager and you only need them in Kubernetes: use External Secrets Operator.
  • Many consumers need per-secret access control: SOPS gives file-level, key-possession access only.

Ecosystem and Integrations

Integration How SOPS is used
Flux kustomize-controller decrypts spec.decryption.provider: sops with age/PGP keys from a Secret or cloud/OpenBao workload identity
Argo CD No native support. KSOPS, helm-secrets or argocd-vault-plugin run in the repo-server
Helm helm-secrets plugin decrypts values files
Terraform / OpenTofu carlpett/sops provider with a data source or (Terraform >= 1.11) an ephemeral resource
Kubernetes Encrypt Secret manifests with encrypted_regex: ^(data\|stringData)$. See Kubernetes
helmfile / vals Read SOPS files as a value source

Topic Map

  • How-to Guides: install, age and KMS setup, .sops.yaml, encrypt/edit/rotate, key groups, CI/CD, Flux, Argo CD, Terraform, troubleshooting.
  • Reference: release history, formats, backend matrix, subcommands, environment variables, .sops.yaml schema, on-disk format, hardening checklist.
  • Explanation: architecture, envelope and value-level encryption, MAC, key groups, decryption order, rotation semantics, GitOps models, threat model, governance.

Sources

Questions

Answered

  • Q: age or PGP? Use age. It has simpler key management (one key pair, or an SSH key, plugin or PQ hybrid), a smaller attack surface (no keyring, agent or keyserver) and modern cryptography (X25519 + ChaCha20-Poly1305, optional ML-KEM-768 hybrid). PGP is not deprecated in 3.13.3. Keep it only for existing files or PGP-centric organizations. See age vs PGP.

  • Q: What is the difference between updatekeys and rotate? sops updatekeys syncs a file's master keys with the current .sops.yaml rule without changing the data key or re-encrypting values. sops rotate generates a new data key and re-encrypts every value (optionally adding or removing keys with --add-*/--rm-*). After a compromise, run updatekeys first, then rotate, then rotate the real credentials. See Key Rotation Semantics.

  • Q: Can SOPS encrypt binary files? Yes. In BINARY mode (any unrecognized extension, or --input-type binary) SOPS encrypts the whole file as one value and writes a JSON document with the base64 ciphertext under data plus the usual sops metadata. There is no sidecar file. The output is larger than the input because of base64.

  • Q: How does .sops.yaml path matching work? SOPS finds the nearest .sops.yaml by searching upward from the current working directory. Rules are evaluated top to bottom, and the first rule whose path_regex matches the file path (relative to the config file) wins. A rule without path_regex matches everything, so it belongs last. Keys passed on the command line or in environment variables override the config.

  • Q: Can I use SOPS with Terraform? Yes. The carlpett/sops provider offers data "sops_file" (values end up in state) and, with Terraform >= 1.11 and provider >= 1.3.0, an ephemeral "sops_file" resource that keeps plaintext out of state.

  • Q: How do key groups work? With several key groups, the data key is split with Shamir's Secret Sharing, one share per group. By default one key from every group is needed. shamir_threshold lowers that to k of n groups. This gives separation of duty across teams or backends.

  • Q: What is the recommended pattern for SOPS in a GitOps workflow? Encrypt Kubernetes Secrets with encrypted_regex: ^(data|stringData)$ and .sops.yaml rules per environment. With Flux, let kustomize-controller decrypt in-cluster (age key Secret or KMS workload identity). With Argo CD, use KSOPS or helm-secrets in the repo-server, knowing that plaintext passes through the repo-server. See GitOps Decryption Models.

  • Q: Does SOPS have audit logging? Not by default. Cloud KMS, Key Vault and Vault/OpenBao log each decryption API call. SOPS can optionally log decryptions to PostgreSQL (/etc/sops/audit.yaml). age and PGP leave no server-side trail.

Open

  • Q: What will the CNCF TOC decide in the health review (#2098)? Options are relicensing away from MPL-2.0, archiving, or moving to another foundation (Linux Foundation or OpenSSF). The issue was open with no decision as of 2026-09-25.
  • Q: How does SOPS perform on very large files (thousands of keys)? Each leaf is encrypted separately with its own 32-byte IV and tag, so ciphertext files grow substantially and encrypt/decrypt time scales with leaf count. No official benchmark exists (checked 2026-09-28), so measure before relying on SOPS for very large documents.
  • Q: When will post-quantum age keys be practical by default? PQ recipients are about 2,000 characters long, and every decrypting tool (SOPS >= 3.12.0, Flux kustomize-controller >= v1.9.0, KSOPS, helm-secrets) must support them. Which KSOPS and helm-secrets releases can decrypt PQ-recipient files is still open.