SOPS — Secrets OPerationS

Terminal

Security

Published

July 15, 2026

Modified

July 15, 2026

Overview

SOPS (Secrets OPerationS) is a tool for encrypting secrets while preserving the structure of configuration files. Unlike traditional encryption tools that produce opaque blobs, SOPS encrypts only the values and comments, leaving keys in plaintext so the file remains human-readable and editable¹.

It works with common configuration formats such as YAML, JSON, INI, and dotenv files, making it suitable for any workflow where sensitive data lives alongside structural configuration.

Example

Consider a simple configuration file with database credentials:

config.yaml

database:
  host: db.example.com
  port: 5432
  user: admin
  password: mysecretpassword

Generate an Age key pair if you don’t have one:

age-keygen -o age.key

Create a .sops.yaml configuration file including the public key. By default, SOPS encrypts all leaf values. To encrypt only specific fields, use regex matching in .sops.yaml:

.sops.yaml

creation_rules:
  - age:
      - age1q8... # your public key
    encrypted_regex: "^password$"

This pattern matches only the key named exactly password, leaving host, port, and user unencrypted. Then encrypt the file:

sops --encrypt config.yaml > config.enc.yaml

After encryption, the structure remains intact with only the password encrypted:

config.enc.yaml

database:
  host: db.example.com
  port: 5432
  user: admin
  password: ENC[AES256_GCM,data:.../...,type:str]
sops:
  age:
#…
    encrypted_regex: ^password$
    lastmodified: "2026-07-15T13:05:50Z"
#…

Keys (in this example password) stay visible, making it clear what each encrypted value represents without exposing the actual secret. The sops metadata section at the bottom stores the encrypted data key and integrity information².

Use Cases

SOPS is useful whenever you need to store encrypted secrets in version control or share them across systems:

Infrastructure as Code — encrypt database credentials, API tokens, or certificates embedded in Terraform, Ansible, or Kubernetes manifests
Configuration Management — protect secrets in application config files without losing the ability to review or diff changes
Team Collaboration — grant decryption access to specific team members using Age, PGP, or cloud KMS keys
Disaster Recovery — keep encrypted backups of critical configurations that can be decrypted offline

Configuration

A .sops.yaml file can define multiple creation rules matched by file path, each with its own key holders and encryption scope. Here is an example for a project with different teams and sensitivity levels:

creation_rules:
  # Production database credentials — admin and dba keys only.
  - path_regex: prod/database/.*\.sops\.ya?ml$
    encrypted_regex: ^password$
    age:
      - age1admin...key1
      - age1dba...key2

  # Staging secrets — developer and staging service account.
  - path_regex: staging/.*\.sops\.ya?ml$
    age:
      - age1dev...key3
      - age1staging...key4

  # Fallback — admin key for any other encrypted file.
  - path_regex: \.sops\.ya?ml$
    age: age1admin...key1

Key patterns used here:

First match wins — rules are evaluated top to bottom, so specific paths take precedence over the catch-all fallback
Separate key holders per scope — the admin key decrypts everything, while team-specific keys are limited to their own directories, limiting damage if a key is compromised
Selective encryption — encrypted_regex: ^password$ encrypts only the password field, leaving hostnames and ports visible for quick review
Path-based scoping — path_regex ensures each rule applies only to files in the intended directory

Key Holders

When SOPS encrypts a file, it generates a random data key used to encrypt the actual values. This data key is then encrypted separately for each key holder listed in the creation rule and stored in the sops metadata section³. Any key holder possessing the matching private key can decrypt the data key and read the file.

Multiple Holders

By default, listing multiple keys under a single creation rule means any one of them can decrypt the file:

creation_rules:
  - path_regex: secrets\.ya?ml$
    age:
      - age1#… alice key
      - age1#… bob key

Here, either Alice or Bob can decrypt independently. This is useful when you want multiple people to have access without depending on each other.

Key Groups

Sometimes you need multiple people to cooperate to decrypt a file. SOPS supports this through key groups and Shamir’s Secret Sharing, which splits the data key into parts that must be combined:

