SOPS Encryption - Ankra Platform

SOPS (Secrets OPerationS) encryption allows you to securely store sensitive values like passwords, API keys, and credentials in your GitOps repository. Encrypted values are automatically decrypted during deployment.

What is SOPS?

SOPS is an editor for encrypted files that supports YAML, JSON, ENV, INI and BINARY formats. Ankra uses SOPS with AGE encryption to protect sensitive values in your Stack configurations.

How It Works

In the Stack Builder: You enter secrets in plaintext
On Save: Ankra encrypts marked fields with your organisation’s AGE public key
In Git: Encrypted values appear as ENC[AES256_GCM,...] - safe to commit
On Deploy: ArgoCD’s helm-secrets plugin decrypts values using the private key

Getting Started

Setting up SOPS encryption is a single step. Once initialized, encryption is enabled by default and cluster decryption is handled automatically.

Navigate to Encryption Settings

Go to Organisation Settings → Encryption.

Initialize Encryption

Click Initialize Encryption. This generates an AGE key pair:

Public key: Used to encrypt values (visible to you)
Private key: Used to decrypt values (stored securely in Ankra’s vault)

That’s it. After initialization:

Encryption is enabled by default - fields you mark as encrypted will be protected immediately.
Cluster decryption is automatic - any cluster with ArgoCD installed receives the decryption key automatically. There is nothing to configure per-cluster.

The AGE public key is displayed on the Encryption settings page. You can copy it for use with external SOPS tools if needed. The public key looks like: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

Encrypting Values in Stacks

Using the Stack Builder

When editing a manifest or add-on values in the Stack Builder:

Look for the Encrypted Keys (SOPS) section
Add key names that should be encrypted (e.g., password, apiKey, token)
Enter the plaintext value as normal
On save, Ankra encrypts those specific keys

Only the specified keys are encrypted. Other values remain in plaintext for easy review and debugging.

Common Keys to Encrypt

Key Name	Use Case
`password`	Database passwords, admin credentials
`apiKey`	Third-party API keys
`token`	Authentication tokens, tunnel tokens
`secretKey`	Encryption keys, signing keys
`connectionString`	Database connection strings with credentials
`privateKey`	SSH keys, TLS private keys

Example: Encrypting a Database Password

Before encryption (what you see in the editor):

apiVersion: v1
kind: Secret
metadata:
  name: postgres-credentials
  namespace: database
type: Opaque
stringData:
  username: app_user
  password: super-secret-password

After encryption (what’s stored in Git):

apiVersion: v1
kind: Secret
metadata:
  name: postgres-credentials
  namespace: database
type: Opaque
stringData:
  username: app_user
  password: ENC[AES256_GCM,data:vxvYs7vKw+bPqNWO3tE=,iv:...,tag:...,type:str]
sops:
  age:
    - recipient: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
      enc: |
        -----BEGIN AGE ENCRYPTED FILE-----
        YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBxVEdI...
        -----END AGE ENCRYPTED FILE-----
  encrypted_regex: ^(password)$
  version: 3.9.4

Example: Encrypting a Registry Pull Secret (`.dockerconfigjson`)

A kubernetes.io/dockerconfigjson Secret stores its payload under a key whose name literally begins with a dot: .dockerconfigjson. Add that key, leading dot included, to the Encrypted Keys (SOPS) list (or pass --key .dockerconfigjson to the CLI). The leading dot marks it as a literal key name rather than a nested dotted path, so it is matched and encrypted as-is.

apiVersion: v1
kind: Secret
metadata:
  name: registry-auth
  namespace: platform
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: ENC[AES256_GCM,data:vxvYs7vKw+bPqNWO3tE=,iv:...,tag:...,type:str]
sops:
  age:
    - recipient: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
      enc: |
        -----BEGIN AGE ENCRYPTED FILE-----
        YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBxVEdI...
        -----END AGE ENCRYPTED FILE-----
  encrypted_regex: ^(\.dockerconfigjson)$
  version: 3.9.4

Encrypting Helm Values

