Skip to content

Update edge docs for native sidecars enabled by default in Linkerd 2.20#2123

Merged
alpeb merged 2 commits into
mainfrom
alpeb/native-sidecar-2.20
Jun 15, 2026
Merged

Update edge docs for native sidecars enabled by default in Linkerd 2.20#2123
alpeb merged 2 commits into
mainfrom
alpeb/native-sidecar-2.20

Conversation

@alpeb

@alpeb alpeb commented Jun 3, 2026

Copy link
Copy Markdown
Member

As of Linkerd 2.20 the proxy is injected by default as a native sidecar container (an init container with restartPolicy: Always) instead of a regular container. Update the edge docs accordingly:

  • features/native-sidecars.md: state the new default and replace the "Enabling" section with instructions for disabling the mode, via the config.linkerd.io/proxy-enable-native-sidecar: false annotation at the namespace or workload level, or globally via the Helm value proxy.nativeSidecar: false
  • features/proxy-injection.md, reference/architecture.md: mention the proxy is now injected as a native sidecar by default
  • features/cni.md, tasks/grafana.md: scope the initContainer networking limitation (and its workarounds) to the case where native sidecars have been disabled, since init containers now have network access by default
  • tasks/graceful-shutdown.md: meshed Jobs and Cronjobs now complete without extra configuration; scope the hanging-pod issue and the manual /shutdown workaround to the non-native-sidecar case. Drop the --wait-before-seconds option and the "Slow Updating Clients" section, which are no longer relevant with native sidecars
  • tasks/adding-your-service.md: fix the mesh verification command to look for the proxy under spec.initContainers instead of spec.containers

@alpeb alpeb force-pushed the alpeb/native-sidecar-2.20 branch from 87f49af to a90b2e2 Compare June 3, 2026 23:09

@raykroeker raykroeker left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left a comment related to clarity around manual shutdown and a question.

Comment thread linkerd.io/content/2-edge/tasks/graceful-shutdown.md Outdated
traffic cannot flow. In that case you should either avoid meshing grafana's
pod, skip outbound port 443 via the
`config.linkerd.io/skip-outbound-ports: "443"` annotation, or run the container
with the proxy's UID. See

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Running multiple processes under the same UID feels like a general anti-pattern. I understand we recommend it elsewhere, should we continue to promote it?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One advantage of this approach is that it keeps that specific init container out of the mesh, whereas the annotation alternative would apply to all containers in the pod. That said, I can see your point; it may be worth discussing further. If you feel strongly about it, please feel free to open a ticket so we can track it

As of Linkerd 2.20 the proxy is injected by default as a native sidecar
container (an init container with `restartPolicy: Always`) instead of a
regular container. Update the edge docs accordingly:

- features/native-sidecars.md: state the new default and replace the
  "Enabling" section with instructions for disabling the mode, via the
  `config.linkerd.io/proxy-enable-native-sidecar: false` annotation at
  the namespace or workload level, or globally via the Helm value
  `proxy.nativeSidecar: false`
- features/proxy-injection.md, reference/architecture.md: mention the
  proxy is now injected as a native sidecar by default
- features/cni.md, tasks/grafana.md: scope the initContainer networking
  limitation (and its workarounds) to the case where native sidecars
  have been disabled, since init containers now have network access by
  default
- tasks/graceful-shutdown.md: meshed Jobs and Cronjobs now complete
  without extra configuration; scope the hanging-pod issue and the
  manual /shutdown workaround to the non-native-sidecar case. Drop the
  `--wait-before-seconds` option and the "Slow Updating Clients"
  section, which are no longer relevant with native sidecars
- tasks/adding-your-service.md: fix the mesh verification command to
  look for the proxy under `spec.initContainers` instead of
  `spec.containers`
@alpeb alpeb force-pushed the alpeb/native-sidecar-2.20 branch from a90b2e2 to b8d907f Compare June 15, 2026 17:23
@alpeb alpeb merged commit 3c0d998 into main Jun 15, 2026
7 checks passed
@alpeb alpeb deleted the alpeb/native-sidecar-2.20 branch June 15, 2026 17:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants