Skip to content

credential-helpers.md

Latest commit

 

History

History
68 lines (50 loc) · 3.09 KB

credential-helpers.md

File metadata and controls

68 lines (50 loc) · 3.09 KB
Raw

Credential helpers (aws-vault & friends)

Many kubeconfigs authenticate through an exec credential plugin — for example aws eks get-token wrapped in aws-vault exec <profile>. These plugins rely on two things that a terminal gives them but a GUI launch does not:

  • a populated PATH (so the helper binary is found), and
  • ambient cloud credentials / environment (so the helper can mint a token).

When you launch Klustr from Finder, the Dock, or a .desktop entry, the OS starts it without your shell's startup files — so an exec plugin that works in your terminal can fail in the app. Klustr fixes this in two layers.

Layer 1: shell-environment import (automatic)

On a GUI launch (macOS/Linux only — never on Windows, never when started from a terminal), Klustr runs your login shell once, captures its environment, and merges into its own process:

  • your full PATH, plus
  • an allowlist of relevant variables (AWS_VAULT_BACKEND, AWS_CONFIG_FILE, KUBECONFIG, proxy variables, …).

This happens before the first connection attempt, so the first exec plugin run already sees the merged environment. In most setups this alone makes terminal-only kubeconfigs work from the Dock with no configuration.

Layer 2: credential providers (aws-vault)

If your cluster needs an aws-vault profile's credentials specifically, map the context to a profile:

  1. Open the Connections screen → Credential helpers section.
  2. Find your context. Klustr preselects a likely profile from the kubeconfig exec block's --profile / AWS_PROFILE hint.
  3. Pick the aws-vault profile to use and save the mapping.

On connect, Klustr runs aws-vault export --format=json <profile> (you may see the macOS Keychain prompt the first time) and injects the captured keys into the exec plugin's environment — so aws eks get-token behaves exactly as it would under aws-vault exec <profile> -- ....

What's stored where

  • Secrets live in memory only. They are never written to disk and never logged.
  • The on-disk store (under your user config directory) holds the provider and profile names only — never credential values.

Refresh and expiry

Klustr re-captures credentials about five minutes before they expire and rebuilds the context's clients automatically (the exec authenticator snapshots its environment, so a refresh needs fresh clients). If a refresh fails, you'll get an error toast with a Retry action.

Troubleshooting

  • Still can't authenticate from the Dock, but it works from a terminal. Confirm the helper binary is on the PATH your login shell exports (Layer 1 uses $SHELL -ilc). If you keep tools in a non-standard directory, make sure your shell rc adds it to PATH.
  • Keychain prompt keeps appearing. That's aws-vault unlocking its backend; it's expected on first capture and after the backend locks.
  • Wrong profile picked. Re-open Connections → Credential helpers and change the mapping; the kubeconfig hint is only a default.

Other providers (granted, saml2aws, …) can slot in beside aws-vault in the future — the provider interface is generic.