For add-ons (Helm charts), you can encrypt specific values:

Open the add-on in the Stack Builder
In the values editor, find the Encrypted Keys (SOPS) section
Add paths to sensitive values

Helm Values Path Examples

Path	Description
`adminPassword`	Top-level key
`auth.password`	Nested key (uses dot notation)
`credentials.apiKey`	Deeply nested key

Example: Encrypting Grafana admin password

# Values for grafana chart
adminUser: admin
adminPassword: my-grafana-password  # ← This gets encrypted
persistence:
  enabled: true

Add adminPassword to the encrypted keys list.

Using the CLI

You can also encrypt and decrypt values using the Ankra CLI for local GitOps workflows.

Encrypting Manifest Values

# Encrypt a key in a manifest
ankra cluster encrypt manifest trinity-database-secret --key TRINITY_DB_PASSWORD -f cluster.yaml

This will:

Find the manifest in the cluster YAML
Read the referenced manifest file
Encrypt the specified key using your organisation’s SOPS key
Update the manifest file with encrypted values
Add the key to encrypted_paths in the cluster YAML

Encrypting Addon Values

# Encrypt a key in addon configuration
ankra cluster encrypt addon --name grafana --key adminPassword -f cluster.yaml

Decrypting for Inspection

To view the decrypted contents of a manifest file:

# View decrypted manifest content
ankra cluster decrypt manifest trinity-database-secret -f cluster.yaml

The decrypt command prints to stdout, so you can pipe it to other tools or redirect to a file if needed.

Adding Keys to Existing Encrypted Files

You can add new encrypted keys to files that are already SOPS-encrypted:

# File already has 'password' encrypted, now add 'api_token'
ankra cluster encrypt manifest my-secret --key api_token -f cluster.yaml

The CLI will automatically decrypt the file, merge the encrypted paths, and re-encrypt with all keys protected.

This only works if the file was encrypted with your organisation’s SOPS key. If the file was encrypted by a different organisation, you’ll see an error message and need to decrypt it first using the original key.

For more CLI commands, see the Ankra CLI documentation.

How Decryption Works

When SOPS is initialized for your organisation, Ankra automatically configures decryption on clusters that have ArgoCD:

Deploys the AGE private key as a Kubernetes Secret in the ArgoCD namespace
Configures helm-secrets plugin on the ArgoCD repo-server
Sets up automatic decryption during Helm template rendering

What Gets Deployed

Component	Namespace	Purpose
`ankra-sops-age-key` Secret	`argocd`	Stores the AGE private key
helm-secrets plugin	ArgoCD repo-server	Enables SOPS decryption in Helm
SOPS binary	ArgoCD repo-server	Performs the actual decryption

ArgoCD Integration

The helm-secrets plugin is automatically configured with:

HELM_SECRETS_BACKEND=sops - Use SOPS for decryption
SOPS_AGE_KEY_FILE=/ankra-sops-age-key/age.agekey - Path to the private key
Support for secrets:// value file scheme

Troubleshooting

Deployment Fails with Decryption Error

Verify SOPS is initialized at the organisation level (Organisation Settings → Encryption)
Confirm the cluster has ArgoCD installed and that the repo-server has restarted
Ensure the content was encrypted with the current organisation key (not a rotated key)

# Check ArgoCD repo-server logs
kubectl logs -n argocd -l app.kubernetes.io/component=repo-server | grep -i sops

Cluster Not Decrypting Encrypted Values

The cluster needs ArgoCD to decrypt SOPS values. If ArgoCD is not installed:

Create a Stack with the ArgoCD add-on
Deploy and wait for ArgoCD to become ready
The SOPS decryption key will be deployed automatically

Values Not Being Encrypted

Check that the key name matches exactly (case-sensitive)
Verify SOPS is initialized at the organisation level
Ensure the key is added to the Encrypted Keys list before saving

Keys must be top-level or specified with dot notation for nested paths.

Key Rotation Stuck

If you initiated key rotation but can’t complete it:

