plexctl kubeconfig

Synopsis

plexctl kubeconfig issues a one-time mediated Kubernetes access session against a Resource, then renders a kubeconfig from the returned one-time JWT and the on-Node API-proxy listener endpoint. It POSTs an IssueSession request with kind=k8s and acts locally on the resulting IssuedSession; it does not open the browser attach WebSocket.

plexctl kubeconfig --project-id <uuid> --resource-id <uuid> --impersonate-user <user> [flags]

Subcommands

plexctl kubeconfig is a single-leaf command — there are no subcommands. It performs one operation: issue the session, then emit the kubeconfig.

plexctl kubeconfig

POSTs /v1/projects/{project_id}/sessions with a kind=k8s body carrying the impersonation target, expecting 201 Created with an IssuedSession. plexctl then writes a minimal kubeconfig binding a single cluster (the proxy listener over https) to a single user (the one-time token as the bearer credential) through one context named plexsphere. The document is written to stdout by default, or to --output-file when provided. A file sink is created mode 0600 because the kubeconfig embeds a bearer token; when a file sink is used the document never touches stdout.

--project-id and --resource-id are parsed as UUIDs locally; --impersonate-user is required and an empty value exits 2. --impersonate-group is repeatable and optional.

Flags

plexctl kubeconfig

Flag	Type	Required	Description
--project-id	string (UUID)	yes	Owning Project UUID.
--resource-id	string (UUID)	yes	Target Resource UUID.
--impersonate-user	string	yes	Kubernetes user the mediated session impersonates.
--impersonate-group	string (repeatable)	no	Kubernetes group the session asserts. Repeat the flag for multiple groups.
--ttl-seconds	int	no	Requested session TTL in seconds (server default when zero).
--output-file	string	no	Write the kubeconfig to this path (mode 0600) instead of stdout.

Persistent flags inherited from root

--server, --profile, --token-file, --output. See ../plexctl.md for the canonical list. (The --output format flag governs error rendering; the kubeconfig body itself is always YAML.)

Exit codes

See ../plexctl.md#exit-code-taxonomy for the inherited base table. The cases that apply to this family:

Code	Trigger
0	The kubeconfig was written to stdout or --output-file.
1	Transport or API failure, a 5xx, an issued session with no listener endpoint, a render failure, or an --output-file write failure.
2	Malformed --project-id / --resource-id UUID or a missing required flag.
3	Missing or insecure credentials, a 401 Unauthorized, or a 401 step_up_required (re-authenticate before retrying).
4	403 Forbidden.
77	ReBAC denial (403 Forbidden with code == "rebac_denied").

Examples

Emit a kubeconfig to stdout

export PLEXSPHERE_URL="${PLEXSPHERE_URL:-https://localhost:8080}"

plexctl kubeconfig \
  --server           "${PLEXSPHERE_URL}" \
  --project-id       0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --resource-id      0190a8b8-d3e3-7d3d-8d3d-d3d3d3d3d3d3 \
  --impersonate-user platform-admin

Write a kubeconfig to a 0600 file, asserting groups

plexctl kubeconfig \
  --server            "${PLEXSPHERE_URL}" \
  --project-id        0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --resource-id       0190a8b8-d3e3-7d3d-8d3d-d3d3d3d3d3d3 \
  --impersonate-user  platform-admin \
  --impersonate-group system:masters \
  --impersonate-group ops \
  --output-file       ./plexsphere.kubeconfig

Cross-references

• ssh.md and tcp-forward.md — the sibling mediated-session families over the same IssueSession operation.
• ../../../../api/openapi/plexsphere-v1.yaml
• ../../../../cmd/plexctl/commands/kubeconfig.go
• ../../../contexts/access.md