Merge pull request #223 from telepresenceio/docs/v2.21.0

Docs release for 2.21.0-rc.0

Makefile

@@ -8,7 +8,7 @@ telepresence-remote:
 .PHONY: telepresence-remote
 
 # MATCH_TAGS is the regexp matching the tags that we expect will have docs.
-MATCH_TAGS ?= ^v2\.[2-9][0-9]+\.[0-9]+$$
+MATCH_TAGS ?= ^v2\.[2-9][0-9]+\.[0-9]+(-rc\.[0-9]+)?$$
 
 # EXCLUDE_TAGS is used when we want to exclude some of the matching tags from the telepresence repository
 EXCLUDE_TAGS ?=
@@ -37,3 +37,31 @@ pull-docs: telepresence-remote
 	git add .
 	rm -rf docs
 	git checkout HEAD -- docs
+
+DOCS_VERSION:=${DOCS_VERSION}
+DOCS_BRANCH:=${DOCS_BRANCH}
+
+.PHONY: read-branch
+read-branch:
+	git fetch telepresence
+	rm -rf docs
+	git add docs || true
+	git read-tree --prefix docs -u telepresence/$(DOCS_BRANCH):docs
+
+# drop-version will remove the version given by DOCS_VERSION.
+# Example:
+# DOCS_VERSION=2.21 make drop-version
+.PHONY: drop-version
+drop-version:
+	rm -rf "versioned_docs/version-$(DOCS_VERSION)"
+	rm -rf "versioned_sidebars/version-$(DOCS_VERSION)-sidebars.json"
+	jq '. - ["$(DOCS_VERSION)"]' versions.json > versions.tmp && mv versions.tmp versions.json
+
+# generate-version will first remove the given version and then regenerate it. Assumes that
+# read-branch has been called just prior.
+.PHONY: generate-version
+generate-version: drop-version
+	yarn docusaurus docs:version $(DOCS_VERSION)
+	rm -rf docs
+	git checkout HEAD -- docs
+	git add .

blog/2024-12-10-telepresence-2.21.md

