SOPS (Secrets OPerationS)

sops는 YAML, JSON, dotenv, binary 파일을 부분 단위로 암호화하면서 Git 친화적인 형태를 유지하는 secret 관리 도구다.

• sops는 파일 전체를 opaque blob으로 바꾸지 않고 구조를 유지한 채 암호화한다.
• 이 저장소 맥락에서는 age recipient 기반 구성이 가장 단순하다.
• 새 파일 암호화에는 recipient/KMS 지정이 필요하지만, 기존 sops 파일 편집과 복호화는 파일 내부 메타데이터를 사용한다.

sops encrypt --age age1example... secret.yaml
sops decrypt secret.enc.yaml
sops edit secret.enc.yaml
sops updatekeys -y secret.enc.yaml

• sops encrypt [options] FILE
• sops decrypt [options] FILE
• sops edit [options] FILE
• sops updatekeys [options] FILE

• –age, -a: 새 문서를 암호화할 age recipient 목록. SOPS_AGE_RECIPIENTS로도 지정 가능.
• –pgp, -p: PGP fingerprint 기반 암호화.
• –kms, -k: AWS KMS ARN 목록.
• –in-place, -i: stdout 대신 원본 파일에 다시 기록.
• –input-type, –output-type: 확장자로 타입을 판별하기 어렵거나 stdin을 쓸 때 형식을 고정.
• –unencrypted-regex: 정규식에 맞는 key만 평문으로 남긴다.
• –encrypted-regex: 정규식에 맞는 key만 암호화한다.
• –mac-only-encrypted: MAC 계산 범위를 실제로 암호화되는 값으로 제한한다.
• –ignore-mac: 복호화 시 Message Authentication Code 검증 실패를 무시한다. 복구/조사 목적이 아니면 평소에는 권장되지 않는다.
• –extract: decrypt 시 특정 키/브랜치만 추출.
• –filename-override: stdin 사용 시 설정 로딩과 파일 타입 판별용 파일명을 강제로 지정.
• –decryption-order: 복호화 시도 순서를 제어.

# age 공개키 recipient로 새 YAML 암호화
sops encrypt --age age1exampleexampleexampleexampleexampleexample secret.yaml > secret.enc.yaml
 
# 복호화해서 stdout으로 확인
sops decrypt secret.enc.yaml
 
# 원본 파일을 직접 편집
sops edit secret.enc.yaml
 
# 특정 값만 추출
sops decrypt --extract '["database"]["password"]' secret.enc.yaml
 
# .env 파일을 제자리 암호화
sops --encrypt --in-place secrets.env
 
# 특정 key만 암호화하고 나머지는 평문 유지
sops encrypt --encrypted-regex '^(data|stringData)$' secret.yaml > secret.enc.yaml
 
# MAC 오류를 무시하고 강제로 확인
sops decrypt --ignore-mac secret.enc.yaml
 
# .sops.yaml 정책 변경 후 key metadata 재정렬
sops updatekeys -y secret.enc.yaml

creation_rules:
  - path_regex: \.prod\.yaml$
    age: age1exampleexampleexampleexampleexampleexample
  - path_regex: \.env$
    age: >-
      age1exampleexampleexampleexampleexampleexample,
      age1secondrecipientexampleexampleexampleexample

• 기본 설정 파일은 .sops.yaml이다.
• creation_rules는 새 문서를 암호화할 때 어떤 key provider를 붙일지 결정한다.
• encrypted_regex와 unencrypted_regex는 어떤 key를 암호화 대상으로 볼지 정교하게 제한할 때 쓴다.
• team 단위 운영에서는 recipient를 파일마다 직접 넣기보다 .sops.yaml으로 중앙 관리하는 편이 안전하다.

creation_rules:
  - path_regex: secrets/.*\.yaml$
    age: age1exampleexampleexampleexampleexampleexample
    encrypted_regex: '^(data|stringData)$'

• SOPS_AGE_RECIPIENTS: 새 문서 암호화 시 기본 age recipient 목록.
• SOPS_PGP_FP: 기본 PGP fingerprint 목록.
• SOPS_KMS_ARN: 기본 AWS KMS ARN 목록.
• SOPS_GCP_KMS_IDS: 기본 GCP KMS resource ID 목록.
• SOPS_AZURE_KEYVAULT_URLS: 기본 Azure Key Vault key URL 목록.
• SOPS_VAULT_URIS: 기본 HashiCorp Vault Transit key URI 목록.
• SOPS_CONFIG: 사용할 .sops.yaml 경로를 명시적으로 고정.
• SOPS_DECRYPTION_ORDER: 복호화 시도 순서 지정. 예: age,pgp,kms.
• SOPS_ENABLE_LOCAL_KEYSERVICE: 로컬 keyservice 사용 여부 제어.
• SOPS_KEYSERVICE: 추가 keyservice endpoint 지정.
• SOPS_GPG_EXEC: 기본 gpg 대신 다른 실행 파일 경로 지정.
• SOPS_EDITOR: sops edit에서 사용할 editor 지정.
• SOPS_DISABLE_VERSION_CHECK: 버전 확인 비활성화.

