Docs and release notes.

Signed-off-by: Thomas Hallgren <[email protected]>
telepresenceio · Oct 23, 2024 · e5128da · e5128da
1 parent f26b8d5
commit e5128da
Show file tree

Hide file tree

Showing 6 changed files with 97 additions and 29 deletions.
diff --git a/CHANGELOG.yml b/CHANGELOG.yml
@@ -36,11 +36,6 @@ items:
   - version: 2.21.0
     date: TBD
     notes:
-      - 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: Intercepts targeting a specific container
         body: ->
@@ -55,6 +50,25 @@ items:
           client originate from the specified container. Additionally, if the
           `--replace` option is used, it ensures that this container is replaced.
         docs: https://telepresence.io/docs/reference/intercepts/container
+      - 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: https://telepresence.io/docs/reference/config
+      - 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.
   - version: 2.20.2
     date: 2024-10-21
     notes:

diff --git a/docs/install/manager.md b/docs/install/manager.md
@@ -61,11 +61,18 @@ clusters:
     extensions:
     - name: telepresence.io
       extension:
-        manager:
-          namespace: staging
+        cluster:
+          defaultManagerNamespace: staging
   name: example-cluster
 ```
 
+or add the config the `config.yml`:
+
+```yaml
+cluster:
+ defaultManagerNamespace: staging
+```
+
 See [the kubeconfig documentation](../reference/config.md#manager) for more information.
 
 ## Upgrading/Downgrading the Traffic Manager.

diff --git a/docs/reference/cluster-config.md b/docs/reference/cluster-config.md
@@ -5,8 +5,7 @@ title: Cluster-side configuration
 
 For the most part, Telepresence doesn't require any special
 configuration in the cluster and can be used right away in any
-cluster (as long as the user has adequate [RBAC permissions](rbac.md)
-and the cluster's server version is `1.19.0` or higher).
+cluster (as long as the user has adequate [RBAC permissions](rbac.md).
 
 ## Helm Chart configuration
 Some cluster specific configuration can be provided when installing

diff --git a/docs/reference/config.md b/docs/reference/config.md
@@ -5,8 +5,8 @@ title: Laptop-side configuration
 # Laptop-side configuration
 
 There are a number of configuration values that can be tweaked to change how Telepresence behaves.
-These can be set in two ways: globally, by a platform engineer with powers to deploy the Telepresence Traffic Manager, or locally by any user.
-One important exception is the location of the traffic manager itself, which, if it's different from the default of `ambassador`, [must be set](#manager) locally per-cluster to be able to connect.
+These can be set in three ways: globally, by a platform engineer with powers to deploy the Telepresence Traffic Manager, or locally by any user, either in the Telepresence configuration file `config.yml`, or as a Telepresence extension the Kubernetes configuration.
+One important exception is the configuration of the of the traffic manager namespace, which, if it's different from the default of `ambassador`, [must be set](#manager) locally to be able to connect.
 
 ## Global Configuration
 
@@ -246,9 +246,7 @@ For Linux, the above paths are for a user-level configuration. For system-level
 
 ### Values
 
-The config file currently supports values for the [cluster](#cluster), [grpc](#grpc), [images](#images), [logLevels](#log-levels),
-and [timeouts](#timeouts) keys.
-The definitions of these values are identical to those values in the `client` config above.
+The definitions of the values in the `config.yml` are identical to those values in the `client` config above, but without the top level `client` key.
 
 Here is an example configuration to show you the conventions of how Telepresence is configured:
 **note: This config shouldn't be used verbatim, since the registry `privateRepo` used doesn't exist**
@@ -271,12 +269,13 @@ grpc:
 
 Configuration that is specific to a cluster can also be overriden per-workstation by modifying your `$KUBECONFIG` file.
 It is recommended that you do not do this, and instead rely on upstream values provided to the Traffic Manager. This ensures
-that all users that connect to the Traffic Manager will have the same routing and DNS resolution behavior.
-An important exception to this is the [`manager.namespace` configuration](#manager) which must be set locally.
+that all users that connect to the Traffic Manager will behave the same.
+An important exception to this is the [`cluster.defaultManagerNamespace` configuration](#manager) which must be set locally.
 
 ### Values
 
-The kubeconfig supports values for `dns`, `also-proxy`, `never-proxy`, and `manager`.
+The definitions of the values in the Telepresence kubeconfig extension are identical to those values in the `config.yml` config. The values will be merged into the config and have higher
+priority when Telepresence is connected to the extended cluster.
 
 Example kubeconfig:
 ```yaml
