Skip to content

[WIP]Added docs for KubeVirt#2612

Open
song-jiang wants to merge 1 commit intotigera:mainfrom
song-jiang:song-kubevirt-docs
Open

[WIP]Added docs for KubeVirt#2612
song-jiang wants to merge 1 commit intotigera:mainfrom
song-jiang:song-kubevirt-docs

Conversation

@song-jiang
Copy link
Copy Markdown
Contributor

Product Version(s):

Issue:

Link to docs preview:

SME review:

  • An SME has approved this change.

DOCS review:

  • A member of the docs team has approved this change.

Additional information:

Merge checklist:

  • Deploy preview inspected wherever changes were made
  • Build completed successfully
  • Test have passed

Copilot AI review requested due to automatic review settings March 27, 2026 16:54
@song-jiang song-jiang requested a review from a team as a code owner March 27, 2026 16:54
@netlify
Copy link
Copy Markdown

netlify bot commented Mar 27, 2026

Deploy Preview for calico-docs-preview-next failed. Why did it fail? →

Name Link
🔨 Latest commit e281b00
🔍 Latest deploy log https://app.netlify.com/projects/calico-docs-preview-next/deploys/69c6b664f38a5d00088072a3

@netlify
Copy link
Copy Markdown

netlify bot commented Mar 27, 2026

Deploy Preview for tigera failed. Why did it fail? →

Built without sensitive environment variables

Name Link
🔨 Latest commit e281b00
🔍 Latest deploy log https://app.netlify.com/projects/tigera/deploys/69c6b6646bd7690008d73709

@song-jiang song-jiang changed the title Added docs for KubeVirt [WIP]Added docs for KubeVirt Mar 27, 2026
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Adds a new KubeVirt networking doc section to the Calico and Calico Enterprise documentation sites and exposes it in the left-nav sidebars.

Changes:

  • Adds a new “networking for KubeVirt” sidebar category for both Calico and Calico Enterprise.
  • Introduces new KubeVirt docs pages covering networking basics (IP persistence, live migration prerequisites) and BGP routing considerations for live migration.
  • Adds KubeVirt landing/index pages that render a DocCardList for the new section.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
sidebars-calico.js Adds a new “Calico networking for KubeVirt” category and links new docs into the Calico sidebar.
sidebars-calico-enterprise.js Adds a new “Calico Enterprise networking for KubeVirt” category and links new docs into the Enterprise sidebar.
calico/networking/kubevirt/index.mdx Adds KubeVirt section landing page for Calico.
calico/networking/kubevirt/kubevirt-networking.mdx Adds Calico KubeVirt networking guide (IP persistence, migration prerequisites, config pointers).
calico/networking/kubevirt/live-migration-bgp.mdx Adds Calico guide for BGP behavior/configuration considerations during live migration.
calico-enterprise/networking/kubevirt/index.mdx Adds KubeVirt section landing page for Calico Enterprise.
calico-enterprise/networking/kubevirt/kubevirt-networking.mdx Adds Enterprise KubeVirt networking guide (mirrors OSS structure/content with Enterprise links).
calico-enterprise/networking/kubevirt/live-migration-bgp.mdx Adds Enterprise guide for BGP behavior/configuration considerations during live migration.

Comment on lines +123 to +136
IP address persistence is enabled by default. If it has been previously disabled, re-enable
it by updating the `IPAMConfiguration` resource:

```yaml
apiVersion: projectcalico.org/v3
kind: IPAMConfiguration
metadata:
name: default
spec:
strictAffinity: false
autoAllocateBlocks: true
maxBlocksPerHost: 0
kubeVirtVMAddressPersistence: Enabled
```
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

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

This section says IP address persistence is enabled by default, but the IPAMConfiguration reference in this repo shows kubeVirtVMAddressPersistence defaulting to Disabled. Also, the sample IPAMConfiguration includes autoAllocateBlocks, which is not present in the IPAMConfiguration reference schema here—please align the text and example with the documented fields/defaults (or update the reference if the API has changed).

Copilot uses AI. Check for mistakes.
Comment on lines +179 to +236
$[prodname] uses Linux kernel route metrics to steer traffic during live migration.
The route priority settings are configured through the `FelixConfiguration` resource:

```yaml
apiVersion: projectcalico.org/v3
kind: FelixConfiguration
metadata:
name: default
spec:
ipv4NormalRoutePriority: 1024
ipv4ElevatedRoutePriority: 512
ipv6NormalRoutePriority: 1024
ipv6ElevatedRoutePriority: 512
liveMigrationRouteConvergenceTime: 30s
```

