{"slug":"deploy-tsrecorder-on-kubernetes-using-the-operator","title":"Deploy tsrecorder on Kubernetes using the operator","tags":["tailscale","containers"],"agent_summary":"Last validated: Dec 8, 2025","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Deploy tsrecorder on Kubernetes using the operator\r\n\r\nLast validated: Dec 8, 2025\r\n\r\nIn Tailscale 1.74 and later, you can deploy [`tsrecorder`](https://tailscale.com/docs/features/tailscale-ssh/tailscale-ssh-session-recording) to your Kubernetes cluster using the operator and its [`Recorder` Custom Resource Definition](https://github.com/tailscale/tailscale/blob/main/k8s-operator/api.md#recorder).\r\nYou can use this as a [recording destination for SSH sessions](https://tailscale.com/docs/features/tailscale-ssh/tailscale-ssh-session-recording).\r\nThe recorder will connect to your tailnet and receive end-to-end-encrypted recordings using WireGuard just like any other `tsrecorder` devices running in your tailnet.\r\n\r\nTailscale SSH session recordingis available for [the Personal and Enterprise plans](https://tailscale.com/pricing).\r\n\r\n## [Prerequisites](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder\\#prerequisites)\r\n\r\n- Set up the [Kubernetes operator](https://tailscale.com/docs/features/kubernetes-operator).\r\n\r\n- (Optional) create a [tag](https://tailscale.com/docs/features/tags), for example `tag:k8s-recorder`, to attach to the `tsrecorder` device.\r\nThis might be a useful way to refer to the recorder when configuring the [access control policies](https://tailscale.com/docs/features/access-control) for SSH session recording. Make sure the operator is one of the [tag owners](https://tailscale.com/docs/reference/syntax/policy-file#tag-owners) for your recorder tag:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n\"tagOwners\": {\r\n \t\"tag:k8s-operator\": [],\r\n \t\"tag:k8s-recorder\": [\"tag:k8s-operator\"],\r\n}\r\n```\r\n\r\n- (Optional) [enable HTTPS](https://tailscale.com/docs/how-to/set-up-https-certificates) for your tailnet if you want to use the recorder's UI.\r\n\r\n\r\n## [Deploy](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder\\#deploy)\r\n\r\n1. Create your `Recorder` resource based on the below. Use the [reference documentation](https://github.com/tailscale/tailscale/blob/main/k8s-operator/api.md#recorder)\r\nto update it as required and then save it as `recorder.yaml`.\r\n\r\nThe following spec will save recordings to a local temporary directory, and only persist for the lifetime of the pod.\r\nUse the `s3` storage option shown below for durable storage.\r\n\r\n```yaml\r\napiVersion: tailscale.com/v1alpha1\r\nkind: Recorder\r\nmetadata:\r\n name: recorder\r\nspec:\r\n enableUI: true\r\n```\r\n\r\n2. Apply the file:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nkubectl apply -f recorder.yaml\r\n```\r\n\r\n3. (Optional) wait for the recorder to become ready:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nkubectl wait --for condition=RecorderReady=true Recorder recorder\r\n```\r\n\r\n\r\n\r\nFor example, this command will return information similar to the following:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nrecorder.tailscale.com/recorder condition met\r\n```\r\n\r\n4. (Optional) find the URL for the recorder's UI:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nkubectl get Recorder recorder\r\n```\r\n\r\n\r\n\r\nFor example, this command will return information similar to the following:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nNAME STATUS URL\r\nrecorder RecorderCreated https://recorder-0.tails-scales.ts.net\r\n```\r\n\r\n\r\n## [Examples](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder\\#examples)\r\n\r\n### [Static S3 credentials](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder\\#static-s3-credentials)\r\n\r\nThe following example:\r\n\r\n- Creates a `Secret` named \"s3-auth\" with AWS credentials for writing to a pre-existing S3 bucket named \"tsrecorder-bucket\".\r\n- Deploys a `StatefulSet` with a single replica of `tsrecorder`.\r\n- Assigns the tag `tag:k8s-recorder` to the recorder tailnet device.\r\n- Enables the recorder's UI.\r\n- Stores the recordings in an S3 bucket called \"tsrecorder-bucket\".\r\n- Gets S3 credentials as environment variables from a `Secret` called \"s3-auth\" in\r\nthe same namespace as the Tailscale operator.\r\n\r\n```yaml\r\napiVersion: v1\r\nkind: Secret\r\nmetadata:\r\n name: s3-auth\r\n namespace: tailscale\r\nstringData:\r\n AWS_ACCESS_KEY_ID: ABC...\r\n AWS_SECRET_ACCESS_KEY: xyz123...\r\n---\r\napiVersion: tailscale.com/v1alpha1\r\nkind: Recorder\r\nmetadata:\r\n name: recorder\r\nspec:\r\n enableUI: true\r\n tags:\r\n - \"tag:k8s-recorder\"\r\n storage:\r\n s3:\r\n endpoint: s3.us-east-1.amazonaws.com\r\n bucket: tsrecorder-bucket\r\n credentials:\r\n secret:\r\n name: s3-auth\r\n```\r\n\r\n### [IAM roles for service accounts (IRSA)](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder\\#iam-roles-for-service-accounts-irsa)\r\n\r\nYou can modify the above example to use IRSA for S3 credentials instead of static credentials stored in a `Secret`.\r\n\r\n1. Follow the [AWS instructions for IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html). When you select the name and namespace of the `ServiceAccount` to attach your policy to, use the Tailscale Kubernetes Operator's namespace (usually `tailscale`) and a name of your choosing (the default `ServiceAccount` name is the same as the `Recorder` resource's name). This will be reflected in the trust policy document, for example:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n{\r\n \"Version\": \"2012-10-17\",\r\n \"Statement\": [\\\r\n {\\\r\n \"Effect\": \"Allow\",\\\r\n \"Principal\": {\\\r\n \"Federated\": \"arn:aws:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE\"\\\r\n },\\\r\n \"Action\": \"sts:AssumeRoleWithWebIdentity\",\\\r\n \"Condition\": {\\\r\n \"StringEquals\": {\\\r\n \"oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub\": \"system:serviceaccount:tailscale:my-recorder\",\\\r\n \"oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud\": \"sts.amazonaws.com\"\\\r\n }\\\r\n }\\\r\n }\\\r\n ]\r\n}\r\n```\r\n\r\n2. Use the `Recorder` field `.spec.statefulSet.pod.serviceAccount` to annotate its service account with the correct AWS role.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```yaml\r\napiVersion: tailscale.com/v1alpha1\r\nkind: Recorder\r\nmetadata:\r\n name: recorder\r\nspec:\r\n enableUI: true\r\n tags:\r\n - \"tag:k8s-recorder\"\r\nstorage:\r\n s3:\r\n endpoint: s3.us-east-1.amazonaws.com\r\n bucket: tsrecorder-bucket\r\nstatefulSet:\r\n pod:\r\n serviceAccount:\r\n name: my-recorder\r\n annotations:\r\n eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/my-s3-role\r\n```\r\n\r\n## [Known issues and limitations](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder\\#known-issues-and-limitations)\r\n\r\n- The only durable storage method currently available is `s3`. If `s3` storage isn't configured, recordings will be saved to a local temporary directory, and will only persist for the lifetime of the `Pod`.\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":"

Deploy tsrecorder on Kubernetes using the operator

\n

Last validated: Dec 8, 2025

\n

In Tailscale 1.74 and later, you can deploy tsrecorder to your Kubernetes cluster using the operator and its Recorder Custom Resource Definition.\r\nYou can use this as a recording destination for SSH sessions.\r\nThe recorder will connect to your tailnet and receive end-to-end-encrypted recordings using WireGuard just like any other tsrecorder devices running in your tailnet.

\n

Tailscale SSH session recordingis available for the Personal and Enterprise plans.

\n

Prerequisites

\n\n
\"tagOwners\": {\r\n   \t\"tag:k8s-operator\":   [],\r\n   \t\"tag:k8s-recorder\":   [\"tag:k8s-operator\"],\r\n}\n
\n\n

Deploy

\n
    \n
  1. Create your Recorder resource based on the below. Use the reference documentation\r\nto update it as required and then save it as recorder.yaml.
    2. \n
\n

The following spec will save recordings to a local temporary directory, and only persist for the lifetime of the pod.\r\nUse the s3 storage option shown below for durable storage.

\n
apiVersion: tailscale.com/v1alpha1\r\nkind: Recorder\r\nmetadata:\r\n  name: recorder\r\nspec:\r\n  enableUI: true\n
\n
    \n
  1. Apply the file:
    2. \n
\n
kubectl apply -f recorder.yaml\n
\n
    \n
  1. (Optional) wait for the recorder to become ready:
    2. \n
\n
kubectl wait --for condition=RecorderReady=true Recorder recorder\n
\n

For example, this command will return information similar to the following:

\n
recorder.tailscale.com/recorder condition met\n
\n
    \n
  1. (Optional) find the URL for the recorder's UI:
    2. \n
\n
kubectl get Recorder recorder\n
\n

For example, this command will return information similar to the following:

\n
NAME       STATUS            URL\r\nrecorder   RecorderCreated   https://recorder-0.tails-scales.ts.net\n
\n

Examples

\n

Static S3 credentials

\n

The following example:

\n\n
apiVersion: v1\r\nkind: Secret\r\nmetadata:\r\n  name: s3-auth\r\n  namespace: tailscale\r\nstringData:\r\n  AWS_ACCESS_KEY_ID: ABC...\r\n  AWS_SECRET_ACCESS_KEY: xyz123...\r\n---\r\napiVersion: tailscale.com/v1alpha1\r\nkind: Recorder\r\nmetadata:\r\n  name: recorder\r\nspec:\r\n  enableUI: true\r\n  tags:\r\n    - \"tag:k8s-recorder\"\r\n  storage:\r\n    s3:\r\n      endpoint: s3.us-east-1.amazonaws.com\r\n      bucket: tsrecorder-bucket\r\n      credentials:\r\n        secret:\r\n          name: s3-auth\n
\n

IAM roles for service accounts (IRSA)

\n

You can modify the above example to use IRSA for S3 credentials instead of static credentials stored in a Secret.

\n
    \n
  1. Follow the AWS instructions for IRSA. When you select the name and namespace of the ServiceAccount to attach your policy to, use the Tailscale Kubernetes Operator's namespace (usually tailscale) and a name of your choosing (the default ServiceAccount name is the same as the Recorder resource's name). This will be reflected in the trust policy document, for example:
    2. \n
