Telepresence

Telepresence uses two forms of credentials rooted in a single Certificate Authority (quictunnel.CA) to secure file-sharing and gRPC communication. The authentication enforcement level is tied to the manager's security.authentication.mode:

• disabled / permissive: Credentials are verified and failures are logged, but connections without credentials are still allowed (maintains backward compatibility).
• enforcing: No valid session credential is permitted for any file operation or connection.

Credential Types

1. X.509 session client certificate: Used for TLS-based transports like the QUIC tunnel. The Common Name (CN) is set to the sessionID.
2. Signed session token: A compact bearer string used for transports that cannot carry certificates (e.g., FTP PASS command or gRPC metadata on plaintext port-forwarded channels). The format is v1.<sessionID>.<expiry>.<base64url ECDSA-sig by the CA key>.

Telepresence offers two modes for attaching to workloads:

1. Sidecar Mode (Default): Uses a mutating webhook to inject an agent container into your pods. This requires a pod restart and modifies the workload's pod template.
2. Node-agent Mode: Runs as a node-pinned Kubernetes Job that enters the existing target pod's Linux namespaces from the outside. This requires no workload mutation and no pod restart.

When to use node-agent

• When mutating or restarting the workload is undesirable or disallowed (e.g., expensive startup times).
• When workloads are managed by an operator that conflicts with the sidecar webhook.
• In clusters where the agent-injector is disabled (agentInjector.enabled=false).

Trade-offs and Requirements

• Privilege: Node-agents require high privileges (hostPID: true, SYS_ADMIN, SYS_PTRACE, NET_ADMIN, and NET_RAW).
• Security Standards: The traffic-manager namespace must permit the privileged Pod Security Standard.
• Incompatibility: Clusters that reject hostPID (like GKE Autopilot) cannot run node-agents; you must use the sidecar mode there.

# To use node-agent for a specific attachment, use the --node-agent flag
telepresence intercept <service> --node-agent

# To use node-agent for wiretap
telepresence wiretap <service> --node-agent

# To use node-agent for ingest
telepresence ingest <service> --node-agent

To achieve RBAC-equivalent security on the QUIC path, authorization must be embedded within the client certificate, as the agent (which terminates the connection) is the only component that can enforce it.

Two implementation strategies were evaluated:

Option A: Session-wide certificate with namespace list

• Mechanism: The manager embeds an allowed set of namespaces in a single session certificate using Authorizer.CanPortForward. The agent verifies this list during the TLS handshake.
• Pros: Single certificate for the session.
• Cons: The scope is frozen for the certificate's lifetime (e.g., 24h via clientCertValidity). Revoking RBAC does not take effect until the certificate expires.

Option B: Per-agent certificates (Recommended)

• Mechanism: The manager provides a new RPC GetQuicAgentClientCert(session, podUID). This mints a short-lived certificate specifically for one agent, naming that agent's identity. The agent verifies that the presented certificate matches its own SNI.
• Pros:
  • Authorizes against the actual target.
  • Supports per-pod-name RBAC via CanPortForward's fallback.
  • Naturally short-lived (minutes instead of hours).
  • Composes well with session binding requirements.
• Cons: Requires one extra unary RPC per agent per session.

The framework uses rt.Fixture[T] to manage resources via declarative, memoized specs.

Key Concepts

• Memoization: rt.Get(t, f) returns a resource. If the resource exists and matches the spec, it is reused. If not, it is provisioned. A provisioning failure for a fixture will cause all subsequent tests requiring that fixture to be skipped.
• Mutation: rt.Mutate(t, f) is used when a test needs to change a shared resource (like a manager spec or a workload). It performs a Get followed by invalidation at the end of the test, ensuring the next test re-provisions the new state.
• Lazy Provisioning: Suites do not provision in SetupSuite. Resources are only provisioned when an accessor (like s.Manager()) is called. This allows filtered test runs to be extremely fast.
• Mutual Exclusivity: Manager specs are mutually exclusive. Provisioning a new spec invalidates all previous specs and connections, as the rollout replaces the pods used for port-forwarding.
• Workload Lifecycle: Workloads are always destroyed at the end of a run (even in dev mode) to prevent node resource exhaustion. If a workload manifest changes, it is deleted and recreated.
• Adoption: In dev mode (without RTEST_TEARDOWN), the framework attempts to 'adopt' existing namespaces, releases, and connections from previous runs to speed up subsequent tests.

The Telemount plugin allows remote directories from Kubernetes traffic agents to be mounted as Docker volumes in your local containers. This is used during attachment commands like telepresence ingest, intercept, replace, or wiretap.

Workflow:

1. The daemon starts a bridge mounter that proxies the traffic agent's SFTP server to the daemon's localhost.
2. When attaching a container (using --docker-run, --docker-build, or --docker-debug), Telepresence merges volume flags from the command line (-v, --volume, --mount) with volumes propagated from the remote pod's traffic agent. Command-line flags take priority.
3. For each volume, Telepresence executes docker create volume --driver=telemount, passing the SFTP proxy port.
4. The container is started with the resulting volumes attached.
5. Upon detachment, volumes are unmounted and removed, and the SFTP proxy is closed.

Configuration:

• The plugin registry, name, and tag can be configured via docker.telemount in config.yml.