# The YAML in this file should contain:
#
# items: An array of releases with the following attributes:
#     - version: The (optional) version number of the release, if applicable.
#     - date: >-
#         The date of the release in the format YYYY-MM-DD.
#         If the date is (SUPERSEDED), then the release didn't happen, which means
#         that its notes belong to the next release.
#     - notes: An array of noteworthy changes included in the release, each having the following attributes:
#         - type: The type of change, one of `bugfix`, `feature`, `security` or `change`.
#         - title: A short title of the noteworthy change.
#         - body: >-
#             Two or three sentences describing the change and why it
#             is noteworthy.  This is HTML, not plain text or
#             markdown.  It is handy to use YAML's ">-" feature to
#             allow line-wrapping.
#         - image: >-
#             The URL of an image that visually represents the
#             noteworthy change.  This path is relative to the
#             `release-notes` directory; if this file is
#             `FOO/releaseNotes.yml`, then the image paths are
#             relative to `FOO/release-notes/`.
#         - docs: The path to the documentation page where additional information can be found.
#
# For older changes, see CHANGELOG.OLD.md
items:
  - version: 2.33.0
    date: (TBD)
    notes:
      - type: feature
        title: HTTP intercepts can follow every workload selected by one Service
        body: >-
          A Kubernetes Service can route requests to more than one workload,
          such as stable and canary Deployments, while an intercept previously
          followed only the workload named by the user. HTTP intercepts
          without <code>--replace</code> now let each selected workload
          participate in one logical intercept, so filtered traffic reaches
          the same local handler regardless of which selected workload
          receives it. If the selected workloads or their traffic-agents
          cannot support shared interception, Telepresence warns and keeps
          the historical single-workload behavior instead of failing the
          intercept.
        docs: reference/attachments/cli
      - type: security
        title: Daemons listen on the loopback interface only
        body: >-
          The root daemon and the user daemon accepted connections on every
          network interface, so any host on the same network could reach
          their gRPC APIs. Both daemons now listen on 127.0.0.1 only. The
          managed root daemon installed by the macOS, Linux and Windows
          installers is bound the same way.
      - type: security
        title: The kubeauth daemon requires a token
        body: >-
          The kubeauth daemon served exec-plugin cluster credentials to any
          caller on the network. It now requires a random per-run token
          that only the daemon container receives, and its port file is
          readable only by the user.
      - type: change
        title: Unchanged intercept updates no longer rewrite the stored intercept
        body: >-
          The traffic-manager compares the result of an intercept update with the
          stored intercept and keeps the stored one when nothing changed, so
          no-op updates no longer bump the modification time or notify watchers.
      - type: change
        title: Agent updates roll out within the workload's allowed unavailability
        body: >-
          When a workload's agent configuration changes, the traffic-manager
          now replaces its pods in batches sized by the workload's
          <code>maxUnavailable</code>, waits for the replacements to become
          ready between batches, and defers while the workload is already
          rolling out. An eviction refused by a PodDisruptionBudget is retried
          for thirty seconds before the workload is restarted through its
          controller. A deferral is logged after a minute and, after five
          minutes, gives way to such a restart as well. Uninstalling the
          traffic-manager still removes every agent at once.
        docs: reference/cluster-config#agent-rollout-pacing
      - type: bugfix
        title: Traffic-agent recovers file-sharing credentials after a traffic-manager restart
        body: >-
          After a traffic-manager restart, an agent that re-registered with
          the new manager kept the previous manager's session-token
          verification key, because it fetched the QUIC CA only when its
          manager session started. In enforcing mode, clients were rejected
          with <code>fileshareauth: this agent requires a session
          credential</code> until the agent pod was replaced. The agent now
          fetches the CA again each time it re-registers, and retries a failed
          fetch until it succeeds or the manager session ends.
          The client likewise refetches the agent QUIC credentials after it
          reconnects to a restarted manager, so agent connections return to QUIC
          instead of staying on the port-forward fallback.
      - type: feature
        title: HTTP header filters can match one member of a list-valued header
        body: >-
          A header filter named <code>name[key]</code> matches the value of the
          member with that key in a header that holds a list of
          <code>key=value</code> members, such as <code>baggage</code>,
          <code>tracestate</code>, <code>cookie</code>, or
          <code>forwarded</code>. Developers who each select on their own
          member, for example <code>--http-header 'baggage[session]=alice-1'</code>
          and <code>--http-header 'baggage[session]=bob-2'</code>, can now
          intercept the same workload at the same time.
        docs: concepts/attachments
  - version: 2.32.3
    date: 2026-10-21
    notes:
      - type: bugfix
        title: Intercept creation no longer hangs on a denied workload watch
        body: >-
          A client whose attachment grant covers a single workload can create
          its intercept, but the traffic-manager denies the namespace-wide
          workload watch that the user daemon starts for it. The user daemon
          retried that denial forever, so the CLI hung after the intercept
          was already active. A denied or unmanaged namespace now ends the
          watch at once and the error reaches the caller, so the intercept
          command finishes and <code>telepresence list</code> reports the
          denial instead of an empty result.
        docs: https://github.com/telepresenceio/telepresence/pull/4341
      - type: bugfix
        title: Each connect phase gets its own timeout
        body: >-
          Connecting to the traffic-manager, fetching the remote client
          configuration, and starting the root daemon session shared one
          <code>trafficManagerConnect</code> timeout, so a slow but successful
          early phase could leave too little time for the next one and fail the
          connect. Each phase now starts with the full timeout.
      - type: bugfix
        title: The route-controller stops routing loops through deleted pod IPs
        body: >-
          On local clusters, in-cluster traffic to the IP of a deleted pod,
          typically a restarted traffic-manager, left the node through its
          default route, reached the workstation's TUN device, and was dialed
          again from the cluster, flooding the connection with tunnels until
          the client ran out of ports. The route-controller now also drops
          forwarded traffic to the node's own pod CIDRs when it is about to
          leave through the node's default route.
        docs: reference/route-controller
      - type: bugfix
        title: Argo CD syncs no longer hang on the pre-upgrade migration hook
        body: >-
          The <code>traffic-manager-migrate-statefulset</code> pre-upgrade hook
          Job runs with a dedicated ServiceAccount, Role and RoleBinding that
          the chart rendered as ordinary release resources. Helm creates
          release resources before it runs pre-upgrade hooks, so plain
          <code>helm upgrade</code> worked, but Argo CD runs pre-upgrade hooks
          in its PreSync phase on every sync, including the first, before any
          release resource exists. The hook pod could not be created and the
          sync hung. The three RBAC objects are now pre-upgrade hooks that
          sort before the Job, so they exist when it starts under both Helm
          and Argo CD, and they are removed together with the Job once it has
          succeeded.
  - version: 2.32.2
    date: 2026-10-08
    notes:
      - type: bugfix
        title: Root daemon no longer shuts down after a brief stall
        body: >-
          After a stall of more than six seconds, the root daemon could
          mistake its own heartbeat for a stale one and shut down. This was
          seen mainly on Windows. The user daemon then retried the lost
          connection forever while the session still looked connected. The
          heartbeat is now reliable, and if the root daemon exits, the user
          daemon quits as it does on <code>telepresence quit -s</code>. Run
          <code>telepresence connect</code> to start both daemons again.
        docs: https://github.com/telepresenceio/telepresence/issues/4332
      - type: bugfix
        title: Improve selected-intercept tunnel stability
        body: >-
          Selected-intercept tunnels now reconnect agent dial watchers with
          backoff, clean up abandoned forwards more carefully, use separate
          timeouts for agent connections and intercepted endpoints, and reject
          dial requests when responder capacity is full instead of letting
          work accumulate. The default for the <code>endpointDial</code>
          timeout is raised from 3 to 15 seconds, so a connection to a cluster
          address that is not yet accepting connections is retried for longer
          before it fails.
      - type: change
        title: Clearer diagnostics for slow or stalled selected intercepts
        body: >-
          The traffic-agent and the client now log a summary line, with the
          elapsed time and the identifiers needed to match both ends, when a
          selected HTTP intercept request, a client stream, or a dial response
          was slow or failed. The traffic-agent also stops waiting for a client
          that never answers a dial request once the client's own dial deadline
          plus a grace period has passed, instead of holding the request open.
  - version: 2.32.1
    date: 2026-09-25
    notes:
      - type: bugfix
        title: Chart hook Jobs accept chart versions with build metadata
        body: >-
          The <code>traffic-manager-migrate-statefulset</code> pre-upgrade hook
          and the <code>uninstall-agents</code> pre-delete hook built their
          <code>helm.sh/chart</code> pod label from the raw chart version. A
          version carrying SemVer build metadata produced a label with a
          <code>+</code>, and the API server rejected the Job, failing the
          upgrade or uninstall. This affects installations whose tooling appends
          build metadata to the chart version, most commonly Flux with an OCI
          chart source, where helm-controller adds the artifact digest. Plain
          <code>helm install</code> and <code>helm upgrade</code>, Flux with a
          HelmRepository source, and Argo CD in its default setup are not
          affected, and an installed traffic-manager keeps working. The
          pre-delete hook already had this flaw in 2.31.x; the pre-upgrade hook
          is new in 2.32.0. Both hooks now use the same sanitized label as the
          rest of the chart.
  - version: 2.32.0
    date: 2026-09-24
    notes:
      - type: feature
        title: Guided traffic-manager setup with telepresence setup
        body: >-
          The new <code>telepresence setup</code> command analyzes the
          cluster (install privileges, QUIC and node-agent viability,
          webhook reachability, namespace scale, routing conflicts, and any
          existing installation), asks only the questions the findings leave
          open, and then validates, writes, or applies a fully configured
          traffic-manager Helm install. <code>--output</code> produces a
          normal Helm values file for GitOps, <code>--input</code> re-runs
          without repeating prior decisions (and is also how every answer
          can be preset, keeping the command's own flag surface small), and
          <code>--apply</code> installs or upgrades with post-apply
          verification, including a real QUIC reachability check. When
          install privileges are missing, the report itemizes exactly what
          to hand to a cluster admin instead of a dead end, and
          <code>telepresence setup --format json</code> is a convenient
          attachment for bug reports. The interview also asks whether to
          enforce authentication, which RBAC grant to require, whether to
          enable Direct Connect, an external control endpoint using an
          existing TLS Secret or cert-manager, and whether older clients
          need access, so the client's cluster permissions can be minimized
          without hand-editing a values file.
        docs: reference/setup
      - type: feature
        title: External control endpoint for clients without Kubernetes API access
        body: >-
          The new Helm setting <code>externalEndpoint</code> publishes a TLS
          gRPC listener that serves only the traffic-manager's client-facing
          RPC surface, with per-method session-ownership enforcement and
          admission controls in front of token validation. A client
          configured with <code>cluster.managerAddress</code> (and
          optionally <code>cluster.managerServerCA</code>) dials it directly
          and makes no Kubernetes API requests at all; it authenticates with
          its kubeconfig's bearer token, or with its client certificate
          directly in the TLS handshake when no bearer source exists.
          Publishing the endpoint requires
          <code>security.authentication.mode: enforcing</code> and a
          persisted server certificate, from an existing TLS Secret or
          cert-manager. The documentation calls this approach Direct
          Connect.
        docs: reference/external-endpoint
      - type: feature
        title: Required grant for Telepresence-specific RBAC authorization
        body: >-
          The new Helm setting <code>security.authorization.requiredGrant</code>
          (<code>portforward</code>, <code>telepresence</code>, or
          <code>any</code>; default <code>any</code>) selects which RBAC
          grant the traffic-manager requires when it authorizes a caller:
          the legacy <code>pods/portforward</code> permission, Telepresence's
          own policy attributes -- <code>create</code> on
          <code>connections.telepresence.io</code> to connect, and
          <code>create</code> or <code>get</code> on
          <code>attachments.telepresence.io</code> to intercept or ingest a
          named workload -- or either. The chart renders client Roles to
          match, the manager logs a migration warning whenever a caller
          authorizes only via the legacy grant, and sessions and intercepts
          restored after a manager restart are re-authorized and rebuilt
          from their specifications.
        docs: reference/rbac
      - type: feature
        title: Clients connect to the traffic-manager by its fixed pod name
        body: >-
          The client now port-forwards directly to the
          <code>traffic-manager-0</code> pod, so the only Kubernetes
          permission a connection needs is <code>create</code> on
          <code>pods/portforward</code> for that one pod name. The previous
          discovery grants (get services, list pods) remain available as a
          fallback and are rendered while the new Helm setting
          <code>clientRbac.legacyAccess</code> is true (the default);
          pre-2.32 clients and installs that override <code>apiPort</code>
          still need them.
        docs: reference/rbac
      - type: feature
        title: Log gathering and namespace discovery through the traffic-manager
        body: >-
          <code>telepresence gather-logs</code> now streams traffic-manager
          and traffic-agent logs (and, with <code>--get-pod-yaml</code>, pod
          manifests) through the traffic-manager, which reads them on the
          client's behalf, and a client watching all namespaces receives the
          manager's managed-namespace list the same way. A client therefore
          no longer needs Kubernetes permissions to list pods, read
          <code>pods/log</code>, or list namespaces; log access is instead
          authorized by <code>get</code> on the <code>logs</code> and
          <code>logs/yaml</code> resources in <code>telepresence.io</code>,
          which the chart's client Roles grant. The streaming bounds are
          tunable through the new Helm setting <code>logStreaming</code>,
          and both features fall back to the old direct Kubernetes API
          access when the traffic-manager predates them.
        docs: reference/rbac
      - type: feature
        title: Choose the port that receives non-intercepted traffic
        body: >-
          The <code>telepresence.io/inject-inactive-port</code>
          annotation names the container port the traffic-agent forwards traffic
          to while no intercept is active, instead of the intercepted container
          port. It applies to workloads with exactly one intercepted container port.
        docs: reference/cluster-config
      - type: feature
        title: Completion for use flag
        body: >-
          Automcompletion for <code>use</code> flag now dynamically generates
          completions based on existing daemons.
      - type: change
        title: The traffic-manager runs as a StatefulSet with a fixed pod name
        body: >-
          The traffic-manager Deployment is now a single-replica StatefulSet
          whose pod is always named <code>traffic-manager-0</code>. A
          pre-upgrade hook migrates an existing Deployment install
          automatically; rolling back to an older chart requires uninstall
          and reinstall. Because a one-replica StatefulSet cannot surge a
          replacement pod, an image update includes a brief window with no
          ready manager -- client sessions survive it and re-establish with
          their intercepts intact.
      - type: change
        title: The deprecated --replace flag has been removed
        body: >-
          The <code>--replace</code> flag of <code>telepresence intercept</code>, deprecated
          since 2.22.0, has been removed. Use the <code>telepresence replace</code> command
          instead. The traffic-manager now ignores HTTP filters that older clients send
          along with a replace request.
      - type: change
        title: Agent watch streams omit container environments the client does not need
        body: >-
          The traffic-manager sent every container's environment variables with
          each agent update, which made reconnect snapshots large in namespaces
          with many pods. Clients now receive agent updates without the
          environment maps and fetch a full description only when an ingest or
          intercept needs one. Older clients keep receiving the full payloads.
      - type: change
        title: The traffic-agent reuses connections to HTTP intercept handlers
        body: >-
          Each request matched by an HTTP intercept opened a new tunnel to the
          workstation and closed it when the response ended. The traffic-agent now
          keeps a transport per intercept and protocol version, reuses its
          connections across requests, and reports tunnel traffic when a connection
          closes rather than after every request.
      - type: change
        title: Daemon logs name the reason a session ended
        body: >-
          When a user or root daemon session stops, the logs said only that it
          ended. Both daemons now cancel their session with a cause, such as a
          disconnect request or a failed initialization, and the session summary
          reports how long it ran, the cause, and any error, so a session that
          disappears can be traced to what stopped it.
      - type: bugfix
        title: Recover promptly from stalled manager sessions
        body: >-
          Manager keepalive failures now use the existing session repair path
          instead of ending the client session. Expired sessions recover
          immediately, while repeated transient failures trigger repair
          without dropping active intercepts.
      - type: bugfix
        title: Workload watch delivery survives cancelled and stalled subscribers
        body: >-
          The traffic-manager batches workload events and delivers them to every
          watching client. A client whose watch had ended, or one that stopped
          reading, could hold up delivery to all other clients. Cancelled watches
          are now skipped, a subscriber that does not read within ten seconds is
          dropped, and events are partitioned by namespace once per batch instead
          of once per subscriber.
      - type: bugfix
        title: Intercept-only lists no longer wait for the workload watcher
        body: >-
          <code>telepresence list --intercepts</code> built its rows from the
          workload watcher snapshot, so an active intercept was missing from the
          list while that snapshot was empty or slow to arrive. The list is now
          built from the current intercepts themselves, and workload details such
          as services and replica counts are added when the watcher has them.
      - type: bugfix
        title: Preserve agent images during concurrent pod injection
        body: >-
          The agent injector reused a cached sidecar config across concurrent
          pod admissions while serializing that config temporarily cleared
          creation-only fields such as the traffic-agent image. A concurrent
          admission could observe the cleared image and produce invalid
          traffic-agent and init-container patches with empty image fields.
          Serialization now strips those fields from a local copy, so parallel
          pod creation cannot corrupt the cached config or block a workload
          rollout.
      - type: bugfix
        title: Crossing between namespace-selector and cluster-wide scope restarts the traffic-manager
        body: >-
          A <code>helm upgrade</code> that added or removed the
          <code>namespaceSelector</code> of a live installation kept the
          running pod, which continued with the informer topology of its
          old scope and left workload watching -- and with it
          <code>telepresence list</code> and agent-config generation --
          broken until a manual restart. The scope is now stamped into the
          pod template, so an upgrade crossing that boundary rolls the
          deployment, exactly as a change to the static
          <code>namespaces</code> list always has. Changes within a
          selector are still picked up live, without a restart.
      - type: bugfix
        title: Intercepts work in namespaces created after a no-injector manager started
        body: >-
          With <code>agentInjector.enabled=false</code>, the traffic-manager
          only watched the namespaces that existed when its pod started.
          A managed namespace created later never got watchers, so every
          intercept of a workload there failed with <code>has no
          interceptable port</code> until the manager was restarted, and
          Service changes never refreshed already-generated agent
          configurations. The manager now follows namespace changes and
          keeps agent configurations up to date even when the
          agent-injector is disabled.
      - type: bugfix
        title: telepresence compose forwards --profile to docker compose
        body: >-
          The profiles given with <code>--profile</code> were applied when
          Telepresence loaded the project but never passed on to the
          <code>docker compose</code> command that starts the stack, so
          <code>telepresence compose --profile &lt;name&gt; up</code> reported
          "no service selected" and stopped. The stop that runs when an attached
          <code>up</code> is interrupted now carries the profiles too, so profiled
          services are stopped as well.
        docs: https://github.com/telepresenceio/telepresence/issues/4278
      - type: change
        title: Kubernetes client log lines no longer interrupt the terminal output
        body: >-
          Warnings returned by the API server and log lines from the Kubernetes client, such
          as client-side throttling notices, are written to <code>cli.log</code> instead of
          the terminal, where they broke the progress display of commands like
          <code>telepresence setup</code>. Setup also raises its request budget so the
          privilege probe no longer waits on throttling, and each probe's progress line
          now ends with its result.
      - type: bugfix
        title: Node-agent intercepts serve their volume mounts again
        body: >-
          Mounts made through a node-hosted traffic-agent failed with
          "Operation not permitted" over sshfs or "Permission denied" over
          fuseftp, because the agent's confined SFTP and FTP servers knew
          only the sidecar's fixed mounts tree and not the intercepted
          container's filesystem. Both servers now follow the node-agent's
          links into it, and mounted content is reachable again.
      - type: bugfix
        title: Ingest no longer waits out the intercept timeout before it starts
        body: >-
          The user daemon handled a new agent pod before telling the root daemon about
          it, so an ingest waited the full intercept timeout for a pod the root daemon
          did not know yet. The pod is now relayed first, and the ingest starts as soon
          as the agent is reachable.
      - type: change
        title: Direct agent connections no longer depend on a connect-time permission check
        body: >-
          Connecting no longer issues a <code>SelfSubjectAccessReview</code>
          for <code>pods/portforward</code> in every mapped namespace before
          reaching the traffic-manager. A QUIC direct path to an agent now
          works whether or not the client may create
          <code>pods/portforward</code>. An attachment in a namespace where
          the client may not create <code>pods/portforward</code> and the
          QUIC tunnel is unavailable now fails at once with a clear message
          instead of hanging. Against a traffic-manager at v2.32 or later,
          an explicit <code>--mapped-namespaces</code> list is likewise no
          longer probed with a <code>get pods</code> review per namespace.
      - type: feature
        title: Signed Windows binaries and installers
        body: >-
          Windows releases ship <code>telepresence.exe</code> and the MSI
          with timestamped Authenticode signatures from a SignPath
          Foundation certificate, so enterprises can allow the binary by
          publisher instead of per-run admin approval. The exes now also
          carry version metadata visible in Explorer's Properties dialog.
          The MSI is published for both amd64 and arm64, for Intune/GPO
          deployment.
          <a href="https://github.com/telepresenceio/telepresence/issues/4284">#4284</a>
        docs: install/client
      - type: change
        title: Windows MSI states its volume-mount prerequisites
        body: >-
          The MSI installs Telepresence and the daemon service only, so it
          now warns during interactive installation when WinFsp or
          SSHFS-Win is missing instead of installing silently without
          them. The install page documents the MSI, and the daemon's
          "sshfs is not installed" message on Windows names the two
          packages to install.
        docs: install/client
      - type: change
        title: Windows installer is an MSI for amd64 and arm64
        body: >-
          The setup bundle <code>telepresence-windows-amd64-setup.exe</code>
          is no longer published. <code>telepresence-windows-amd64.msi</code>
          and <code>telepresence-windows-arm64.msi</code> install
          Telepresence, the daemon service, and wintun; WinFsp and
          SSHFS-Win are installed separately for volume mounts.
        docs: install/client
      - type: bugfix
        title: Temporary volume mount directories are removed
        body: >-
          The user daemon now creates the <code>telfs-</code> mount
          directory under <code>intercept.mountsRoot</code> and removes it
          when the intercept or ingest ends, however the session ends, and
          sweeps abandoned empty ones at startup.
      - type: bugfix
        title: Linux package upgrades keep the root daemon service running
        body: >-
          Upgrading the <code>.rpm</code> package stopped and disabled
          <code>telepresence-rootd.service</code>, because the removed
          package's scriptlets ran after the new package had enabled it.
          The remove scriptlets now act only on a real removal, and an
          upgrade restarts the service so the new daemon runs.
        docs: install/client
      - type: bugfix
        title: Status names the embedded root daemon correctly
        body: >-
          When the user daemon runs with elevated privileges and embeds the
          root daemon, <code>telepresence status</code> and
          <code>telepresence version</code> printed that section under the
          user daemon's name. It is now labelled as the embedded root
          daemon.
      - type: bugfix
        title: Volume mounts on Windows find SSHFS-Win without PATH changes
        body: >-
          The SSHFS-Win installer does not add its <code>bin</code> directory
          to <code>PATH</code>, so intercepts installed from the MSI reported
          that sshfs was not installed. The daemon now also looks for
          <code>sshfs-win.exe</code> in SSHFS-Win's installation directory
          under Program Files, and the new <code>intercept.sshfsPath</code>
          setting names the executable explicitly for installations
          elsewhere.
        docs: install/client
      - type: bugfix
        title: Leaving an intercept on Windows unmounts its drive
        body: >-
          Ending an intercept with a volume mount on Windows only terminated the
          <code>sshfs-win</code> launcher and left its <code>sshfs</code> child,
          and with it the mounted drive, behind. The whole process tree is now
          terminated, so the drive disappears when the intercept ends.
  - version: 2.31.2
    date: 2026-08-02
    notes:
      - type: change
        title: Namespaced installs no longer read ingresses cluster-wide
        body: >-
          A namespace-scoped traffic-manager install now grants read access
          to <code>ingresses</code> through the per-namespace Roles instead
          of the <code>traffic-manager-cluster-wide-&lt;namespace&gt;</code>
          ClusterRole, which now only covers the cluster-scoped
          <code>servicecidrs</code> resource. The manager already watches
          ingresses per managed namespace in this mode, so no functionality
          changes.
      - type: bugfix
        title: telepresence apply and delete no longer panic with formatted output
        body: >-
          Running <code>telepresence apply</code> or <code>telepresence
          delete</code> with <code>--format json</code> panicked whenever an
          attachment was actually created or removed: the inner intercept or
          ingest operation emitted its own command-level output object, and
          the command's summary then collided with it. The summary is now
          the command's only output object.
      - type: bugfix
        title: Attach commands no longer fail when the pod to evict is already gone
        body: >-
          The traffic-manager evicts pods that lack an up-to-date
          traffic-agent so that the mutating webhook can inject one on
          recreation. When such a pod was replaced concurrently, for
          instance by a rollout that was still in flight, the eviction
          returned a "not found" error and commands like
          <code>telepresence intercept</code> failed. The traffic-manager
          now treats an already deleted pod as a successful eviction.
      - type: security
        title: The traffic-agent verifies the caller's session on its network ports
        body: >-
          A traffic-agent's gRPC, FTP, and SFTP ports were reachable by any
          pod in the cluster, and a caller declaring another client's session
          ID could receive that client's intercepted traffic. The
          traffic-manager now mints a session-scoped credential that the
          client presents on every agent connection, and the agent refuses a
          caller whose credential names a different session. With
          <code>security.authentication.mode=enforcing</code>, connections
          without a valid credential are rejected outright; in the other
          modes they are verified and logged, so existing clients are
          unaffected.
        docs: reference/authentication.md
      - type: security
        title: The traffic-agent's SFTP server is confined to the exports tree
        body: >-
          The SFTP server that backs <code>telepresence mount</code> resolved
          absolute paths against the whole traffic-agent container
          filesystem, so any peer that could reach the port could read files
          like <code>/etc/passwd</code>. It now serves only the tree of
          volumes exported for mounting, the same confinement the FTP server
          has always had, and symbolic links can no longer escape it.
        docs: reference/authentication.md
      - type: security
        title: Changing the log level requires an owned session
        body: >-
          The traffic-manager accepted a log-level change from any caller,
          although the new level propagated to the manager and every
          traffic-agent. The request now carries the client's session, whose
          ownership the manager verifies. Requests from older clients
          without a session are still honored unless
          <code>security.authentication.mode=enforcing</code>.
        docs: reference/authentication.md
      - type: bugfix
        title: The QUIC forwarder becomes ready under enforcing authentication
        body: >-
          With <code>security.authentication.mode=enforcing</code> and the
          QUIC tunnel enabled, the quic-forwarder's backend watch was
          rejected as unauthenticated, its allowlist never became ready, and
          clients silently fell back to port-forward transport. The watch is
          now exempt from authentication, like <code>Version</code> and the
          health checks, and the forwarder warns when its allowlist stays
          empty.
  - version: 2.31.1
    date: 2026-07-28
    notes:
      - type: feature
        title: Client-certificate authentication for cert-only kubeconfigs
        body: >-
          The traffic-manager can now authenticate clients whose kubeconfig
          credentials are a client certificate and therefore never produce a
          bearer token. An auth-only TLS listener on the manager, reachable
          through the client's existing port-forward, lets such a client
          present its certificate and be issued a short-lived session token;
          identity is derived from the certificate exactly as the Kubernetes
          API server would. This lets <code>enforcing</code> mode
          (<code>security.authentication.mode</code>) work on clusters, such
          as bare-metal and <code>kubeadm</code> installs, whose kubeconfigs
          are cert-only. It is enabled automatically whenever
          <code>security.authentication.mode</code> is
          <code>enforcing</code>, and can be turned off with the Helm value
          <code>security.authentication.x509.enabled: false</code>; it has no
          effect under any other mode. When active, the chart also creates a
          <code>RoleBinding</code> in <code>kube-system</code> to the stock
          <code>extension-apiserver-authentication-reader</code>
          <code>Role</code>, needed to read the cluster's client CA.
        docs: reference/authentication
  - version: 2.31.0
    date: 2026-07-22
    notes:
      - type: security
        title: Traffic-manager authentication and authorization
        body: >-
          The traffic-manager now authenticates every caller against the
          cluster's Kubernetes identities: traffic-agents present a
          projected, audience-bound ServiceAccount token, and clients forward
          the bearer token that their kubeconfig credentials resolve to
          (a static token, a token file, or an exec credential plugin). A
          session is bound to the identity that created it, so a caller can
          no longer act on another client's or agent's session regardless of
          mode, and creating an intercept now requires the caller's
          Kubernetes identity to hold RBAC access
          (<code>pods/portforward</code>) in the target namespace. This
          closes
          <a href="https://github.com/telepresenceio/telepresence/security/advisories/GHSA-j8j4-rw65-56r6">GHSA-j8j4-rw65-56r6</a>
          and
          <a href="https://github.com/telepresenceio/telepresence/security/advisories/GHSA-6j3h-rp73-6rvf">GHSA-6j3h-rp73-6rvf</a>.
        docs: reference/authentication
      - type: feature
        title: An authentication mode with opt-in enforcement
        body: >-
          The new Helm value <code>security.authentication.mode</code>
          controls how strictly the traffic-manager enforces the caller
          authentication above: <code>disabled</code> performs no token
          validation at all, <code>permissive</code> (the default) validates
          tokens and logs authorization decisions without ever rejecting a
          call, and <code>enforcing</code> rejects calls that present no
          valid token and intercepts the caller is not authorized for.
          Enforcement is an explicit opt-in so that upgrading the
          traffic-manager never breaks an existing installation; enable it
          once your client and agent fleet is running this release or later.
        docs: reference/authentication
      - type: feature
        title: Opt-in QUIC transport for the tunnel
        body: >-
          The traffic-manager can now expose a QUIC endpoint for the tunnel
          (Helm chart value <code>quicTunnel.enabled</code>). When the
          endpoint is reachable, the client automatically upgrades new
          tunneled connections to it, removing the head-of-line blocking that
          the shared port-forwarded gRPC connection imposes across flows. The
          port-forwarded gRPC transport remains the default and is used as the
          fallback whenever the QUIC endpoint is disabled or unreachable, and
          <code>telepresence status</code> now reports which transport is
          active.
      - type: feature
        title: Declarative workstation state with telepresence apply and delete
        body: >-
          The new <code>telepresence apply -f &lt;manifest&gt;</code> command
          brings the workstation to the state described by a YAML manifest: an
          optional connection with its flags, and a set of attachments
          (intercept, replace, ingest, or wiretap) complete with theirs. The
          manifest is validated against a JSON schema, apply is idempotent and
          re-creates attachments whose spec has drifted, and
          <code>--dry-run</code> reports what would change without touching
          anything. The <code>telepresence delete -f &lt;manifest&gt;</code>
          command tears the state down again, disconnecting only when the
          manifest declares the connection. Each attachment can also declare
          a <code>command</code>, a local process that apply starts detached
          once the attachment is up and keeps in sync on later applies, and
          that delete stops.
      - type: change
        title: One combined traffic-manager watcher per client
        body: >-
          The client now registers a single combined watcher stream
          (<code>WatchSessionEvents</code>) with the traffic-manager for
          everything related to workloads and attachments: agent pods and the
          client's intercepts. The user daemon relays the agent-pod events to
          the root daemon locally, halving the number of watcher streams the
          traffic-manager serves per client. Bulk container data
          (environments, mounts) is no longer streamed at all; it is fetched
          on demand when an attachment needs it. Both directions remain fully
          backward compatible: a new client degrades to the separate watchers
          against an older traffic-manager, and an older client keeps using
          them against a new one.
      - type: bugfix
        title: Ingests in other namespaces survive agent churn in the connected namespace
        body: >-
          An ingest into a namespace other than the connected one would lose
          its volume mounts and port-forwards as soon as any traffic-agent
          activity occurred in the connected namespace, because the agent
          snapshot bookkeeping treated every ingest as belonging to the
          connected namespace. The bookkeeping is now namespace-aware, and a
          same-named workload in the connected namespace can no longer be
          mistaken for the ingested one.
      - type: bugfix
        title: Progress rendering stops when the reported operation stops
        body: >-
          The TTY progress renderer's stop signal only worked for the first
          start/stop cycle, so a later progress-reporting operation in the
          same command could leave the render goroutine of a previous one
          alive, duplicating and re-rendering stale progress lines over
          subsequent output. Every stop now reliably ends its own cycle, and
          a lingering goroutine from a previous cycle can no longer silence
          the rendering of the next one.
      - type: bugfix
        title: Warning events are attributed to the right workload
        body: >-
          The event watch that explains why a workload fails to become ready
          matched any object whose name starts with the workload's name and a
          dash, so warnings for an unrelated sibling (for example a Service
          named <code>traffic-manager-something</code>) could be attributed
          to the workload, aborting an install wait with someone else's
          error. The prefix match now only accepts Pods and ReplicaSets, the
          kinds a workload owns.
  - version: 2.30.1
    date: 2026-07-17
    notes:
      - type: change
        title: Enabling node-agent mode makes it the client default
        body: >-
          Installing the traffic-manager with <code>nodeAgent.enabled=true</code>
          now also makes the node-agent the default mode for client
          attachments; previously the client-side default had to be enabled
          separately through the Helm chart's
          <code>client.nodeAgent.enabled</code> value. An explicitly set
          <code>client.nodeAgent.enabled</code> always wins, so administrators
          can keep the sidecar as the default while still allowing node-agent
          attachments by setting it to <code>false</code>.
        docs: reference/node-agent
      - type: bugfix
        title: Ports forwarded with --to-pod bind the loopback interface only
        body: >-
          The local listeners created for <code>--to-pod</code> ports bound
          all workstation interfaces, exposing the forwarded pod ports to the
          local network. They now bind the loopback interface, matching the
          flag's documented <code>localhost:PORT</code> contract. A
          containerized daemon is unaffected: its listeners stay on all
          interfaces of the daemon container's private network namespace,
          which docker port publishing requires.
  - version: 2.30.0
    date: 2026-07-14
    notes:
      - type: feature
        title: Node-hosted traffic-agent
        body: >-
          Telepresence can now attach to workloads without sidecar injection. When a
          cluster administrator enables node-agent mode in the
          traffic-manager's Helm chart (<code>nodeAgent.enabled=true</code>;
          the manager's namespace must admit privileged pods), intercepts,
          wiretaps, and ingests can be served by a node-pinned agent that
          attaches to the existing pod's Linux namespaces, leaving the
          workload unmodified and its pods unrestarted. The agent-injector
          webhook is not involved and may even be disabled entirely.
          Administrators can set the client default cluster-wide through the
          Helm chart's <code>client.nodeAgent.enabled</code> value;
          individual workstations may override it in <code>config.yml</code>,
          and a single attachment with the <code>--node-agent</code> flag.
        docs: reference/node-agent
      - type: change
        title: The engagement concept is renamed to attachment
        body: >-
          The umbrella term for the replace, intercept, ingest, and wiretap
          modes is now "attachment": you attach to a workload and detach from
          it. The new <code>telepresence detach</code> command replaces
          <code>telepresence leave</code>, which keeps working as a hidden,
          deprecated alias. Command output, such as the "ready to attach"
          messages from <code>telepresence list</code>, follows the new
          vocabulary.
        docs: reference/attachments/cli
      - type: change
        title: macOS volume mounts now use FUSE-T
        body: >-
          The recommended FUSE stack on macOS is now
          <a href="https://github.com/macos-fuse-t/fuse-t">FUSE-T</a> with its
          sshfs build (<code>brew install fuse-t fuse-t-sshfs</code>),
          replacing the deprecated macfuse/sshfs-mac combination. FUSE-T is
          kext-less, so it needs no kernel extension approval and no reboot.
          The client also terminates sshfs gracefully when a mount ends,
          giving it time to unmount; under FUSE-T, a killed sshfs left a
          stale NFS mount behind that prevented subsequent mounts.
        docs: troubleshooting
  - version: 2.29.3
    date: 2026-07-08
    notes:
      - type: bugfix
        title: Intercepts of multi-replica workloads deliver traffic from every pod
        body: >-
          An intercept of a workload with several replicas only delivered the
          traffic that reached the pod recorded on the intercept. The agents in
          the other pods redirected their share of the requests but had no way
          to hand them to the client, so those requests timed out. The
          traffic-manager now tells the client to open a dial watcher to every
          agent pod of an intercepted workload, regardless of the intercept's
          mechanism and filters, so traffic is delivered no matter which
          replica the service picks. Previously only intercepts with HTTP
          filters received this treatment.
      - type: bugfix
        title: HTTP-filtered wiretaps no longer block matching requests
        body: >-
          A wiretap with an HTTP filter (such as <code>--http-path-prefix</code>
          or <code>--http-header</code>) copied each matching request to the
          client but never forwarded the original to the application: the
          traffic-agent served the tap synchronously and deadlocked on its own
          copy of the request, so matching traffic was silently black-holed
          and callers timed out. Taps are now served concurrently and the
          request always proceeds to its real destination, whether that is the
          application container or an intercepting client.
  - version: 2.29.2
    date: 2026-07-04
    notes:
      - type: bugfix
        title: Pod subnets are now routed when the traffic-manager runs with hostNetwork
        body: >-
          A traffic-manager that runs with <code>hostNetwork: true</code> reports
          a node IP as its pod IP. This polluted the pod subnets that the
          <code>coverPodIPs</code> strategy derives with node subnets, and it made
          the client's pod connectivity check conclude that the workstation was
          already connected to the cluster network whenever the node IP happened
          to be directly reachable, leaving the real pod subnets unrouted so that
          all pod traffic (such as volume mounts) stalled. Host-network pods are
          now excluded from pod-subnet derivation, and the connectivity check is
          skipped when the manager's pod IP isn't covered by an announced pod
          subnet.
  - version: 2.29.1
    date: 2026-06-23
    notes:
      - type: bugfix
        title: Fix slow windows connection time with warp
        body: >-
          When running telepresence connect, we list all interfaces and use
          <code>net.InterfaceByIndex(idx)</code> on each of them. This function
          takes ~10ms so when you have LOTS of interfaces it takes a while.
      - type: bugfix
        title: Allow mapping namespaces that the traffic-manager does not manage
        body: >-
          Restores the ability to pass namespaces that the traffic-manager does
          not manage to <code>--mapped-namespaces</code>, so short DNS names
          (such as <code>svc.ns</code>) resolve for them again. A 2.29.0
          regression rejected such namespaces at connect. Mapping only affects
          the client's DNS — names are resolved by the traffic-manager or a
          traffic-agent, so management is not required. Targeting an unmanaged
          namespace for an engagement remains an error, and listing one now
          fails fast with that error instead of hanging until a timeout.
  - version: 2.29.0
    date: 2026-06-20
    notes:
      - type: feature
        title: Local traffic to intercepted destinations no longer round-trips through the cluster
        body: >-
          When the handler of one intercept dials a cluster destination that is
          covered by another of the client's active intercepts, the connection
          used to travel to the cluster only to arrive back at a local intercept
          handler. The root daemon now connects such traffic directly to the
          handler, both for the intercepted service's ClusterIP and for the pod
          IPs of all the intercepted workload's pods. The behavior is enabled by
          default and controlled with the new client configuration setting
          <code>intercept.localShortcut</code>. The shortcut is connection
          based and cannot evaluate header or path filters, so by default it
          applies to all intercepts, on the assumption that filters exist to
          limit how an intercept impacts others, not the developer's own
          traffic. Set <code>intercept.localShortcutIsGlobal</code> to false
          when local traffic must honor the filters exactly, at the cost of
          the round trip through the cluster. Wiretaps are never shortcut,
          since they receive a copy of the traffic rather than the traffic
          itself.
        docs: reference/config
      - type: feature
        title: Add a --format flag for consistent structured output
        body: >-
          A new global <code>--format=json|yaml|json-stream</code> flag
          produces clean, envelope-free structured output for every command,
          emitting the command's object directly instead of wrapping it in the
          <code>cmd</code>/<code>stdout</code>/<code>stderr</code>/<code>err</code>
          envelope that <code>--output</code> uses for some commands. On error
          it emits a clean object carrying a single <code>error</code> field on
          stdout and exits non-zero. <code>version</code>, <code>list</code>,
          <code>list-contexts</code>, and <code>list-namespaces</code> now
          produce script-friendly structured output under
          <code>--format</code>. The older <code>--output</code> flag keeps its
          exact previous behavior but is deprecated, and the two flags are
          mutually exclusive.
      - type: feature
        title: Make the agent-injector webhook reachable from outside the cluster
        body: >-
          The Helm chart can now expose the agent-injector mutating webhook to
          an API server that cannot reach an in-cluster Service, such as Amazon
          EKS with Calico where the control plane is outside the pod network.
          <code>agentInjector.service.type</code> and
          <code>agentInjector.service.nodePort</code> expose the injector
          Service (for example as a <code>NodePort</code>) independently of the
          chart-wide service type,
          <code>agentInjector.certificate.altNames</code> adds Subject
          Alternative Names to the webhook certificate, and
          <code>agentInjector.webhook.url</code> points the webhook at an
          external URL instead of the in-cluster Service.
        docs: troubleshooting#eks-calico-and-traffic-agent-injection-timeouts
      - type: feature
        title: Configure agent-injector webhook objectSelector
        body: >-
          The <code>agentInjector.webhook.objectSelector</code> Helm chart value accepts
          an optional Kubernetes label selector so the mutating admission webhook applies
          only to matching pods. This helps clusters that need to exclude system or
          third-party workloads from agent injection.
      - type: feature
        title: Resolve and reach Istio ServiceEntry hosts from the workstation
        body: >-
          Names that only a service mesh can resolve — such as Istio
          <code>ServiceEntry</code> hosts when Istio's DNS proxying is enabled —
          can now be used from the workstation. The traffic-agent's DNS lookups
          are subjected to the mesh's DNS interception, and the new Helm chart
          value <code>agent.serviceMesh.dialSubnets</code> lists address ranges
          (for example Istio's ServiceEntry auto-allocation range
          <code>240.240.0.0/16</code>) that the agent must dial through the mesh
          proxy. Engage a meshed workload, or connect with
          <code>--proxy-via</code> through one, and the ServiceEntry host
          resolves and routes via the mesh.
        docs: howtos/istio
      - type: feature
        title: Show ingress URLs for intercepted service ports
        body: >-
          The output of <code>telepresence intercept</code> and
          <code>telepresence list</code> now shows the ingress URLs through
          which an intercepted service port can be reached. When the intercept
          uses HTTP header filters, a ready-to-paste <code>curl</code> example
          with the matching <code>-H</code> flags is included, making it easy
          to send a request that is routed to the intercept handler on the
          workstation.
      - type: feature
        title: Report why the traffic-manager pod isn't ready during helm install
        body: >-
          When <code>telepresence helm install</code> or
          <code>telepresence helm upgrade</code> waits for the traffic-manager and
          its pod cannot become ready (a bad image, insufficient resources, or an
          unschedulable pod), the command now reports the underlying Kubernetes
          reason (for example <code>ImagePullBackOff</code>) and points at
          <code>kubectl describe pod</code>, instead of a confusing Helm rollback
          error. It also aborts as soon as a terminal failure is detected rather
          than waiting for the timeout.
      - type: feature
        title: Apply common labels to all Helm chart resources
        body: >-
          A new top-level <code>labels</code> Helm chart value merges custom labels into
          every resource created by the chart, including the traffic-manager Deployment,
          Services, RBAC, cert-manager Certificate and Issuer objects, and lifecycle
          hooks, while preserving the standard Telepresence label set.
      - type: feature
        title: Anonymous usage data collection
        body: >-
          Telepresence now emits anonymous usage reports from the CLI/user
          daemon and from the traffic-manager. Each report carries only an
          installation UUID, OS/architecture, the binary version, a
          code-defined topic such as <code>cmd.connect</code>, and a small
          map of safe-listed entries; it never carries cluster, namespace,
          workload, or address data. Reporting is enabled by default — the
          project has no conventional customers, so this data is the only
          signal we have for which features matter and what to fix. To opt
          out for one workstation set <code>usage.enabled: false</code> in
          <code>config.yml</code>, or drop an empty
          <code>usage-opt-out</code> marker file alongside the machine-wide
          config; the platform installers (macOS, Windows, Linux) manage
          that marker from a checkbox/env-var at install time. To opt out
          for an entire cluster, install the chart with
          <code>--set usage.enabled=false</code>.
        docs: reference/config/#usage
      - type: change
        title: Fail engagements when agent port-forwarding is disabled
        body: >-
          Setting <code>cluster.agentPortForward=false</code> disables all
          direct communication between the client and traffic-agents, so the
          cluster can only be used as a VPN. An attempt to intercept, replace,
          or ingest now fails immediately with an explanatory error instead of
          appearing to start and then never delivering traffic.
        docs: reference/config
      - type: change
        title: Clearer diagnostics when the agent-injector webhook is unreachable
        body: >-
          When an intercept times out waiting for the traffic-agent to arrive
          and the pods were created without a sidecar, the traffic-manager now
          explains that the Kubernetes API server is likely unable to reach the
          agent-injector webhook and points to the EKS/Calico remedies
          (<code>hostNetwork=true</code> or an externally exposed webhook). The
          troubleshooting guide gained a full decision path covering host
          networking, NodePort/LoadBalancer exposure, access restriction, TLS
          SAN requirements, and <code>failurePolicy</code> tradeoffs.
        docs: troubleshooting#eks-calico-and-traffic-agent-injection-timeouts
      - type: change
        title: Align traffic-manager RBAC with workloads Helm chart values
        body: >-
          Traffic-manager cluster- and namespace-scoped RBAC rules for Deployments,
          ReplicaSets, StatefulSets, and Argo Rollouts are now generated from the
          corresponding <code>workloads.*.enabled</code> settings. Disabling a workload
          kind no longer grants get, list, watch, or patch permissions for that kind.
      - type: bugfix
        title: Compose down no longer removes user-defined named volumes
        body: >-
          Tearing down a Compose project that engaged a service with
          replace or intercept previously removed named volumes even when
          <code>-v</code>/<code>--volumes</code> was not given, because the
          connection teardown ran <code>docker compose down --volumes</code>.
          Only Telepresence's own telemount-managed volumes are now removed,
          matching the behavior of <code>docker compose down</code>.
      - type: bugfix
        title: A failed agent injection no longer blocks pod creation
        body: >-
          When the agent-injector webhook returned an error, it denied the pod's
          creation. For an unfixable error, such as an invalid
          <code>telepresence.getambassador.io/inject-traffic-agent</code> annotation
          value, the ReplicaSet controller then retried the creation indefinitely
          and the workload's rollout stalled. Such errors now admit the pod without
          an agent and surface the reason as an admission warning. Transient errors,
          such as the agent configuration not being generatable yet because the
          traffic-manager just started, are now retried within the admission call so
          the agent is injected without denying the pod, and the config generation no
          longer holds a per-namespace lock that serialized simultaneous injections.
      - type: bugfix
        title: Application traffic no longer bypasses the service mesh in engaged pods
        body: >-
          The traffic-agent's own traffic is exempted from service-mesh
          processing using an iptables owner match, but the match was based on
          the agent's UID, which is inherited from the app container's
          securityContext (or defaults to root). An application sharing that
          UID had its outbound traffic silently bypass the mesh sidecar — no
          mTLS, telemetry, or policy enforcement. The agent container is now
          assigned a distinct primary group (default <code>7439</code>,
          overridable with <code>agent.securityContext.runAsGroup</code>) and
          the owner matches are group-based, so application traffic always
          traverses the mesh.
        docs: howtos/istio
      - type: bugfix
        title: Flush the DNS cache when the agent set changes
        body: >-
          The root daemon caches cluster DNS resolutions for up to a minute. If
          a workload and its Service were deleted and recreated, the Service
          could get a new ClusterIP while the daemon kept resolving the name to
          the old, now-defunct address, so traffic to it was silently dropped
          until the cache entry expired. The daemon now flushes the DNS cache
          whenever the set of traffic-agents changes, so a recreated workload's
          new ClusterIP is picked up immediately.
      - type: bugfix
        title: Keep a local DNS server reachable when its IP is in a routed subnet
        body: >-
          When a cluster subnet routed through Telepresence covers the
          workstation's DNS server address (for example an EKS node whose
          resolver lives at <code>172.31.0.2</code> while the pod subnet is
          <code>172.31.0.0/18</code>), queries to that server were captured by
          the TUN-device and tunnelled into the cluster, breaking name
          resolution for everything that isn't a cluster name. Telepresence now
          detects such DNS servers and adds a host route for them to the
          never-proxy set, keeping them reachable on their original interface.
        docs: reference/vpn
      - type: bugfix
        title: Pods using the network or highest address of a routed subnet are now reachable
        body: >-
          A subnet routed through Telepresence used to be assigned to the
          virtual network interface as an interface address. That made the
          subnet's network address resolve to the local host instead of
          entering the device, and made the kernel derive a broadcast entry for
          the subnet's highest address that refused unicast connections, so
          neither address could be reached. A CNI can assign either address to a
          pod — the traffic-manager landing on the network address even
          black-holed the connect-time DNS check — rendering that pod
          unreachable from the workstation. The interface now owns a single
          address from the virtual subnet and routes cluster subnets as plain
          routes, so every address in a routed subnet, its network and highest
          addresses included, is reachable.
        docs: reference/vpn
      - type: bugfix
        title: Remote mounts retry their initial connection to the traffic-agent
        body: >-
          When a remote mount was established right after its pod was created or
          restarted, the first connection to the freshly started traffic-agent
          could lose a race against the routing of the pod's new IP and fail.
          The failure was treated as permanent, so the daemon gave up and left
          the mount directory empty for the rest of the engagement. The daemon
          now retries the initial connection until the agent becomes reachable,
          bounded by the intercept timeout, so the mounts come back on their
          own.
      - type: bugfix
        title: Map IPv6 cluster addresses to IPv6 virtual IPs
        body: >-
          When proxy-via or automatic conflict resolution mapped a cluster IP to
          a virtual IP, an IPv6 address was forced into the IPv4 virtual subnet,
          producing a malformed virtual IP (such as
          <code>246.246.0.1313</code>) that broke the connection on IPv6-only
          and dual-stack clusters. Telepresence now allocates IPv6 virtual IPs
          from a dedicated IPv6 range, so IPv6 services and pods are reachable
          through a virtual IP just like their IPv4 counterparts.
        docs: reference/vpn
      - type: bugfix
        title: Route dual-stack clusters correctly with telepresence connect --docker
        body: >-
          In <code>--docker</code> mode the teleroute network gave every cluster
          route a single next-hop of one address family, so on a dual-stack
          cluster the IPv4 routes received an IPv6 next-hop (or the reverse) and
          became unusable. Each route is now given a next-hop of its own address
          family, so IPv4 and IPv6 cluster traffic is routed to the daemon
          correctly.
        docs: reference/vpn
      - type: bugfix
        title: Reliably inject agents into simultaneously created workloads
        body: >-
          The agent-injector resolved a pod's owner workload from the
          traffic-manager's informer cache. When many workloads were created
          at once, that cache could lag behind the API server, and pods whose
          owner had not yet been observed were admitted without a traffic-agent
          and never reconciled. The injector now confirms a cache miss with a
          direct API call, so bursts of simultaneously created workloads all
          receive their agent.
      - type: bugfix
        title: Ignore non-interface Linux routes
        body: >-
          Linux routing table scans now ignore blackhole, unreachable,
          prohibit, throw, and other routes that do not point to an
          interface before converting kernel routes into Telepresence routes.
          This prevents <code>telepresence connect</code> from failing with
          <code>routing table is inconsistent</code> on systems that have
          null routes, such as MicroK8s blackhole entries.
      - type: bugfix
        title: Pick the correct control-plane when connecting with --docker
        body: >-
          When connecting with <code>--docker</code>, Telepresence rewrites
          the kubeconfig server address to one reachable from the daemon
          container. If several Kubernetes control-planes shared a Docker
          network (for example, multiple kind clusters all attached to the
          <code>kind</code> network), it could pick the wrong one and fail
          the cluster check with a certificate error. It now prefers the
          container that actually publishes the kubeconfig's API port.
      - type: bugfix
        title: Traffic-agent DNS lookups honor the client's DNS lookup timeout
        body: >-
          The traffic-agent imposed a hard-coded 250 millisecond timeout on the
          DNS lookups it performs on behalf of a connected client. A resolution
          that needs search-path expansion, or that passes through a service-mesh
          DNS proxy such as Istio's, can easily take longer, causing spurious
          <code>NXDOMAIN</code> answers on the workstation. The agent now honors
          the deadline of the calling client, which is governed by the
          <code>dns.lookupTimeout</code> client setting.
      - type: bugfix
        title: macOS installer restarts the root daemon on upgrade
        body: >-
          On macOS, the <code>.pkg</code> installer's postinstall called
          <code>launchctl load -w</code>, which is a no-op when the daemon
          is already loaded. As a result, upgrading Telepresence wrote the
          new binary to disk but left the previous version of the root
          daemon running, so users had to restart the service (or reboot)
          to pick up the upgrade. The postinstall now unloads any existing
          instance before loading the new one, mirroring the symmetric
          stop+start the Windows installer already performs.
      - type: bugfix
        title: Clearer error when the cluster cannot be reached
        body: >-
          When the initial cluster check fails, Telepresence now reports, in
          plain language, that it could not reach the cluster — naming the
          kubeconfig context and API server, classifying the cause (host
          could not be resolved, connection refused, timed out, TLS or
          authentication failure), and suggesting to verify the kubeconfig
          context with <code>kubectl cluster-info</code> instead of surfacing
          a raw networking error.
      - type: bugfix
        title: Ingest workloads in mapped namespaces
        body: >-
          The <code>ingest</code> command now accepts <code>--namespace</code> to select
          the workload namespace for that engagement without changing the namespace used
          by <code>telepresence connect</code>. This allows a single connection with
          multiple mapped namespaces to run simultaneous ingests in different namespaces,
          while preserving the connected namespace as the default when no engagement
          namespace is specified. Mirrors the multi-namespace support added for
          <code>intercept</code>, <code>wiretap</code>, and <code>replace</code> in 2.28.0.
          The <code>leave</code> command also accepts <code>--namespace</code> to
          disambiguate ingests with the same workload name across mapped namespaces.
        docs: reference/engagements/cli
      - type: bugfix
        title: Reject unmanaged mapped namespaces
        body: >-
          Clients now reject <code>--mapped-namespaces</code> values that are outside
          the namespace set managed by a namespace-limited traffic-manager. Invalid
          mapped namespace requests now fail during connect with a helpful error
          instead of leaving the client connected with namespaces that cannot be
          handled by the in-cluster manager or traffic-agents.
        docs: reference/engagements/cli
      - type: bugfix
        title: Do not watch namespaces when only list is allowed
        body: >-
          The traffic-manager now checks both <code>list</code> and <code>watch</code>
          permissions on cluster-scoped <code>namespaces</code> before enabling dynamic
          namespace selection. Installations where the manager can list namespaces but
          not watch them (for example namespace-scoped RBAC while broader
          <code>list namespaces</code> is granted to other principals) no longer start a
          cluster-wide namespace informer and instead use the configured static namespace
          set, avoiding repeated <code>cannot watch resource "namespaces" at the cluster
          scope</code> errors in the logs.
      - type: bugfix
        title: Avoid transient traffic-agent readiness probe warnings
        body: >-
          The injected traffic-agent readiness probe now invokes a small
          traffic-agent readiness command instead of running <code>/bin/stat</code>
          directly. The command waits briefly for the readiness marker file,
          avoiding transient kubelet warnings when the agent startup creates
          the marker just after the probe executes.
  - version: 2.28.0
    date: 2026-05-11
    notes:
      - type: feature
        title: Intercept workloads in mapped namespaces
        body: >-
          The <code>intercept</code>, <code>wiretap</code>, and <code>replace</code>
          commands now accept <code>--namespace</code> to select the workload namespace
          for that engagement without changing the namespace used by
          <code>telepresence connect</code>. This allows a single connection with
          multiple mapped namespaces to run simultaneous personal HTTP intercepts in
          different namespaces, while preserving the connected namespace as the default
          when no engagement namespace is specified.
        docs: reference/engagements/cli
      - type: bugfix
        title: Preserve the default gateway for never-proxy routes
        body: >-
          Static routes installed for <code>--never-proxy</code> and
          <code>client.routing.neverProxySubnets</code> now preserve the matching
          default route gateway and source address. This prevents routed client
          environments, such as VMs that reach cluster networks through a default
          gateway, from receiving unusable on-link routes for never-proxied
          destinations.
      - type: bugfix
        title: Route also-proxy traffic through the traffic-manager
        body: >-
          Connections to addresses covered by <code>--also-proxy</code> or
          <code>client.routing.alsoProxySubnets</code> now use the traffic-manager
          tunnel unless the destination was explicitly translated by
          <code>--proxy-via</code>. This prevents arbitrary also-proxy traffic
          from being sent through an unrelated traffic-agent when mapped namespaces
          or active intercepts make an agent available.
        docs: reference/config#alsoproxysubnets
      - type: bugfix
        title: Use traffic-agent UID for init-container iptables rules
        body: >-
          Injected init containers now program owner-based iptables exclusions
          from the traffic-agent container's configured <code>runAsUser</code>
          when available, rather than the init process UID. This prevents pods
          that run application containers as the same user as the init container
          from accidentally bypassing mesh or agent routing rules.
      - type: bugfix
        title: Use fully-qualified traffic-manager hostnames for injected agents
        body: >-
          Injected traffic-agent configs now use a fully-qualified
          traffic-manager service DNS name when the cluster domain can be
          determined. This avoids relying on workload DNS search paths to resolve
          the manager service from another namespace, while preserving the
          existing short name fallback.
      - type: bugfix
        title: Avoid probing cleartext HTTP app protocols
        body: >-
          Traffic-agents now recognize common cleartext HTTP/1 Kubernetes Service
          <code>appProtocol</code> values such as <code>http</code> and
          <code>kubernetes.io/http</code>. This skips unnecessary TLS and HTTP/2
          probing for known HTTP/1 services, avoiding request latency when those
          probes cannot connect through the inactive proxy port.
      - type: bugfix
        title: Add /usr/sbin to systemd root daemon path
        body: >-
          Ensures /usr/sbin is in the PATH used by the root daemon when it is run
          by systemd.  This ensures iptables can be found by the daemon.
      - type: bugfix
        title: Reconnect the root daemon when its activity watcher fails
        body: >-
          The user daemon now reconnects to the root daemon when the root daemon's
          activity watcher fails, instead of leaving the session stuck until the
          user manually reconnects. Telepresence reuses the saved network
          configuration, clears stale DNS routing state before reconnecting, swaps
          in the new root daemon client, and re-posts DNS domains after reconnecting.
      - type: bugfix
        title: Handle pod IP output traffic in agent init
        body: >-
          Injected init containers now route pod IP output traffic through the
          same traffic-agent iptables chains used for loopback traffic. This
          lets service mesh sidecars and traffic-agent forwarding paths that
          connect to the application through the pod IP reach the expected
          redirect and DNAT rules, avoiding missed routing when the pod IP does
          not use the loopback interface.
      - type: bugfix
        title: Bound selected-intercept dial responders
        body: >-
          Selected-intercept dial responders are now capped so bursty workloads
          cannot make the client daemon fan out unbounded goroutines and gRPC
          tunnels. VIF open failures also return a plain nil device and tolerate
          partially initialized Linux devices during cleanup, making failed setup
          paths safer.
      - type: bugfix
        title: Use loopback address for kubeauth exec stub
        body: >-
          The patched kubeconfig that the root daemon uses embeds the user daemon's
          gRPC address for the <code>telepresence kubeauth</code> exec stub. When the
          user daemon listens on an unspecified address (for example <code>[::]:PORT</code>
          on a dual-stack host), that literal address was embedded as the dial target,
          which fails on macOS and causes exec-based authenticators such as kubelogin
          to return a broken pipe. The embedded address now normalizes an unspecified
          listener address to the matching loopback (<code>127.0.0.1</code> or
          <code>::1</code>) so the stub can always reach the user daemon.
        docs: https://github.com/telepresenceio/telepresence/issues/4107
      - type: bugfix
        title: Clear agent intercept snapshot on reconnect to prevent stale intercepts
        body: >-
          When the traffic-manager pod restarts, the traffic-agent reconnects but its
          local intercept snapshot (<code>snapMap</code>) retains entries from the old
          manager. Because the new manager sends an empty initial delta, the stale entries
          persist, causing tunnel failures and silently dropped connections. The connector
          side already cleared its snapshot on reconnect, but the agent was missed. The
          agent's repair function now clears the snapshot before reconnecting, matching the
          connector's behavior.
        docs: https://github.com/telepresenceio/telepresence/issues/4095
  - version: 2.27.4
    date: 2026-04-08
    notes:
      - type: bugfix
        title: Fix HTTP intercept routing across replicas
        body: >-
          Personal intercepts (header-based or path-based) on workloads with multiple replicas
          could fail to route traffic correctly because the traffic-manager only marked the pod
          that originally accepted the intercept as intercepted. The client therefore opened a
          dial watcher on a single pod, and requests that reached any other replica had no
          tunnel back to the developer's workstation. The traffic-manager now reports every pod
          of the intercepted workload as intercepted for HTTP and filter-based intercepts, the
          client eagerly establishes dial watchers on all those pods, and the traffic-agent
          fails open to the local app container if the intercept tunnel is momentarily
          unavailable.
  - version: 2.27.3
    date: 2026-03-29
    notes:
      - type: bugfix
        title: Fix Docker teleroute network subnet conflicts with Kubernetes cluster CIDRs
        body: >-
          When using <code>telepresence connect --docker</code> or <code>telepresence compose</code>,
          Docker's default IPAM could assign a subnet that overlaps with the Kubernetes cluster's
          service CIDR (e.g., <code>172.20.0.0/16</code> on EKS), causing network creation to fail.
          Telepresence now pre-computes a non-conflicting RFC 1918 subnet by checking both existing
          Docker networks and the cluster's routing CIDRs before creating the teleroute network.
        docs: https://github.com/telepresenceio/telepresence/issues/4005
      - type: bugfix
        title: Fix Docker Compose default network subnet conflicts with Kubernetes cluster CIDRs
        body: >-
          When using <code>telepresence compose</code>, Docker Compose auto-creates a default network
          whose subnet could overlap with Kubernetes cluster CIDRs, causing cluster traffic to be
          misrouted. Telepresence now configures the default network with an explicit non-conflicting
          subnet in the rendered compose file.
  - version: 2.27.2
    date: 2026-03-09
    notes:
      - type: bugfix
        title: Fix duplicate Section field in .deb package causing dpkg install failure
        body: >-
          The <code>.deb</code> package control file contained a duplicate <code>Section</code> field,
          which caused <code>dpkg -i</code> to fail with a parsing error. The <code>Section</code>
          field was specified both as a top-level <code>nfpm</code> default and explicitly under
          <code>deb.fields</code>. Moved to the top-level <code>section</code> key and removed the
          <code>deb.fields</code> block entirely.
        docs: https://github.com/telepresenceio/telepresence/issues/4073
  - version: 2.27.1
    date: 2026-03-08
    notes:
      - type: bugfix
        title: Fix duplicate Priority field in .deb package causing dpkg install failure
        body: >-
          The <code>.deb</code> package control file contained a duplicate <code>Priority</code> field,
          which caused <code>dpkg -i</code> to fail with a parsing error. This was caused by
          <code>nfpm</code> adding <code>Priority: optional</code> by default while the build
          configuration also specified it explicitly under <code>deb.fields</code>.
        docs: https://github.com/telepresenceio/telepresence/issues/4070
      - type: bugfix
        title: Fix ingest command lookup when container name is not specified
        body: >-
          The traffic manager now properly handles ingest lookups when using
          <code>telepresence ingest &lt;workload&gt; -- command</code> without specifying
          a container name. Previously, this would fail for workloads because the lookup
          couldn't find ingests with empty container names. The traffic manager now provides
          clearer error messages when a container name is required but not specified, and
          correctly resolves ingests for single-container workloads automatically.
        docs: https://github.com/telepresenceio/telepresence/issues/4067
  - version: 2.27.0
    date: 2026-02-28
    notes:
      - type: feature
        title: Add macOS package installer with root daemon as a system service
        body: >-
          A new macOS package installer (.pkg) is now available that installs Telepresence with the root daemon
          configured as a launchd service. This eliminates the need for elevated privileges when using Telepresence,
          as the daemon starts automatically at boot and runs in the background. Available for both Intel (amd64)
          and Apple Silicon (arm64) Macs.
        docs: install/client
      - type: feature
        title: Add Linux package installers with root daemon as a system service
        body: >-
          New Linux package installers (.deb for Debian/Ubuntu and .rpm for Fedora/RHEL) are now available that
          install Telepresence with the root daemon configured as a systemd service. This eliminates the need for
          elevated privileges when using Telepresence, as the service is enabled and started automatically during
          installation. Available for both amd64 and arm64 architectures.
        docs: install/client
      - type: feature
        title: Add Windows installer with root daemon as a system service
        body: >-
          A new Windows installer (.exe) is now available that installs Telepresence with the root daemon configured
          as a Windows service. The installer bundles WinFSP and SSHFS-Win dependencies for volume mount support,
          adds Telepresence to the system PATH, and optionally installs the TelepresenceDaemon service. This eliminates
          the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only
          due to dependency constraints.
        docs: install/client
      - type: feature
        title: Add route-controller DaemonSet to prevent routing loops on local clusters
        body: >-
          A new optional <code>route-controller</code> DaemonSet can be deployed alongside the traffic-manager
          on local Kubernetes clusters (Kind, minikube, k3d, Docker Desktop) to prevent routing loops caused by
          deleted or non-existent service ClusterIPs. It installs an iptables <code>FORWARD</code> chain
          <code>DROP</code> rule for the service CIDR on every node, and adds per-IP kernel blackhole routes
          when a Service is deleted. Enable it with <code>routeController.enabled=true</code> in the Helm chart.
        docs: reference/route-controller
      - type: feature
        title: Automatic cache cleanup on version change
        body: >-
          Telepresence now tracks its version in a version.json file in the cache directory. When the CLI detects
          that the major.minor version differs from the running binary, it automatically quits running daemons and
          clears stale cache entries (preserving logs). This prevents issues caused by leftover cache files from a
          previous version. Patch and pre-release version changes do not trigger a cache cleanup.
      - type: bugfix
        title: Cluster DNS not injected into containers started by telepresence compose
        body: >-
          When using <code>telepresence compose up</code>, cluster hostnames did not resolve inside the compose
          container because the daemon DNS IP and the tel2-search DNS search domain were not being added to the
          generated compose spec. DNS and dns_search are now correctly set for all engaged compose services.
        docs: https://github.com/telepresenceio/telepresence/issues/4053
  - version: 2.26.2
    date: 2026-02-14
    notes:
      - type: bugfix
        title: Dial 127.0.0.1 instead of 0.0.0.0 when connecting to local daemons
        body: >-
          When a VPN routes all private network addresses, dialing 0.0.0.0 gets routed through the VPN instead
          of reaching the locally running daemon. This causes Telepresence to report that no daemon is running
          even though the processes are active and listening. The client now dials 127.0.0.1 explicitly, and
          the Docker-published daemon port is bound to 127.0.0.1 to match.
        docs: https://github.com/telepresenceio/telepresence/issues/4048
      - type: bugfix
        title: Fix HTTP intercepts via telepresence compose failing when httpFilters or httpPaths are set
        body: >-
          The compose extension set HeaderFilters and PathFilters on the intercept spec but left the mechanism as "tcp".
          This caused the traffic manager to reject the intercept with "global TCP/UDP intercepts are disabled".
          The mechanism is now correctly switched to "http" when any HTTP filters are specified, matching the behavior
          of the CLI intercept command.
      - type: bugfix
        title: Fix "root daemon is embedded" error on Windows elevated terminals
        body: >-
          When running Telepresence in an elevated (administrator) terminal on Windows, commands like connect and
          loglevel failed with "root daemon is embedded". The user daemon now correctly delegates to the in-process
          root daemon session instead of returning an error.
        docs: https://github.com/telepresenceio/telepresence/issues/4049
      - type: bugfix
        title: Fix h2c (HTTP/2 cleartext) prior knowledge not working on transport
        body: >-
          Since Go 1.24, having both HTTP1 and UnencryptedHTTP2 enabled on an HTTP transport causes Go to
          default to HTTP/1.1 instead of using h2c prior knowledge. The transport now explicitly disables
          HTTP1 when UnencryptedHTTP2 is enabled, fixing h2c communication for both the default forwarding
          handler and intercepted traffic.
        docs: https://github.com/telepresenceio/telepresence/issues/4056
  - version: 2.26.1
    date: 2026-01-26
    notes:
      - type: bugfix
        title: Add support for "warning" as an alias for "warn" in log levels
        body: >-
          The "warning" alias for "warn" was the only acceptable value in the Helm chart, yet the traffic manager didn't accept it. This is
          now fixed so that both names are accepted by the Helm chart and by the traffic manager.
        docs: https://github.com/telepresenceio/telepresence/issues/4043
  - version: 2.26.0
    date: 2026-01-23
    notes:
      - type: feature
        title: Add ability for cluster admins to revoke other users' intercepts.
        body: |-
          The traffic-manager can now execute commands defined in the traffic-manager ConfigMap. As a result, clients that are authorized to
          update this ConfigMap can issue those commands.

          This mechanism lays the groundwork for distinguishing administrators from regular users in Telepresence. Administrators can be
          granted RBAC permissions that allow them to update the traffic-manager ConfigMap, while regular users cannot.

          The new command, `telepresence revoke <intercept-id>`, uses this mechanism to revoke the intercept associated with the specified
          ID.
        docs: reference/engagements/conflicts
      - type: feature
        title: Add support for overriding intercepts owned by inactive clients
        body: >-
          Introduce the Helm chart setting `intercept.inactiveBlockTimeout` that controls the maximum amount of time an intercept may be
          held by a client that is unreachable or inactive. Once this timeout is exceeded, the intercept no longer blocks conflicting
          intercepts and may be automatically removed when another client attempts to create a conflicting intercept.
        docs: reference/engagements/conflicts
      - type: feature
        title: Add support for sudo-rs
        body: >-
          Telepresence now supports running the root daemon using `sudo-rs`. This is necessary on Ubuntu where `sudo-rs` has become the
          default for `sudo`.
      - type: feature
        title: Add configuration to disable global TCP/UDP intercepts
        body: >-
          A new Helm chart configuration option `intercept.allowGlobalIntercepts` has been added to control
          whether global TCP/UDP intercepts are permitted. When set to `false`, only HTTP intercepts with
          header or path filters are allowed, preventing users from creating global intercepts that block
          other developers from intercepting the same port. This is particularly useful in shared development
          environments where multiple developers need to work on the same service simultaneously. The setting
          defaults to `true` to maintain full backward compatibility with existing deployments. When a user
          attempts to create a global intercept while the setting is disabled, they receive a helpful error
          message suggesting the use of `--http-header` or `--http-path-*` flags for HTTP-filtered intercepts.
        docs: reference/cluster_config#restricting_global_intercepts
      - type: feature
        title: Enhanced Traffic Manager Startup Reliability
        body: |-
          The Traffic Manager deployment now includes a `startupProbe` that accurately detects when the service is fully initialized and
          ready to handle traffic. This enhancement brings the following benefits:

          - **Prevents Premature Traffic Routing**: The manager only reports itself as ready after all configurations are loaded,
          eliminating potential race conditions
          - **Smoother Upgrades and Rollouts**: Deployment orchestration tools can reliably determine when the Traffic Manager is
          operational, improving overall installation stability

          This change is particularly beneficial in large clusters or complex networking environments where initialization may take longer
          than expected.
      - type: feature
        title: Support customizable daemon config file
        body: >-
          The config file for Telepresence is now configurable through the command-line flag `--config`.
          The `--config <agent config>` flag of the `telepresence genyaml` command was renamed to `--agent` to avoid confusion.
      - type: feature
        title: Support customizable daemon log file paths
        body: >-
          Log file paths for the Telepresence daemons are now configurable through the command-line flag `--logfile`
          that denotes a custom log file location or redirect of the log output to stdout/stderr. Two new log-level
          configuration entries for `cli` and `kubeAuthDaemon` are also introduced, expanding the existing log-level
          controls beyond just `userDaemon` and `rootDaemon`.
      - type: feature
        title: Add ability to exclude or include modifications made by other injectors when injecting the traffic agent.
        body: >-
          The Traffic Agent now has a new configuration option `agentInjector.mutationAware` that can be set to `false` to exclude
          modifications made by other injectors when injecting the traffic agent. Setting `agentInjector.mutationAware=true` requires
          `agentInjector.webhook.reinvocationPolicy=IfNeeded`. The default setting is `true`.
      - type: feature
        title: Add ability to disable the Traffic Agent's HTTP2/Clear-Text probing.
        body: >-
          The Traffic Agent now has a new configuration option `agent.enableH2cProbing` that can be set to `false` to disable the
          HTTP2/Clear-Text probing. The default setting is `true` to preserve backwards compatibility, but this will be changed to `false`
          in a future release.
      - type: feature
        title: Add ability to configure the Traffic Agent's retry interval for watching intercepts.
        body: >-
          The Traffic Agent's retry interval when it establishes its watcher for intercepts is now configurable using the Helm chart value
          `agent.watchRetryInterval`. The default retry interval was also increased from 2 seconds to 10 seconds to improve resilience when
          connections to the traffic manager are lost.
      - type: feature
        title: Make traffic-agent consumption metrics reporting optional.
        body: >-
          Metrics reporting for the traffic-agent can now be optionally enabled or disabled via the `agent.enableConsumptionMetrics` Helm
          chart value. The traffic-agent metrics will also be completely disabled when the Helm chart value `prometheus.port` is unset or
          zero.
          This change is intended to reduce the amount of unnecessary traffic generated by the traffic-agent when consumption metrics
          reporting is of no interest to the user.
      - type: feature
        title: Improved efficiency of traffic manager map updates.
        body: >-
          The watchable map has been refactored into a client/server model that supports delta-based updates. Where supported, gRPC now
          transmits only incremental changes instead of full snapshots, significantly reducing payload sizes. This improvement is especially
          important for large clusters, where full snapshots can be sizable and costly to transmit. Full snapshot streaming remains
          available as a backward-compatible fallback for clients that do not support delta methods.
      - type: change
        title: Use TCP/IP instead of Unix sockets for all communication between local processes.
        body: >-
          Telepresence now uses TCP/IP sockets for all communication between local processes. This change reduces the
          risk of socket-related errors caused by lingering sockets from previous Telepresence sessions. It also
          eliminates the difficulties of using Unix sockets for communication between a system service and user
          processes on Windows.
      - type: change
        title: Don't allow connect with --docker when client is configured with intercept.useFtp=true
        body: |-
          The `--docker` flag is not allowed when the client is configured with `intercept.useFtp=true` and an error is now generated
          instantly by the `telepresence connect --docker` command.

          The docker volume plugin cannot use FTP because it requires two ports: a fixed control port that Telepresence can proxy, and a
          dynamic data port (randomly chosen during connection) that Telepresence cannot proxy on-demand. The port-forwarder only forwards
          pre-configured ports and doesn't understand FTP's protocol. Consequently, FTP isn't allowed in this scenario. If it was, then when
          an FTP server tells the client to use an unpredictable second port for file transfers, Telepresence would block it—causing the
          connection to fail every time.
      - type: change
        title: Better names for the Telepresence Daemons
        body: |-
          Using the name xxx-foreground isn't very intuitive when talking about daemon processes. Yes, the command, when issued in a
          terminal, will start the daemon in foreground so the names of the commands does have some logic to them, but then again, starting
          in the foreground is the default behavior of any command. And when the same command is started from the CLI, it will be started in
          the background, despite its name.

          The daemons are therefore now renamed:

          - connector-foreground =&gt; userd
          - daemon-foreground =&gt; rootd
          - kubeauth-foreground =&gt; kubeauthd

          This also affects the Telepresence hidden CLI commands `telepresence daemon-foreground` and `telepresence connector-foreground`.
      - type: bugfix
        title: Add retry logic for tunnel connection attempts
        body: >-
          The tunnel dialer now uses a backoff-based retry mechanism when establishing connections. This ensures that dialing attempts for
          both TCP and UDP protocols persist if the target IP is not immediately ready to receive requests.
      - type: bugfix
        title: Retry mechanism for client tunnel creation
        body: >-
          The traffic agent now includes a backoff-based retry mechanism when establishing tunnel streams to a client. This prevents
          "no dial watcher" connection failures caused by a race condition where the tunnel request arrives before the client has fully
          initialized its communication channel.
      - type: bugfix
        title: Fix "close of closed channel" panic in the root daemon process.
        body: >-
          The root daemon process would sometimes panic with "close of closed channel" due to a race condition in the DNS cache logic.
          This issue has been fixed.
  - version: 2.25.2
    date: 2025-12-26
    notes:
      - type: bugfix
        title: Ensure that the exit code from a docker command becomes the exit code of the Telepresence command.
        body: >-
          When running a Docker command using `telepresence docker-run` or `telepresence curl`, the exit code would be 1 for all non-zero
          exit codes from the Docker command. This has been fixed so that the exit code from the Docker command becomes the exit code of the
          Telepresence command.
      - type: bugfix
        title: Fix a bug causing truncation of command text when generating external command help.
        body: >-
          The Telepresence CLI would truncate the command text when generating help for external commands such as `docker compose` that
          had text spanning more than one line. This has been fixed so that the full command text is displayed.
      - type: bugfix
        title: Fix schema for agent.image.pullSecrets
        body: >-
          The `agent.image.pullSecrets` is referenced by the helm chart's deployment.yaml but was previously disallowed by the schema file.
  - version: 2.25.1
    date: 2025-11-10
    notes:
      - type: bugfix
        title: Volumes did not mount correctly when using `telepresence connect --docker` when Docker had IPv6 enabled.
        body: >-
          Telepresence failed to mount volumes after connecting with `telepresence connect --docker` when Docker Engine had IPv6 enabled in
          its default bridge network. Disabling IPv6 in the Telepresence client configuration did not resolve the issue. This was fixed in
          Telepresence Volume Plugin "telemount" version 0.3.2, which circumvented a [bug in sshfs](https://github.com/libfuse/sshfs/issues/335).
          Additionally, the volume plugin will no longer use IPv6 when the client configuration `docker.enableIPv6` is set to `false`.
      - type: bugfix
        title: Remove unnecessary setcap from traffic binary
        body: >-
          The setcap capability (cap_net_bind_service) was removed from the traffic binary build process.
          This capability was originally added to allow the binary to bind to privileged ports, specifically
          port 443 for the mutating webhook. Since version 2.24.0, the default mutating webhook port was
          changed to 8443 (a non-privileged port), making this capability unnecessary. Removing it simplifies
          the build process and reduces the security surface area.
  - version: 2.25.0
    date: 2025-10-16
    notes:
      - type: feature
        title: HTTP Intercepts with HTTP header and path filtering
        body: |-
          Telepresence now supports HTTP Intercepts, enabling fine-grained HTTP traffic filtering for intercepts.
          Users can intercept only specific HTTP requests based on headers and URL paths using the new `--http-header`,
          `--http-path-prefix`, `--http-path-equal`, and `--http-path-regex` flags. This allows multiple developers
          to work on the same service simultaneously by intercepting only their specific traffic patterns, rather than
          intercepting all traffic to a service.

          **Routing Precedence Model**: Header-based intercepts take priority over path-only intercepts. When multiple
          intercepts are active on the same workload, requests are evaluated against header-based filters first, then
          path-only filters. This enables different developers to use header-based personal intercepts (e.g.,
          `x-user=alice`) while others use path-based intercepts (e.g., `/admin/*`) without conflicts.

          **Conflict Detection**: Intercepts conflict only when their filters would route the same traffic to different
          destinations. Key rules:

          - Different header values (e.g., `X-User=adam` vs `X-User=bertil`) do NOT conflict
          - Header filters use subset logic: `X-User=adam` conflicts with `X-User=adam, X-Session=123` (first is subset)
          - Same headers with different paths do NOT conflict: `X-User=adam + /api/*` vs `X-User=adam + /admin/*`
          - Path-only intercepts operate at a lower priority tier than header-based intercepts

          The feature maintains full backward compatibility with existing TCP intercepts.
        docs: howtos/engage#intercept-your-application
      - type: feature
        title: TLS/mTLS Intercept Support
        body: |-
          Support was added for HTTP-filtered intercepts on applications using TLS/mTLS encryption. The new functionality enables
          Telepresence to decrypt and inspect encrypted traffic by accessing TLS certificates, facilitating debugging and testing of secure
          applications.

          Certificates can be accessed via mounted volumes or Kubernetes secrets in the same namespace. New annotations
          (`telepresence.io/downstream-cert-path` and `telepresence.io/downstream-cert-secret`) allow configuration of certificate paths or
          secrets for decrypting traffic on specified ports. For mTLS, the `telepresence.io/upstream-cert-` annotation prefix supports
          re-encryption of upstream traffic using client-side certificates.

          For self-signed certificates, the `telepresence.io/upstream-insecure-skip-verify` annotation bypasses verification, enabling
          HTTP-filtered intercepts in development environments. The `--plaintext` option allows unencrypted traffic during intercepts or
          wiretaps.
        docs: howtos/mtls
      - type: feature
        title: Add MCP server to Telepresence CLI
        body: >-
          The Telepresence CLI now includes a lightweight MCP server that can be used to allow local AI agents to execute
          some CLI commands, such as connecting to a traffic manager, listing interceptable apps, and creating an intercept.
          The server can be enabled using the new `telepresence mcp claude enable` or `telepresence mcp vscode enable` commands.
      - type: feature
        title: Enhance Resilience of Engagements During Traffic-Manager Redeploys
        body: >-
          The telepresence client and traffic-agent now automatically reconnect to the traffic-manager after a restart.
          Upon reconnection, they share their current state, ensuring ongoing engagements remain uninterrupted. This
          improvement minimizes user impact during traffic-manager upgrades.
      - type: feature
        title: Add support for IPv6 and dual-stack when using `telepresence connect --docker`
        body: |-
          Telepresence now supports using `telepresence connect --docker` together with Kubernetes single-stack IPv4
          networking, single-stack IPv6 networking, or dual-stack networking with both network families. Both are
          enabled by default, but can be disabled by setting the `client.docker.enableIPv4` or `client.docker.enableIPv6`
          to false in the Helm chart, or by using the corresponding settings `docker.enableIPv4` or `docker.enableIPv6`
          the client configuration file.

          The new dual-stack support requires the teleroute network plugin 0.5.0 or later. The client will install this
          version automatically unless you work in an air-gapped environment.
      - type: feature
        title: RESTful API Service Reintroduced with HTTP Filtering Support
        body: >-
          The Telepresence RESTful API service has been restored with enhanced support for HTTP header and path filtering. This service
          enables workloads to programmatically query whether they should handle requests based on active intercepts.
          Added `--metadata` flag allows attaching custom metadata to intercepts that can be retrieved through the API endpoints.
          The API server is now accessible via `TELEPRESENCE_API_HOST` and `TELEPRESENCE_API_PORT` environment variables in both cluster
          pods and local intercept handlers.
        docs: reference/restapi
      - type: feature
        title: More efficient DNS handling in the traffic-manager
        body: |-
          Telepresence will no longer send DNS queries for A and AAAA records to the traffic-manager. Instead, it will
          send a single query for the name and then derive the record type from the type of IP address (IPv4 or IPv6) in
          the response. This reduces the number of DNS queries sent to the cluster's DNS server and makes the behavior
          more consistent with the `net.LookupNetIP` function in the Go standard library, which the traffic-manager
          ultimately uses.

          The lookups will now be performed exclusively by the traffic-manager, never by the traffic-agent. This means
          that traffic-agents with special DNS configurations might stop working. If this is a problem, the old behavior
          can be restored by setting the `client.dns.useComplexLookup` parameter in the Helm chart or the
          `dns.useComplexLookup` parameter in the client configuration file.
      - type: feature
        title: Updated Helm chart to include keywords and the source repository URL.
        body: >-
          Improves the Helm chart's discoverability on platforms like Artifact Hub and
          automatically adds a direct link to the source code for users, providing better context.
      - type: change
        title: Telepresence client now requires a traffic manager version of at least 2.21.0.
        body: >-
          The traffic manager is now required to be at least version 2.21.0. Versions earlier than 2.21.0 will no
          longer work. The reason for this is that implementing the new reconnect behavior would require too much
          conditional code with older traffic-managers, and a lot of functionality wouldn't work anyway.
      - type: change
        title: Build binaries and docker images that are stripped from dwarf and debug info.
        body: >-
          The Telepresence binaries and docker images are now built with the `-w -s` flags, which strip the debug
          symbols and the DWARF information. This reduces the size of the binaries and docker images by about 50MB.
          Debug binaries can be built using `DEBUG=1 make build`.
  - version: 2.24.1
    date: 2025-09-05
    notes:
      - type: bugfix
        title: Fix invalid filename generated by telepresence gather-logs command
        body: >-
          The `telepresence gather-logs` command would generate a filename that was invalid on Windows unless the user
          specified the filename explicitly using the `--output-file` flag. This was fixed using a more condensed
          format for the timestamp in the filename.
        docs: https://github.com/telepresenceio/telepresence/issues/3956
      - type: bugfix
        title: A `telepresence connect --docker` fails kubeconfig points to a port-forwarded localhost
        body: >-
          Telepresence would fail to connect to a cluster from within a container if the kubeconfig pointed to a
          port-forwarded localhost because that localhost is not reachable from within the container. This situation is
          now detected so that the address used from within the container has "localhost" replaced with
          "host.docker.internal", or an alternative alias configured by the user using the new `docker.hostGateway`
          parameter in the client configuration.
      - type: bugfix
        title: A `telepresence connect --docker` would fail with some k3s configurations
        body: >-
          Telepresence would fail to connect to a k3s cluster unless the cluster's IP was a loopback address. This is
          now changed so that any IP:port combination is accepted as long as a container can be found that defines a
          mapping for it.
      - type: bugfix
        title: Restore default value for agent-state.yaml in the traffic-manager configmap
        body: >-
          The value was previously an empty string which caused problems when when Argo CD tried to synchronize it.
        docs: https://github.com/telepresenceio/telepresence/pull/3953
  - version: 2.24.0
    date: 2025-08-25
    notes:
      - type: feature
        title: Support for Docker Compose
        body: >-
          Telepresence now supports integration with Docker Compose. It connects to and interacts with cluster resources
          by utilizing `x-tele` extensions within a Docker Compose specification. These extensions configure
          your local services to effectively act as handlers for Telepresence connections, providing them with the
          necessary access to the traffic, volumes, and environment of the engaged container.
        docs: howtos/docker-compose
      - type: feature
        title: Serve up a web-page with telepresence serve.
        body: >-
          A new `telepresence serve <service>` command was added that starts a web browser on the specified service. The
          command is especially useful when used in combination with `telepresence connect --docker` because it will
          then expose the given service on a random port on localhost.
        docs: reference/cli/telepresence_serve
      - type: feature
        title: Add ability to optionally clean up sidecars that have been idle above a specified duration
        body: >-
          Added configuration parameter `agent.maxIdleTime` to the Helm Chart, to control how long a sidecar can be idle before it is cleaned up.
          The updating of latestEngagementTime is done every 1m in the Remain Call, which is now called every 1min, compared to every 5s in the past.
          The agent state (containing latestEngagementTime) is updated in memory, and lazily persisted to the traffic-manager configmap every 2min.
          Removal of the sidecar is also done in the Remain Call, if the sidecar has been idle for longer than the configured `agent.maxIdleTime`.
      - type: feature
        title: Add option to drop client label in prometheus metrics for GDPR compliance
        docs: https://github.com/telepresenceio/telepresence/issues/3491
        body: >-
          The Helm Chart now has a `prometheus.dropClientLabel` option that can be set to true to drop the client label from the prometheus metrics.
          This is useful for GDPR compliance, as the client label contains personal data, which can be potentially problematic, i.e allowing the ability to
          track the working times of an individual.
      - type: feature
        title: Prefix metrics with "telepresence_"
        docs: https://github.com/telepresenceio/telepresence/issues/3920
        body: Avoids metric conflicts and makes these more explicit to improve search in observability stacks.
      - type: feature
        title: CLI documentation in markdown format
        body: >-
          The Telepresence CLI is now capable of generating its own documentation in markdown format using the
          new `telepresence man-pages` command. The generated documentation is included under the heading "Telepresence
          CLI" in the the Telepresence reference documentation.
        docs: reference/cli/telepresence
      - type: feature
        title: Service Port Rerouting
        body: >-
          The telepresence connect command introduces a new `--reroute-remote <host>:<port>:<new-port>[/{tcp|udp}]` flag,
          allowing users to remap service ports. This feature redirects requests sent to `<host>:<new-port>` to
          `<host>:<port>` within the Telepresence VIF. The flag can be repeated.
      - type: feature
        title: Local Port Rerouting
        body: >-
          The telepresence connect command introduces a new `--reroute-local <local-port>:<host>:<port>[/{tcp|udp}]` flag,
          allowing users to redirect requests sent to ports on localhost to arbitrary service ports. This feature enables
          requests sent to `localhost:<local-port>` to be redirected to `<host:port>`. The flag can be repeated.
      - type: feature
        title: Add information about using Kubernetes auth plugins when using Telepresence CLI in a container
        body: >-
          Kubernetes, and hence the Telepresence CLI, must have access to auth plugins declared in the kubeconfig. A
          section was added to the documentation explaining how to achieve this when using the Telepresence CLI in a
          container.
        docs: reference/inside-container#kubernetes-auth-plugins
      - type: feature
        title: Add log directory to the output of `telepresence config view`
        body: >-
          The `telepresence config view` command now includes the path to the directory where the Telepresence logs are
          stored.
      - type: change
        title: The default port for the mutating webhook is now 8443. It used to be 443
        body: >-
          Port numbers below 1000 are reserved for privileged processes and are often restricted by firewalls.
          Consequently, the default port for the mutating webhook was changed from 443 to 8443. You can override this
          default port using the agentInjector.webhook.port value in the Helm Chart. This change is particularly
          significant for clusters using Telepresence, where firewall rules limit the admission webhook's access to
          worker nodes, such as in an Amazon EKS cluster.
  - version: 2.23.6
    date: 2025-07-23
    notes:
      - type: bugfix
        title: Public DNS names aren't resolved from local docker application started by Telepresence
        body: >-
          A container running using `telepresence docker-run` or `telepresence <engage-type> --docker-run` was not able to resolve public
          DNS names such as "google.com". The problem is caused by an undocumented behavior in Docker's internal DNS-resolver when the
          `--dns` flag is used in conjunction with the teleroute network, where the DNS-server no longer finds public names even thought
          another bridge network is connected. The problem was solved by using a fallback resolver in the Telepresence DNS resolver.
  - version: 2.23.5
    date: 2025-07-20
    notes:
      - type: bugfix
        title: Let docker.Start pass on --interactive to docker start.
        body: >-
          An `-i` or `--interactive` flag given when the user runs a container with telepresence must be propagated to
          `docker start` to attach `stdin`.
  - version: 2.23.4
    date: 2025-07-18
    notes:
      - type: bugfix
        title: Never truncate meaningful output from a command
        body: >-
          The new human-friendly output using a progress reporter would sometimes truncate error output. This is no
          longer the case. Instead, all output will be wrapped.
      - type: bugfix
        title: Typo in client mount-policy "RemoteReadonly" should be "RemoteReadOnly"
        body: >-
          The Helm Chart correctly expects the remote read-only mount policy to be `RemoteReadOnly`, but the client
          expected it to be `RemoteReadonly` (without a leading capital letter in the word "only").
      - type: bugfix
        title: DNS server does not respect semicolons as comments in resolv.conf files
        body: >-
          Telepresence does not work correctly if `/etc/resolv.conf` contains semicolons, which are valid comments as of
          [linux manpage](https://man7.org/linux/man-pages/man5/resolv.conf.5.html).
        docs: https://github.com/telepresenceio/telepresence/issues/3908
      - type: bugfix
        title: Use NXDOMAIN instead SERVFAIL for DNS recursion errors (timeouts)
        body: >-
          A DNS for a single label name that fails in a minikube - or another type of local cluster - will sometimes
          result in a recursive lookup on the host. Without any type of recursion detection, this lookup will timeout
          waiting for itself. Previously, this resulted in a `SERVFAIL` from the cluster DNS, which triggered renewed
          lookup attempts that never stopped. This is now changed so that the same type of timeouts instead results
          in an `NXDOMAIN` error that doesn't trigger renewed attempts.

          Also, the recursion check now handles that the cluster's DNS adds suffixes from its search-path.
        docs: reference/config#recursioncheck
  - version: 2.23.3
    date: 2025-07-07
    notes:
      - type: bugfix
        title: Fix tunnel channel reuse in traffic-agent to prevent connection failures
        body: >-
          Previously, when a tunnel became active, the map maintained by the traffic-agent containing channel values for
          agent-to-client tunnels wasn't cleared. This resulted in closed channels remaining in the map. When port
          numbers were eventually reused, these stale entries would be discovered and their closed channels would cause
          immediate stream termination, leading to data loss.
      - type: bugfix
        title: The -p flags would have no effect in combination with --docker-run
        body: |-
          When using `telepresence <engage> --docker-run` with a `-p <port spec>` flag, the Docker driver silently
          ignored the port specification. This occurred because the `--network=<teleroute network>` flag disabled both
          additional network directives and the default bridge network (which is normally used when no network is
          specified). This has been resolved by:

          1. Adding the teleroute network after container creation instead of using a flag
          2. Replacing the single `docker run` command with a sequence of:
             - `docker create`
             - Network addition
             - `docker start`
      - type: bugfix
        title: Requests lost when using wiretap
        body: >-
          Wiretap connection `Close` and `Write` could sometimes be out of sync, so that the `Close` would be executed
          before the `Write`, causing a "read/write on closed pipe" error and loss of data.
  - version: 2.23.2
    date: 2025-06-27
    notes:
      - type: bugfix
        title: Adding an alsoProxy subnet with 32-bit mask no longer works on macOS
        body: >-
          Routing improvements introduced in 2.23.0 surfaced a problem when using special handling of submets with
          32-bit masks. The special handling now causes problems on macOS. The logic is now conditioned to only run
          under linux since it's no longer needed on other operating systems.
      - type: bugfix
        title: The gather-logs command produces no cluster-side logs when connected with --docker
        body: >-
          The `telepresence gather-logs` command did not include cluster-side logs when connected using `--docker`,
          because it tried to store such logs in a temporary directory created by the CLI. The directory was not mounted
          in the daemon container. This is now changed so that the temporary directory is created under the users
          cache directory, which is guaranteed to be mounted on the container.
      - type: bugfix
        title: Docker volume mounts failing when connected using both --docker --proxy-via flags
        body: >-
          The volume mounter would fail when doing a `telepresence connect --docker --proxy-via all=<workload>` followed
          by an intercept using `--docker-run`, because the bridge that the daemon created would try to access the
          intercepted pod using its proxied IP. Now, the bridge will instead use the pod's real IP.
  - version: 2.23.1
    date: 2025-06-24
    notes:
      - type: feature
        title: New telepresence helm version command.
        body: >-
          The new `telepresence helm version` command prints the version of the helm client that is embedded in the
          telepresence binary.
      - type: bugfix
        title: Engagement disconnects after certain amount of time
        body: |-
          The configuration parameter `connectionTTL`, controlling how long a client could be completely idle before
          the traffic-manager or traffic-agent would consider it dead and disconnect (default 24 hours), had no effect.
          Instead, an engagement would disconnect after 2 hours (the default gRPC `keepAlive.Time` duration). The
          default of 24 hours is now reinstated.

          The Helm value `client.connectionTTL` was moved to `grpc.connectionTTL` because it is a server configuration.
          The old value will still work, but it is deprecated and will be removed eventually.
        docs: https://github.com/telepresenceio/telepresence/issues/3861
      - type: bugfix
        title: Telepresence breaks if config.yml exists but is empty
        body: >-
          Telepresence would refuse to connect with a misleading error if the `config.yml` file containing the client's
          configuration parameters existed but was empty.
        docs: https://github.com/telepresenceio/telepresence/issues/3887
  - version: 2.23.0
    date: 2025-06-17
    notes:
      - type: feature
        title: New telepresence wiretap command
        body: >-
          The new `telepresence wiretap` command introduces a read-only form of an `intercept` where the original
          container will run unaffected while a copy of the wiretapped traffic is sent to the client.

          Similar to an `ingest`, a `wiretap` will always enforce read-only status on all volume mounts, and since that
          makes the `wiretap` completely read-only, there's no limit to how many simultaneous wiretaps that can be
          served. In fact, a `wiretap` and an `intercept` on the same port can run simultaneously.
      - type: feature
        title: Add Telepresence Docker Network Plugin "Teleroute"
        body: |-
          The new Teleroute plugin makes it possible for containers to use the Telepresence daemon's VIF without having
          to change their network mode, i.e. a `--network container:<daemon container>` is no longer needed. Instead,
          a container can use a custom network created when the Telepresence daemon connects to the cluster.
          This network uses the new driver "teleroute" which is provided by Telepresence.

          With the Teleroute Docker network plugin in place, there's no longer a need for special handling of network
          related docker flags, and the following changes have been made:

          1. The Teleroute Docker network driver will be installed unless it is already present.
          2. A Teleroute network will be created when starting the Telepresence daemon as a container. This network will
             then communicate with that container and expose the same CIDRs as the daemon's VIF.
          3. A container started with `telepresence curl`, or
             `telepresence {ingest|intercept|replace|wiretap} --docker-{run|build|debug}` will no longer change its
             network mode using `--network container:<daemon container>`, instead it will use
             `--network <name of teleroute network>`.
          4. As a consequence of #3, published ports and other networks that are added no longer need special handling
             using socat containers, so all of that has been removed.
        docs: reference/teleroute
      - type: feature
        title: Control whether the initContainer injection is enabled/disabled
        body: >-
          The initContainer injection can be optionally disabled by setting the `agent.initContainer.enabled` parameter
          to false in the `values.yaml` file of the Helm chart. This feature was added to improve compatibility with
          systems like OpenShift where the initContainer injection cannot be used due to inability to give initContainer
          NET_ADMIN permissions.
      - type: feature
        title: Human friendly progress reporting
        body: >-
          Telepresence now uses a progress reporter that is very similar to the one used by Docker compose. The
          implementation is a variation of that reporter's source code, so big thanks to the Docker compose CLI authors
          for making it available as OSS.

          A new global `--progress <progress>` flag was added. It defaults to "auto" which means that the style is
          chosen depending on whether the command runs from a tty type terminal. Other possible values are "plain",
          "quiet", and "json". `--progress quiet` is implied when formatted output is chosen using `--output json|yaml`.
      - type: feature
        title: Add the ability to use a name for the target host, and defer its resolution
        body: >-
          Knowing the IP of the local service that acts as the handler service for an intercept, replace, or wiretap
          is not possible until that service has been started, and telepresence will therefore now accept a name for the
          `--address` flag. The name is not resolved by the daemon until a request is made to the engaged container on a
          port that is routed to the local service.
      - type: feature
        title: Add intercept.mountsRoot to the client configuration
        body: >-
          The new `intercept.mountsRoot` can be set to a directory that will be used as the root for all automatically
          generated mount directories. The default is to use the platforms temp directory.

          The setting is not used on windows, where the mounts use drive letters.
      - type: feature
        title: Add docker.addHostGateway to the client configuration.
        body: >-
          When `docker.addHostGateway` is set to `true`, the `docker run`
          that starts the containerized Telepresence daemon will include the flag
          `--add-host host.docker.internal:host-gateway`.

          The flag is set to `true` by default on linux platforms and `false` on
          other platforms.
      - type: feature
        title: Client configuration to override the Helm download URL
        body: >-
          The default download URL `oci://ghcr.io/telepresenceio/telepresence-oss` used when installing Helm charts with
          versions that differ from the version of the embedded Helm chart can now be overridden using the client config
          value `helm.chartURL`.
      - type: change
        title: Dropped support for Telepresence legacy flags
        body: |-
          The `telepresence` CLI command will no longer support legacy flags such as:

          - `--swap-deployment`
          - `--new-deployment`
          - `--docker-mount`
          - `--method`

          A "Legacy Telepresence command used" warning has been printed for several years now, and the mapping for the
          `--swap-deployment` was the `intercept` command, which is very confusing today since we now have the `replace`
          command.
      - type: bugfix
        title: Let containerized daemon consistently use the same port for gRPC
        body: >-
          The port used for the containerized gRPC was randomly selected using the hosts network namespace. This is now
          changed so that the port used by the container is preset and configurable and then mapped to a random port
          on the host.

          The port number can be configured using `grpc.daemonPort` and defaults to `4038`.
      - type: bugfix
        title: Telepresence fails to start the root daemon on Windows unless current user is the administrator
        body:
          The telepresence CLI starts a user daemon and a root daemon. The latter is started using administrator
          privileges. On a Windows box, this means that the root daemon runs using a different user account (typically
          "Administrator") unless the current user can run processes with elevated privileges. The socket used for
          communication with the root daemon was assumed to reside in `%USERPROFILE%\AppData\Local\telepresence`
          and was therefore not found by the CLI and the user daemon. The location will henceforth always be based on the
          `%USERDATA` of the CLI user.
        docs: https://github.com/telepresenceio/telepresence/issues/3875
      - type: bugfix
        title: Telepresence DNS Fallback stripping CNAME information from DNS Records.
        body: >-
          The fallback DNS server used on Linux systems without a systemd.resolved configuration, would assume that
          suffixes belonging to the `search` defined in the `/etc/resolved` had been added by the caller. Since this
          search path was assumed to be intended for the local machine only, the suffix was stripped off prior to
          sending the name to the cluster for resolution. This made queries fail that relied on the qualified name to
          resolve CNAME records. The logic stripping the suffix was therefore removed.
        docs: https://github.com/telepresenceio/telepresence/issues/3873
  - version: 2.22.6
    date: 2025-06-03
    notes:
      - type: bugfix
        title: Regression causing "unexpected slice size" with older traffic-managers.
        body: >-
          Older traffic-managers have a different way of reporting the service-subnet. The new way, using a
          list of subnets reused a proto slice in the GRPC message that was expected to be empty, but older
          traffic-managers will pass the IP of the kube-dns here. It cannot be parsed as a list of
          subnets. A check that remedies this mismatch was inserted.
  - version: 2.22.5
    date: 2025-05-29
    notes:
      - type: bugfix
        title: Unable to correctly determine service CIDR with Kubernetes >= 1.33
        body: >-
          Starting with Kubernetes 1.33, the strategy of extracting the cluster's service CIDR from an error message no
          longer works because the error message has changed. The root cause for this is that Kubernetes introduced the
          ability to use [Multiple Service CIDRs](https://gist.github.com/aojea/c20eb117bf1c1214f8bba26c495be9c7). Since
          `ServiceCIDR` is now a resource, it can be easily retrieved (and modified) using standard Kubernetes client
          API calls, and this is what the traffic manager will use going forward.

          The fix required an addition to the traffic-manager's RBAC, granting it sufficient permissions to list
          `networking.k8s.io/servicecidrs`. A future enhancement will allow the traffic manager to watch for service
          CIDR changes.
      - type: bugfix
        title: Helm chart schema type for nodeSelector was incorrect
        body: >-
          The Helm chart schema for the `nodeSelector` value was incorrect. Kubernetes defines different types for
          nodeSelector (inside PodSpec objects) and NodeSelector (inside NodeAffinity, VolumeNodeAffinity and a
          bunch of other places). The schema was changed to use the correct type. The name `nodeSelector` is still
          used in the Helm chart so this change is backwards compatible.
      - type: bugfix
        title: Pods with container ports named the same caused intercept to fail
        body: >-
          Intercept container ports now have numbers appended to them if there are multiple
          ports from multiple containers with the same name. This bugfix works around an issue
          where Kubernetes allows multiple port definitions in a pod spec to have the same name.
      - type: bugfix
        title: Don't include k8s-defs.json to chart package
        body: >-
          The k8s-defs.json was unnecessarily included to the Helm chart package and this increased the Helm release
          secret size so much that it could prevent installation of the Helm chart depending on k8s settings. To fix
          this k8s-defs.json is not included to the Helm chart anymore.
  - version: 2.22.4
    date: 2025-04-26
    notes:
      - type: bugfix
        title: Don't require internet access when installing the traffic-manager using Helm
        body: >-
          A regression occurred with the introduction of Helm validation in version 2.22.0. The schema relied on
          external HTTPS links, which inadvertently created a requirement for internet accessibility. To resolve this,
          we have embedded these resources within the schema, thus removing the need for an internet connection.
      - type: bugfix
        title: Client failed connect with "failed to exit idle mode" in the connector.log after being idle
        body: >-
          The port-forward connections used for connecting the daemon to the traffic-agents were using
          an incorrect context, causing them to fail after being idle for some time.
      - type: bugfix
        title: Fix deadlock in Telepresence daemon
        body: >-
          A deadlock would sometimes occur in the Telepresence daemon that prevented it from doing a clean
          exit during `telepresence quit`.
      - type: bugfix
        title: Don't log error message when a pod watcher ends due to cancellation
        body: >-
          Errors printed in the daemon log during normal cancellation of the WatchAgentPods goroutine are
          now removed.
  - version: 2.22.3
    date: 2025-04-08
    notes:
      - type: change
        title: The Windows install script will now install Telepresence to "%ProgramFiles%\telepresence"
        body: |-
          Telepresence is now installed into "%ProgramFiles%\telepresence" instead of "C:\telepresence".
          The directory and the Path entry for  `C:\telepresence` are not longer used and should be removed.
      - type: bugfix
        title: The Windows install script didn't handle upgrades properly
        body: |-
          The following changes were made:

            - The script now requires administrator privileges
            - The Path environment is only updated when there's a need for it
        docs: https://github.com/telepresenceio/telepresence/issues/3827
      - type: bugfix
        title: The Telepresence Helm chart could not be used as a dependency in another chart.
        body: >-
          The JSON schema validation implemented in Telepresence 2.22.0 had a defect: it rejected the `global` object.
          This object, a Helm-managed construct, facilitates the propagation of arbitrary configurations from a parent
          chart to its dependencies. Consequently, charts intended for dependency use must permit the presence of the
          `global` object.
        docs: https://github.com/telepresenceio/telepresence/issues/3833
      - type: bugfix
        title: Recreating namespaces was not possible when using a dynamically namespaced Traffic Manager
        body: >-
          A shared informer was sometimes reused when namespaces were removed and then later added again, leading
          to errors like "handler ... was not added to shared informer because it has stopped already".
        docs: https://github.com/telepresenceio/telepresence/issues/3831
      - type: bugfix
        title: Single label name DNS lookups didn't work unless at least one traffic-agent was installed
        body: >-
          A problem with incorrect handling of single label names in the traffic-manager's DNS resolver was fixed. The
          problem would cause lookups like `curl echo` to fail, even though telepresence was connected to a namespace
          containing an "echo" service, unless at least one of the workloads in the connected namespace had a
          traffic-agent.
  - version: 2.22.2
    date: 2025-03-28
    notes:
      - type: bugfix
        title: Panic when using telepresence replace in a IPv6-only cluster
        body: |-
          A "slice bounds out of range" would occur when the targeted Pod's Traffic Agent requested a local dialer to
          be created on the client. This was due to a glitch in the VPN-tunnel implementation that got triggered when
          a remote IPv6-address was combined with a local IPv4-address.
        docs: https://github.com/telepresenceio/telepresence/issues/3828
  - version: 2.22.1
    date: 2025-03-27
    notes:
      - type: bugfix
        title: Only restore inactive traffic-agent after a replace.
        body: |-
          A regression in the 2.20.0 release would cause the traffic-agent to be replaced with a dormant version that
          didn't touch any ports when an intercept ended. This terminated other ongoing intercepts on the same pod.
          This is now changed so that the traffic-agent remains unaffected for this use-case.
  - version: 2.22.0
    date: 2025-03-14
    notes:
      - type: feature
        title: New telepresence replace command.
        body: |-
          The new `telepresence replace` command simplifies and clarifies container replacement.

          Previously, the `--replace` flag within the `telepresence intercept` command was used to replace containers.
          However, this approach introduced inconsistencies and limitations:

          * **Confusion:** Using a flag to modify the core function of a command designed for traffic interception led
            to ambiguity.
          * **Inaccurate Behavior:** Replacement was not possible when no incoming traffic was intercepted, as the
            command's design focused on traffic routing.

          To address these issues, the `--replace` flag within `telepresence intercept` has been deprecated. The new
          `telepresence replace` command provides a dedicated and consistent method for replacing containers, enhancing
          clarity and reliability.

          Key differences between `replace` and `intercept`:

          1. **Scope:** The `replace` command targets and affects an entire container, impacting all its traffic, while
             an `intercept` targets specific services and/or service/container ports.
          2. **Port Declarations:** Remote ports specified using the `--port` flag are container ports.
          3. **No Default Port:** A `replace` can occur without intercepting any ports.
          4. **Container State:** During a `replace`, the original container is no longer active within the cluster.

          The deprecated `--replace` flag still works, but is hidden from the `telepresence intercept` command help, and
          will print a deprecation warning when used.
      - type: feature
        title: Add json-schema for the Telepresence Helm Chart
        body: >-
          Helm can validate a chart using a json-schema using the command `helm lint`, and this schema can be part of
          the actual Helm chart. The telepresence-oss Helm chart now includes such a schema, and a new
          `telepresence helm lint` command was added so that linting can be performed using the embedded chart.
      - type: feature
        title: No dormant container present during replace.
        body: |-
          Telepresence will no longer inject a dormant container during a `telepresence replace` operation. Instead, the
          Traffic Agent now directly serves as the replacement container, eliminating the need to forward traffic to the
          original application container. This simplification offers several advantages when using the `--replace` flag:

            - **Removal of the init-container:** The need for a separate init-container is no longer necessary.
            - **Elimination of port renames:** Port renames within the intercepted pod are no longer required.
      - type: feature
        title: One single invocation of the Telepresence intercept command can now intercept multiple ports.
        body: >-
          It is now possible to intercept multiple ports with one single invocation of `telepresence intercept` by just
          repeating the `--port` flag.
      - type: feature
        title: Unify how Traffic Manager selects namespaces
        body: |-
          The definition of what namespaces that a Traffic Manager would manage use was scattered into several Helm
          chart values, such as `manager.Rbac.namespaces`, `client.Rbac.namespaces`, and
          `agentInjector.webhook.namespaceSelector`. The definition is now unified to the mutual exclusive top-level
          Helm chart values `namespaces` and `namespaceSelector`.

          The `namespaces` value is just for convenience and a short form of expressing:
          ```yaml
          namespaceSelector:
            matchExpressions:
             - key: kubernetes.io/metadata.name
               operator: in
               values: <namespaces>.
          ```

        docs: install/manager#static-versus-dynamic-namespace-selection
      - type: feature
        title: Improved control over how remote volumes are mounted using mount policies
        body: >-
          Mount policies, that affects how the telepresence traffic-agent shares the pod's volumes, and also how the
          client will mount them, can now be provided using the Helm chart value `agent.mountPolicies` or as JSON
          object in the workload annotation `telepresence.io/mount-policies`. A mount policy is applied to a volume
          or to all paths matching a path-prefix (distinguished by checking if first character is a '/'), and can
          be one of `Ignore`, `Local`, `Remote`, or `RemoteReadOnly`.
      - type: feature
        title: List output includes workload kind.
        body: >-
          The output of the `telepresence list` command will now include the workload kind (deployment, replicaset,
          statefulset, or rollout) in all entries.
      - type: feature
        title: Add ability to override the default securityContext for the Telepresence init-container
        body: >-
          Users can now use the Helm value `agent.initSecurityContext` to override the default securityContext for the
          Telepresence init-container.
      - type: change
        title: Let download page use direct links to GitHub
        body: >-
          The download links on the release page now points directly to the assets on the download page, instead of
          using being routed from getambassador.io/download/tel2oss/releases.
      - type: change
        title: Use telepresence.io as annotation prefix instead of telepresence.getambassador.io
        body: >-
          The workload and pod annotations used by Telepresence will now use the prefix `telepresence.io` instead of
          `telepresence.getambassador.io`. The new prefix is consistent with the prefix used by labels, and it also
          matches the host name of the documentation site. Annotations using the old name will still work, but warnings
          will be logged when they are encountered.
      - type: change
        title: Make the DNS recursion check configurable and turn it off by default.
        body: >-
          Very few systems experience a DNS recursion lookup problem. It can only occur when the cluster runs locally
          and the cluster's DNS is configured to somehow use DNS server that is started by Telepresence. The check
          is therefore now configurable through the client setting `dns.recursionCheck`, and it is `false` by default.
      - type: change
        title: Trigger the mutating webhook with Kubernetes eviction objects instead of patching workloads.
        body: >-
          Telepresence will now attempt to evict pods in order to trigger the traffic-agent's injection or removal, and
          revert to patching workloads if evictions are prevented by the pod's disruption budget. This causes a slight
          change in the traffic-manager RBAC, as the traffic-manager must be able to create "pod/eviction" objects.
      - type: change
        title: The telepresence-agents configmap is no longer used.
        body: >-
          The traffic-agent configuration was moved into a pod-annotation. This avoids sync problems between the
          telepresence-agents (which is no no longer present) and the pods.
      - type: change
        title: Drop deprecated current-cluster-id command.
        body: >-
          The clusterID was deprecated some time ago, and replaced by the ID of the namespace where the traffic-manager
          is installed.
      - type: bugfix
        title: Make telepresence connect --docker work with Rancher Desktop
        body: >-
          Rancher Desktop will start a K3s control-plane and typically expose the
          Kubernetes API server at `127.0.0.1:6443`. Telepresence can connect to
          this cluster when running on the host, but the address is not available
          when connecting in docker mode.

          The problem is solved by ensuring that the Kubernetes API server address used when
          doing a `telepresence connect --docker` is swapped from 127.0.0.1 to the
          internal address of the control-plane node. This works because that
          address is available to other docker containers, and the Kubernetes API
          server is configured with a certificate that accepts it.
      - type: bugfix
        title: Rename charts/telepresence to charts/telepresence-oss.
        body: >-
          The Helm chart name "telepresence-oss" was inconsistent with its contained folder "telepresence". As a result,
          attempts to install the chart using an argo ApplicationSet failed. The contained folder was renamed to match
          the chart name.
      - type: bugfix
        title: Conflict detection between namespaced and cluster-wide install.
        body: >-
          The namespace conflict detection mechanism would only discover conflicts between two _namespaced_ Traffic
          Managers trying to manage the same namespace. This is now fixed so that all types conflicts are discovered.
        docs: install/manager#namespace-collision-detection
      - type: bugfix
        title: Don't dispatch DNS discovery queries to the cluster.
        body: >-
          macOS based systems will often PTR queries using nameslike `b._dns-sd._udp`, lb._dns-sd._udp`, or
          `db-dns-sd._udp`. Those queries are no longer dispatched to the cluster.
      - type: bugfix
        title: Using the --namespace option with telepresence causes a deadlock.
        body: >-
          Using `telepresence list --namespace <ns>` with a namespace different from the one that telepresence was
          connected to, would cause a deadlock, and then produce an empty list.
      - type: bugfix
        title: Fix problem with exclude-suffix being hidden by DNS search path.
        body: >-
          In some situations, a name ending with an exclude-suffix like "xyz.com" would be expanded by a search path
          into "xyz.com.&lt;connected namespace&gt;" and therefore not be excluded. Instead, the name was sent to the cluster
          to be resolved, causing an unnecessary load on its DNS server.
  - version: 2.21.3
    date: 2025-02-06
    notes:
      - type: bugfix
        title: Using the --proxy-via flag would sometimes cause connection timeouts.
        body: >-
          Typically, a `telepresence connect --proxy-via <subnet>=<workflow>` would fail with a "deadline exceeded"
          message when several workloads were present in the namespace, the one targeted by the proxy-via didn't yet
          have an agent installed, and other workloads had an agent. This was due to a race condition in the logic
          for the agent-based port-forwards in the root daemon. The conditions causing this race are now eliminated.
      - type: bugfix
        title: Fix panic in root daemon when using the "allow conflicting subnets" feature on macOS.
        body: >-
          A regression was introduced in version 2.21.0, causing a panic due to an unimplemented method in the
          TUN-device on macOS based clients.
      - type: bugfix
        title: Ensure that annotation enabled traffic-agents are uninstall when uninstalling the traffic-manager.
        body: >-
          A traffic-agent injected because the workload had the inject annotation enabled would sometimes not get
          uninstalled when the traffic-manager was uninstalled.
  - version: 2.21.2
    date: 2025-01-26
    notes:
      - type: bugfix
        title: Fix panic when agentpf.client creates a Tunnel
        body: >-
          A race could occur where several requests where made to `agentpf.client.Tunnel` on a client that had errored
          when creating its port-forward to the agent. The implementation could handle one such requests but not
          several, resulting in a panic in situations where multiple simultaneous requests were made to the same client
          during a very short time period,
      - type: bugfix
        title: Fix goroutine leak in dialer.
        body: >-
          The context passed to the `Tunnel` call that creates a stream for a dialer, was not cancelled when the dialer
          was finished, so the stream was never properly closed, leading to one dormant goroutine for each stream.
  - version: 2.21.1
    date: 2024-12-17
    notes:
      - type: bugfix
        title: Allow ingest of serverless deployments without specifying an inject-container-ports annotation
        body: >-
          The ability to intercept a workload without a service is built around the
          `telepresence.getambassador.io/inject-container-ports` annotation, and it was also required in order to ingest
          such a workload. This was counterintuitive and the requirement was removed. An ingest doesn't use a port.
        docs: https://github.com/telepresenceio/telepresence/issues/3741
      - type: bugfix
        title: Upgrade module dependencies to get rid of critical vulnerability.
        body: >-
          Upgrade module dependencies to latest available stable. This includes upgrading golang.org/x/crypto, which
          had critical issues, from 0.30.0 to 0.31.0 where those issues are resolved.
  - version: 2.21.0
    date: 2024-12-13
    notes:
      - type: feature
        title: Automatic VPN conflict avoidance
        body: >-
          Telepresence not only detects subnet conflicts between the cluster and workstation VPNs but also resolves them
          by performing network address translation to move conflicting subnets out of the way.
        docs: reference/vpn
      - type: feature
        title: Virtual Address Translation (VNAT).
        body: >-
          It is now possible to use a virtual subnet without routing the affected IPs to a specific workload. A new
          `telepresence connect --vnat CIDR` flag was added that will perform virtual network address translation of
          cluster IPs. This flag is very similar to the `--proxy-via CIDR=WORKLOAD` introduced in 2.19, but without
          the need to specify a workload.
        docs: reference/vpn
      - type: feature
        title: Intercepts targeting a specific container
        body: >-
          In certain scenarios, the container owning the intercepted port differs
          from the container the intercept targets. This port owner's sole purpose
          is to route traffic from the service to the intended container, often
          using a direct localhost connection.

          This update introduces a `--container <name>` option to the intercept
          command. While this option doesn't influence the port selection, it
          guarantees that the environment variables and mounts propagated to the
          client originate from the specified container. Additionally, if the
          `--replace` option is used, it ensures that this container is replaced.
        docs: reference/engagements/container
      - type: feature
        title: New telepresence ingest command
        body: >-
          The new `telepresence ingest` command, similar to `telepresence intercept`, provides local access to the
          volume mounts and environment variables of a targeted container. However, unlike `telepresence intercept`,
          `telepresence ingest` does not redirect traffic to the container and ensures that the mounted volumes are
          read-only.

          An ingest requires a traffic-agent to be installed in the pods of the targeted workload. Beyond that, it's
          a client-side operation. This allows developers to have multiple simultaneous ingests on the same container.
        docs: howtos/intercepts#ingest-your-service
      - type: feature
        title: New telepresence curl command
        body: >-
          The new `telepresence curl` command runs curl from within a container. The command requires that a connection
          has been established using `telepresence connect --docker`, and the container that runs `curl` will share the
          same network as the containerized telepresence daemon.
        docs: reference/docker-run#the-telepresence-curl-command
      - type: feature
        title: New telepresence docker-run command
        body: >-
          The new `telepresence docker-run <flags and arguments>` requires that a connection has been established using
          `telepresence connect --docker` It will perform a `docker run <flags and arguments>` and add the flag necessary
          to ensure that started container shares the same network as the containerized telepresence daemon.
        docs: reference/docker-run#the-telepresence-docker-run-command
      - type: feature
        title: Mount everything read-only during intercept
        body: >-
          It is now possible to append ":ro" to the intercept `--mount` flag value. This ensures that all remote volumes
          that the intercept mounts are read-only.
      - type: feature
        title: Unify client configuration
        body: >-
          Previously, client configuration was divided between the config.yml file and a Kubernetes extension. DNS and
          routing settings were initially found only in the extension. However, the Helm client structure allowed
          entries from both.

          To simplify this, we've now aligned the config.yml and Kubernetes extension with the Helm client structure.
          This means DNS and routing settings are now included in both. The Kubernetes extension takes precedence over
          the config.yml and Helm client object.

          While the old-style Kubernetes extension is still supported for compatibility, it cannot be used with the new
          style.
        docs: reference/config
      - type: feature
        title: Use WebSockets for port-forward instead of the now deprecated SPDY.
        body: >-
          Telepresence will now use WebSockets instead of SPDY when creating port-forwards to the Kubernetes Cluster, and
          will fall back to SPDY when connecting to clusters that don't support SPDY. Use of the deprecated SPDY can be
          forced by setting `cluster.forceSPDY=true` in the `config.yml`.

          See [Streaming Transitions from SPDY to WebSockets](https://kubernetes.io/blog/2024/08/20/websockets-transition/)
          for more information about this transition.
      - type: feature
        title: Make usage data collection configurable using an extension point, and default to no-ops
        body: >-
          The OSS code-base will no longer report usage data to the proprietary collector at Ambassador Labs. The actual calls
          to the collector remain, but will be no-ops unless a proper collector client is installed using an extension point.
      - type: feature
        title: Add deployments, statefulSets, replicaSets to workloads Helm chart value
        body: >-
          The Helm chart value `workloads` now supports the kinds `deployments.enabled`, `statefulSets.enabled`, `replicaSets.enabled`.
          and `rollouts.enabled`. All except `rollouts` are enabled by default. The traffic-manager will ignore workloads, and
          Telepresence will not be able to intercept them, if the `enabled` of the corresponding kind is set to `false`.
        docs: reference/engagements/sidecar#disable-workloads
      - type: feature
        title: Improved command auto-completion
        body: >-
          The auto-completion of namespaces, services, and containers have been added where appropriate, and the default
          file auto completion has been removed from most commands.
      - type: feature
        title: Docker run flags --publish, --expose, and --network now work with docker mode connections
        body: >-
          After establishing a connection to a cluster using `telepresence connect --docker`, you can run new containers that share
          the same network as the containerized daemon that maintains the connection. This enables seamless communication between
          your local development environment and the remote services.

          Normally, Docker has a limitation that prevents combining a shared network configuration with custom networks
          and exposing ports. However, Telepresence now elegantly circumvents this limitation so that a container started with
          `telepresence docker-run`, `telepresence intercept --docker-run`, or `telepresence ingest --docker-run` can use flags
          like `--network`, `--publish`, or `--expose`.

          To achieve this, Telepresence temporarily adds the necessary network to the containerized daemon. This allows the new
          container to join the same network. Additionally, Telepresence starts extra socat containers to handle port mapping,
          ensuring that the desired ports are exposed to the local environment.
        docs: reference/docker-run#the-telepresence-docker-run-command
      - type: feature
        title: Prevent recursion in the Telepresence Virtual Network Interface (VIF)
        body: >-
          Network problems may arise when running Kubernetes locally (e.g., Docker Desktop, Kind, Minikube, k3s),
          because the VIF on the host is also accessible from the cluster's nodes. A request that isn't handled by a
          cluster resource might be routed back into the VIF and cause a recursion.

          These recursions can now be prevented by setting the client configuration property
          `routing.recursionBlockDuration` so that new connection attempts are temporarily blocked for a specific
          IP:PORT pair immediately after an initial attempt, thereby effectively ending the recursion.
        docs: howtos/cluster-in-vm
      - type: feature
        title: Allow Helm chart to be included as a sub-chart
        body: >-
          The Helm chart previously had the unnecessary restriction that the .Release.Name under which telepresence is installed is literally
          called "traffic-manager".  This restriction was preventing telepresence from being included as a sub-chart in a parent chart
          called anything but "traffic-manager". This restriction has been lifted.
      - type: feature
        title: Add Windows arm64 client build
        body: >-
          Telepresence client is now available for Windows ARM64.
          Updated the release workflow files in github actions to build and publish the Windows ARM64 client.
      - type: change
        title: The --agents flag to telepresence uninstall is now the default.
        body: >-
          The `telepresence uninstall` was once capable of uninstalling the traffic-manager as well as traffic-agents.
          This behavior has been deprecated for some time now and in this release, the command is all about uninstalling
          the agents. Therefore the `--agents` flag was made redundant and whatever arguments that are given to the
          command must be name of workloads that have an agent installed unless the `--all-agents` is used, in which
          case no arguments are allowed.
      - type: change
        title: Performance improvement for the telepresence list command
        body: >-
          The `telepresence list` command will now retrieve its data from the traffic-manager, which significantly
          improves its performance when used on namespaces that have a lot of workloads.
      - type: change
        title: During an intercept, the local port defaults to the targeted port of the intercepted container instead of 8080.
        body: >-
          Telepresence mimics the environment of a target container during an intercept, so it's only natural that the default
          for the local port is determined by the targeted container port rather than just defaulting to 8080.

          A default can still be explicitly defined using the `config.intercept.defaultPort` setting.
      - type: change
        title: Move the telepresence-intercept-env configmap data into traffic-manager configmap.
        body: >-
          There's no need for two configmaps that store configuration data for the traffic manager. The traffic-manager
          configmap is also watched, so consolidating the configuration there saves some k8s API calls.
      - type: change
        title: Tracing was removed.
        body: >-
          The ability to collect trace has been removed along with the `telepresence gather-traces` and
          `telepresence upload-traces` commands. The underlying code was complex and has not been well maintained since
          its inception in 2022. We have received no feedback on it and seen no indication that it has ever been used.
      - type: bugfix
        title: Remove obsolete code checking the Docker Bridge for DNS
        body: >-
          The DNS resolver checked the Docker bridge for messages on Linux. This code was obsolete and caused problems
          when running in Codespaces.
      - type: bugfix
        title: Fix telepresence connect confusion caused by /.dockerenv file
        body: >-
          A `/.dockerenv` will be present when running in a GitHub Codespaces environment. That doesn't mean that
          telepresence cannot use docker, or that the root daemon shouldn't start.
      - type: bugfix
        title: Cap timeouts.connectivityCheck at 5 seconds.
        body: >-
          The timeout value of `timeouts.connectivityCheck` is used when checking if a cluster is already reachable
          without Telepresence setting up an additional network route. If it is, this timeout should be high enough to
          cover the delay when establishing a connection. If this delay is higher than a second, then chances are very
          low that the cluster already is reachable, and if it can, that all accesses to it will be very slow. In such
          cases, Telepresence will create its own network interface and do perform its own tunneling.

          The default timeout for the check remains at 500 millisecond, which is more than sufficient for the majority
          of cases.
      - type: bugfix
        title: Prevent that traffic-manager injects a traffic-agent into itself.
        body: >-
          The traffic-manager can never be a subject for an intercept, ingest, or proxy-via, because that means that
          it injects the traffic-agent into itself, and it is not designed to do that. A user attempting this will
          now see a meaningful error message.
      - type: bugfix
        title: Don't include pods in the kube-system namespace when computing pod-subnets from pod IPs
        body: >-
          A user would normally never access pods in the `kube-system` namespace directly, and automatically including pods
          included there when computing the subnets will often lead to problems when running the cluster locally. This namespace
          is therefore now excluded in situations when the pod subnets are computed from the IPs of pods. Services in this
          namespace will still be available through the service subnet.

          If a user should require the pod-subnet to be mapped, it can be added to the `client.routing.alsoProxy`
          list in the helm chart.
      - type: bugfix
        title: Let routes belonging to an allowed conflict be added as a static route on Linux.
        body: >-
          The `allowConflicting` setting didn't always work on Linux because the conflicting subnet was just added as a
          link to the TUN device, and therefore didn't get subjected to routing rule used to assign priority to the
          given subnet.
  - version: 2.20.3
    date: 2024-11-18
    notes:
      - type: bugfix
        title: Ensure that Telepresence works with GitHub Codespaces
        body: >-
          GitHub Codespaces runs in a container, but not as root. Telepresence didn't handle this situation
          correctly and only started the user daemon. The root daemon was never started.
        docs: https://github.com/telepresenceio/telepresence/issues/3722
      - type: bugfix
        title: Mounts not working correctly when connected with --proxy-via
        body: >-
          A mount would try to connect to the sftp/ftp server using the original (cluster side) IP although that
          IP was translated into a virtual IP when using `--proxy-via`.
        docs: https://github.com/telepresenceio/telepresence/issues/3715
  - version: 2.20.2
    date: 2024-10-21
    notes:
      - type: bugfix
        title: Crash in traffic-manager configured with agentInjector.enabled=false
        body: >-
          A traffic-manager that was installed with the Helm value `agentInjector.enabled=false` crashed when a
          client used the commands `telepresence version` or `telepresence status`. Those commands would call
          a method on the traffic-manager that panicked if no traffic-agent was present. This method will now
          instead return the standard `Unavailable` error code, which is expected by the caller.
  - version: 2.20.1
    date: 2024-10-10
    notes:
      - type: bugfix
        title: Some workloads missing in the telepresence list output (typically replicasets owned by rollouts).
        body: >-
          Version 2.20.0 introduced a regression in the `telepresence list` command, resulting in the omission of
          all workloads that were owned by another workload. The correct behavior is to just omit those workloads
          that are owned by the supported workload kinds `Deployment`, `ReplicaSet`, `StatefulSet`, and `Rollout`.
          Furthermore, the `Rollout` kind must only be considered supported when the Argo Rollouts feature is
          enabled in the traffic-manager.
      - type: bugfix
        title: Allow comma separated list of daemons for the gather-logs command.
        body: >-
          The name of the `telepresence gather-logs` flag `--daemons` suggests that the argument can contain more
          than one daemon, but prior to this fix, it couldn't. It is now possible to use a comma separated
          list, e.g. `telepresence gather-logs --daemons root,user`.
  - version: 2.20.0
    date: 2024-10-03
    notes:
      - type: feature
        title: Add timestamp to telepresence_logs.zip filename.
        body: >-
          Telepresence is now capable of easily find telepresence gather-logs by certain timestamp.
      - type: feature
        title: Enable intercepts of workloads that have no service.
        body: >-
          Telepresence is now capable of intercepting workloads that have no associated service. The intercept will then target container port
          instead of a service port. The new behavior is enabled by adding a <code>telepresence.getambassador.io/inject-container-ports</code>
          annotation where the value is a comma separated list of port identifiers consisting of either the name or the port number of a container
          port, optionally suffixed with `/TCP` or `/UDP`.
        docs: https://telepresence.io/docs/reference/engagements/cli#intercepting-without-a-service
      - type: feature
        title: Publish the OSS version of the telepresence Helm chart
        body: >-
          The OSS version of the telepresence helm chart is now available at ghcr.io/telepresenceio/telepresence-oss, and
          can be installed using the command:<br/>
          <code>helm install traffic-manager oci://ghcr.io/telepresenceio/telepresence-oss --namespace ambassador --version 2.20.0</code>
          The chart documentation is published at <a href="https://artifacthub.io/packages/helm/telepresence-oss/telepresence-oss">ArtifactHUB</a>.
        docs: https://artifacthub.io/packages/helm/telepresence-oss/telepresence-oss
      - type: feature
        title: Control the syntax of the environment file created with the intercept flag --env-file
        body: >-
          A new <code>--env-syntax &lt;syntax&gt;</code> was introduced to allow control over the syntax of the file created when using the intercept
          flag <code>--env-file &lt;file&gt;</code>. Valid syntaxes are &quot;docker&quot;, &quot;compose&quot;, &quot;sh&quot;, &quot;csh&quot;, &quot;cmd&quot;,
          and &quot;ps&quot;; where &quot;sh&quot;, &quot;csh&quot;, and &quot;ps&quot; can be suffixed with &quot;:export&quot;.
        docs: https://telepresence.io/docs/reference/environment
      - type: feature
        title: Add support for Argo Rollout workloads.
        body: >-
          Telepresence now has an opt-in support for Argo Rollout workloads.
          The behavior is controlled by `workloads.argoRollouts.enabled` Helm chart value.
          It is recommended to set the following annotation <code>telepresence.getambassador.io/inject-traffic-agent: enabled</code>
          to avoid creation of unwanted revisions.
      - type: bugfix
        title: Enable intercepts of containers that bind to podIP
        body: >-
          In previous versions, the traffic-agent would route traffic to localhost during periods when an intercept wasn't
          active. This made it impossible for an application to bind to the pod's IP, and it also meant that service meshes binding
          to the podIP would get bypassed, both during and after an intercept had been made.
          This is now changed, so that the traffic-agent instead forwards non intercepted requests to the pod's IP, thereby
          enabling the application to either bind to localhost or to that IP.
      - type: change
        title: Use ghcr.io/telepresenceio instead of docker.io/datawire for OSS images and the telemount Docker volume plugin.
        body: >-
          All OSS telepresence images and the telemount Docker plugin are now published at the public registry ghcr.io/telepresenceio
          and all references from the client and traffic-manager has been updated to use this registry
          instead of the one at docker.io/datawire.
      - title: Use nftables instead of iptables-legacy
        type: change
        body: >-
          Some time ago, we introduced iptables-legacy because users had problems using Telepresence with Fly.io where nftables
          wasn't supported by the kernel. Fly.io has since fixed this, so Telepresence will now use nftables again. This in turn,
          ensures that modern systems that lack support iptables-legacy will work.
      - type: bugfix
        title: Root daemon wouldn't start when sudo timeout was zero.
        body: >-
          The root daemon refused to start when <code>sudo</code> was configured with a <code>timestamp_timeout=0</code>.
          This was due to logic that first requested root privileges using a sudo call, and then relied on that these
          privileges were cached, so that a subsequent call using <code>--non-interactive</code> was guaranteed to succeed.
          This logic will now instead do one single sudo call, and rely solely on sudo to print an informative prompt and
          start the daemon in the background.
      - type: bugfix
        title: Detect minikube network when connecting with --docker
        body: >-
          A <code>telepresence connect --docker</code> failed when attempting to connect to a minikube that
          uses a docker driver because the containerized daemon did not have access to the <code>minikube</code>
          docker network. Telepresence will now detect an attempt to connect to that network and attach it to
          the daemon container as needed.
  - version: 2.19.1
    date: "2024-07-12"
    notes:
      - type: feature
        title: Add brew support for the OSS version of Telepresence.
        body: >-
          The Open-Source Software version of Telepresence can now be installed using the brew formula
          via <code>brew install telepresenceio/telepresence/telepresence-oss</code>.
        docs: https://github.com/telepresenceio/telepresence/issues/3609
      - type: feature
        title: Add --create-namespace flag to the telepresence helm install command.
        body: >-
          A <code>--create-namespace</code> (default <code>true</code>) flag was added to the <code>telepresence helm
          install</code> command. No attempt will be made to create a namespace for the traffic-manager if it is explicitly
          set to <code>false</code>. The command will then fail if the namespace is missing.
      - type: feature
        title: Introduce DNS fallback on Windows.
        body: >-
          A <code>network.defaultDNSWithFallback</code> config option has been introduced on Windows. It will cause the
          DNS-resolver to fall back to the resolver that was first in the list prior to when Telepresence establishes a
          connection. The option is default <code>true</code> since it is believed to give the best experience but can be
          set to <code>false</code> to restore the old behavior.
      - type: feature
        title: Brew now supports MacOS (amd64/arm64) / Linux (amd64)
        body: >-
          The brew formula can now dynamically support MacOS (amd64/arm64) / Linux (amd64) in a single formula
        docs: https://github.com/datawire/homebrew-blackbird/issues/19
      - type: feature
        title: Add ability to provide an externally-provisioned webhook secret
        body: >-
          Added <code>supplied</code> as a new option for <code>agentInjector.certificate.method</code>.
          This fully disables the generation of the Mutating Webhook's secret, allowing the chart to use the values of a
          pre-existing secret named <code>agentInjector.secret.name</code>. Previously, the install would fail when it
          attempted to create or update the externally-managed secret.
      - type: feature
        title: Let PTR query for DNS server return the cluster domain.
        body: >-
          The <code>nslookup</code> program on Windows uses a PTR query to retrieve its displayed "Server" property.
          This Telepresence DNS resolver will now return the cluster domain on such a query.
      - type: feature
        title: Add scheduler name to PODs templates.
        body: >-
          A new Helm chart value <code>schedulerName</code> has been added. With this feature, we are
          able to define some particular schedulers from Kubernetes to apply some different strategies to allocate telepresence resources,
          including the Traffic Manager and hooks pods.
      - type: bugfix
        title: Race in traffic-agent injector when using inject annotation
        body: >-
          Applying multiple deployments that used the <code>telepresence.getambassador.io/inject-traffic-agent: enabled</code> would cause
          a race condition, resulting in a large number of created pods that eventually had to be deleted, or sometimes in
          pods that didn't contain a traffic agent.
      - type: bugfix
        title: Fix configuring custom agent security context
        body: ->
          The traffic-manager helm chart will now correctly use a custom agent security context if one is provided.
  - version: 2.19.0
    date: "2024-06-15"
    notes:
      - type: feature
        title: Warn when an Open Source Client connects to an Enterprise Traffic Manager.
        body: >-
          The difference between the OSS and the Enterprise offering is not well understood, and OSS users often install
          a traffic-manager using the Helm chart published at getambassador.io. This Helm chart installs an enterprise
          traffic-manager, which is probably not what the user would expect. Telepresence will now warn when an OSS client
          connects to an enterprise traffic-manager and suggest switching to an enterprise client, or use
          <code>telepresence helm install</code> to install an OSS traffic-manager.
      - type: feature
        title: Add scheduler name to PODs templates.
        body: >-
          A new Helm chart value <code>schedulerName</code> has been added. With this feature, we are
          able to define some particular schedulers from Kubernetes to apply some different strategies to allocate telepresence resources,
          including the Traffic Manager and hooks pods.
      - type: bugfix
        title: Improve traffic-manager performance in very large clusters.
        body: ->
          The traffic-manager will now use a shared-informer when keeping track of deployments. This will significantly
          reduce the load on the Kublet in large clusters and therefore lessen the risk for the traffic-manager being
          throttled, which can lead to other problems.
      - type: bugfix
        title: Kubeconfig exec authentication failure when connecting with --docker from a WSL linux host
        body: >-
          Clusters like Amazon EKS often use a special authentication binary that is declared in the kubeconfig using an
          <code>exec</code> authentication strategy. This binary is normally not available inside a container. Consequently,
          a modified kubeconfig is used when <code>telepresence connect --docker</code> executes, appointing a <code>kubeauth
          </code> binary which instead retrieves the authentication from a port on the Docker host that communicates with another
          process outside of Docker. This process then executes the original <code>exec</code> command to retrieve the necessary
          credentials.

          This setup was problematic when using WSL, because even though <code>telepresence connect --docker</code> was executed on
          a Linux host, the Docker host available from <code>host.docker.internal</code> that the <code>kubeauth</code> connected to
          was the Windows host running Docker Desktop. The fix for this was to use the local IP of the default route instead of
          <code>host.docker.internal</code> when running under WSL..
  - version: 2.18.6
    date: (SUPERSEDED)
    notes:
      - type: bugfix
        title: Fix bug in workload cache, causing endless recursion when a workload uses the same name as its owner.
        body: >-
          The workload cache was keyed by name and namespace, but not by kind, so a workload named the same as its
          owner workload would be found using the same key. This led to the workload finding itself when looking up
          its owner, which in turn resulted in an endless recursion when searching for the topmost owner.
      - type: bugfix
        title: FailedScheduling events mentioning node availability considered fatal when waiting for agent to arrive.
        body: >-
          The traffic-manager considers some events as fatal when waiting for a traffic-agent to arrive after an injection
          has been initiated. This logic would trigger on events like &quot;Warning FailedScheduling 0/63 nodes are
          available&quot; although those events indicate a recoverable condition and kill the wait. This is now fixed so
          that the events are logged but the wait continues.
  - version: 2.18.5
    date: (SUPERSEDED)
    notes:
      - type: bugfix
        title: Improve how the traffic-manager resolves DNS when no agent is installed.
        body: >-
          The traffic-manager is typically installed into a namespace different from the one that clients are
          connected to. It's therefore important that the traffic-manager adds the client's namespace when
          resolving single label names in situations where there are any agents to dispatch the DNS query to.
      - type: change
        title: Removal of ability import legacy artifact into Helm.
        body: >-
          A helm install would make attempts to find manually installed artifacts and make them managed by
          Helm by adding the necessary labels and annotations. This was important when the Helm chart was first
          introduced but is far less so today, and this legacy import was therefore removed.
      - type: bugfix
        title: Docker aliases deprecation caused failure to detect Kind cluster.
        body: >-
          The logic for detecting if a cluster is a local Kind cluster, and therefore needs some special attention when
          using <code>telepresence connect --docker</code>, relied on the presence of <code>Aliases</code> in the Docker
          network that a Kind cluster sets up. In Docker versions from 26 and up, this value is no longer used, but the
          corresponding info can instead be found in the new <code>DNSNames</code> field.
        docs: https://docs.docker.com/engine/deprecated/#container-short-id-in-network-aliases-field
      - type: bugfix
        title: Include svc as a top-level domain in the DNS resolver.
        body: >-
          It's not uncommon that use-cases involving Kafka or other middleware use FQNs that end with
          &quot;svc&quot;. The core-DNS resolver in Kubernetes can resolve such names. With this bugfix,
          the Telepresence DNS resolver will also be able to resolve them, and thereby remove the need
          to add &quot;.svc&quot; to the include-suffix list.
        docs: https://github.com/telepresenceio/telepresence/issues/2814
      - type: feature
        title: Add ability to enable/disable the mutating webhook.
        body: >-
          A new Helm chart boolean value <code>agentInjector.enable</code> has been added that controls the agent-injector
          service and its associated mutating webhook. If set to <code>false</code>, the service, the webhook, and the
          secrets and certificates associated with it, will no longer be installed.
      - type: feature
        title: Add ability to mount a webhook secret.
        body: >-
          A new Helm chart value <code>agentInjector.certificate.accessMethod</code> which can be set to <code>watch</code>
          (the default) or <code>mount</code> has been added. The <code>mount</code> setting is intended for clusters with
          policies that prevent containers from doing a <code>get</code>, <code>list</code> or <code>watch</code> of a
          <code>Secret</code>, but where a latency of up to 90 seconds is acceptable between the time the secret is
          regenerated and the agent-injector picks it up.
      - type: feature
        title: Make it possible to specify ignored volume mounts using path prefix.
        body: >-
          Volume mounts like <code>/var/run/secrets/kubernetes.io</code> are not declared in the workload. Instead, they
          are injected during pod-creation and their names are generated. It is now possible to ignore such mounts using a
          matching path prefix.
      - type: feature
        title: Make the telemount Docker Volume plugin configurable
        body: >-
          A <code>telemount</code> object was added to the <code>intercept</code> object in <code>config.yml</code>
          (or Helm value <code>client.intercept</code>), so that the automatic download and installation of this plugin can
          be fully customised.
      - type: feature
        title: Add option to load the kubeconfig yaml from stdin during connect.
        body: >-
          This allows another process with a kubeconfig already loaded in memory
          to directly pass it to <code>telepresence connect</code> without needing a separate
          file. Simply use a dash "-" as the filename for the <code>--kubeconfig</code> flag.
      - type: feature
        title: Add ability to specify agent security context.
        body: >-
          A new Helm chart value <code>agent.securityContext</code> that will allow configuring the security context of
          the injected traffic agent.  The value can be set to a valid Kubernetes securityContext object, or can be set
          to an empty value (<code>{}</code>) to ensure the agent has no defined security context.  If no value is specified,
          the traffic manager will set the agent's security context to the same as the first container's of the workload
          being injected into.
      - type: change
        title: Tracing is no longer enabled by default.
        body: >-
          Tracing must now be enabled explicitly in order to use the <code>telepresence gather-traces</code>
          command.
      - type: change
        title: Removal of timeouts that are no longer in use
        body: >-
          The <code>config.yml</code> values <code>timeouts.agentInstall</code> and <code>timeouts.apply</code> haven't
          been in use since versions prior to 2.6.0, when the client was responsible for installing the traffic-agent.
          These timeouts are now removed from the code-base, and a warning will be printed when attempts are made to use
          them.
      - type: bugfix
        title: Search all private subnets to find one open for dnsServerSubnet
        body: >-
          This resolves a bug that did not test all subnets in a private range, sometimes resulting in the warning,
          "DNS doesn't seem to work properly."
  - version: 2.18.4
    date: (SUPERSEDED)
    notes:
      - type: bugfix
        title: Docker aliases deprecation caused failure to detect Kind cluster.
        body: >-
          The logic for detecting if a cluster is a local Kind cluster, and therefore needs some special attention when
          using <code>telepresence connect --docker</code>, relied on the presence of <code>Aliases</code> in the Docker
          network that a Kind cluster sets up. In Docker versions from 26 and up, this value is no longer used, but the
          corresponding info can instead be found in the new <code>DNSNames</code> field.
  - version: 2.18.3
    date: (SUPERSEDED)
    notes:
      - type: bugfix
        title: Creation of individual pods was blocked by the agent-injector webhook.
        body: >-
          An attempt to create a pod was blocked unless it was provided by a workload. Hence, commands like
          <code>kubectl run -i busybox --rm --image=curlimages/curl --restart=Never -- curl echo-easy.default</code>
          would be blocked from executing.
  - version: 2.18.2
    date: (SUPERSEDED)
    notes:
      - type: bugfix
        title: Fix panic due to root daemon not running.
        body: >-
          If a <code>telepresence connect</code> was made at a time when the root daemon was not running (an abnormal
          condition) and a subsequent intercept was then made, a panic would occur when the port-forward to the agent
          was set up. This is now fixed so that the initial <code>telepresence connect</code> is refused unless the root
          daemon is running.
  - version: 2.18.1
    date: (SUPERSEDED)
    notes:
      - type: bugfix
        title: Get rid of telemount plugin stickiness
        body: >-
          The <code>datawire/telemount</code> that is automatically downloaded and installed, would never be
          updated once the installation was made. Telepresence will now check for the latest release of the
          plugin and cache the result of that check for 24 hours. If a new version arrives, it will be
          installed and used.
      - type: bugfix
        title: Use route instead of address for CIDRs with masks that don't allow "via"
        body: >-
          A CIDR with a mask that leaves less than two bits (/31 or /32 for IPv4)
          cannot be added as an address to the VIF, because such addresses must
          have bits allowing a "via" IP.

          The logic was modified to allow such CIDRs to become static routes, using the
          VIF base address as their "via", rather than being VIF addresses in their own right.
      - type: bugfix
        title: Containerized daemon created cache files owned by root
        body: >-
          When using <code>telepresence connect --docker</code> to create a containerized daemon, that
          daemon would sometimes create files in the cache that were owned by root, which then caused
          problems when connecting without the <code>--docker</code> flag.
      - type: bugfix
        title: Remove large number of requests when traffic-manager is used in large clusters.
        body: >-
          The traffic-manager would make a very large number of API requests during cluster start-up
          or when many services were changed for other reasons. The logic that did this was refactored
          and the number of queries were significantly reduced.
      - type: bugfix
        title: Don't patch probes on replaced containers.
        body: >-
          A container that is being replaced by a <code>telepresence intercept --replace</code>
          invocation will have no liveness-, readiness, nor startup-probes. Telepresence didn't
          take this into consideration when injecting the traffic-agent, but now it will refrain
          from patching symbolic port names of those probes.
      - type: bugfix
        title: Don't rely on context name when deciding if a kind cluster is used.
        body: >-
          The code that auto-patches the kubeconfig when connecting to a kind cluster from within
          a docker container, relied on the context name starting with "kind-", but although all
          contexts created by kind have that name, the user is still free to rename it or to create
          other contexts using the same connection properties. The logic was therefore changed
          to instead look for a loopback service address.
  - version: 2.18.0
    date: "2024-02-09"
    notes:
      - type: feature
        title: Include the image for the traffic-agent in the output of the version and status commands.
        body: >-
          The version and status commands will now output the image that the traffic-agent will be using when injected
          by the agent-injector.
      - type: feature
        title: Custom DNS using the client DNS resolver.
        body: >-
          <p>A new <code>telepresence connect --proxy-via CIDR=WORKLOAD</code> flag was introduced, allowing Telepresence
          to translate DNS responses matching specific subnets into virtual IPs that are used locally. Those virtual IPs
          are then routed (with reverse translation) via the pod's of a given workload. This makes it possible to handle
          custom DNS servers that resolve domains into loopback IPs. The flag may also be used in cases where the
          cluster's subnets are in conflict with the workstation's VPN.</p>
          <p>The CIDR can also be a symbolic name that identifies a subnet or list of subnets:</p><table><tbody>
          <tr><td><code>also</code></td><td>All subnets added with --also-proxy</td></tr>
          <tr><td><code>service</code></td><td>The cluster's service subnet</td></tr>
          <tr><td><code>pods</code></td><td>The cluster's pod subnets.</td></tr>
          <tr><td><code>all</code></td><td>All of the above.</td></tr>
          </tbody></table>
      - type: bugfix
        title: Ensure that agent.appProtocolStrategy is propagated correctly.
        body: >-
          The <code>agent.appProtocolStrategy</code> was inadvertently dropped when moving license related code fromm the
          OSS repository the repository for the Enterprise version of Telepresence. It has now been restored.
      - type: bugfix
        title: Include non-default zero values in output of telepresence config view.
        body: >-
          The <code>telepresence config view</code> command will now print zero values in the output when
          the default for the value is non-zero.
      - type: bugfix
        title: Restore ability to run the telepresence CLI in a docker container.
        body: >-
          The improvements made to be able to run the telepresence daemon in docker
          using <code>telepresence connect --docker</code> made it impossible to run
          both the CLI and the daemon in docker. This commit fixes that and
          also ensures that the user- and root-daemons are merged in this
          scenario when the container runs as root.
      - type: bugfix
        title: Remote mounts when intercepting with the --replace flag.
        body: >-
          A <code>telepresence intercept --replace</code> did not correctly mount all volumes, because when the
          intercepted container was removed, its mounts were no longer visible to the agent-injector when it
          was subjected to a second invocation. The container is now kept in place, but with an image that
          just sleeps infinitely.
      - type: bugfix
        title: Intercepting with the --replace flag will no longer require all subsequent intercepts to use --replace.
        body: >-
          A <code>telepresence intercept --replace</code> will no longer switch the mode of the intercepted workload,
          forcing all subsequent intercepts on that workload to use <code>--replace</code> until the agent is
          uninstalled. Instead, <code>--replace</code> can be used interchangeably just like any other intercept flag.
      - type: bugfix
        title: Kubeconfig exec authentication with context names containing colon didn't work on Windows
        body: >-
          The logic added to allow the root daemon to connect directly to the cluster using the user daemon as a proxy
          for exec type authentication in the kube-config, didn't take into account that a context name sometimes
          contains the colon ":" character. That character cannot be used in filenames on windows because it is the
          drive letter separator.
      - type: bugfix
        title: Provide agent name and tag as separate values in Helm chart
        body: >-
          The <code>AGENT_IMAGE</code> was a concatenation of the agent's name and tag. This is now changed so that the
          env instead contains an <code>AGENT_IMAGE_NAME</code> and <code>AGENT_INAGE_TAG</code>. The <code>AGENT_IMAGE
          </code> is removed. Also, a new env <code>REGISTRY</code> is added, where the registry of the traffic-
          manager image is provided. The <code>AGENT_REGISTRY</code> is no longer required
          and will default to <code>REGISTRY</code> if not set.
      - type: bugfix
        title: Environment interpolation expressions were prefixed twice.
        body: >-
          Telepresence would sometimes prefix environment interpolation expressions in the traffic-agent twice so
          that an expression that looked like <code>$(SOME_NAME)</code> in the app-container, ended up as <code>
          $(_TEL_APP_A__TEL_APP_A_SOME_NAME)</code> in the corresponding expression in the traffic-agent.
      - type: bugfix
        title: Panic in root-daemon on darwin workstations with full access to cluster network.
        body: >-
          A darwin machine with full access to the cluster's subnets will never create a TUN-device, and a check was
          missing if the device actually existed, which caused a panic in the root daemon.
      - type: bugfix
        title: Show allow-conflicting-subnets in telepresence status and telepresence config view.
        body: >-
          The <code>telepresence status</code> and <code>telepresence config view</code> commands didn't show the
          <code>allowConflictingSubnets</code> CIDRs because the value wasn't propagated correctly to the CLI.
      - type: feature
        title: It is now possible use a host-based connection and containerized connections simultaneously.
        body: >-
          Only one host-based connection can exist because that connection will alter the DNS to reflect the namespace
          of the connection. but it's now possible to create additional connections using <code>--docker</code> while
          retaining the host-based connection.
      - type: feature
        title: Ability to set the hostname of a containerized daemon.
        body: >-
          The hostname of a containerized daemon defaults to be the container's ID in Docker. You now can override the
          hostname using <code>telepresence connect --docker --hostname &lt;a name&gt;</code>.
      - type: feature
        title: New <code>--multi-daemon</code>flag to enforce a consistent structure for the status command output.
        body: >-
          The output of the <code>telepresence status</code> when using <code>--output json</code> or <code>--output
          yaml</code> will either show an object where the <code>user_daemon</code> and <code>root_daemon</code>
          are top level elements, or when multiple connections are used, an object where a <code>connections</code>
          list contains objects with those daemons. The flag <code>--multi-daemon</code> will enforce the latter
          structure even when only one daemon is connected so that the output can be parsed consistently. The reason
          for keeping the former structure is to retain backward compatibility with existing parsers.
      - type: bugfix
        title: Make output from telepresence quit more consistent.
        body: >-
          A quit (without -s) just disconnects the host user and root daemons but will quit a container based daemon.
          The message printed was simplified to remove some have/has is/are errors caused by the difference.
      - type: bugfix
        title: "Fix &quot;tls: bad certificate&quot; errors when refreshing the mutator-webhook secret"
        body: >-
          The <code>agent-injector</code> service will now refresh the secret used by the <code>mutator-webhook</code>
          each time a new connection is established, thus preventing the certificates to go out-of-sync when
          the secret is regenerated.
      - type: bugfix
        title: Keep telepresence-agents configmap in sync with pod states.
        body: >-
          An intercept attempt that resulted in a timeout due to failure of injecting the traffic-agent left the
          <code>telepresence-agents</code> configmap in a state that indicated that an agent had been added, which
          caused problems for subsequent intercepts after the problem causing the first failure had been fixed.
      - type: bugfix
        title: The <code>telepresence status</code> command will now report the status of all running daemons.
        body: >-
          A <code>telepresence status</code>, issued when multiple containerized daemons were active, would error with
          &quot;multiple daemons are running, please select one using the --use &lt;match&gt; flag&quot;. This is now
          fixed so that the command instead reports the status of all running daemons.
      - type: bugfix
        title: The <code>telepresence version</code> command will now report the version of all running daemons.
        body: >-
          A <code>telepresence version</code>, issued when multiple containerized daemons were active, would error with
          &quot;multiple daemons are running, please select one using the --use &lt;match&gt; flag&quot;. This is now
          fixed so that the command instead reports the version of all running daemons.
      - type: bugfix
        title: Multiple containerized daemons can now be disconnected using <code>telepresence quit -s</code>
        body: >-
          A <code>telepresence quit -s</code>, issued when multiple containerized daemons were active, would error with
          &quot;multiple daemons are running, please select one using the --use &lt;match&gt; flag&quot;. This is now
          fixed so that the command instead quits all daemons.
      - type: bugfix
        title: The DNS search path on Windows is now restored when Telepresence quits
        body: >-
          The DNS search path that Telepresence uses to simulate the DNS lookup functionality in the connected
          cluster namespace was not removed by a <code>telepresence quit</code>, resulting in connectivity problems
          from the workstation. Telepresence will now remove the entries that it has added to the search list when
          it quits.
      - type: bugfix
        title: The user-daemon would sometimes get killed when used by multiple simultaneous CLI clients.
        body: >-
          The user-daemon would die with a fatal &quot;fatal error: concurrent map writes&quot; error in the
          <code>connector.log</code>, effectively killing the ongoing connection.
      - type: bugfix
        title: Multiple services ports using the same target port would not get intercepted correctly.
        body: >-
          Intercepts didn't work when multiple service ports were using the same container port. Telepresence would
          think that one of the ports wasn't intercepted and therefore disable the intercept of the container port.
      - type: bugfix
        title: Root daemon refuses to disconnect.
        body: >-
          The root daemon would sometimes hang forever when attempting to disconnect due to a deadlock in
          the VIF-device.
      - type: bugfix
        title: Fix panic in user daemon when traffic-manager was unreachable
        body: >-
          The user daemon would panic if the traffic-manager was unreachable. It will now instead report
          a proper error to the client.
      - type: change
        title: Removal of backward support for versions predating 2.6.0
        body: >-
          The telepresence helm installer will no longer discover and convert workloads that were modified by versions
          prior to 2.6.0. The traffic manager will and no longer support the muxed tunnels used in versions prior to
          2.5.0.
  - version: 2.17.0
    date: "2023-11-14"
    notes:
      - type: feature
        title: Additional Prometheus metrics to track intercept/connect activity
        body: >-
          This feature adds the following metrics to the Prometheus endpoint: <code>connect_count</code>,
          <code>connect_active_status</code>, <code>intercept_count</code>, and <code>intercept_active_status</code>.
          These are labeled by client/install_id.
          Additionally, the <code>intercept_count</code> metric has been renamed to <code>active_intercept_count</code>
          for clarity.
      - type: feature
        title: Make the Telepresence client docker image configurable.
        body: >-
          The docker image used when running a Telepresence intercept in docker mode can now be configured using
          the setting <code>images.clientImage</code> and will default first to the value of the environment <code>
          TELEPRESENCE_CLIENT_IMAGE</code>, and then to the value preset by the telepresence binary. This
          configuration setting is primarily intended for testing purposes.
      - type: feature
        title: Use traffic-agent port-forwards for outbound and intercepted traffic.
        body: >-
          The telepresence TUN-device is now capable of establishing direct port-forwards to a traffic-agent in the
          connected namespace. That port-forward is then used for all outbound traffic to the device, and also for
          all traffic that arrives from intercepted workloads. Getting rid of the extra hop via the traffic-manager
          improves performance and reduces the load on the traffic-manager. The feature can only be used if the client
          has Kubernetes port-forward permissions to the connected namespace. It can be disabled by setting <code>
          cluster.agentPortForward</code> to <code>false</code> in <code>config.yml</code>.
      - type: feature
        title: Improve outbound traffic performance.
        body: >-
          The root-daemon now communicates directly with the traffic-manager instead of routing all outbound traffic
          through the user-daemon. The root-daemon uses a patched kubeconfig where <code>exec</code> configurations to
          obtain credentials are dispatched to the user-daemon. This to ensure that all authentication plugins will
          execute in user-space. The old behavior of routing everything through the user-daemon can be restored by
          setting <code>cluster.connectFromRootDaemon</code> to <code>false</code> in <code>config.yml</code>.
      - type: feature
        title: New networking CLI flag --allow-conflicting-subnets
        body: >-
          telepresence connect (and other commands that kick off a connect) now accepts an --allow-conflicting-subnets
          CLI flag. This is equivalent to client.routing.allowConflictingSubnets in the helm chart, but can be specified
          at connect time. It will be appended to any configuration pushed from the traffic manager.
      - type: change
        title: Warn if large version mismatch between traffic manager and client.
        body: >-
          Print a warning if the minor version diff between the client and the traffic manager is greater than three.
      - type: change
        title: The authenticator binary was removed from the docker image.
        body: >-
          The <code>authenticator</code> binary, used when serving proxied <code>exec</code> kubeconfig credential
          retrieval, has been removed. The functionality was instead added as a subcommand to the <code>telepresence
          </code> binary.
  - version: 2.16.1
    date: "2023-10-12"
    notes:
      - type: feature
        title: Add --docker-debug flag to the telepresence intercept command.
        body: >-
          This flag is similar to <code>--docker-build</code> but will start the container with more relaxed security
          using the <code>docker run</code> flags <code>--security-opt apparmor=unconfined --cap-add SYS_PTRACE</code>.
      - type: feature
        title: Add a --export option to the telepresence connect command.
        body: >-
          In some situations it is necessary to make some ports available to the
          host from a containerized telepresence daemon. This commit adds a
          repeatable <code>--expose &lt;docker port exposure&gt;</code> flag to the connect
          command.
      - type: feature
        title: Prevent agent-injector webhook from selecting from kube-xxx namespaces.
        body: >-
          The <code>kube-system</code> and <code>kube-node-lease</code> namespaces should not be affected by a
          global agent-injector webhook by default. A default <code>namespaceSelector</code> was therefore added
          to the Helm Chart <code>agentInjector.webhook</code> that contains a <code>NotIn</code> preventing those
          namespaces from being selected.
      - type: bugfix
        title: Backward compatibility for pod template TLS annotations.
        body: >-
          Users of Telepresence &lt; 2.9.0 that make use of the pod template TLS annotations were unable to upgrade because
          the annotation names have changed (now prefixed by "telepresence."), and the environment expansion of the
          annotation values was dropped. This fix restores support for the old names (while retaining the new ones) and
          the environment expansion.
      - type: security
        title: Built with go 1.21.3
        body: >-
          Built Telepresence with go 1.21.3 to address CVEs.
      - type: bugfix
        title: Match service selector against pod template labels
        body: >-
          When listing intercepts (typically by calling <code>telepresence list</code>) selectors of services are matched
          against workloads. Previously the match was made against the labels of the workload, but now they are matched
          against the labels pod template of the workload. Since the service would actually be matched against pods this
          is more correct. The most common case when this makes a difference is that statefulsets now are listed when they should.
  - version: 2.16.0
    date: "2023-10-02"
    notes:
      - type: bugfix
        title: The helm sub-commands will no longer start the user daemon.
        body: >-
          The <code>telepresence helm install/upgrade/uninstall</code> commands will no longer start the telepresence
          user daemon because there's no need to connect to the traffic-manager in order for them to execute.
      - type: bugfix
        title: Routing table race condition
        body: >-
          A race condition would sometimes occur when a Telepresence TUN device was deleted and another created in rapid
          succession that caused the routing table to reference interfaces that no longer existed.
      - type: bugfix
        title: Stop lingering daemon container
        body: >-
          When using <code>telepresence connect --docker</code>, a lingering container could be present, causing errors
          like &quot;The container name NN is already in use by container XX ...&quot;. When this happens, the connect
          logic will now give the container some time to stop and then call <code>docker stop NN</code> to stop it
          before retrying to start it.
      - type: bugfix
        title: Add file locking to the Telepresence cache
        body: >-
          Files in the Telepresence cache are accesses by multiple processes. The processes will now use advisory
          locks on the files to guarantee consistency.
      - type: change
        title: Lock connection to namespace
        body: >-
          The behavior changed so that a connected Telepresence client is bound to a namespace. The namespace can then
          not be changed unless the client disconnects and reconnects. A connection is also given a name. The default
          name is composed from <code>&lt;kube context name&gt;-&lt;namespace&gt;</code> but can be given explicitly
          when connecting using <code>--name</code>. The connection can optionally be identified using the option
          <code>--use &lt;name match&gt;</code> (only needed when docker is used and more than one connection is active).
      - type: change
        title: Deprecation of global --context and --docker flags.
        body: >-
          The global flags <code>--context</code> and <code>--docker</code> will now be considered deprecated unless used
          with commands that accept the full set of Kubernetes flags (e.g. <code>telepresence connect</code>).
      - type: change
        title: Deprecation of the --namespace flag for the intercept command.
        body: >-
          The <code>--namespace</code> flag is now deprecated for <code>telepresence intercept</code> command. The flag can instead
          be used with all commands that accept the full set of Kubernetes flags (e.g. <code>telepresence connect</code>).
      - type: change
        title: Legacy code predating version 2.6.0 was removed.
        body: >-
          The telepresence code-base still contained a lot of code that would modify workloads instead of relying on
          the mutating webhook installer when a traffic-manager version predating version 2.6.0 was discovered. This
          code has now been removed.
      - type: feature
        title: Add `telepresence list-namespaces` and `telepresence list-contexts` commands
        body: >-
          These commands can be used to check accessible namespaces and for automation.
      - type: change
        title: Implicit connect warning
        body: >-
          A deprecation warning will be printed if a command other than <code>telepresence connect</code> causes an
          implicit connect to happen. Implicit connects will be removed in a future release.
  - version: 2.15.1
    date: "2023-09-06"
    notes:
      - type: security
        title: Rebuild with go 1.21.1
        body: >-
          Rebuild Telepresence with go 1.21.1 to address CVEs.
      - type: security
        title: Set security context for traffic agent
        body: >-
          Openshift users reported that the traffic agent injection was failing due to a missing security context.
  - version: 2.15.0
    date: "2023-08-29"
    notes:
      - type: security
        title: Add ASLR to telepresence binaries
        body: >-
          ASLR hardens binary sercurity against fixed memory attacks.
      - type: feature
        title: Added client builds for arm64 architecture.
        body: >-
          Updated the release workflow files in github actions to including building and publishing the client binaries for arm64 architecture.
        docs: https://github.com/telepresenceio/telepresence/issues/3259
      - type: bugfix
        title: KUBECONFIG env var can now be used with the docker mode.
        body: >-
          If provided, the KUBECONFIG environment variable was passed to the kubeauth-foreground service as a parameter.
          However, since it didn't exist, the CLI was throwing an error when using <code>telepresence connect --docker</code>.
        docs: https://github.com/telepresenceio/telepresence/pull/3300
      - type: bugfix
        title: Fix deadlock while watching workloads
        body: >-
          The <code>telepresence list --output json-stream</code> wasn't releasing the session's lock after being
          stopped, including with a <code>telepresence quit</code>. The user could be blocked as a result.
        docs: https://github.com/telepresenceio/telepresence/pull/3298
      - type: bugfix
        title: Change json output of telepresence list command
        body: >-
          Replace deprecated info in the JSON output of the telepresence list command.
  - version: 2.14.4
    date: "2023-08-21"
    notes:
      - type: bugfix
        title: Nil pointer exception when upgrading the traffic-manager.
        body: >-
          Upgrading the traffic-manager using <code>telepresence helm upgrade</code> would sometimes
          result in a helm error message <q>executing "telepresence/templates/intercept-env-configmap.yaml"
          at &lt;.Values.intercept.environment.excluded&gt;: nil pointer evaluating interface {}.excluded"</q>
        docs: https://github.com/telepresenceio/telepresence/issues/3313
  - version: 2.14.2
    date: "2023-07-26"
    notes:
      - type: bugfix
        title: Telepresence now use the OSS agent in its latest version by default.
        body: >-
          The traffic manager admin was forced to set it manually during the chart installation.
        docs: https://github.com/telepresenceio/telepresence/issues/3271
  - version: 2.14.1
    date: "2023-07-07"
    notes:
      - type: feature
        title: Envoy's http idle timout is now configurable.
        body: >-
          A new <code>agent.helm.httpIdleTimeout</code> setting was added to the Helm chart that controls
          the proprietary Traffic agent's http idle timeout. The default of one hour, which in some situations
          would cause a lot of resource consuming and lingering connections, was changed to 70 seconds.
      - type: feature
        title: Add more gauges to the Traffic manager's Prometheus client.
        body: >-
          Several gauges were added to the Prometheus client to make it easier to monitor
          what the Traffic manager spends resources on.
      - type: feature
        title: Agent Pull Policy
        body: >-
          Add option to set traffic agent pull policy in helm chart.
      - type: bugfix
        title: Resource leak in the Traffic manager.
        body: >-
          Fixes a resource leak in the Traffic manager caused by lingering tunnels between the clients and
          Traffic agents. The tunnels are now closed correctly when terminated from the side that created them.
      - type: bugfix
        title: Fixed problem setting traffic manager namespace using the kubeconfig extension.
        body: >-
          Fixes a regression introduced in version 2.10.5, making it impossible to set the traffic-manager namespace
          using the telepresence.io kubeconfig extension.
        docs: https://www.telepresence.io/docs/reference/config#manager
  - version: 2.14.0
    date: "2023-06-12"
    notes:
      - type: feature
        title: DNS configuration now supports excludes and mappings.
        body: >-
          The DNS configuration now supports two new fields, excludes and mappings. The excludes field allows you to
          exclude a given list of hostnames from resolution, while the mappings field can be used to resolve a hostname with
          another.
        docs: https://github.com/telepresenceio/telepresence/pull/3172

      - type: feature
        title: Added the ability to exclude environment variables
        body: >-
          Added a new config map that can take an array of environment variables that will
          then be excluded from an intercept that retrieves the environment of a pod.

      - type: bugfix
        title: Fixed traffic-agent backward incompatibility issue causing lack of remote mounts
        body: >-
          A traffic-agent of version 2.13.3 (or 1.13.15) would not propagate the directories under
          <code>/var/run/secrets</code> when used with a traffic manager older than 2.13.3.

      - type: bugfix
        title: Fixed race condition causing segfaults on rare occasions when a tunnel stream timed out.
        body: >-
          A context cancellation could sometimes be trapped in a stream reader, causing it to incorrectly return
          an undefined message which in turn caused the parent reader to panic on a <code>nil</code> pointer reference.
        docs: https://github.com/telepresenceio/telepresence/pull/2963

      - type: change
        title: Routing conflict reporting.
        body: >-
          Telepresence will now attempt to detect and report routing conflicts with other running VPN software on client machines.
          There is a new configuration flag that can be tweaked to allow certain CIDRs to be overridden by Telepresence.

      - type: change
        title: test-vpn command deprecated
        body: >-
          Running telepresence test-vpn will now print a deprecation warning and exit. The command will be removed in a future release.
          Instead, please configure telepresence for your VPN's routes.
  - version: 2.13.3
    date: "2023-05-25"
    notes:
      - type: feature
        title: Add imagePullSecrets to hooks
        body: >-
          Add .Values.hooks.curl.imagePullSecrets and .Values.hooks curl.imagePullSecrets to Helm values.
        docs: https://github.com/telepresenceio/telepresence/pull/3079

      - type: change
        title: Change reinvocation policy to Never for the mutating webhook
        body: >-
          The default setting of the reinvocationPolicy for the mutating webhook dealing with agent injections changed from Never to IfNeeded.

      - type: bugfix
        title: Fix mounting fail of IAM roles for service accounts web identity token
        body: >-
          The eks.amazonaws.com/serviceaccount volume injected by EKS is now exported and remotely mounted during an intercept.
        docs: https://github.com/telepresenceio/telepresence/issues/3166

      - type: bugfix
        title: Correct namespace selector for cluster versions with non-numeric characters
        body: >-
          The mutating webhook now correctly applies the namespace selector even if the cluster version contains non-numeric characters. For example, it can now handle versions such as Major:"1", Minor:"22+".
        docs: https://github.com/telepresenceio/telepresence/pull/3184

      - type: bugfix
        title: Enable IPv6 on the telepresence docker network
        body: >-
          The "telepresence" Docker network will now propagate DNS AAAA queries to the Telepresence DNS resolver when it runs in a Docker container.
        docs: https://github.com/telepresenceio/telepresence/issues/3179

      - type: bugfix
        title: Fix the crash when intercepting with --local-only and --docker-run
        body: >-
          Running telepresence intercept --local-only --docker-run no longer  results in a panic.
        docs: https://github.com/telepresenceio/telepresence/issues/3171

      - type: bugfix
        title: Fix incorrect error message with local-only mounts
        body: >-
          Running telepresence intercept --local-only --mount false no longer results in an incorrect error message saying "a local-only intercept cannot have mounts".
        docs: https://github.com/telepresenceio/telepresence/issues/3171

      - type: bugfix
        title: specify port in hook urls
        body: >-
          The helm chart now correctly handles custom agentInjector.webhook.port that was not being set in hook URLs.
        docs: https://github.com/telepresenceio/telepresence/pull/3161

      - type: bugfix
        title: Fix wrong default value for disableGlobal and agentArrival
        body: >-
          Params .intercept.disableGlobal and .timeouts.agentArrival are now correctly honored.