A kubectl exec plugin that securely stores your kubeconfig credentials in the macOS Keychain and retrieves them on-demand. This improves the security of your Kubernetes configuration by keeping sensitive credentials encrypted in the system keychain instead of stored as plain text on disk.

• Features
• Prerequisites
• Installation
• Setup
• Usage
• Updating Credentials
• Troubleshooting
• License

• Secure Storage: Stores your kubeconfig in the encrypted macOS Keychain instead of plain text
• Automatic Credential Retrieval: Transparently retrieves credentials when you run kubectl commands
• Automatic Sync: Syncs clusters, contexts, and users from the keychain to your local kubeconfig
• Backup Protection: Automatically creates timestamped backups when updating your kubeconfig
• Zero Configuration: Works seamlessly with existing kubectl workflows

Before you begin, ensure you have the following installed:

• macOS (10.12 or later) - This tool uses the macOS Keychain
• kubectl - Kubernetes command-line tool, tested with v1.35.0
• uv - Python package manager and runner (install from astral.sh)
• Python 3.7+ - Required by the exec plugin
• PyYAML - Python YAML library (installed automatically by uv pip install pyyaml)

brew install minisign kubectl uv
uv pip install pyyaml

1. Download the script to a location in your PATH or a directory you'll reference later:

   # Option 1: Place in a utilities directory
   mkdir -p ~/utils
   curl -o ~/utils/kubectl-keychain-exec.py https://raw.githubusercontent.com/qdrddr/kubectl-keychain/main/kubectl-keychain-exec.py
   chmod +x ~/utils/kubectl-keychain-exec.py

   Or simply clone the repository:

   git clone https://github.com/yourusername/kubectl-keychain.git
   cd kubectl-keychain
   chmod +x kubectl-keychain-exec.py

2. Verify the script is executable:

   ls -la ~/utils/kubectl-keychain-exec.py
   # Should show: -rwxr-xr-x

Save your existing kubeconfig to the macOS Keychain:

security add-generic-password \
  -a "k8s-user" \
  -s "k8s-kubeconfig" \
  -w "$(cat ~/.kube/config)" \
  -U

What this does:

• -a "k8s-user": Sets the account name
• -s "k8s-kubeconfig": Sets the service name (This is the Keychain item name you can find in the app)
• -w "$(cat ~/.kube/config)": Stores the contents of your kubeconfig file
• -U: Updates the entry if it already exists

Verification: Open Keychain Access.app and search for "k8s-kubeconfig" to confirm it was stored by opening the item and checking the "Show password" checkbox.

Edit your local kubeconfig file (~/.kube/config) and replace the client-certificate-data and client-key-data entries with an exec plugin configuration for each user in the users section for the current context.

Before:

users:
- name: admin@mykubernetes
  user:
    client-certificate-data: LS0tLS1CRUdJTi... (long base64 string)
    client-key-data: LS0tLS1CRUdJTi... (long base64 string)

After:

users:
- name: admin@mykubernetes
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: uv
      args:
      - run
      - ~/utils/kubectl-keychain-exec.py
      env: null
      interactiveMode: IfAvailable
      provideClusterInfo: false

Important Notes:

• Replace ~/utils/kubectl-keychain-exec.py with the actual path to your script
• Use the absolute path (e.g., /Users/yourname/utils/kubectl-keychain-exec.py) for reliability
• You only need to update the users section for the current context. The script will automatically update the other users when you run kubectl next time.
• Keep the name field unchanged

Every time you run kubectl command, the script will automatically sync your kubeconfig from the keychain (only if the file needs to be synced).

Once setup is complete, simply use kubectl normally:

kubectl get pods
kubectl get nodes
kubectl describe pod <pod-name>

When you run any kubectl command:

1. The exec plugin automatically retrieves your credentials from the Keychain
2. Clusters, contexts, and users are synced from the keychain to your local kubeconfig
3. Your credentials are used to authenticate with the Kubernetes cluster
4. The credentials are never stored in plain text on disk

To manually sync your kubeconfig from the keychain (useful after updating credentials):

uv run ~/utils/kubectl-keychain-exec.py sync

This is possible but rudementary since each time you run kubectl the script will automatically sync your kubeconfig from the keychain if needed as long as the local kubeconfig current context has exec plugin configured.

If you need to update your kubeconfig with new credentials, you have two options:

1. Open Keychain Access.app
2. Search for "k8s-kubeconfig"
3. Double-click the entry
4. Click "Show password"
5. Replace the entire content with your new kubeconfig
6. Click "Save"

1. Create a temporary file with your new (~/.kube/new-temp-kubeconfig.yaml):

   cat > /tmp/new-temp-kubeconfig.yaml << 'EOF'
   # Paste your new kubeconfig here
   EOF

2. Update the keychain entry:

   security add-generic-password \
     -a "k8s-user" \
     -s "k8s-kubeconfig" \
     -w "$(cat /tmp/new-temp-kubeconfig.yaml)" \
     -U

3. Remove the temporary file:

   rm /tmp/new-temp-kubeconfig.yaml

4. (Optional) Sync your local kubeconfig:

   uv run ~/utils/kubectl-keychain-exec.py sync

• Your kubeconfig is stored encrypted in the macOS Keychain
• Credentials are only decrypted when needed by kubectl
• The local kubeconfig file (~/.kube/config) contains only the exec plugin configuration, not actual credentials
• Always ensure your kubeconfig backups are stored securely
• Regularly rotate your Kubernetes credentials as part of your security practices

See LICENSE.md for details.