creation_rules:
  - path_regex: vault\.ya?ml$
    shamir_threshold: 2
    key_groups:
      - age:
          - age1#… alice key
      - age:
          - age1#… bob key
      - age:
          - age1#… charlie key

With shamir_threshold: 2, any two of the three key holders can decrypt the file together. No single person can do it alone. This is useful for high-value secrets where you want to prevent unauthorized access by a lone individual while still allowing recovery if one person leaves.

Identity Types

SOPS supports several types of key holders, which can be mixed in the same configuration:

Age — Simple key management using public-key cryptography
PGP/GnuPG — Traditional OpenPGP keys (organization using PGP already)

You can combine offline keys (Age, PGP) with online keys (cloud KMS) for redundancy. For example, use a cloud KMS for day-to-day automation and an Age key stored offline as a disaster recovery fallback.

Key Rotation

Updating .sops.yaml only affects newly encrypted files. Existing files still carry the old list of key holders in their metadata. To sync existing files with the updated configuration, use the rotate option⁴:

sops --rotate secrets.sops.yaml

Common reasons to rotate:

Onboarding a new team member — after adding their public key to .sops.yaml, rotate existing files so they can decrypt them immediately
Offboarding — remove a departing person’s key from .sops.yaml and rotate to revoke their access
Compromise — if a private key is exposed, replace it in the config and rotate to invalidate the leaked key

Rotation generates a fresh data key, re-encrypts all values, and updates the metadata to match the current .sops.yaml.

Footnotes

SOPS Project
https://getsops.io/docs https://github.com/getsops/sops ↩︎
SOPS File Format Reference
https://getsops.io/docs/reference/↩︎
SOPS File Format Reference
https://getsops.io/docs/reference/↩︎
SOPS Key Management
https://getsops.io/docs/usage/key-management/↩︎