Cancel the rotation if you haven’t re-encrypted content yet
If content is already re-encrypted, verify by checking the sops.age.recipient field matches the new public key
Click Confirm Rotation to finalize

AI Prompts

Press ⌘+J to open the AI Assistant and use these prompts:

Set Up SOPS for a Stack

I have a Stack with database credentials. Help me encrypt
the password field with SOPS before pushing to Git.

Troubleshoot Decryption Failure

My Stack deployment is failing with a SOPS decryption error.
Help me troubleshoot.

Advanced Configuration

The defaults described above work for most setups. The following sections cover optional configuration that you may need if you want to change the default behaviour.

Disabling Organisation Encryption

SOPS encryption is enabled by default after initialization. If you need to temporarily stop encrypting new values (existing encrypted content remains encrypted):

Go to Organisation Settings → Encryption
Toggle SOPS Encryption off

When disabled, fields marked for encryption will be saved in plaintext. Re-enable at any time to resume encryption. This does not affect clusters’ ability to decrypt already-encrypted values.

Per-Cluster Decryption Toggle

Ankra automatically deploys the SOPS decryption key to every cluster that has ArgoCD. If you need to manage this manually for a specific cluster:

Go to your cluster → Settings → Encryption
Toggle Enable SOPS Decryption on or off

Disabling cluster decryption will cause deployments with encrypted values to fail on that cluster. Only disable this if the cluster should not process encrypted Stacks.

Key Rotation

Periodically rotating encryption keys is a security best practice. Consider rotating keys quarterly or after team member departures.

Go to Encryption Settings

Navigate to Organisation Settings → Encryption.

Click Rotate Keys

This generates a new AGE key pair while preserving the old one temporarily.

Re-encrypt Existing Content

Before confirming, you must re-encrypt all existing SOPS-encrypted content in your Git repositories with the new public key.

Confirm Rotation

Once all content is re-encrypted, click Confirm Rotation to finalize. The old private key is then securely deleted.

Critical: You must re-encrypt all content before confirming rotation. Failing to do so will result in decryption failures for content encrypted with the old key.

Cancelling Key Rotation

If you need to abort a rotation in progress, click Cancel Rotation. The new key pair is discarded and the existing key remains active.

Stacks

Build and deploy reusable Stack configurations.

GitOps

Sync Stacks with Git repositories.

Cloudflare Tunnel

Encrypt tunnel tokens with SOPS.

Manifests

Create custom Kubernetes resources with encryption.

​What is SOPS?

​How It Works

​Getting Started

​Encrypting Values in Stacks

​Using the Stack Builder

​Common Keys to Encrypt

​Example: Encrypting a Database Password

​Example: Encrypting a Registry Pull Secret (.dockerconfigjson)

​Encrypting Helm Values

​Helm Values Path Examples

​Using the CLI

​Encrypting Manifest Values

​Encrypting Addon Values

​Decrypting for Inspection

​Adding Keys to Existing Encrypted Files

​How Decryption Works

​What Gets Deployed

​ArgoCD Integration

​Troubleshooting

​AI Prompts

​Advanced Configuration

​Disabling Organisation Encryption

​Per-Cluster Decryption Toggle

​Key Rotation

​Cancelling Key Rotation

​Related

Stacks

GitOps

Cloudflare Tunnel

Manifests

What is SOPS?

How It Works

Getting Started

Encrypting Values in Stacks

Using the Stack Builder

Common Keys to Encrypt

Example: Encrypting a Database Password

Example: Encrypting a Registry Pull Secret (`.dockerconfigjson`)

Encrypting Helm Values

Helm Values Path Examples

Using the CLI

Encrypting Manifest Values

Encrypting Addon Values

Decrypting for Inspection

Adding Keys to Existing Encrypted Files

How Decryption Works

What Gets Deployed

ArgoCD Integration

Troubleshooting

AI Prompts

Advanced Configuration

Disabling Organisation Encryption

Per-Cluster Decryption Toggle

Key Rotation

Cancelling Key Rotation

Related