Squashed 'docs/pre-release/' changes from f272202d..7503dfc8

7503dfc8 Don't use backslash in container mount paths. 30851852 Ensure that DPipe stderr is logged as errors d0815f68 Merge branch 'release/v2' into donnyyung/gh-actions e884bfab Update docs 20aea3ed Add release notes and documentation. git-subtree-dir: docs/pre-release git-subtree-split: 7503dfc8ad1f0c679cd72e05e31a026a765ab144
telepresenceio · Jan 10, 2022 · c10d58d · c10d58d
1 parent adf0760
commit c10d58d
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 12 deletions.
diff --git a/reference/config.md b/reference/config.md
@@ -31,6 +31,9 @@ grpc:
   maxReceiveSize: 10Mi
 telepresenceAPI:
   port: 9980
+intercept:
+  appProtocolStrategy: portName
+  defaultPort: "8088"
 ```
 
 #### Timeouts
@@ -62,8 +65,6 @@ case insensitive:
  - `info`
  - `warning` or `warn`
  - `error`
- - `fatal`
- - `panic`
 
 For whichever log-level you select, you will get logs labeled with that level and of higher severity.
 (e.g. if you use `info`, you will also get logs labeled `error`. You will NOT get logs labeled `debug`.
@@ -134,6 +135,29 @@ The `telepresenceAPI` controls the behavior of Telepresence's RESTful API server
 If the `traffic-manager` is auto-installed, its webhook agent injector will be configured to add the `TELEPRESENCE_API_PORT` environment to the app container when the `traffic-agent` is injected.
 See [RESTful API server](../restapi) for more info.
 
+#### Intercept
+The `intercept` controls applies to how telepresence will intercept the communications to the intercepted service.
+
+The `defaultPort` controls what port that will be selected when no `--port` flag is given to the `telepresence intercept` command. The default value is "8080".
+
+The `appProtocolStrategy` is only relevant when using personal intercepts and controls how telepresence selects the application protocol to use when intercepting a service that has no `service.ports.appProtocol` defined. Valid values are:
+
+| Value        | Resulting action                                                                                       |
+|--------------|--------------------------------------------------------------------------------------------------------|
+| `http2Probe` | The telepresence traffic-agent will probe the intercepted container to check whether it supports http2 |
+| `portName`   | Telepresence will make an educated guess about the protocol based on the name of the service port      |
+| `http`       | Telepresence will use http                                                                             |
+| `http2`      | Telepresence will use http2                                                                            |
+
+When `portName` is used, Telepresence will determine the protocol by the name of the port: `<protocol>[-suffix]`. The following protocols are recognized:
+
+| Protocol | Meaning                               |
+|----------|---------------------------------------|
+| `http`   | Plaintext HTTP/1.1 traffic            |
+| `http2`  | Plaintext HTTP/2 traffic              |
+| `https`  | TLS Encrypted HTTP (1.1 or 2) traffic |
+| `grpc`   | Same as http2                         |
+
 ## Per-Cluster Configuration
 Some configuration is not global to Telepresence and is actually specific to a cluster.  Thus, we store that config information in your kubeconfig file, so that it is easier to maintain per-cluster configuration.
 

diff --git a/reference/intercepts/index.md b/reference/intercepts/index.md
@@ -68,14 +68,25 @@ your cluster; if it detects it correctly, may simply press "enter" and
 accept the default, otherwise you must tell Telepresence the correct
 value.
 
-When creating an intercept with the `http` mechanism, the
-traffic-agent sends a `GET /telepresence-http2-check` request to your
-service and to the process running on your local machine at the port
-specified in your intercept, in order to determine if they support
-HTTP/2.  This is required for the intercepts to behave correctly.  If
-you do not have a service running locally when the intercept is
-created, the traffic-agent will use the result it got from checking
-the in-cluster service.
+When creating an intercept with the `http` mechanism, Telepresence must
+determine the application protocol to use (HTTP/1.1 or HTTP/2). If the
+service's `ports.appProtocol` field is set, it will be used. If not, then
+Telepresence will use the configured [application protocol strategy](../config/#intercept)
+to determine the protocol. The default behavior (`http2Probe` strategy) is
+to send a `GET /telepresence-http2-check` request to your service in order
+to determine if it supports HTTP/2.  This is required for the intercepts to
+behave correctly.
+
+### TLS
+
+If the intercepted service expects TLS, then Telepresence must terminate the
+TLS in order to use the `http` mechanism. It is then common to also restore
+the TLS by originating it again. This is controlled using [TLS annotations](../cluster-config/#tls)
+in the workload.
+
+Use the `--http-plaintext` flag when doing an intercept when the service in the
+cluster is using TLS in case you want to use plaintext for the communication with the
+process on your local workstation. 
 
 ## Supported workloads
 
@@ -224,7 +235,7 @@ Oftentimes, there's a 1-to-1 relationship between a service and a
 workload, so telepresence is able to auto-detect which service it
 should intercept based on the workload you are trying to intercept.
 But if you use something like
-[Argo](https://www.getambassador.io/docs/argo/latest/), there may be
+[Argo](https://www.getambassador.io/docs/argo/latest/quick-start/), there may be
 two services (that use the same labels) to manage traffic between a
 canary and a stable service.
 

diff --git a/release-notes/telepresence-2.4.10-actions.png b/release-notes/telepresence-2.4.10-actions.png
diff --git a/releaseNotes.yml b/releaseNotes.yml
@@ -26,7 +26,6 @@
 #             `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.