\n
{\r\n     \"Version\": \"2012-10-17\",\r\n     \"Statement\": [\\\r\n       {\\\r\n         \"Effect\": \"Allow\",\\\r\n         \"Principal\": {\\\r\n           \"Federated\": \"arn:aws:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE\"\\\r\n         },\\\r\n         \"Action\": \"sts:AssumeRoleWithWebIdentity\",\\\r\n         \"Condition\": {\\\r\n           \"StringEquals\": {\\\r\n             \"oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub\": \"system:serviceaccount:tailscale:my-recorder\",\\\r\n             \"oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud\": \"sts.amazonaws.com\"\\\r\n           }\\\r\n         }\\\r\n       }\\\r\n     ]\r\n}\n
\n
    \n
  1. Use the Recorder field .spec.statefulSet.pod.serviceAccount to annotate its service account with the correct AWS role.
    2. \n
\n
apiVersion: tailscale.com/v1alpha1\r\nkind: Recorder\r\nmetadata:\r\n     name: recorder\r\nspec:\r\n     enableUI: true\r\n     tags:\r\n    - \"tag:k8s-recorder\"\r\nstorage:\r\n    s3:\r\n      endpoint: s3.us-east-1.amazonaws.com\r\n      bucket: tsrecorder-bucket\r\nstatefulSet:\r\n    pod:\r\n      serviceAccount:\r\n        name: my-recorder\r\n        annotations:\r\n          eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/my-s3-role\n
\n

Known issues and limitations

\n\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}