2.3 KiB
Troubleshooting
This document provides solutions to common issues encountered when working with buun-stack.
Table of Contents
Vault Issues
Vault is Sealed
Symptom
When running just vault::get or other Vault-related recipes, you encounter this error:
Error authenticating: Error making API request.
URL: PUT https://vault.example.com/v1/auth/oidc/oidc/auth_url
Code: 503. Errors:
* Vault is sealed
Cause
Vault automatically seals itself when:
- The Vault pod is restarted
- The node where Vault is running is restarted
- The machine is rebooted
- Vault encounters certain error conditions
When sealed, Vault cannot decrypt its data and all operations are blocked.
Solution
Unseal Vault using your unseal key:
Option 1: Using the Web UI
- Navigate to your Vault host (e.g.,
https://vault.example.com) - Enter your unseal key in the web interface
- Click "Unseal"
Option 2: Using just recipe (Recommended)
just vault::unseal
This recipe will prompt for the unseal key interactively. You can also set the VAULT_UNSEAL_KEY environment variable to avoid entering it repeatedly:
# Set in .env.local
VAULT_UNSEAL_KEY=your-unseal-key-here
# Or use 1Password reference
VAULT_UNSEAL_KEY=op://vault/unseal/key
Option 3: Using kubectl
# Get the unseal key from your secure storage
UNSEAL_KEY="your-unseal-key-here"
# Unseal Vault
kubectl exec -n vault vault-0 -- vault operator unseal "${UNSEAL_KEY}"
After unsealing, restart the External Secrets Operator to ensure it reconnects properly:
kubectl rollout restart -n external-secrets deploy/external-secrets
Prevention
Important: Store your Vault unseal key and root token securely. You will need them whenever Vault is sealed.
Recommended storage locations:
- Password manager (1Password, Bitwarden, etc.)
- Secure note in your organization's secret management system
- Encrypted file on secure storage
Never commit unseal keys to version control.
Verification
After unsealing, verify Vault is operational:
# Check Vault status
kubectl exec -n vault vault-0 -- vault status
# Test secret access
just vault::get test/path field