DOCS-2997: Write the L2 network troubleshooting guide - #2949
Open
ctauchen wants to merge 2 commits into
Open
Conversation
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a symptom-oriented troubleshooting guide for Calico Enterprise L2 bridge networking, focusing on where to find actionable signals (Felix vs workload/CNI/Multus) and what diagnostics to collect when bridge state isn’t captured automatically.
Changes:
- Expanded the page from a brief stub into a full troubleshooting flow organized by symptom.
- Added guidance on log locations, diagnostic bundle collection, and bridge-state commands to gather manually.
- Added multiple specific failure-pattern sections plus a consolidated “Additional resources” list.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| 1. Run the standard diagnostics bundle: | ||
|
|
||
| ```bash | ||
| kubectl exec -n calico-system <calico-node-pod> -- calicoctl cluster diags |
Comment on lines
+129
to
+130
| 2. **The pool is not marked for L2 use.** A pool without `allowedUses: L2Workload` is not a | ||
| candidate for an L2 interface. |
ctauchen
force-pushed
the
DOCS-2997-7-troubleshoot
branch
from
August 21, 2026 11:08
1db20db to
f3ca5a4
Compare
Fill in the troubleshooting guide for L2 bridge networking, organized by symptom rather than by tool. The guide opens with where the signals are, because L2 problems report themselves somewhere unusual. Bridge problems appear only in the Felix log inside calico-node, with no Kubernetes event, no resource condition, and no metric. Attachment problems appear in the workload status and the CNI and Multus logs. The diagnostics section says that bridge state is not part of the standard bundle and has to be collected by hand, so a support case does not arrive without it. Entries cover the failures that are silent, late, or self-concealing: a bridge that does not meet its prerequisites, a workload with two interfaces called eth0 because the multi-interface mode was missed, a node taken off the network while its bridge was being configured, and a packet capture that masks the hardware filtering problem it was opened to investigate. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ctauchen
force-pushed
the
DOCS-2997-7-troubleshoot
branch
from
August 21, 2026 11:10
f3ca5a4 to
9e74793
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
calico-enterprise/networking/l2-bridge/troubleshoot.mdx:45
- The diagnostics bundle command here assumes running
calicoctlinside acalico-nodepod. Elsewhere in the Calico Enterprise docs, the standard guidance is to installcalicoctlas a kubectl plugin and runkubectl calico cluster diags(see calico-enterprise/operations/troubleshoot/troubleshooting.mdx:9-21). Aligning this page with that standard avoids requiring readers to identify a specific calico-node pod and avoids implyingcalicoctlmust be present inside the pod.
1. Run the standard diagnostics bundle:
```bash
kubectl exec -n calico-system <calico-node-pod> -- calicoctl cluster diags
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (2)
calico-enterprise/networking/l2-bridge/troubleshoot.mdx:46
- The diagnostics command is executed inside a calico-node pod, which means the generated
.tar.gzbundle will be written into the container filesystem and is not straightforward to retrieve. The calicoctl reference also documentscluster diagsas runnable from any location with kubeconfig access. Consider switching this step to a directcalicoctl cluster diagsinvocation (or add explicitkubectl cpretrieval instructions).
1. Run the standard diagnostics bundle:
```bash
kubectl exec -n calico-system <calico-node-pod> -- calicoctl cluster diags
**calico-enterprise/networking/l2-bridge/troubleshoot.mdx:65**
* This section instructs users to increase Felix logging to Debug, but only says to set it back to `Info` without providing the command to do so. Adding the explicit rollback command helps prevent leaving clusters in a noisy Debug logging state.
Set it back to Info afterwards.
</details>
Add a comment at the top of the page naming the user story it exists to serve. This page serves one story only. Diagnosis is framed by the reader's goal, which is why it is a how-to rather than a section appended to the setup guides. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (2)
calico-enterprise/networking/l2-bridge/troubleshoot.mdx:40
kubectl describe pod <pod>omits the pod namespace, which can be misleading because the workload pod usually isn’t in the current/default namespace. Include an explicit namespace placeholder so the command is copy/pasteable.
kubectl describe pod <pod>
calico-enterprise/networking/l2-bridge/troubleshoot.mdx:53
- The diagnostics bundle step currently runs
calicoctl cluster diagsviakubectl execinto acalico-nodepod. That’s inconsistent with the calicoctl reference, which describes running this command anywhere with kubeconfig, and it also leaves readers without a clear local path to the generated.tar.gzbundle. Prefer documenting the directcalicoctl cluster diagsinvocation from a machine with cluster access.
1. Run the standard diagnostics bundle:
```bash
kubectl exec -n calico-system <calico-node-pod> -- calicoctl cluster diags
</details>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fills in the troubleshooting guide for L2 bridge networking. Seventh in the DOCS-2997 sequence, and near the end because it references the setup guides.
The guide is organized by symptom rather than by tool, so a reader arrives with a problem and finds it.
It opens with where the signals are, because that is genuinely unusual here and looking in the obvious places wastes time. Bridge prerequisite failures appear only in the Felix log inside calico-node: no Kubernetes event, no condition on the Network, no status on the workload, no metric. Attachment failures appear in the workload status and the CNI and Multus logs instead.
The diagnostics section states that bridge state is not collected by the standard bundle and has to be gathered by hand. A support case from a cluster in this state otherwise arrives with the Felix warning and nothing else about the bridge.
The entries deliberately favour failures that are silent, late, or self-concealing:
Two notes:
Changed page: https://deploy-preview-2949--calico-docs-preview-next.netlify.app/calico-enterprise/next/networking/l2-bridge/troubleshoot