AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: sops-age-gitops-secret-encryption

SOPS & Age Declarative Secret Encryption for GitOps Pipelines

Production secret management standard for GitOps and Kubernetes repositories. Mandates Mozilla SOPS with modern Age key cryptography to encrypt sensitive YAML values while preserving unencrypted keys for transparent git diffs, strictly prohibiting raw base64 Secret commits.

Prohibited Anti-Pattern: AI commits base64-encoded Kubernetes Secret manifests to git repositories, assuming base64 is encryption and leaking production credentials.

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: SOPS & Age Declarative Secret Encryption for GitOps Pipelines - Production secret management standard for GitOps and Kubernetes repositories. Mandates Mozilla SOPS with modern Age key cryptography to encrypt sensitive YAML values while preserving unencrypted keys for transparent git diffs, strictly prohibiting raw base64 Secret commits.
globs: **/*secret*.enc.yaml, **/*secret*.sops.yaml, **/.sops.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/sops-age-gitops-secret-encryption"
---

# SOPS & Age Declarative Secret Encryption for GitOps Pipelines

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: AI commits base64-encoded Kubernetes Secret manifests to git repositories, assuming base64 is encryption and leaking production credentials.

## System Constraints
You are a DevSecOps and GitOps Security Specialist. NEVER commit unencrypted Kubernetes Secrets or plain API keys into Git version control. Base64 is NOT encryption. Always use Mozilla SOPS with age or cloud KMS keys with an explicit .sops.yaml directory configuration.

## Strict Guidelines
- Maintain a top-level .sops.yaml configuration matching encrypted file patterns and designating specific age/KMS recipient keys.
- Encrypt values only, leaving YAML dictionary keys in plaintext (sops default) to facilitate transparent pull request code reviews and git diffs.
- Integrate SOPS secret decryption into ArgoCD or Flux GitOps controllers using native decryption plugins or Kustomize SOPS generators.
- Store the age master private key securely in a cluster secret or external vault (AWS Secrets Manager / Vault); never commit keys to git.
- Use pre-commit hooks (git-secrets / detect-secrets) to block unencrypted Secret resources prior to git commit.

## Bad vs Good Implementations
### SOPS .sops.yaml Rules and Encrypted GitOps Secret Manifest

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Kubernetes Secret base64 encoding is an encoding scheme, not encryption. Committing this file to git exposes production database credentials to anyone with read access to the repo or git history.
```yaml
# FATAL: Plaintext/Base64 Kubernetes Secret in Git repo
apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
type: Opaque
data:
  # Base64 is completely trivial to decode: echo "..." | base64 -d
  password: c3VwZXJfc2VjcmV0X3Bhc3N3b3JkXzEyMw==
```

#### Production Standard (Correct)
> **Standard**: Encrypts sensitive stringData using SOPS with age cryptography. Keys and metadata remain readable for clean Git diffs, but payloads can only be decrypted by the GitOps cluster holding the private age key.
```yaml
# .sops.yaml
creation_rules:
  - path_regex: .*/secrets/.*\.sops\.yaml$
    encrypted_regex: '^(data|stringData)$'
    age: 'age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p'

---
# secrets/db-credentials.sops.yaml (Safe to commit into Git)
apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
type: Opaque
stringData:
  # Value is securely encrypted with Age public key
  password: ENC[AES256_GCM,data:4gY3iJ6e7PjH,iv:jP9K...,tag:9a1B...,type:str]
sops:
  kms: []
  age:
    - recipient: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
      enc: | ...
  version: 3.9.0
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

SOPS & Git Secret Linter MCP
Verifies that all committed secrets match .sops.yaml encryption rules.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

askills: SOPS & Age GitOps Hardener
Automates SOPS .sops.yaml creation and configures Flux/ArgoCD decryption pipelines.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: SOPS & Age Declarative Secret Encryption for GitOps Pipelines

SOPS & Age Declarative Secret Encryption for GitOps Pipelines defines an industrial-grade behavioral standard for devops engineering. Production secret management standard for GitOps and Kubernetes repositories. Mandates Mozilla SOPS with modern Age key cryptography to encrypt sensitive YAML values while preserving unencrypted keys for transparent git diffs, strictly prohibiting raw base64 Secret commits. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI commits base64-encoded Kubernetes Secret manifests to git repositories, assuming base64 is encryption and leaking production credentials. Without an explicit system instruction file, developers spend hours debugging silent failures.
Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftAI commits base64-encoded Kubernetes Secret manifests to git repositories, assuming base64 is encryption and leaking production credentials.Critical
Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production.
Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture InconsistencyAI assistants produce mixed paradigms across files, creating fragmented codebase conventions.Medium
Increases cognitive load during code reviews and leads to maintenance debt across engineering teams.
Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.
Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Maintain a top-level .sops.yaml configuration matching encrypted file patterns and designating specific age/KMS recipient keys.

Maintain a top-level .sops.yaml configuration matching encrypted file patterns and designating specific age/KMS recipient keys.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Encrypt values only, leaving YAML dictionary keys in plaintext (sops default) to facilitate transparent pull request code reviews and git diffs.

Encrypt values only, leaving YAML dictionary keys in plaintext (sops default) to facilitate transparent pull request code reviews and git diffs.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Integrate SOPS secret decryption into ArgoCD or Flux GitOps controllers using native decryption plugins or Kustomize SOPS generators.

Integrate SOPS secret decryption into ArgoCD or Flux GitOps controllers using native decryption plugins or Kustomize SOPS generators.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Store the age master private key securely in a cluster secret or external vault (AWS Secrets Manager / Vault)

Store the age master private key securely in a cluster secret or external vault (AWS Secrets Manager / Vault); never commit keys to git.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Use pre-commit hooks (git-secrets / detect-secrets) to block unencrypted Secret resources prior to git commit.

Use pre-commit hooks (git-secrets / detect-secrets) to block unencrypted Secret resources prior to git commit.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is SOPS & Age Declarative Secret Encryption for GitOps Pipelines critical for AI coding assistants?

Production secret management standard for GitOps and Kubernetes repositories. Mandates Mozilla SOPS with modern Age key cryptography to encrypt sensitive YAML values while preserving unencrypted keys for transparent git diffs, strictly prohibiting raw base64 Secret commits. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI commits base64-encoded Kubernetes Secret manifests to git repositories, assuming base64 is encryption and leaking production credentials.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →
devops
86

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

devops
118

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

devops
40

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

SOPS