# `AshVault.KeyProviders.OpenBao.KubernetesAuth`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/key_providers/open_bao/kubernetes_auth.ex#L1)

A supervised OpenBao token holder for the Kubernetes auth method.

Configured per provider with `auth: {:kubernetes, opts}` instead of `:token`:

    config :my_app, AshVault.KeyProviders.OpenBaoTransit,
      address: "https://openbao.foundry.svc:8200",
      cacertfile: "/etc/openbao-ca/ca.crt",
      auth: {:kubernetes, role: "ashvault-foundry"}

## Options

  * `:role` (required) — the `auth/<mount>/role/<role>` to log in as.
  * `:mount` — the auth mount path. Default `"kubernetes"`.
  * `:jwt_path` — the projected service-account token. Default
    `"/var/run/secrets/kubernetes.io/serviceaccount/token"`.
  * `:refresh_fraction` — log in again once this fraction of the lease has elapsed.
    Default `2/3`.
  * `:backoff_min` / `:backoff_max` — milliseconds between failed logins, doubling
    from min to max. Defaults `1_000` and `30_000`.
  * `:login_timeout` — milliseconds a caller waits for an in-flight login. Default
    `15_000`.

## Behaviour

One holder runs per provider module, started on first use under AshVault's own
supervisor. It logs in with `POST /v1/auth/<mount>/login`, caches the client token,
and logs in **again** — rather than calling `renew-self` — once `:refresh_fraction` of
the lease has passed. A fresh login re-reads the service-account JWT every time (the
kubelet rotates projected tokens), and is not capped by the role's `token_max_ttl`
the way renewal is. A `lease_duration` of `0` is a token that never expires and is
never refreshed.

The login runs in a task, so callers holding a still-valid token are never blocked by
a refresh. Concurrent callers arriving with no valid token share one login.

A failed refresh keeps serving the old token until it actually expires, and retries
with exponential backoff. Once there is no valid token, a caller inside the backoff
window gets the last failure immediately instead of triggering another login. Every
failure is `AshVault.Errors.ProviderUnavailable` with reason
`{:kubernetes_auth, reason}`: retryable, never `KeyDestroyed`.

## Secrets

The JWT is read, sent and dropped; it is never kept in state. The client token is
kept in state, and `format_status/1` redacts it (and the task reply that carries it)
from `:sys.get_status/1` and crash reports. Neither value, nor the login response
body, ever reaches a log line or an error struct.

# `options`

```elixir
@type options() :: %{
  role: String.t(),
  mount: String.t(),
  jwt_path: Path.t(),
  refresh_fraction: float(),
  backoff_min: pos_integer(),
  backoff_max: pos_integer(),
  login_timeout: pos_integer()
}
```

Validated Kubernetes auth options.

# `options!`

```elixir
@spec options!(module(), keyword()) :: options()
```

Validate `auth: {:kubernetes, opts}` options, filling defaults.

Raises `ArgumentError` on a configuration fault: retrying cannot fix it.

# `token`

```elixir
@spec token(module(), options()) :: {:ok, String.t()} | {:error, Exception.t()}
```

The current client token for `provider`, logging in first if there is none.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