--- title: SOPS — Secrets OPerationS date: 2026/07/15 date-modified: 2026/07/15 categories: - Terminal - Security --- ## Overview **SOPS** (Secrets OPerationS) is a tool for encrypting **secrets** while preserving the structure of configuration files. Unlike traditional encryption tools that produce opaque blobs, SOPS encrypts only the **values** and **comments**, leaving keys in plaintext so the file remains human-readable and editable[^KL2dw]. [^KL2dw]: SOPS Project <https://getsops.io/docs> <https://github.com/getsops/sops> It works with common configuration formats such as **YAML**, **JSON**, **INI**, and **dotenv** files, making it suitable for any workflow where sensitive data lives alongside structural configuration. ### Example Consider a simple configuration file with database credentials: ```{.yaml filename=config.yaml} database: host: db.example.com port: 5432 user: admin password: mysecretpassword ``` Generate an **Age** key pair if you don't have one: ```bash age-keygen -o age.key ``` Create a `.sops.yaml` configuration file including the public key. By default, SOPS encrypts all leaf values. To encrypt only specific fields, use **regex matching** in `.sops.yaml`: ```{.yaml filename=".sops.yaml"} creation_rules: - age: - age1q8... # your public key encrypted_regex: "^password$" ``` This pattern matches only the key named exactly `password`, leaving `host`, `port`, and `user` unencrypted. Then encrypt the file: ```bash sops --encrypt config.yaml > config.enc.yaml ``` After encryption, the structure remains intact with only the **password** encrypted: ```{.yaml filename="config.enc.yaml"} database: host: db.example.com port: 5432 user: admin password: ENC[AES256_GCM,data:.../...,type:str] sops: age: #… encrypted_regex: ^password$ lastmodified: "2026-07-15T13:05:50Z" #… ``` **Keys** (in this example `password`) stay visible, making it clear what each encrypted value represents without exposing the actual secret. The `sops` metadata section at the bottom stores the encrypted data key and integrity information[^F7t2m]. [^F7t2m]: SOPS File Format Reference <https://getsops.io/docs/reference/> ### Use Cases SOPS is useful whenever you need to store encrypted secrets in version control or share them across systems: * **Infrastructure as Code** — encrypt database credentials, API tokens, or certificates embedded in Terraform, Ansible, or Kubernetes manifests * **Configuration Management** — protect secrets in application config files without losing the ability to review or diff changes * **Team Collaboration** — grant decryption access to specific team members using **Age**, **PGP**, or cloud **KMS** keys * **Disaster Recovery** — keep encrypted backups of critical configurations that can be decrypted offline ## Configuration A `.sops.yaml` file can define **multiple creation rules** matched by file path, each with its own key holders and encryption scope. Here is an example for a project with different teams and sensitivity levels: ```yaml creation_rules: # Production database credentials — admin and dba keys only. - path_regex: prod/database/.*\.sops\.ya?ml$ encrypted_regex: ^password$ age: - age1admin...key1 - age1dba...key2 # Staging secrets — developer and staging service account. - path_regex: staging/.*\.sops\.ya?ml$ age: - age1dev...key3 - age1staging...key4 # Fallback — admin key for any other encrypted file. - path_regex: \.sops\.ya?ml$ age: age1admin...key1 ``` Key patterns used here: * **First match wins** — rules are evaluated top to bottom, so specific paths take precedence over the catch-all fallback * **Separate key holders per scope** — the **admin** key decrypts everything, while team-specific keys are limited to their own directories, limiting damage if a key is compromised * **Selective encryption** — `encrypted_regex: ^password$` encrypts only the password field, leaving hostnames and ports visible for quick review * **Path-based scoping** — `path_regex` ensures each rule applies only to files in the intended directory ## Key Holders When SOPS encrypts a file, it generates a random **data key** used to encrypt the actual values. This data key is then encrypted separately for each **key holder** listed in the creation rule and stored in the `sops` metadata section[^F7t2m]. Any key holder possessing the matching private key can decrypt the data key and read the file. ### Multiple Holders By default, listing multiple keys under a single creation rule means **any one** of them can decrypt the file: ```yaml creation_rules: - path_regex: secrets\.ya?ml$ age: - age1#… alice key - age1#… bob key ``` Here, either Alice or Bob can decrypt independently. This is useful when you want multiple people to have access without depending on each other. ### Key Groups Sometimes you need **multiple** people to cooperate to decrypt a file. SOPS supports this through **key groups** and **Shamir's Secret Sharing**, which splits the data key into parts that must be combined: ```yaml creation_rules: - path_regex: vault\.ya?ml$ shamir_threshold: 2 key_groups: - age: - age1#… alice key - age: - age1#… bob key - age: - age1#… charlie key ``` With `shamir_threshold: 2`, any **two** of the three key holders can decrypt the file together. No single person can do it alone. This is useful for high-value secrets where you want to prevent unauthorized access by a lone individual while still allowing recovery if one person leaves. ### Identity Types SOPS supports several types of key holders, which can be mixed in the same configuration: * **Age** — Simple key management using public-key cryptography * **PGP/GnuPG** — Traditional OpenPGP keys (organization using PGP already) You can combine offline keys (Age, PGP) with online keys (cloud KMS) for redundancy. For example, use a cloud KMS for day-to-day automation and an Age key stored offline as a disaster recovery fallback. ### Key Rotation Updating `.sops.yaml` only affects **newly** encrypted files. Existing files still carry the old list of key holders in their metadata. To sync existing files with the updated configuration, use the rotate option[^w9k3p]: [^w9k3p]: SOPS Key Management <https://getsops.io/docs/usage/key-management/> ```bash sops --rotate secrets.sops.yaml ``` Common reasons to rotate: * **Onboarding a new team member** — after adding their public key to `.sops.yaml`, rotate existing files so they can decrypt them immediately * **Offboarding** — remove a departing person's key from `.sops.yaml` and rotate to revoke their access * **Compromise** — if a private key is exposed, replace it in the config and rotate to invalidate the leaked key Rotation generates a fresh data key, re-encrypts all values, and updates the metadata to match the current `.sops.yaml`.