Debug sessions
A debug session runs kubectl, aws, gcloud, or az on your machine against one customer deployment, with credentials scoped to that deployment and limited to the approval window. It fits when no named operation answers your question. Every session needs an approved access request.
# Request access, wait for approval, then run the command
alien debug customer-1/us-east-1 --request-access -- kubectl get pods -n checkout
# Reuse an approved request
alien debug customer-1/us-east-1 --access-request ar_5k2m8q -- kubectl get events -n checkout
# No command opens a local shell with the session's environment set
alien debug customer-1/us-east-1 --access-request ar_5k2m8qA deployment is a dep_… ID or <group>/<name>.
Get approval
Without an approved request, Alien refuses the session with DEBUG_ACCESS_REQUEST_REQUIRED. Get one in your command, or create it first:
--request-accesscreates a request for the tool in your command, waits for approval, and starts the session. Forkubectl, the request is scoped to the namespace in-n. For a cloud CLI, add--access-cloud-scope <account-or-project>.--access-durationsets the window (default30m).- Create it first and pass its ID:
alien access-requests create --deployment customer-1/us-east-1 \
--debug-tool kubectl --debug-namespace checkout --duration 30m
alien access-requests wait ar_5k2m8q
alien debug customer-1/us-east-1 --access-request ar_5k2m8q -- kubectl get pods -n checkoutThese rules hold for the whole session:
- Only the requester can use it. A request an API key created works only for that API key. Another caller's request ID is refused with
a debug session can only use a grant its caller requested. - The scope holds on every call. A
kubectlgrant for one namespace refuses other namespaces and cluster-wide resources such as nodes. A cloud grant for one account refuses others. - It ends with the approval. Alien checks the grant on every forwarded call and closes the session when the window ends or the request is revoked.
What the session can do
| Deployment | Session runs as | Limits |
|---|---|---|
| Push (AWS, Google Cloud, Azure) | The deployment's management identity, the cloud role Alien uses for ongoing management | What the initial setup granted it. Cloud CLI calls go through a local proxy that signs them with that identity. |
| Remote Operator on Kubernetes | The Operator's ServiceAccount and cloud identity | Its Role: list on workloads, Pods, events, and metrics, plus rules from enabled operations. |
On a Remote Operator installation, kubectl runs with the Operator's ServiceAccount token. kubectl get pods works, but kubectl get configmaps fails with forbidden unless an enabled operation declares that rule. To allow more, enable such an operation and apply the permission update.
Cloud CLIs are signed with the Operator's workload identity, so they have the cloud permissions you granted in Connect cloud APIs.
Each kubectl request on a Remote Operator installation returns one buffered response. Streaming commands such as kubectl logs -f, exec, port-forward, and cp aren't supported.
The CLI writes credential files, such as a kubeconfig, to a per-session temporary directory with 0600 permissions, and deletes them when the command exits.
Shell and exec
On Machines and local deployments, open a shell or run a command inside the runtime itself:
alien debug shell customer-1/edge-site
alien debug exec customer-1/edge-site --machine m_2k7d -- journalctl -u my-daemon --since "10 min ago"
alien debug exec customer-1/edge-site --resource api -- uname -a--resource attaches to a Container or Daemon, --machine to one host. exec times out after 120 seconds by default (--timeout-seconds). On local deployments, only workspace admins can open these sessions.
Audit
Operations → Debug lists every session: who opened it, on which deployment, under which access request, and when it ended. When you need to read application data instead, use a command that returns only what you ask for.