-#         - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link.
 
 docTitle: Telepresence Release Notes
 docDescription: >-
@@ -39,6 +38,61 @@ docDescription: >-
 changelog: https://github.com/telepresenceio/telepresence/blob/$branch$/CHANGELOG.md
 
 items:
+  - version: 2.4.10
+    date: "(TBD)"
+    notes:
+      - type: feature
+        title: Application Protocol Strategy
+        body: >-
+          The strategy used when selecting the application protocol for personal intercepts can now be configured using
+          the <code>intercept.appProtocolStrategy</code> in the <code>config.yml</code> file.
+        docs: reference/config/#intercept
+      - type: feature
+        title: Helm value for the Application Protocol Strategy
+        body: >-
+          The strategy when selecting the application protocol for personal intercepts in agents injected by the
+          mutating webhook can now be configured using the <code>agentInjector.appProtocolStrategy</code> in the Helm chart.
+        docs: install/helm
+      - type: feature
+        title: New <code>--http-plaintext</code> option
+        body: >-
+          The flag <code>--http-plaintext</code> can be used to ensure that an intercept uses plaintext http or grpc when
+          communicating with the workstation process.
+        docs: reference/intercepts/#tls
+      - type: feature
+        title: Configure the default intercept port
+        body: >-
+          The port used by default in the <code>telepresence intercept</code> command (8080), can now be changed by setting
+          the <code>intercept.defaultPort</code> in the <code>config.yml</code> file.
+        docs: reference/config/#intercept
+      - type: change
+        title: Telepresence CI now uses Github Actions
+        body: >-
+          Telepresence now uses Github Actions for doing unit and integration testing. It is
+          now easier for contributors to run tests on PRs since maintainers can add an
+          "ok to test" label to PRs (including from forks) to run integration tests.
+        docs: https://github.com/telepresenceio/telepresence/actions
+        image: telepresence-2.4.10-actions.png
+      - type: bugfix
+        title: Check conditions before asking questions
+        body: >-
+          User will not be asked to log in or add ingress information when creating an intercept until a check has been 
+          made that the intercept is possible.
+        docs: reference/intercepts/
+      - type: bugfix
+        title: Fix invalid log statement
+        body: >-
+          Telepresence will no longer log invalid: <code>"unhandled connection control message: code DIAL_OK"</code> errors.
+      - type: bugfix
+        title: Log errors from sshfs/sftp
+        body: >-
+          Output to <code>stderr</code> from the traffic-agent's <code>sftp</code> and the client's <code>sshfs</code> processes
+          are properly logged as errors.
+      - type: bugfix
+        title: Don't use Windows path separators in workload pod template
+        body: >-
+          Auto installer will no longer not emit backslash separators for the <code>/tel-app-mounts</code> paths in the
+          traffic-agent container spec when running on Windows.
   - version: 2.4.9
     date: "2021-12-09"
     notes: