feat(cli): document skip ports behavior for tap (#1966)

[Mike-4-prog]

Problem

The tap command did not have a dedicated reference page in the docs, making it harder for users to understand usage, flags, and the --skip-port behavior.

Solution

Create content/2.19/reference/cli/tap.md including:

• Usage examples for deployments and services

• Flags table with --namespace, --output, --help

• Notes about skipped ports and proxy behavior

• Clear description of purpose and behavior

Validation

Tested locally by running hugo server -D in the docs repo. Verified that:

• The tap page renders correctly

• Usage and examples match official Linkerd 2.19 CLI documentation

• Markdown formatting is consistent with other CLI pages

[kflynn]

Hmmmmm, have you run the commands in the doc? We probably don't want to document deprecated command forms...

[cratelyn]

miscellaneous questions:

[Mike-4-prog]

@kflynn @cratelyn
Thank you all for the feedback!

I'll update the formatting (whitespace, line wrapping, and header spacing)
to match the repository style.

I'll also double-check the command examples to ensure they match the
current CLI syntax and update them if needed.

Regarding the placement of this content, I'm happy to move it to the
existing dashboard/tap page if that would be preferred. Will get back as soon as I'm done. Thank you!

[Mike-4-prog]

Hi @kflynn, @cratelyn

I've updated the tap.md page to reflect the current linkerd viz tap command, including all valid flags and up-to-date examples tested on a local cluster.
After reviewing the docs, I think (my opinion though) this content is best kept on this reference page, rather than moving it to the Viz dashboard page, because tap is a CLI command reference and not about the dashboard itself. That said, I'd defer to your final decision on placement.

Please let me know if you’d like any additional adjustments.

[cratelyn]

thanks for addressing the feedback from before!

besides one lingering whitespace nit, this looks good. once we sort out a good home for this page (cc: @kflynn), we'll need to copy this content into linkerd.io/content/2-edge, and we'll be ready to merge this.

thank you again for taking the time to submit this, @Mike-4-prog!

[travisbeckham]

tap is already documented on the viz command page. Since tap is a sub command it is not listed in the top-level list of commands.

https://linkerd.io/2.19/reference/cli/viz/#tap

The discoverability of tap is not great, but I don't think it's a good idea to duplicate this content and treat it like a top level command, because we would have to be consistent and do it for all other sub commands.

I haven't thought about this too much, but maybe we could show sub commands on the listing page, although before we decide on a solution we should understand how much additional content would be displayed.

Another thing to note is that the content of the cli reference pages are pulled from data/cil/2-19.yaml. These data files are dynamically generated, and so I don't think we should be creating manual content for this one command.

[Mike-4-prog]

@travisbeckham @cratelyn @kflynn
Thanks for the clarification, @travisbeckham — that makes sense regarding tap being a subcommand under linkerd viz and the need to avoid duplicating content across the CLI reference.

My goal here was mainly to improve clarity around usage and flags (especially around skipped ports), but I agree that consistency across subcommands is important.

I’m happy to adapt this in whatever way fits best — whether that means refining the existing viz page content, or restructuring how subcommands like tap are surfaced for better discoverability.

I’ve also fixed the trailing whitespace issue in this PR.

Please let me know how you’d prefer to proceed.

[travisbeckham]

@Mike-4-prog There is some precedence for supplementing the dynamic content with manual content. You can see an example in viz routes. I think we could follow the same pattern and add the note about skipped ports in the tap section. If the description, examples, or flags need to be updated, then that should be done in the linkerd repo so it can be pulled in by the data files.

[Mike-4-prog]

@Mike-4-prog There is some precedence for supplementing the dynamic content with manual content. You can see an example in viz routes. I think we could follow the same pattern and add the note about skipped ports in the tap section. If the description, examples, or flags need to be updated, then that should be done in the linkerd repo so it can be pulled in by the data files.

Thanks, @travisbeckham — this is really helpful.

That makes sense to follow the existing pattern (like in viz routes) and avoid duplicating generated CLI reference content.

I’ll move the skipped ports note into the tap section on the viz page and remove the standalone tap.md approach.

I’ll leave flags, examples, and descriptions as-is since those should come from the main Linkerd repo.

I’ll push an update shortly.

[Mike-4-prog]

@travisbeckham
I’ve removed the standalone tap.md page to avoid duplicating generated CLI reference content, and added an in-line skipped ports note as part of the tap section in the viz page. Let me know if you’d like any adjustments to placement or wording.

[travisbeckham]

Thanks for making the change @Mike-4-prog.

Instead of using a blockquote to highlight the content, we have a {{< note >}} shortcode that can be used. It inserts the "Note:" text and icon automatically. For example:

{{< note >}}If a pod is configured with the annotations
`config.linkerd.io/skip-inbound-ports` or
`config.linkerd.io/skip-outbound-ports`, traffic on those ports bypasses the
Linkerd proxy. Because `linkerd tap` observes traffic through the proxy,
**traffic on skipped ports cannot be tapped**.{{< /note >}}

[Mike-4-prog]

Thanks for making the change @Mike-4-prog.

Instead of using a blockquote to highlight the content, we have a {{< note >}} shortcode that can be used. It inserts the "Note:" text and icon automatically. For example:

{{< note >}}If a pod is configured with the annotations
`config.linkerd.io/skip-inbound-ports` or
`config.linkerd.io/skip-outbound-ports`, traffic on those ports bypasses the
Linkerd proxy. Because `linkerd tap` observes traffic through the proxy,
**traffic on skipped ports cannot be tapped**.{{< /note >}}

@travisbeckham Great! Will fix this shortly and revert back. Thank you.

[Mike-4-prog]

Thanks for making the change @Mike-4-prog.
Instead of using a blockquote to highlight the content, we have a {{< note >}} shortcode that can be used. It inserts the "Note:" text and icon automatically. For example:

{{< note >}}If a pod is configured with the annotations
`config.linkerd.io/skip-inbound-ports` or
`config.linkerd.io/skip-outbound-ports`, traffic on those ports bypasses the
Linkerd proxy. Because `linkerd tap` observes traffic through the proxy,
**traffic on skipped ports cannot be tapped**.{{< /note >}}

@travisbeckham Great! Will fix this shortly and revert back. Thank you.

Thanks, @travisbeckham — updated to use the note shortcode.

[travisbeckham]

Thanks @Mike-4-prog! This looks good to me, although it will need to be copied to the edge-2 docs. @kflynn, I'll let you give the final approval on this change.

[Mike-4-prog]

Thanks @Mike-4-prog! This looks good to me, although it will need to be copied to the edge-2 docs. @kflynn, I'll let you give the final approval on this change.

@travisbeckham Great. Will wait for the final approval then. Also open to helping out in more docs task for this project and more as I see them.

[cratelyn]

this looks good to me too! just one last little chore before this can be merged, @Mike-4-prog. thank you for opening up this fix, it will be very helpful to clarify this in our docs.

[Mike-4-prog]

this looks good to me too! just one last little chore before this can be merged, @Mike-4-prog. thank you for opening up this fix, it will be very helpful to clarify this in our docs.

[Mike-4-prog]

Thanks, @cratelyn.
The note has already been added to the viz.md file under the tap section as suggested. Let me know if you'd like it adjusted further!

[Mike-4-prog]

@cratelyn I think I mistakenly closed this PR earlier. I felt it was from the maintainers, upon checks I see the issue. My apologies about this. I have actually made those fixes...Do check again and let me know please

[cratelyn]

@cratelyn I think I mistakenly closed this PR earlier. I felt it was from the maintainers, upon checks I see the issue. My apologies about this. I have actually made those fixes...Do check again and let me know please

it's alright, thank you for understanding!

see one remaining comment above, here: #2105 (comment)

we maintain distinct copies of the documentation for historical releases, and a 2-edge directory for ongoing development in edge releases. we will just need to copy these new documentation changes there as well.

[Mike-4-prog]

@cratelyn I think I mistakenly closed this PR earlier. I felt it was from the maintainers, upon checks I see the issue. My apologies about this. I have actually made those fixes...Do check again and let me know please

it's alright, thank you for understanding!

see one remaining comment above, here: #2105 (comment)

we maintain distinct copies of the documentation for historical releases, and a 2-edge directory for ongoing development in edge releases. we will just need to copy these new documentation changes there as well.

Hi @cratelyn

Thanks for the guidance! I’ve added the skipped-ports note to the 2-edge viz.md page, mirroring the placement in the 2.19 docs. Both versions now have the note immediately after the tap description.

Please let me know if any further adjustments are needed before merging.

Thanks again!

[cratelyn]

ping @kflynn, i believe this should be ready for a final look 😌