fix(windows): add non-cross-subnet requirement to VXLAN encapsulation to Windows docs #2496
Conversation
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
This PR addresses a critical gap in the Windows installation documentation for Calico. It adds a missing prerequisite step to ensure that VXLANCrossSubnet encapsulation is changed to VXLAN before installing Calico on Windows nodes, as Windows does not support cross-subnet encapsulation.
Changes:
- Adds a new list item in the VXLAN installation instructions warning users that
VXLANCrossSubnetis not supported on Windows - Provides a kubectl patch command to change the encapsulation type from
VXLANCrossSubnettoVXLANfor single IP pool configurations - Applied consistently across all affected versions of both Calico OSS (3.29, 3.30, 3.31, and current) and Calico Enterprise (3.20-2, 3.21-2, 3.22-2, 3.23-1, and current)
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| calico/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to the current version of Calico OSS Windows installation component |
| calico_versioned_docs/version-3.31/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to Calico OSS version 3.31 |
| calico_versioned_docs/version-3.30/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to Calico OSS version 3.30 |
| calico_versioned_docs/version-3.29/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to Calico OSS version 3.29 |
| calico-enterprise/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to the current version of Calico Enterprise Windows installation component |
| calico-enterprise_versioned_docs/version-3.23-1/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to Calico Enterprise version 3.23-1 |
| calico-enterprise_versioned_docs/version-3.22-2/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to Calico Enterprise version 3.22-2 |
| calico-enterprise_versioned_docs/version-3.21-2/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to Calico Enterprise version 3.21-2 |
| calico-enterprise_versioned_docs/version-3.20-2/_includes/components/CalicoWindowsInstall.js | Adds VXLAN encapsulation requirement step to Calico Enterprise version 3.20-2 |
| <> | ||
| <li> | ||
| Ensure that cross-subnet encapsulation is disabled. You must use <code>VXLAN</code> and NOT <code>VXLANCrossSubnet</code> | ||
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | |
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured. If you have multiple IP pools, ensure that each pool that will be used by Windows nodes is configured with <code>encapsulation: VXLAN</code> by updating the corresponding installation or IPPool resources, as described in the IP pool configuration documentation: |
| <> | ||
| <li> | ||
| Ensure that cross-subnet encapsulation is disabled. You must use <code>VXLAN</code> and NOT <code>VXLANCrossSubnet</code> | ||
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | |
| as the <code>encapsulation:</code> of your IP pool. If you only have one IP pool configured, you can use the following | |
| command to update it. If you have multiple IP pools, identify the correct pool in your <code>Installation</code> resource | |
| and adjust the <code>/spec/calicoNetwork/ipPools/<index>/encapsulation</code> path in the JSON patch so that it | |
| targets the desired pool: |
| Ensure that cross-subnet encapsulation is disabled. You must use <code>VXLAN</code> and NOT <code>VXLANCrossSubnet</code> | ||
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | ||
| <br /> | ||
| <br /> | ||
| <CodeBlock language='bash'> | ||
| {`kubectl patch installation default --type='json' -p='[{"op": "replace", "path": "/spec/calicoNetwork/ipPools/0/encapsulation", "value": "VXLAN"}]`} | ||
| </CodeBlock> |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | |
| <br /> | |
| <br /> | |
| <CodeBlock language='bash'> | |
| {`kubectl patch installation default --type='json' -p='[{"op": "replace", "path": "/spec/calicoNetwork/ipPools/0/encapsulation", "value": "VXLAN"}]`} | |
| </CodeBlock> | |
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured. | |
| If you have multiple IP pools configured, update the <code>encapsulation</code> field to <code>VXLAN</code> on each IP pool that will be used by Windows nodes. | |
| <br /> | |
| <br /> | |
| <CodeBlock language='bash'> | |
| {`kubectl patch installation default --type='json' -p='[{"op": "replace", "path": "/spec/calicoNetwork/ipPools/0/encapsulation", "value": "VXLAN"}]`} |
| <> | ||
| <li> | ||
| Ensure that cross-subnet encapsulation is disabled. You must use <code>VXLAN</code> and NOT <code>VXLANCrossSubnet</code> | ||
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | |
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured. If you have multiple IP pools, update each relevant pool's <code>encapsulation</code> field to <code>VXLAN</code> instead of using this single-pool example: |
| <> | ||
| <li> | ||
| Ensure that cross-subnet encapsulation is disabled. You must use <code>VXLAN</code> and NOT <code>VXLANCrossSubnet</code> | ||
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | |
| as the <code>encapsulation:</code> of your IP pool. If you have multiple IP pools configured, update the patch path to target the correct pool index (for example, <code>/spec/calicoNetwork/ipPools/1/encapsulation</code>) or edit the Installation resource YAML directly for the desired pool. Use this command to change it if you only have one IP pool configured: |
| <> | ||
| <li> | ||
| Ensure that cross-subnet encapsulation is disabled. You must use <code>VXLAN</code> and NOT <code>VXLANCrossSubnet</code> | ||
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | |
| as the <code>encapsulation:</code> of your IP pool. If you only have a single IP pool configured, you can use the | |
| following command to update it. If you have multiple IP pools, update each pool's <code>encapsulation</code> field as | |
| needed; see the <Link to="/networking/ippools">Configuring IP pools</Link> documentation for details. |
| <> | ||
| <li> | ||
| Ensure that cross-subnet encapsulation is disabled. You must use <code>VXLAN</code> and NOT <code>VXLANCrossSubnet</code> | ||
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | |
| as the <code>encapsulation:</code> of your IP pool. If you have multiple IP pools configured, ensure that each pool used by Windows nodes has its <code>encapsulation</code> set to <code>VXLAN</code>; you can do this by adjusting the <code>ipPools</code> index in the patch path shown below or by editing the Installation resource manifest directly. Use this command to change it if you only have one IP pool configured: |
| <> | ||
| <li> | ||
| Ensure that cross-subnet encapsulation is disabled. You must use <code>VXLAN</code> and NOT <code>VXLANCrossSubnet</code> | ||
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: |
There was a problem hiding this comment.
The instruction states "Use this command to change it if you only have one IP pool configured" but doesn't provide clear guidance for users with multiple IP pools. Consider adding a note about what users should do if they have multiple IP pools, or link to documentation about managing multiple IP pools.
| as the <code>encapsulation:</code> of your IP pool. Use this command to change it if you only have one IP pool configured: | |
| as the <code>encapsulation:</code> of your IP pool. If you have multiple IP pools configured, update the patch to use the index of the specific pool you want to modify (for example, <code>/ipPools/1/encapsulation</code>) or edit the Installation resource YAML directly for that pool. Use the following command as-is when you have only a single IP pool configured: |
1 participant
Product Version(s):
Issue: #1547
Link to docs preview:
SME review:
DOCS review:
Additional information:
Merge checklist: