Skip to content

docs: use current control plane admin port names - #2169

Open
lbarrosby wants to merge 2 commits into
linkerd:mainfrom
lbarrosby:docs/control-plane-admin-port-names
Open

lbarrosby wants to merge 2 commits into
linkerd:mainfrom
lbarrosby:docs/control-plane-admin-port-names

Conversation

@lbarrosby

Copy link
Copy Markdown

Problem

linkerd/linkerd2#14111 renamed the control plane container ports so they are unique per pod on Kubernetes 1.33 (admin-http became dest-admin, spval-admin, policy-admin, ident-admin, injector-admin, the service mirror uses svcmi-admin, and the viz Prometheus port became admin). The 2.19 and 2-edge docs still use admin-http in three places:

  • Exporting Metrics with an external Prometheus: the linkerd-controller job keeps only ports whose name is admin-http, and the linkerd-service-mirror job keeps only linkerd-service-mirror;admin-http. No container port has that name anymore, so following this page gives an external Prometheus that scrapes the proxies but none of the control plane or service mirror metrics. Nothing fails, so the data is just missing.
  • Exporting Metrics, federation ServiceMonitor: port: admin-http refers to a port on the viz Prometheus Service that no longer exists (it is admin), so the ServiceMonitor has no targets.
  • Using debug endpoints: the jsonpath lookup for admin-http on the identity pod prints nothing.

Solution

  • Use the relabeling that the bundled linkerd-viz Prometheus has used since fix(viz): adjust prometheus config to match new admin port names linkerd2#15090: keep ports ending in admin, then drop linkerd-admin so proxies aren't scraped twice by the controller job. The service mirror job matches (linkerd-service-mirror|controller);.*-admin$ like the chart does, which also covers the multicluster controller (ctrl-admin).
  • Point the federation ServiceMonitor at port admin.
  • Use ident-admin in the pprof example and link to the Control Plane Port Names reference for the other components.

The same change is applied to 2.19 and 2-edge. 2.18 and older predate the rename and are left as they are.

Validation

  • Checked the port names against the charts at edge-25.10.1 (2.19) and main: admin-http matches no control plane or viz port in either, and the new regexes keep every *-admin and admin port while excluding linkerd-admin.
  • markdownlint -c linkerd.io/.markdownlint.yaml passes on the changed files.

AI disclosure: written with the help of Claude Code, reviewed and tested by me.

Problem

linkerd/linkerd2#14111 renamed the control plane container ports for
Kubernetes 1.33 (admin-http became dest-admin, ident-admin, injector-admin
and so on, and the viz Prometheus port became admin). The 2.19 and 2-edge
docs still use admin-http:

- the external Prometheus scrape config keeps only ports named admin-http,
  so it scrapes no control plane or service mirror metrics at all;
- the federation ServiceMonitor points at a Prometheus Service port that no
  longer exists;
- the pprof example looks up a port named admin-http and prints nothing.

Solution

Use the same relabeling the bundled linkerd-viz Prometheus uses since
linkerd/linkerd2#15090 (keep ports ending in admin, drop linkerd-admin so
proxies aren't scraped twice), point the ServiceMonitor at port admin, and
use ident-admin in the debug endpoint example, linking to the port names
reference.

Validation

Port names checked against the charts at edge-25.10.1 (2.19) and main.
markdownlint passes on the changed files.

Signed-off-by: Lucas Barros <lucasbarros.kam@gmail.com>
@lbarrosby

Copy link
Copy Markdown
Author

Friendly ping. If this isn't something you want in the project, feel free to say so and I'll close it. The same goes for #2170, also from me.

…admin-port-names

Signed-off-by: Lucas Barros <lucasbarros.kam@gmail.com>
@netlify

netlify Bot commented Nov 16, 2026

Copy link
Copy Markdown

👷 Deploy request for linkerdio pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit 4abae04

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.

1 participant