| Field | Description | Default |
|-------|-------------|---------|
| `ipv4NormalRoutePriority` | Route metric under normal (non-migration) conditions. | 1024 |
| `ipv4ElevatedRoutePriority` | Route metric during and immediately after live migration. Must be less than the normal priority (lower metric = higher priority in the Linux kernel). | 512 |
| `ipv6NormalRoutePriority` | Same as `ipv4NormalRoutePriority` for IPv6. | 1024 |
| `ipv6ElevatedRoutePriority` | Same as `ipv4ElevatedRoutePriority` for IPv6. | 512 |
| `liveMigrationRouteConvergenceTime` | How long elevated route priority is held after migration completes, allowing BGP routes to converge across the cluster before reverting to normal priority. | 30s |

:::note

Route priority values must be in the range [1, 2147483646]. The elevated priority must be
lower than the normal priority for traffic steering to work correctly.

:::

The defaults are suitable for most deployments. You may need to increase
`liveMigrationRouteConvergenceTime` if your BGP topology requires more time for route propagation
(for example, in large multi-rack deployments).

If you use BGP networking, you must also set the normal route priority in the `BGPConfiguration`
resource to match the `FelixConfiguration` values. BIRD uses this to identify elevated-priority
routes during live migration and to correctly override local workload routes with higher-priority
BGP-learned routes:

```yaml
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
name: default
spec:
ipv4NormalRoutePriority: 1024
ipv6NormalRoutePriority: 1024
```

:::warning

The `ipv4NormalRoutePriority` and `ipv6NormalRoutePriority` values in `BGPConfiguration` must
match the corresponding values in `FelixConfiguration`. Mismatched values will cause incorrect
route selection during live migration.

:::

Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

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

The FelixConfiguration/BGPConfiguration fields shown here (ipv4NormalRoutePriority, ipv4ElevatedRoutePriority, liveMigrationRouteConvergenceTime, etc.) don’t appear in this repo’s generated FelixConfiguration/BGPConfiguration reference content (no matches in the FelixConfig config-params JSON or BGPConfiguration reference). Please verify the correct field names for the current release and update this section (or regenerate/update the reference docs if these fields are now supported).

Suggested change
$[prodname] uses Linux kernel route metrics to steer traffic during live migration.
The route priority settings are configured through the `FelixConfiguration` resource:
```yaml
apiVersion: projectcalico.org/v3
kind: FelixConfiguration
metadata:
name: default
spec:
ipv4NormalRoutePriority: 1024
ipv4ElevatedRoutePriority: 512
ipv6NormalRoutePriority: 1024
ipv6ElevatedRoutePriority: 512
liveMigrationRouteConvergenceTime: 30s
```
| Field | Description | Default |
|-------|-------------|---------|
| `ipv4NormalRoutePriority` | Route metric under normal (non-migration) conditions. | 1024 |
| `ipv4ElevatedRoutePriority` | Route metric during and immediately after live migration. Must be less than the normal priority (lower metric = higher priority in the Linux kernel). | 512 |
| `ipv6NormalRoutePriority` | Same as `ipv4NormalRoutePriority` for IPv6. | 1024 |
| `ipv6ElevatedRoutePriority` | Same as `ipv4ElevatedRoutePriority` for IPv6. | 512 |
| `liveMigrationRouteConvergenceTime` | How long elevated route priority is held after migration completes, allowing BGP routes to converge across the cluster before reverting to normal priority. | 30s |
:::note
Route priority values must be in the range [1, 2147483646]. The elevated priority must be
lower than the normal priority for traffic steering to work correctly.
:::
The defaults are suitable for most deployments. You may need to increase
`liveMigrationRouteConvergenceTime` if your BGP topology requires more time for route propagation
(for example, in large multi-rack deployments).
If you use BGP networking, you must also set the normal route priority in the `BGPConfiguration`
resource to match the `FelixConfiguration` values. BIRD uses this to identify elevated-priority
routes during live migration and to correctly override local workload routes with higher-priority
BGP-learned routes:
```yaml
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
name: default
spec:
ipv4NormalRoutePriority: 1024
ipv6NormalRoutePriority: 1024
```
:::warning
The `ipv4NormalRoutePriority` and `ipv6NormalRoutePriority` values in `BGPConfiguration` must
match the corresponding values in `FelixConfiguration`. Mismatched values will cause incorrect
route selection during live migration.
:::
$[prodname] uses Linux kernel route metrics to steer traffic during live migration so that
traffic is drained from the source node and shifted to the destination node without breaking
existing connections.
During a live migration, $[prodname] temporarily installs routes with a higher priority
(lower metric value in the Linux kernel) towards the destination VM. After the migration
completes and routing has converged, these temporary routes are removed so that normal
workload routing behavior is restored.
The exact tunables and defaults for route metrics are release-dependent and are exposed
through standard $[prodname] configuration resources. For the current release, consult the
following reference pages for the supported configuration fields:
- [FelixConfiguration reference](../../reference/resources/felixconfig.mdx)
- [BGPConfiguration reference](../../reference/resources/bgpconfig.mdx)
:::note
In the Linux kernel, a lower route metric value corresponds to a higher-priority route.
When live migration is enabled, routes that steer traffic to the destination VM must have a
lower metric than the normal workload routes for traffic steering to work correctly.
:::
For most deployments, the defaults are suitable and no tuning is required. If you have a
complex or high-latency BGP topology and observe slow convergence during live migration, work
with your network team or $[prodname] support to determine whether route-priority tuning is
appropriate for your environment.

Copilot uses AI. Check for mistakes.
Comment on lines +120 to +176
# Elevated-priority route (target pod): tag with community 65000:100
- action: Accept
peerType: eBGP
priority: 512
operations:
- addCommunity:
value: "65000:100"
# Normal-priority route (source pod): tag with community 65000:200
- action: Accept
peerType: eBGP
priority: 1024
operations:
- addCommunity:
value: "65000:200"
importV4:
# Match elevated-priority community: restore priority 512
- action: Accept
communities:
values: ["65000:100"]
operations:
- setPriority:
value: 512
# Match normal-priority community: restore priority 1024
- action: Accept
communities:
values: ["65000:200"]
operations:
- setPriority:
value: 1024
- action: Accept
exportV6:
- action: Accept
peerType: eBGP
priority: 512
operations:
- addCommunity:
value: "65000:100"
- action: Accept
peerType: eBGP
priority: 1024
operations:
- addCommunity:
value: "65000:200"
importV6:
- action: Accept
communities:
values: ["65000:100"]
operations:
- setPriority:
value: 512
- action: Accept
communities:
values: ["65000:200"]
operations:
- setPriority:
value: 1024
- action: Accept
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

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

The BGPFilter example uses fields/operations (peerType, priority, communities, operations, addCommunity, setPriority) that aren’t present in this repo’s BGPFilter reference schema (which only documents fields like cidr, prefixLength, matchOperator, source, interface, action). Please confirm the actual BGPFilter capabilities and either adjust the example to valid fields or update/regenerate the BGPFilter reference docs so they match.

Suggested change
# Elevated-priority route (target pod): tag with community 65000:100
- action: Accept
peerType: eBGP
priority: 512
operations:
- addCommunity:
value: "65000:100"
# Normal-priority route (source pod): tag with community 65000:200
- action: Accept
peerType: eBGP
priority: 1024
operations:
- addCommunity:
value: "65000:200"
importV4:
# Match elevated-priority community: restore priority 512
- action: Accept
communities:
values: ["65000:100"]
operations:
- setPriority:
value: 512
# Match normal-priority community: restore priority 1024
- action: Accept
communities:
values: ["65000:200"]
operations:
- setPriority:
value: 1024
- action: Accept
exportV6:
- action: Accept
peerType: eBGP
priority: 512
operations:
- addCommunity:
value: "65000:100"
- action: Accept
peerType: eBGP
priority: 1024
operations:
- addCommunity:
value: "65000:200"
importV6:
- action: Accept
communities:
values: ["65000:100"]
operations:
- setPriority:
value: 512
- action: Accept
communities:
values: ["65000:200"]
operations:
- setPriority:
value: 1024
- action: Accept
# Allow exporting IPv4 routes for live-migrated workloads to other racks/ASNs
- action: Accept
# Allow exporting additional IPv4 routes associated with the migration
- action: Accept
importV4:
# Accept imported IPv4 routes for live-migrated workloads from other racks/ASNs
- action: Accept
# Fallback rule to accept any remaining IPv4 routes relevant to migration
- action: Accept
exportV6:
# Allow exporting IPv6 routes for live-migrated workloads to other racks/ASNs
- action: Accept
# Allow exporting additional IPv6 routes associated with the migration
- action: Accept
importV6:
# Accept imported IPv6 routes for live-migrated workloads from other racks/ASNs
- action: Accept
# Fallback rule to accept any remaining IPv6 routes relevant to migration
- action: Accept

Copilot uses AI. Check for mistakes.
Comment on lines +124 to +136
IP address persistence is enabled by default. If it has been previously disabled, re-enable
it by updating the `IPAMConfiguration` resource:

```yaml
apiVersion: projectcalico.org/v3
kind: IPAMConfiguration
metadata:
name: default
spec:
strictAffinity: false
autoAllocateBlocks: true
maxBlocksPerHost: 0
kubeVirtVMAddressPersistence: Enabled
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

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

This section says IP address persistence is enabled by default, but the IPAMConfiguration reference in this repo shows kubeVirtVMAddressPersistence defaulting to Disabled. Also, the sample IPAMConfiguration includes autoAllocateBlocks, which is not present in the IPAMConfiguration reference schema here—please align the text and example with the documented fields/defaults (or update the reference if the API has changed).

Copilot uses AI. Check for mistakes.
Comment on lines +178 to +237
### Configure live migration route priority

$[prodname] uses Linux kernel route metrics to steer traffic during live migration.
The route priority settings are configured through the `FelixConfiguration` resource:

```yaml
apiVersion: projectcalico.org/v3
kind: FelixConfiguration
metadata:
name: default
spec:
ipv4NormalRoutePriority: 1024
ipv4ElevatedRoutePriority: 512
ipv6NormalRoutePriority: 1024
ipv6ElevatedRoutePriority: 512
liveMigrationRouteConvergenceTime: 30s
```

| Field | Description | Default |
|-------|-------------|---------|
| `ipv4NormalRoutePriority` | Route metric under normal (non-migration) conditions. | 1024 |
| `ipv4ElevatedRoutePriority` | Route metric during and immediately after live migration. Must be less than the normal priority (lower metric = higher priority in the Linux kernel). | 512 |
| `ipv6NormalRoutePriority` | Same as `ipv4NormalRoutePriority` for IPv6. | 1024 |
| `ipv6ElevatedRoutePriority` | Same as `ipv4ElevatedRoutePriority` for IPv6. | 512 |
| `liveMigrationRouteConvergenceTime` | How long elevated route priority is held after migration completes, allowing BGP routes to converge across the cluster before reverting to normal priority. | 30s |

:::note

Route priority values must be in the range [1, 2147483646]. The elevated priority must be
lower than the normal priority for traffic steering to work correctly.

:::

The defaults are suitable for most deployments. You may need to increase
`liveMigrationRouteConvergenceTime` if your BGP topology requires more time for route propagation
(for example, in large multi-rack deployments).

If you use BGP networking, you must also set the normal route priority in the `BGPConfiguration`
resource to match the `FelixConfiguration` values. BIRD uses this to identify elevated-priority
routes during live migration and to correctly override local workload routes with higher-priority
BGP-learned routes:

```yaml
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
name: default
spec:
ipv4NormalRoutePriority: 1024
ipv6NormalRoutePriority: 1024
```

:::warning

The `ipv4NormalRoutePriority` and `ipv6NormalRoutePriority` values in `BGPConfiguration` must
match the corresponding values in `FelixConfiguration`. Mismatched values will cause incorrect
route selection during live migration.

:::

Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

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

The FelixConfiguration/BGPConfiguration fields shown here (ipv4NormalRoutePriority, ipv4ElevatedRoutePriority, liveMigrationRouteConvergenceTime, etc.) don’t appear in this repo’s generated FelixConfiguration/BGPConfiguration reference content (no matches in the FelixConfig config-params JSON or BGPConfiguration reference). Please verify the correct field names for the current release and update this section (or regenerate/update the reference docs if these fields are now supported).

Suggested change
### Configure live migration route priority
$[prodname] uses Linux kernel route metrics to steer traffic during live migration.
The route priority settings are configured through the `FelixConfiguration` resource:
```yaml
apiVersion: projectcalico.org/v3
kind: FelixConfiguration
metadata:
name: default
spec:
ipv4NormalRoutePriority: 1024
ipv4ElevatedRoutePriority: 512
ipv6NormalRoutePriority: 1024
ipv6ElevatedRoutePriority: 512
liveMigrationRouteConvergenceTime: 30s
```
| Field | Description | Default |
|-------|-------------|---------|
| `ipv4NormalRoutePriority` | Route metric under normal (non-migration) conditions. | 1024 |
| `ipv4ElevatedRoutePriority` | Route metric during and immediately after live migration. Must be less than the normal priority (lower metric = higher priority in the Linux kernel). | 512 |
| `ipv6NormalRoutePriority` | Same as `ipv4NormalRoutePriority` for IPv6. | 1024 |
| `ipv6ElevatedRoutePriority` | Same as `ipv4ElevatedRoutePriority` for IPv6. | 512 |
| `liveMigrationRouteConvergenceTime` | How long elevated route priority is held after migration completes, allowing BGP routes to converge across the cluster before reverting to normal priority. | 30s |
:::note
Route priority values must be in the range [1, 2147483646]. The elevated priority must be
lower than the normal priority for traffic steering to work correctly.
:::
The defaults are suitable for most deployments. You may need to increase
`liveMigrationRouteConvergenceTime` if your BGP topology requires more time for route propagation
(for example, in large multi-rack deployments).
If you use BGP networking, you must also set the normal route priority in the `BGPConfiguration`
resource to match the `FelixConfiguration` values. BIRD uses this to identify elevated-priority
routes during live migration and to correctly override local workload routes with higher-priority
BGP-learned routes:
```yaml
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
name: default
spec:
ipv4NormalRoutePriority: 1024
ipv6NormalRoutePriority: 1024
```
:::warning
The `ipv4NormalRoutePriority` and `ipv6NormalRoutePriority` values in `BGPConfiguration` must
match the corresponding values in `FelixConfiguration`. Mismatched values will cause incorrect
route selection during live migration.
:::
To configure route priority and BGP behavior for KubeVirt live migration, follow the guidance in
[BGP routing for KubeVirt live migration](./live-migration-bgp.mdx).

Copilot uses AI. Check for mistakes.
Comment on lines +120 to +176
# Elevated-priority route (target pod): tag with community 65000:100
- action: Accept
peerType: eBGP
priority: 512
operations:
- addCommunity:
value: "65000:100"
# Normal-priority route (source pod): tag with community 65000:200
- action: Accept
peerType: eBGP
priority: 1024
operations:
- addCommunity:
value: "65000:200"
importV4:
# Match elevated-priority community: restore priority 512
- action: Accept
communities:
values: ["65000:100"]
operations:
- setPriority:
value: 512
# Match normal-priority community: restore priority 1024
- action: Accept
communities:
values: ["65000:200"]
operations:
- setPriority:
value: 1024
- action: Accept
exportV6:
- action: Accept
peerType: eBGP
priority: 512
operations:
- addCommunity:
value: "65000:100"
- action: Accept
peerType: eBGP
priority: 1024
operations:
- addCommunity:
value: "65000:200"
importV6:
- action: Accept
communities:
values: ["65000:100"]
operations:
- setPriority:
value: 512
- action: Accept
communities:
values: ["65000:200"]
operations:
- setPriority:
value: 1024
- action: Accept
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

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

The BGPFilter example uses fields/operations (peerType, priority, communities, operations, addCommunity, setPriority) that aren’t present in this repo’s BGPFilter reference schema (which only documents fields like cidr, prefixLength, matchOperator, source, interface, action). Please confirm the actual BGPFilter capabilities and either adjust the example to valid fields or update/regenerate the BGPFilter reference docs so they match.

Suggested change
# Elevated-priority route (target pod): tag with community 65000:100
- action: Accept
peerType: eBGP
priority: 512
operations:
- addCommunity:
value: "65000:100"
# Normal-priority route (source pod): tag with community 65000:200
- action: Accept
peerType: eBGP
priority: 1024
operations:
- addCommunity:
value: "65000:200"
importV4:
# Match elevated-priority community: restore priority 512
- action: Accept
communities:
values: ["65000:100"]
operations:
- setPriority:
value: 512
# Match normal-priority community: restore priority 1024
- action: Accept
communities:
values: ["65000:200"]
operations:
- setPriority:
value: 1024
- action: Accept
exportV6:
- action: Accept
peerType: eBGP
priority: 512
operations:
- addCommunity:
value: "65000:100"
- action: Accept
peerType: eBGP
priority: 1024
operations:
- addCommunity:
value: "65000:200"
importV6:
- action: Accept
communities:
values: ["65000:100"]
operations:
- setPriority:
value: 512
- action: Accept
communities:
values: ["65000:200"]
operations:
- setPriority:
value: 1024
- action: Accept
# Export all IPv4 routes
- action: Accept
cidr: 0.0.0.0/0
prefixLength: 0
matchOperator: In
importV4:
# Import all IPv4 routes
- action: Accept
cidr: 0.0.0.0/0
prefixLength: 0
matchOperator: In
exportV6:
# Export all IPv6 routes
- action: Accept
cidr: ::/0
prefixLength: 0
matchOperator: In
importV6:
# Import all IPv6 routes
- action: Accept
cidr: ::/0
prefixLength: 0
matchOperator: In

Copilot uses AI. Check for mistakes.
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