@@ -0,0 +1,126 @@
+---
+title: Telepresence 2.21
+description: What's new in Telepresence 2.21.
+slug: telepresence-2.21
+authors:
+  - name: Thomas Hallgren
+    title: Maintainer of Telepresence OSS
+    url: https://github.com/thallgren
+    image_url: https://github.com/thallgren.png
+    socials:
+      linkedin: https://www.linkedin.com/in/thallgren/
+---
+
+Telepresence 2.21.0 has been released, and here is a walkthrough of its many new features, such as  automatic VPN
+conflict avoidance, the new `telepresence ingest` command, and the improved docker  support provided by commands like
+`telepresence curl` and `telepresence docker-run`.
+
+<!-- truncate -->
+
+## No More VPN Conflicts
+
+One of the most common problems for Telepresence users has been that the IP ranges used by the Kubernetes cluster that
+they connect to collide with IP ranges provided by other already existing networks on the workstation. Telepresence
+would refuse to connect when such a conflict was detected, and require that the user somehow specified how to resolve
+it. This is no longer the case. Starting with version 2.21.0, Telepresence will proactively resolve the conflict by
+moving the cluster subnets out of the way!
+
+### Virtual Network Address Translation (VNAT)
+The process of moving a subnet is fairly simple. The Telepresence DNS resolver will translate IPs returned by the
+cluster DNS resolver into an IP range that is guaranteed not to conflict, and the Telepresence Virtual Network
+Interface will then translate them back to their original on access.
+
+Telepresence will also ensure that any references to those IPs in the environment that is propagated when using
+`telepresence ingest` or `telepresence intercept` are translated as well. A local process using the environment will
+hence be able to use those IPs to connect to resources in the cluster.
+
+![VNAT](../static/img/vnat-dark.png#gh-dark-mode-only)![VPN Kubernetes config](../static/img/vnat.png#gh-light-mode-only)
+
+### VNAT Caveats
+
+Telepresence may not accurately detect cluster-side IP addresses being used by services running locally on a workstation
+in certain scenarios. This limitation arises when local services obtain IP addresses from remote sources such as
+databases or configmaps, or when IP addresses are sent to it in API calls.
+
+Using commands like `nslookup <svc name>` will show different IP addresses than the ones shown when using commands like
+`kubernetes get svc <svc name>` if the service subnet is subjected to VNAT translation. The same is true when using
+`nslookup <pod name>` and `kubernetes get pod -o wide`.
+
+In situations where VNAT causes problems, it can be disabled. Consult the Technical Reference documentation for more
+details on how to do that.
+
+## New Ingest Command
+
+The new ingest command can be thought of as a light version of intercept. It's in many respects the same thing, but
+without the traffic.
+
+Sometimes, intercepting network traffic to a container isn't the most efficient solution. For example, if you're working
+with a Kafka service that only interacts with a message broker, or if you're planning to send data to your local
+application through other means, just accessing the container's environment and volume mounts might be more practical.
+The new `telepresence ingest <workload> [--container <container name>]` command was designed for this purpose.
+
+First, `telepresence connect` establishes network access to the cluster. Then, `telepresence ingest` makes the
+container's environment and volume mounts available locally, allowing local processes to run, but without receiving
+intercepted traffic.
+
+The syntax for the ingest and intercept commands are very similar, but while the intercept will target a port to
+intercept (and implicitly a container), the ingest command will target a container directly.
+
+There's no conflict when several ingests of the same container, possibly on different workstations, happen
+simultaneously, because volumes are always mounted read-only, and everything happens on the client side.
+
+### Why the term "ingest"?
+I initially considered adding a `--no-traffic` option to the `intercept` command. This would allow users to invoke the
+command without actually intercepting traffic. However, given that "intercept" inherently implies the act of
+intercepting, such an option would be counterintuitive and potentially confusing.
+
+The term "ingest" was [suggested by a user](https://github.com/telepresenceio/telepresence/issues/3713), and it has a
+nice ring to it. The local process indeed ingests the remote container's environment and volume mounts.
+
+## Improved Docker Support
+
+The cluster network that Telepresence makes available when connecting using `telepresence connect --docker`, will be
+confined to the daemon container, so commands like `curl` or `nslookup` would not find the cluster resources when
+executed on the host. To run a curl command, you'd have to do something like:
+
+### telepresence curl
+
+```bash
+docker run --network container:<daemon container name> curlimages/curl <name of service>
+```
+
+The command `telepresence curl` will run a standard `curl` from a docker image that shares the daemon container's
+network, and the above can be replaced with:
+
+```bash
+telepresence curl <name of service>
+```
+
+### telepresence docker-run
+
+The `telepresence docker-run` will do a `docker run` and attach the daemon network. So a command like:
+```bash
+docker run --network container:<daemon container name> --rm -it jonlabell/network-tools ip route
+```
+becomes:
+```bash
+telepresence docker-run --rm -it jonlabell/network-tools ip route
+```
+
+The command will also ensure that port flags like `--publish`, `--expose` works by circumventing the Docker network
+limitation using ephemeral socat containers. It will even enable adding additional `--network` flags by temporarily
+adding them to the daemon container.
+
+The `telpresence intercept/ingest --docker-run` now also leverages this technique.
+
+## Performance Improvements
+
+This release contains several performance improvements. Most notably perhaps the rewrite of the `telepresence list`
+command, so that it now retrieves its data from the traffic-manager instead of doing a large number of API calls to
+the Kubernetes API. This makes a huge difference when the namespace contains a large number of workloads.
+
+## And there's more
+
+The release contains several other improvements such as Windows arm64 support, and the ability to exclude certain
+workload types to offload the traffic-manager. And, of course, a number of bugfixes. For a full list, please review the
+[release notes](../docs/release-notes).

docusaurus.config.ts

@@ -57,9 +57,10 @@ const config: Config = {
 		[
 			'classic',
 			{
+				blog: {
+					beforeDefaultRemarkPlugins: [remarkGithubAdmonitionsToDirectives],
+				},
 				docs: {
-					// Please change this to your repo.
-					// Remove this to remove the "edit this page" links.
 					editUrl: ({docPath}) => {
 						return `https://github.com/telepresenceio/telepresence/tree/thallgren/add-documentation/docs/${docPath}`
 					},
@@ -124,6 +125,11 @@ const config: Config = {
 					docId: 'quick-start',
 					label: 'Docs',
 				},
+				{
+					to: 'blog',
+					position: 'left',
+					label: 'Blog'
+				},
 				{
 					to: 'case-studies',
 					position: 'left',
@@ -180,7 +186,7 @@ const config: Config = {
 	plugins: ["docusaurus-plugin-sass", "./src/plugins/configure-svgo.ts"],
 
 	customFields: {
-		canonicalBaseUrl: "https://www.getambassador.io",
+		canonicalBaseUrl: "https://www.telepresence.io",
 	}
 };
 

src/components/ReleaseNotes/index.tsx

@@ -29,26 +29,15 @@ type TitleProps = {
 export const Title: React.FC<TitleProps> = ({children, type, docs, href}) => {
 	const typeKey = type as keyof typeof titlePrefix;
 
-	const handleViewMore = () => {
-		if (href) {
-			return;
-		}
-		if (docs) {
-			if (docs.indexOf('https://') === 0) {
-				window.location.href = docs;
-			}
-		}
+	if(docs || href) {
+		return (
+		<a className={styles.note__title_link} href={docs ? docs: href}>
+			{typeIcon[typeKey]}
+			<span>{children}</span>
+		</a>)
 	}
-
 	return (
-		<h3
-			className={
-				docs || href
-					? styles.note__title
-					: styles.note__title_no_link
-			}
-			onClick={handleViewMore}
-		>
+		<h3 className={styles.note__title_no_link}>
 			{typeIcon[typeKey]}
 			<span>{children}</span>
 		</h3>

src/components/ReleaseNotes/styles.module.scss

@@ -55,6 +55,25 @@
       color: $blue-dark;
     }
 
+    &_link {
+			font-size: var(--ifm-h3-font-size);
+			color: var(--ifm-heading-color);
+      font-family: var(--ifm-heading-font-family);
+      font-weight: var(--ifm-heading-font-weight);
+      line-height: var(--ifm-heading-line-height);
+      margin: var(--ifm-heading-margin-top) 0 var(--ifm-heading-margin-bottom) 0;
+      margin-block-start: 1em;
+      margin-block-end: 1em;
+      margin-inline-start: 0px;
+      margin-inline-end: 0px;
+      display: grid;
+      grid-template-columns: 20px auto;
+
+      span {
+        padding: 0 0 0 15px;
+      }
+		}
+
     &_no_link {
       display: grid;
       grid-template-columns: 20px auto;

src/css/custom.css

@@ -28,3 +28,7 @@
   --ifm-color-primary-lightest: #4fddbf;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
+[data-theme='light'] img[src$='#gh-dark-mode-only'],
+[data-theme='dark'] img[src$='#gh-light-mode-only'] {
+  display: none;
+}

src/theme/DocItem/Metadata/index.tsx

@@ -12,9 +12,7 @@ type Props = WrapperProps<typeof MetadataType>;
 export default function MetadataWrapper(props: Props): JSX.Element {
   const { siteConfig: {customFields}} = useDocusaurusContext()
   const { pathname } = useLocation();
-  const { metadata } = useDoc();
-  const vpath = pathname.replace(/^\/docs\//, `/docs/telepresence/${metadata.version}/`)
-  const canonical = `${customFields['canonicalBaseUrl']}${vpath}`
+  const canonical = `${customFields['canonicalBaseUrl']}${pathname}`
 
   return (
     <>

versioned_docs/version-2.21/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Telepresence Documentation
+
+This folder contains the Telepresence documentation in a format suitable for a versioned folder in the
+telepresenceio/telepresence.io repository. The folder will show up in that repository when a new minor revision
+tag is created here.
+
+Assuming that a 2.20.0 release is pending, and that a release/v2.20.0 branch has been created, then:
+```console
+$ export TELEPRESENCE_VERSION=v2.20.0
+$ make prepare-release
+$ git push origin {,rpc/}v2.20.0 release/v2.20.0
+```
+
+will result in a `docs/v2.20` folder with this folder's contents in the telepresenceio/telepresence.io repository.
+
+Subsequent bugfix tags for the same minor tag, i.e.:
+```console
+$ export TELEPRESENCE_VERSION=v2.20.1
+$ make prepare-release
+$ git push origin {,rpc/}v2.20.1 release/v2.20.1
+```
+will not result in a new folder when it is pushed, but it will update the content of the `docs/v2.20` folder to
+reflect this folder's content for that tag.

versioned_docs/version-2.21/README.md

@@ -0,0 +1,45 @@
+---
+description: Main menu when using plain markdown. Excluded when generating the website
+---
+# <img src="images/logo.png" height="64px"/> Telepresence Documentation
+raw markdown version, more bells and whistles at [telepresence.io](https://telepresence.io)
+
+- [Quick start](quick-start.md)
+- Install Telepresence
+  - [Install Client](install/client.md)
+  - [Upgrade Client](install/upgrade.md)
+  - [Install Traffic Manager](install/manager.md)
+  - [Cloud Provider Prerequisites](install/cloud.md)
+- Core concepts
+  - [The developer experience and the inner dev loop](concepts/devloop.md)
+  - [Making the remote local: Faster feedback, collaboration and debugging](concepts/faster.md)
+  - [Using Telepresence with Docker](concepts/docker.md)
+  - [Intercepts](concepts/intercepts.md)
+- How do I...
+  - [Code and debug an application locally](howtos/intercepts.md)
+  - [Work with large clusters](howtos/large-clusters.md)
+  - [Host a cluster in Docker or a VM](howtos/cluster-in-vm.md)
+- Technical reference
+  - [Architecture](reference/architecture.md)
+  - [Client reference](reference/client.md)
+  - [Laptop-side configuration](reference/config.md)
+  - [Cluster-side configuration](reference/cluster-config.md)
+  - [Using Docker for intercepts](reference/docker-run.md)
+  - [Running Telepresence in a Docker container](reference/inside-container.md)
+  - [Environment variables](reference/environment.md)
+  - Intercepts
+    - [Configure intercept using CLI](reference/intercepts/cli.md)
+    - [Traffic Agent Sidecar](reference/intercepts/sidecar.md)
+    - [Target a specific container](reference/intercepts/container.md)
+  - [Volume mounts](reference/volume.md)
+  - [DNS resolution](reference/dns.md)
+  - [RBAC](reference/rbac.md)
+  - [Telepresence and VPNs](reference/vpn.md)
+  - [Networking through Virtual Network Interface](reference/tun-device.md)
+  - [Connection Routing](reference/routing.md)
+  - [Monitoring](reference/monitoring.md)
+- [FAQs](faqs.md)
+- [Troubleshooting](troubleshooting.md)
+- [Community](community.md)
+- [Release Notes](release-notes.md)
+- [Licenses](licenses.md)

versioned_docs/version-2.21/community.md

@@ -0,0 +1,13 @@
+---
+title: Community
+hide_table_of_contents: true
+---
+
+# Community
+
+## Contributor's guide
+Please review our [contributor's guide](https://github.com/telepresenceio/telepresence/blob/release/v2/CONTRIBUTING.md)
+on GitHub to learn how you can help make Telepresence better.
+
+## Meetings
+Check out our community [meeting schedule](https://github.com/telepresenceio/telepresence/blob/release/v2/MEETING_SCHEDULE.md) for opportunities to interact with Telepresence developers.