Infrastructure-as-Code with Polycrate: Never Configure SOPS Again

Anyone seriously running Infrastructure-as-Code knows the problem: the workspace in the Git repository contains kubeconfigs, SSH keys, passwords, and API tokens – files that must never end up unencrypted in a remote repository. The cloud-native ecosystem’s usual answer: another tool.

SOPS, git-crypt, sealed-secrets, Vault Agent – each tool solves the problem while simultaneously adding new ones. More configuration files, more key backends, more mental overhead, more things that can break. Polycrate does it differently.

The Tool-Sprawl Problem in Cloud-Native IaC Workflows

A typical IaC workflow in 2024 looks roughly like this:

Workspace management:     polycrate / Terraform / Pulumi
Secrets management:       SOPS + AWS KMS / GCP KMS / Azure Key Vault
Git operations:           git (external, own configuration)
SSH key management:       ssh-agent / ssh-add (manual)
Kube context:             kubectl config use-context (manual)
CI/CD:                    GitHub Actions + custom decrypt steps

Each of these tools has its own configuration syntax, its own error messages, and its own upgrade cycle. For a new team member, onboarding in practice means days of documentation reading until the first kubectl apply works.

Concrete example with SOPS:

# .sops.yaml – extra configuration file everyone needs
creation_rules:
  - path_regex: secrets\.poly$
    kms: arn:aws:kms:eu-central-1:123456789:key/abc-def
    age: age1uz9wjtwnk7wx...
  - path_regex: artifacts/secrets/.*
    kms: arn:aws:kms:eu-central-1:123456789:key/abc-def

Then the actual encryption:

# SOPS workflow
sops --encrypt --in-place secrets.yaml
sops --decrypt secrets.yaml > secrets-decrypted.yaml
# Don't forget: git add, git commit, git push
# And: configure AWS credentials, set KMS access rights...

The Polycrate Approach: Everything Integrated, Nothing to Configure

Polycrate integrates encryption and Git synchronization directly into the workspace lifecycle. No external configuration file, no separate key backend setup, no additional CLI tools required.

The entire secure IaC workflow consists of two commands:

# Encrypt secrets and secure workspace
polycrate workspace encrypt

# Sync workspace (commit + pull + push)
polycrate workspace sync

That’s it.

polycrate workspace encrypt – Security with One Command

The encrypt command encrypts all sensitive files in the workspace with age – a modern, audited encryption standard developed by the same authors as Go itself.

What Gets Encrypted

Polycrate understands the structure of a workspace and automatically knows which files are sensitive:

workspace/
├── secrets.poly              ← will be encrypted
├── workspace.poly            ← stays in plain text (public)
└── artifacts/
    └── secrets/
        ├── kubeconfig.yml    ← will be encrypted
        ├── id_rsa            ← will be encrypted
        └── myblock/
            └── api-token.txt ← will be encrypted

After encryption:

workspace/
├── secrets.poly.age          ← encrypted, safe for Git ✅
├── workspace.poly            ← unchanged ✅
└── artifacts/
    └── secrets/
        ├── kubeconfig.yml.age ← encrypted ✅
        ├── id_rsa.age         ← encrypted ✅
        └── myblock/
            └── api-token.txt.age ← encrypted ✅

The original files are deleted. Only .age files land in the repository.

Key Management Without Manual Configuration

The most important difference from SOPS: no key backend to configure. Polycrate resolves the encryption key automatically – in this priority order:

1. Polycrate API (highest priority) – key is fetched automatically from the workspace
2. Environment variable WORKSPACE_ENCRYPTION_KEY – fallback for CI/CD
3. Interactive prompt – last fallback for manual workflows

In practice with the Polycrate API, that means: just call polycrate workspace encrypt, everything else happens automatically.

$ polycrate workspace encrypt

Found 2 files to encrypt
Encrypted: secrets.poly -> secrets.poly.age
Encrypted: artifacts/secrets/kubeconfig.yml -> artifacts/secrets/kubeconfig.yml.age
Workspace encryption completed successfully

The Pre-Commit Hook: Safety Net Without Discipline

Polycrate automatically installs a pre-commit hook in the Git repository on the first encrypt. This hook prevents unencrypted secrets from being accidentally committed – even if someone forgets to run encrypt first:

# Someone tries to commit secrets.poly unencrypted:
git add secrets.poly
git commit -m "Update secrets"

# The hook fires:
# 🔒 Running Polycrate security checks...
#
# ❌ FATAL: Cannot commit - UNENCRYPTED secrets detected:
#    - secrets.poly
#
# Fix:
#   1. Encrypt: polycrate workspace encrypt
#   2. Commit the .age files

No discipline required. The workspace protects itself.

polycrate workspace decrypt – Restoring Secrets

The reverse process: .age files are decrypted, original files are restored. Again: key resolution is automatic, no setup required.

$ polycrate workspace decrypt

Found 2 encrypted files to decrypt
Decrypted: secrets.poly.age -> secrets.poly
Decrypted: artifacts/secrets/kubeconfig.yml.age -> artifacts/secrets/kubeconfig.yml
Workspace decryption completed successfully

A new team member clones the repository, runs polycrate workspace decrypt – and the workspace is fully operational. No key backend setup, no AWS profiles, no manual key distribution over insecure channels.

polycrate workspace sync – Git Without Git Knowledge

Git is powerful, but for platform engineers managing infrastructure daily, it’s often a source of errors. Forgotten git add, wrong branch names, un-pulled remote changes before a push – all of these lead to avoidable problems.

polycrate workspace sync encapsulates the complete Git workflow in a single command:

1. Uncommitted changes? → Auto-commit with generated message
2. Fetch from remote → check remote state
3. Merge conflicts? → warning with list of affected files
4. Pull remote changes → update local state
5. Push to remote → upload changed state

In practice:

$ polycrate workspace sync

Uncommitted changes detected, committing...
Committed: 485f52d

Fetching from origin...
Fetch complete

Pulling from remote...
Already up to date

Pushing to remote...
Pushed to origin/main

Sync completed successfully

The built-in Git engine is based on go-git and works without an external Git installation. SSH keys are automatically loaded from the workspace – no ssh-add, no ~/.ssh/config entries needed.

For potential merge conflicts, Polycrate warns proactively before the pull and asks for confirmation – unlike standard Git, which only makes conflicts visible after the merge:

Warning: Potential merge conflicts detected!
The following files were modified both locally and on remote:
  • workspace.poly

Continue with pull? This may result in merge conflicts [y/N]:

The Complete Secure IaC Workflow

What does the daily workflow with Polycrate look like?

Morning: Starting the Workspace

cd /workspace/my-infra
polycrate workspace decrypt    # Decrypt secrets from Git
polycrate workspace sync       # Get the latest state

Making Changes

# Adjust Kubernetes manifests, run actions...
polycrate run app deploy

# Add a new secret
echo "new-api-token" > artifacts/secrets/myapp/api-token.txt

End of Day: Securing

polycrate workspace encrypt    # Encrypt all secrets
polycrate workspace sync       # Commit and push

The pre-commit hook ensures no unencrypted secret lands in Git – even if someone calls sync directly without a prior encrypt.

polycrate workspace status – Overview Anytime

The status command shows the complete security and Git state of the workspace:

$ polycrate workspace status

Workspace Encryption Status
============================

Workspace: https://app.polycrate.example.com/ui/workspaces/339cdbb9.../
UUID: 339cdbb9-3829-48f1-9ecf-7bae7f85d2de

🔑 Key Status: ✅ Key available
   Key ID: age1uz9wjtwnk7wx...
   Source: Polycrate API (priority 1)

📁 File Status:
   Encrypted files:
   ✅ secrets.poly.age
   ✅ artifacts/secrets/kubeconfig.yml.age

🔒 Security Status:
   .gitignore: ✅ Properly configured
   Git repo: ✅ Detected
   Branch: main
   Commit: ce4bd771
   Remote: ✅ In sync
   Changes: ✅ Clean working tree

💡 Recommendations:
   - Workspace is properly encrypted and ready to commit

age: The Right Foundation

The choice of age as the encryption algorithm is no coincidence. age was developed by Filippo Valsorda (Go security team, formerly Google) and is:

• Simple: No key ring, no complex configuration
• Modern: X25519, ChaCha20-Poly1305 – no legacy algorithms
• Audited: External security audits completed
• Standard-compatible: All files encrypted by Polycrate can be decrypted with the standard age CLI

The last point is especially important: no vendor lock-in. If Polycrate is unavailable in an emergency, secrets can always be decrypted with the standard tool:

# Emergency decryption without Polycrate
echo "$WORKSPACE_ENCRYPTION_KEY" | age --decrypt -i - secrets.poly.age > secrets.poly

Team Workflow: Key Management via Polycrate API

For teams, the Polycrate API is the recommended solution for central key management. The encryption key is stored as a workspace credential in the API and automatically issued to authorized team members.

# ~/.polycrate/polycrate.yml
api:
  enabled: true
  url: https://api.polycrate.example.com
  api_key: your-api-key

This completely eliminates the question “where is the encryption key?” New team members configure the API once, after which encrypt and decrypt work without any further steps.

Comparison: Polycrate vs. SOPS

Conclusion

The cloud-native ecosystem has a tool-sprawl problem. For every aspect of an infrastructure workflow there’s a specialized tool – and each of these tools wants to be configured, maintained, and understood.

Polycrate takes a different approach: encryption, Git integration, key management, and workflow automation are core features of the tool, not a separate plugin ecosystem. The result is an IaC workflow that is secure without being complex.

# The complete secure IaC workflow:
polycrate workspace decrypt    # Load secrets
polycrate run my-block deploy  # Deploy infrastructure
polycrate workspace encrypt    # Secure secrets
polycrate workspace sync       # Commit and push state

Four commands. One tool. No SOPS configuration.

→ Install Polycrate → Workspace Encryption Documentation → Git Integration Documentation

Polycrate is ayedo’s Infrastructure-as-Code tool for declarative multi-cluster management. Learn more →