En corto

1
2
3
4
5

gpg --list-secret-keys --keyid-format=long   # obtén la fingerprint
# .sops.yaml → creation_rules: pgp: <FINGERPRINT>
sops -e -i secrets.yaml                        # cifra in-place
sops secrets.yaml                              # edita descifrado, re-cifra al guardar
sops -d secrets.yaml                           # descifra a stdout

SOPS cifra los valores de un archivo estructurado (YAML/JSON/env/ini) y deja las llaves legibles, así que un secrets.enc.yaml da un diff de git limpio y revisable. Para descifrar necesitas la llave privada de GPG en la máquina.

Requisitos

gpg y sops instalados. Verifica: gpg --version y sops --version.

1. Consigue una llave GPG

Usa una existente o crea una:

1
2

gpg --full-generate-key
gpg --list-secret-keys --keyid-format=long

Copia la fingerprint de 40 caracteres (la línea larga en hex bajo sec). Esa fingerprint es la que referencia SOPS — no el key id corto.

2. Dile a SOPS qué llave usar

Pon un .sops.yaml en la raíz del repo para no pasar llaves a mano:

1
2
3

creation_rules:
  - path_regex: \.enc\.ya?ml$
    pgp: "FBC7B9E2A4F9289AC0C1D4843C1FCF3D"
  • path_regex acota la regla a los archivos que nombres *.enc.yaml.
  • pgp acepta una o varias fingerprints separadas por coma (varios destinatarios = cualquiera con una de esas llaves privadas puede descifrar).

3. Cifra, edita, descifra

1
2
3

sops -e -i secrets.enc.yaml     # cifra in-place (-i), solo valores
sops secrets.enc.yaml           # abre $EDITOR descifrado; re-cifra al guardar
sops -d secrets.enc.yaml        # descifra a stdout

Commitea el archivo cifrado. El texto plano nunca toca git.

Qué toca SOPS

Parte¿Cifrada?
Valores (password: hunter2)sí
Llaves / estructura (password:)no (diffs legibles)
Bloque extra sops:se agrega (destinatarios, MAC)

Trampas

  • Subkeys: para forzar una subkey concreta de GnuPG, agrega ! al final de la fingerprint en creation_rules (ej. A3D6...E8F!). Solo se respeta desde SOPS 3.9.3.
  • Otro binario de gpg: define SOPS_GPG_EXEC para apuntar SOPS a un wrapper en vez del gpg por defecto.
  • Respalda la llave privada. Si la pierdes, los archivos cifrados se van con ella — SOPS es tan recuperable como la llave GPG. Agrega un segundo destinatario (llave de respaldo/escrow) en creation_rules desde el día uno.
  • Rotar destinatarios: tras editar creation_rules, corre sops updatekeys secrets.enc.yaml para re-cifrar la file key con el nuevo conjunto.
  • Solo los archivos estructurados reciben cifrado a nivel de valor; para un blob usa sops -e --input-type binary.

Git y automatización

  • Lo que vive en git es el archivo cifrado; quien revisa ve nombres de llaves, nunca valores.
  • En cualquier host/CI que deba descifrar, importa primero la llave privada al keyring de GPG (gpg --import) y luego sops -d.
  • Ansible puede consumir SOPS directo con la colección community.sops (ej. el lookup community.sops.sops / load_vars), así los playbooks leen secretos sin un descifrado manual. Verifica que la colección esté instalada en el nodo de control.

Ver también