{"slug":"kubernetes-kubectl-session-and-api-request-recording","title":"Kubernetes 'kubectl' session and API request recording","tags":["tailscale","containers","api"],"agent_summary":"Last validated: Jan 5, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Kubernetes 'kubectl' session and API request recording\r\n\r\nLast validated: Jan 5, 2026\r\n\r\nTailscale Kubernetes Operator session recordingis currently [in beta](https://tailscale.com/docs/reference/tailscale-release-stages#beta).\r\n\r\nThe Tailscale Kubernetes Operator now supports recording all [Kubernetes API request events](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording#kubernetes-api-request-events).\r\n\r\nIn Tailscale 1.70 and later, you can record [kubectl exec](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_exec/), [kubectl debug](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_debug/), [kubectl attach](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_attach/), and [kubectl run](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_run/) session contents, as well as all Kubernetes API requests that pass through the [Kubernetes API server proxy](https://tailscale.com/docs/features/kubernetes-operator/how-to/api-server-proxy).\r\n\r\nTailscale Kubernetes Operator session recordingis available for [the Personal and Enterprise plans](https://tailscale.com/pricing).\r\n\r\nRecorded sessions are sent to a configured [`tsrecorder`](https://tailscale.com/docs/features/tailscale-ssh/tailscale-ssh-session-recording#deploy-a-recorder-node) instance in your tailnet.\r\nThe `tsrecorder` supports storing recorded sessions in an S3-compatible storage or on disk.\r\n\r\nA recording contains:\r\n\r\n- The command sent in the `kubectl` call. For example, `kubectl exec -- cat /myfile.txt` will show up as `cat /myfile.txt`.\r\n- The session type being recorded (either `exec` or `attach`)\r\n- The contents of `stdout` and `stderr` from the attached terminal, but not `stdin`. This prevents the recording of sensitive input, such as passwords.\r\n- Session start timestamp.\r\n- Name and namespace of the `Pod` and name of the container being recorded.\r\n- Tailscale hostname of the API server proxy.\r\n- [Tailscale identity](https://tailscale.com/docs/concepts/tailscale-identity)that initiated the session:\r\n - Tailscale hostname of the source device from which the `kubectl` session was initiated.\r\n - If the source device is [tagged](https://tailscale.com/docs/features/tags), tags of the device.\r\n - If the source device is not tagged, Tailscale user ID and login name.\r\n\r\nThe API server proxy sends session contents to `tsrecorder` over the tailnet, so the traffic is end-to-end encrypted using WireGuard, like any other tailnet traffic.\r\n\r\nYou can choose whether a `kubectl` session should be allowed ('fail open') or be forbidden ('fail closed') if the recording fails. For example, if a connection to tsrecorder cannot be established or fails.\r\n\r\n## [Kubernetes API request events](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording\\#kubernetes-api-request-events)\r\n\r\nTailscale Kubernetes Operator API request recordingis currently [in beta](https://tailscale.com/docs/reference/tailscale-release-stages#beta).\r\n\r\nWith the Tailscale Kubernetes operator, you can record all Kubernetes API requests that pass through the [Kubernetes API server proxy](https://tailscale.com/docs/features/kubernetes-operator/how-to/api-server-proxy). This lets you create a detailed audit trail of cluster interactions for security and compliance purposes.\r\n\r\nA request event contains:\r\n\r\n- Timestamp of when the event occurred.\r\n- Detailed information about the Kubernetes API request, including:\r\n - The verb such as `get`, `list`, `create`.\r\n - The targeted resource such as `pods` and `services`.\r\n - The namespace, name, API group, and version.\r\n- Full HTTP request details, including the method, path, request body and query parameters.\r\n- User agent of the client that made the request (for example, `kubectl/v1.33.3`).\r\n- Source Tailscale machine that the request came from.\r\n- Tailscale identity that initiated the API call, including:\r\n - Tailscale hostname of the source device.\r\n - If the source device is tagged and the tags of the device.\r\n - If the source device is not tagged, the Tailscale user ID and login name.\r\n\r\nThis is all encapsulated in a general tsrecorder event of type `kubernetes-api-request`.\r\n\r\nThe API server proxy sends API request events to [`tsrecorder`](https://tailscale.com/docs/features/tailscale-ssh/tailscale-ssh-session-recording#deploy-a-recorder-node) over your tailnet, so the traffic is end-to-end encrypted using WireGuard, just like any other tailnet traffic.\r\n\r\n### [Enabling Kubernetes API request events](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording\\#enabling-kubernetes-api-request-events)\r\n\r\nTo enable this feature, refer to the [following section](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording#enabling-api-request-event-recording).\r\n\r\n## [Prerequisites](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording\\#prerequisites)\r\n\r\n- Set up the Tailscale Kubernetes Operator with the [API server proxy](https://tailscale.com/docs/features/kubernetes-operator/how-to/api-server-proxy) enabled.\r\n- Deploy a [tagged](https://tailscale.com/docs/features/tags) [`tsrecorder` instance](https://tailscale.com/docs/features/tailscale-ssh/tailscale-ssh-session-recording#deploy-a-recorder-node).\r\nNote that you can also [deploy `tsrecorder` on Kubernetes using the operator](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder).\r\n- Ensure that your [ACLs](https://tailscale.com/docs/features/access-control/acls) allow the operator to access port `80` of the `tsrecorder`.\r\n\r\n## [Configure the session recording](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording\\#configure-the-session-recording)\r\n\r\nYou can configure session recording options using [grants](https://tailscale.com/docs/features/access-control/grants).\r\n\r\nGrants only configure how the API server proxy treats incoming connections; they do not configure tailnet device connectivity. To allow clients to connect, refer to the [API server proxy prerequisites](https://tailscale.com/docs/features/kubernetes-operator/how-to/api-server-proxy#prerequisites).\r\n\r\nYou must specify the source (the tailnet identity that starts the `kubectl` session), the destination (the API server proxy), and the `tsrecorder` instance. You can also specify the failure policy. The default failure policy is to fail open.\r\n\r\nThe following example:\r\n\r\n- Lets requests from `group:engineering` connect to the API server proxy on all operator instances tagged with `tag:k8s-operator` on port `443`.\r\n- Enforces session recording for `kubectl` sessions from [tailnet group](https://tailscale.com/docs/reference/syntax/policy-file#groups)`group:engineering` to all API server proxy instances tagged with `tag:k8s-operator`.\r\n- Configures the recorded sessions to be sent to a `tsrecorder` instance tagged with `tag:tsrecorder`.\r\n- Sets failure policy to \"fail closed\" (if the recording fails, forbid the session).\r\n\r\n```json\r\n\"acls\": [\\\r\n {\\\r\n \"action\": \"accept\",\\\r\n \"src\": [\"group:engineering\"],\\\r\n \"dst\": [\"tag:k8s-operator:443\"]\\\r\n }\\\r\n],\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"group:engineering\"],\\\r\n \"dst\": [\"tag:k8s-operator\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/kubernetes\": [{\\\r\n \"recorder\": [\"tag:tsrecorder\"],\\\r\n \"enforceRecorder\": true,\\\r\n }],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\nIf `tag:tsrecorder` resolves to multiple tailnet IP addresses, the API server proxy will send the recording to the first instance to which it succeeds at establishing a connection.\r\n\r\n### [Enabling API request event recording](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording\\#enabling-api-request-event-recording)\r\n\r\nTo enable Kubernetes API request event recording, add `\"enableEvents\": true` to the `tailscale.com/cap/kubernetes` grant.\r\n\r\nWhen `enableEvents` is set to `true`, all Kubernetes API requests that pass through the proxy will be recorded, in addition to `kubectl` sessions.\r\n\r\nThe following example:\r\n\r\n- Lets requests from `group:engineering` connect to the API server proxy on all operator instances tagged with `tag:k8s-operator` on port `443`.\r\n- Configures the recorded sessions to be sent to a `tsrecorder` instance tagged with `tag:tsrecorder`.\r\n- Enables recording of Kubernetes API request events.\r\n\r\n```json\r\n\"acls\": [\\\r\n {\\\r\n \"action\": \"accept\",\\\r\n \"src\": [\"group:engineering\"],\\\r\n \"dst\": [\"tag:k8s-operator:443\"]\\\r\n }\\\r\n],\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"group:engineering\"],\\\r\n \"dst\": [\"tag:k8s-operator\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/kubernetes\": [{\\\r\n \"recorder\": [\"tag:tsrecorder\"],\\\r\n \"enableEvents\": true,\\\r\n }],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\n### [Combine session recording and group impersonation in grant rules](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording\\#combine-session-recording-and-group-impersonation-in-grant-rules)\r\n\r\nA grant can also combine session recording rules and [API server proxy impersonation rules](https://tailscale.com/docs/features/kubernetes-operator/how-to/api-server-proxy#impersonating-kubernetes-groups-with-grants).\r\n\r\nThe following example:\r\n\r\n- Lets requests from `group:engineering` connect to the API server proxy on all operator instances tagged with `tag:k8s-operator` on port `443`.\r\n\r\n- Configures session recording for `kubectl` sessions from group `group:engineering` to all operator instances tagged with `tag:k8s-operator`.\r\n\r\n- Configures the recorded sessions to be sent to a tsrecorder instance tagged with `tag:tsrecorder`.\r\n\r\n- Configures that requests from `group:engineering` should be impersonated as from Kubernetes group `system:masters`.\r\n\r\n\r\n```json\r\n\"acls\": [\\\r\n {\\\r\n \"action\": \"accept\",\\\r\n \"src\": [\"group:engineering\"],\\\r\n \"dst\": [\"tag:k8s-operator:443\"]\\\r\n }\\\r\n],\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"group:engineering\"],\\\r\n \"dst\": [\"tag:k8s-operator\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/kubernetes\": [{\\\r\n \"impersonate\": {\\\r\n \"groups\": [\"system:masters\"],\\\r\n },\\\r\n \"recorder\": [\"tag:tsrecorder\"],\\\r\n }],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\n### [Enforce recording of all sessions](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording\\#enforce-recording-of-all-sessions)\r\n\r\nTo ensure the recording of all `kubectl` sessions, use the wildcard syntax (`*`) as the grant's source and/or destination.\r\n\r\nThe following example:\r\n\r\n- Enforces recording of all `kubectl` sessions from any source to any API server proxy instance.\r\n\r\n- Configures the recording to be sent to tsrecorder instance tagged with `tag:tsrecorder`.\r\n\r\n\r\n```json\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"dst\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/kubernetes\": [{\\\r\n \"recorder\": [\"tag:tsrecorder\"],\\\r\n \"enforceRecorder\": true,\\\r\n }],\\\r\n },\\\r\n },\\\r\n]\r\n```\r\n\r\n## [Known issues and limitations](https://tailscale.com/docs/features/kubernetes-operator/how-to/session-recording\\#known-issues-and-limitations)\r\n\r\n- In some cases, if an established connection to `tsrecorder` fails midway (because the `tsrecorder` instance fails), the session will be allowed to continue even if the policy is to fail closed.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Kubernetes 'kubectl' session and API request recording

\n

Last validated: Jan 5, 2026

\n

Tailscale Kubernetes Operator session recordingis currently in beta.

\n

The Tailscale Kubernetes Operator now supports recording all Kubernetes API request events.

\n

In Tailscale 1.70 and later, you can record kubectl exec, kubectl debug, kubectl attach, and kubectl run session contents, as well as all Kubernetes API requests that pass through the Kubernetes API server proxy.

\n

Tailscale Kubernetes Operator session recordingis available for the Personal and Enterprise plans.

\n

Recorded sessions are sent to a configured tsrecorder instance in your tailnet.\r\nThe tsrecorder supports storing recorded sessions in an S3-compatible storage or on disk.

\n

A recording contains:

\n\n

The API server proxy sends session contents to tsrecorder over the tailnet, so the traffic is end-to-end encrypted using WireGuard, like any other tailnet traffic.

\n

You can choose whether a kubectl session should be allowed ('fail open') or be forbidden ('fail closed') if the recording fails. For example, if a connection to tsrecorder cannot be established or fails.

\n

Kubernetes API request events

\n

Tailscale Kubernetes Operator API request recordingis currently in beta.

\n

With the Tailscale Kubernetes operator, you can record all Kubernetes API requests that pass through the Kubernetes API server proxy. This lets you create a detailed audit trail of cluster interactions for security and compliance purposes.

\n

A request event contains:

\n\n

This is all encapsulated in a general tsrecorder event of type kubernetes-api-request.

\n

The API server proxy sends API request events to tsrecorder over your tailnet, so the traffic is end-to-end encrypted using WireGuard, just like any other tailnet traffic.

\n

Enabling Kubernetes API request events

\n

To enable this feature, refer to the following section.

\n

Prerequisites

\n\n

Configure the session recording

\n

You can configure session recording options using grants.

\n

Grants only configure how the API server proxy treats incoming connections; they do not configure tailnet device connectivity. To allow clients to connect, refer to the API server proxy prerequisites.

\n

You must specify the source (the tailnet identity that starts the kubectl session), the destination (the API server proxy), and the tsrecorder instance. You can also specify the failure policy. The default failure policy is to fail open.

\n

The following example:

\n\n
\"acls\": [\\\r\n  {\\\r\n    \"action\": \"accept\",\\\r\n    \"src\": [\"group:engineering\"],\\\r\n    \"dst\": [\"tag:k8s-operator:443\"]\\\r\n  }\\\r\n],\r\n\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"group:engineering\"],\\\r\n    \"dst\": [\"tag:k8s-operator\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/kubernetes\": [{\\\r\n        \"recorder\":        [\"tag:tsrecorder\"],\\\r\n        \"enforceRecorder\": true,\\\r\n      }],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

If tag:tsrecorder resolves to multiple tailnet IP addresses, the API server proxy will send the recording to the first instance to which it succeeds at establishing a connection.

\n

Enabling API request event recording

\n

To enable Kubernetes API request event recording, add \"enableEvents\": true to the tailscale.com/cap/kubernetes grant.

\n

When enableEvents is set to true, all Kubernetes API requests that pass through the proxy will be recorded, in addition to kubectl sessions.

\n

The following example:

\n\n
\"acls\": [\\\r\n  {\\\r\n    \"action\": \"accept\",\\\r\n    \"src\": [\"group:engineering\"],\\\r\n    \"dst\": [\"tag:k8s-operator:443\"]\\\r\n  }\\\r\n],\r\n\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"group:engineering\"],\\\r\n    \"dst\": [\"tag:k8s-operator\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/kubernetes\": [{\\\r\n        \"recorder\":        [\"tag:tsrecorder\"],\\\r\n        \"enableEvents\":    true,\\\r\n      }],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

Combine session recording and group impersonation in grant rules

\n

A grant can also combine session recording rules and API server proxy impersonation rules.

\n

The following example:

\n\n
\"acls\": [\\\r\n  {\\\r\n    \"action\": \"accept\",\\\r\n    \"src\": [\"group:engineering\"],\\\r\n    \"dst\": [\"tag:k8s-operator:443\"]\\\r\n  }\\\r\n],\r\n\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"group:engineering\"],\\\r\n    \"dst\": [\"tag:k8s-operator\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/kubernetes\": [{\\\r\n        \"impersonate\": {\\\r\n          \"groups\": [\"system:masters\"],\\\r\n        },\\\r\n        \"recorder\": [\"tag:tsrecorder\"],\\\r\n      }],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

Enforce recording of all sessions

\n

To ensure the recording of all kubectl sessions, use the wildcard syntax (*) as the grant's source and/or destination.

\n

The following example:

\n\n
\"grants\": [\\\r\n  {\\\r\n    \"src\": [\"*\"],\\\r\n    \"dst\": [\"*\"],\\\r\n    \"app\": {\\\r\n      \"tailscale.com/cap/kubernetes\": [{\\\r\n        \"recorder\":        [\"tag:tsrecorder\"],\\\r\n        \"enforceRecorder\": true,\\\r\n      }],\\\r\n    },\\\r\n  },\\\r\n]\n
\n

Known issues and limitations

\n\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}