export SOPS_AGE_RECIPIENTS="age1exampleexampleexampleexampleexampleexample"
export SOPS_CONFIG="$PWD/.sops.yaml"
export SOPS_DECRYPTION_ORDER="age,pgp"
export SOPS_EDITOR="nvim"

• failed to get the data key: 로컬에 복호화 가능한 age identity 또는 KMS/GPG credential이 없는 경우가 많다.
• MAC 검증 오류가 나면 먼저 파일이 수동 편집으로 깨졌는지, recipient/key rotation 이후 metadata가 불일치하는지 본다.
• stdin 기반 암호화가 설정 파일을 못 찾으면 –filename-override를 함께 쓴다.
• editor 실행 문제가 있으면 SOPS_EDITOR 또는 EDITOR 값을 확인한다.
• updatekeys가 기대와 다르게 동작하면 .sops.yaml의 path_regex와 recipient 목록을 다시 본다.

• 로컬 확인 버전: sops 3.13.0
• 지원 형식: JSON, YAML, dotenv, binary
• 지원 key provider: age, PGP, AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault Transit, HuaweiCloud KMS

• sops encrypt는 새 파일 생성 시 key provider를 명시하거나 .sops.yaml 규칙에 의존한다.
• sops decrypt는 결과를 stdout으로 내보내는 기본 동작이 안전한 편이다.
• sops edit는 평문 임시파일을 거치므로 작업 디렉터리, editor swap 파일 정책을 같이 고려해야 한다.
• sops groups와 sops updatekeys는 팀 recipient 변경 시 유용하다.

sops --help

NAME:
   sops - sops - encrypted file editor with AWS KMS, GCP KMS, HuaweiCloud KMS, Azure Key Vault, age, and GPG support
 
USAGE:
   sops is an editor of encrypted files that supports AWS KMS, GCP KMS, AZKV,
  PGP, and Age
 
VERSION:
   3.13.0
 
COMMANDS:
   completion  Generate shell completion scripts
   exec-env    execute a command with decrypted values inserted into the environment
   exec-file   execute a command with the decrypted contents as a temporary file
   publish     Publish sops file or directory to a configured destination
   keyservice  start a SOPS key service server
   filestatus  check the status of the file, returning encryption status
   groups      modify the groups on a SOPS file
   updatekeys  update the keys of SOPS files using the config file
   decrypt     decrypt a file, and output the results to stdout. If no filename is provided, stdin will be used.
   encrypt     encrypt a file, and output the results to stdout. If no filename is provided, stdin will be used.
   rotate      generate a new data encryption key and reencrypt all values with the new key
   edit        edit an encrypted file
   set         set a specific key or branch in the input document.
   unset       unset a specific key or branch in the input document.

sops encrypt --help

NAME:
   sops encrypt - encrypt a file, and output the results to stdout. If no filename is provided, stdin will be used.
 
USAGE:
   sops encrypt [command options] [file]
 
OPTIONS:
   --in-place, -i
   --output value
   --kms value, -k value
   --gcp-kms value
   --hckms value
   --azure-kv value
   --hc-vault-transit value
   --pgp value, -p value
   --age value, -a value
   --input-type value
   --output-type value
   --unencrypted-suffix value
   --encrypted-suffix value
   --unencrypted-regex value
   --encrypted-regex value
   --mac-only-encrypted
   --encryption-context value
   --shamir-secret-sharing-threshold value
   --filename-override value

sops decrypt --help

NAME:
   sops decrypt - decrypt a file, and output the results to stdout. If no filename is provided, stdin will be used.
 
USAGE:
   sops decrypt [command options] [file]
 
OPTIONS:
   --in-place, -i
   --extract value
   --output value
   --input-type value
   --output-type value
   --ignore-mac
   --filename-override value
   --decryption-order value

• age
• openssl
• git

• codex:: 2026-06-17 Created SOPS reference page with age-centric workflow, config example, and help sections.
• codex:: 2026-06-17 Added regex selection, MAC validation notes, and major SOPS environment variables.