headlamp-sealed-secrets-plugin/docs/getting-started/quick-start.md

Quick Start Guide

Get started with the Headlamp Sealed Secrets plugin in 5 minutes.

Prerequisites

Before you begin, ensure:

✅ Plugin is installed ✅ Headlamp is connected to your cluster ✅ Sealed Secrets controller is running

Step 1: Verify Installation

1. Open Headlamp
2. Look for "Sealed Secrets" in the sidebar
3. Click on it to open the plugin

You should see:

• Controller health status (green = healthy)
• List of existing SealedSecrets (if any)
• "Create Sealed Secret" button

Step 2: Create Your First Sealed Secret

Using the UI

1. Click "Create Sealed Secret"

2. Fill in the form:

   • Name: my-first-secret
   • Namespace: default (or your namespace)
   • Scope: strict (recommended for production)

3. Add secret data:

   • Click "Add Key"
   • Key: password
   • Value: mysecretvalue

4. Click "Create"

The plugin will:

• Fetch the public certificate from the controller
• Encrypt your value client-side
• Create the SealedSecret in your cluster

Understanding Scopes

• strict: Secret can only be unsealed with same name+namespace (most secure)
• namespace-wide: Can be renamed within the namespace
• cluster-wide: Can be moved anywhere in the cluster

Step 3: Verify the Sealed Secret

1. Check the list - Your new SealedSecret should appear

2. View details - Click on my-first-secret to see:

   • Metadata (name, namespace, creation time)
   • Scope information
   • Encrypted data (Base64-encoded, encrypted value)
   • Owner references

3. Verify the plain Secret was created:

   kubectl get secret my-first-secret -n default
   

The Sealed Secrets controller automatically creates a plain Kubernetes Secret from your SealedSecret.

Step 4: Use the Secret

The unsealed Secret can be used like any Kubernetes secret:

apiVersion: v1
kind: Pod
metadata:
  name: secret-test-pod
spec:
  containers:
  - name: test-container
    image: nginx
    env:
    - name: SECRET_PASSWORD
      valueFrom:
        secretKeyRef:
          name: my-first-secret
          key: password

Apply it:

kubectl apply -f pod.yaml

Verify:

kubectl exec secret-test-pod -- env | grep SECRET_PASSWORD
# Output: SECRET_PASSWORD=mysecretvalue

Step 5: Download Sealing Keys (Optional)

For CI/CD or offline encryption:

1. Navigate to "Sealing Keys" tab

2. You'll see all active certificates with:

   • Creation date
   • Expiry date (with warnings if expiring soon)
   • Fingerprint

3. Download certificate:

   • Click "Download" on the active key
   • Save as sealed-secrets-cert.pem

4. Use with kubeseal CLI (optional):

   echo -n mysecretvalue | kubeseal \
     --cert sealed-secrets-cert.pem \
     --scope strict \
     --name my-secret \
     --namespace default
   

Common Tasks

Create a Secret with Multiple Keys

1. Click "Create Sealed Secret"
2. Add multiple key-value pairs:
   • Key: username, Value: admin
   • Key: password, Value: secret123
   • Key: api-key, Value: abc123xyz
3. Click "Create"

Update an Existing Secret

Note: You cannot edit SealedSecrets directly. To update:

1. Delete the old SealedSecret:

   kubectl delete sealedsecret my-first-secret -n default
   

2. Create a new one with updated values (using the UI)

3. The controller will recreate the plain Secret

Delete a Sealed Secret

1. Find the secret in the list
2. Click on it to view details
3. Click "Delete" button
4. Confirm deletion

Warning: This also deletes the unsealed Secret!

Troubleshooting

"Controller not found" Error

Check controller status:

kubectl get pods -n kube-system -l name=sealed-secrets-controller

If not running, install it:

kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml

"Permission denied" Error

You need RBAC permissions for SealedSecret resources:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: sealed-secrets-user
rules:
- apiGroups: ["bitnami.com"]
  resources: ["sealedsecrets"]
  verbs: ["get", "list", "create", "delete"]
- apiGroups: [""]
  resources: ["services"]
  verbs: ["get"]

Encryption Fails

1. Check certificate is valid:

   • Go to "Sealing Keys" tab
   • Verify certificate is not expired
   • Check for expiry warnings

2. Verify controller connectivity:

   kubectl get svc -n kube-system sealed-secrets-controller
   

3. Check browser console:

   • View → Toggle Developer Tools
   • Look for encryption errors

Next Steps

Now that you've created your first sealed secret, explore more features:

• User Guide - Learn about all features
• Scopes Explained - Deep dive into scope types
• CI/CD Integration - Automate secret creation
• RBAC Permissions - Configure access control

Best Practices

1. Use strict scope for production secrets
2. Store SealedSecrets in Git (they're safe to commit!)
3. Don't store plain Secrets in Git
4. Monitor certificate expiry (plugin warns 30 days in advance)
5. Backup sealing keys for disaster recovery
6. Rotate secrets regularly (delete and recreate)

Need Help?

• Documentation: Full docs
• Troubleshooting: Common issues
• GitHub Issues: Report bugs
• Discussions: Ask questions