@@ -287,15 +286,14 @@ clusters:
     extensions:
     - name: telepresence.io
       extension:
-        manager:
-          namespace: staging
+        cluster:
+          defaultManagerNamespace: staging
         dns:
-          include-suffixes: [.private]
-          exclude-suffixes: [.se, .com, .io, .net, .org, .ru]
-          local-ip: 8.8.8.8
-          lookup-timeout: 30s
-        never-proxy: [10.0.0.0/16]
-        also-proxy: [10.0.5.0/24]
+          includeSuffixes: [.private]
+          excludeSuffixes: [.se, .com, .io, .net, .org, .ru]
+        routing:
+          neverProxy: [10.0.0.0/16]
+          alsoProxy: [10.0.5.0/24]
   name: example-cluster
 ```
 
@@ -304,9 +302,11 @@ clusters:
 This is the one cluster configuration that cannot be set using the Helm chart because it defines how Telepresence  connects to
 the Traffic manager. When not default, that setting needs to be configured in the workstation's kubeconfig for the cluster.
 
-The `manager` key contains configuration for finding the `traffic-manager` that telepresence will connect to. It supports one key, `namespace`, indicating the namespace where the traffic manager is to be found
+The `cluster.defaultManagerNamespace` key contains configuration for finding the `traffic-manager` that telepresence will connect to.
 
-Here is an example kubeconfig that will instruct telepresence to connect to a manager in namespace `staging`:
+Here is an example kubeconfig that will instruct telepresence to connect to a manager in namespace `staging`. The setting can be overridden using the Telepresence connect flag `--manager-namespace`.
+
+Please note that the `cluster.defaultManagerNamespace` can be set in the `config.yml` too, but will then not be unique per cluster.
 
 ```yaml
 apiVersion: v1
@@ -316,8 +316,8 @@ clusters:
       extensions:
         - name: telepresence.io
           extension:
-            manager:
-              namespace: staging
+            cluster:
+              defaultManagerNamespace: staging
     name: example-cluster
 ```
 

diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -1,6 +1,34 @@
 
 [comment]: # (Code generated by relnotesgen. DO NOT EDIT.)
 # <img src="images/logo.png" height="64px"/> Telepresence Release Notes
+## Version 2.21.0
+## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">[Intercepts targeting a specific container](https://telepresence.io/docs/reference/intercepts/container)</div></div>
+<div style="margin-left: 15px">
+
+-> 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 commit 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.
+</div>
+
+## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">[Unify client configuration](https://telepresence.io/docs/reference/config)</div></div>
+<div style="margin-left: 15px">
+
+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.
+</div>
+
+## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">Make usage data collection configurable using an extension point, and default to no-ops</div></div>
+<div style="margin-left: 15px">
+
+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.
+</div>
+
+## <div style="display:flex;"><img src="images/bugfix.png" alt="bugfix" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">Allow comma separated list of daemons for the gather-logs command.</div></div>
+<div style="margin-left: 15px">
+
+-> 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`.
+</div>
+
 ## Version 2.20.2 <span style="font-size: 16px;">(October 21)</span>
 ## <div style="display:flex;"><img src="images/bugfix.png" alt="bugfix" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">Crash in traffic-manager configured with agentInjector.enabled=false</div></div>
 <div style="margin-left: 15px">

diff --git a/docs/release-notes.mdx b/docs/release-notes.mdx
@@ -7,6 +7,26 @@ import { Note, Title, Body } from '@site/src/components/ReleaseNotes'
 [comment]: # (Code generated by relnotesgen. DO NOT EDIT.)
 
 # Telepresence Release Notes
+## Version 2.21.0
+<Note>
+	<Title type="feature" docs="https://telepresence.io/docs/reference/intercepts/container">Intercepts targeting a specific container</Title>
+	<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 commit 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.</Body>
+</Note>
+<Note>
+	<Title type="feature" docs="https://telepresence.io/docs/reference/config">Unify client configuration</Title>
+	<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.</Body>
+</Note>
+<Note>
+	<Title type="feature">Make usage data collection configurable using an extension point, and default to no-ops</Title>
+	<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.</Body>
+</Note>
+<Note>
+	<Title type="bugfix">Allow comma separated list of daemons for the gather-logs command.</Title>
+	<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`.</Body>
+</Note>
 ## Version 2.20.2 <span style={{fontSize:'16px'}}>(October 21)</span>
 <Note>
 	<Title type="bugfix">Crash in traffic-manager configured with agentInjector.enabled=false</Title>