From 37c1625382f52f180a2ea5640518134aee400e5d Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Fri, 4 Sep 2026 17:21:10 +0100 Subject: [PATCH] DOCS-3033: Improve openings of CC resource reference pages --- calico-cloud/reference/resources/bgpconfig.mdx | 4 ++-- calico-cloud/reference/resources/bgpfilter.mdx | 8 ++++---- calico-cloud/reference/resources/bgppeer.mdx | 6 +++--- calico-cloud/reference/resources/blockaffinity.mdx | 3 ++- calico-cloud/reference/resources/caliconodestatus.mdx | 11 ++++++----- calico-cloud/reference/resources/globalnetworkset.mdx | 2 +- calico-cloud/reference/resources/ipamconfig.mdx | 2 +- calico-cloud/reference/resources/networkset.mdx | 4 ++-- .../resources/stagedkubernetesnetworkpolicy.mdx | 2 +- calico-cloud/reference/resources/tier.mdx | 2 +- .../version-23-2/reference/resources/bgpconfig.mdx | 4 ++-- .../version-23-2/reference/resources/bgpfilter.mdx | 8 ++++---- .../version-23-2/reference/resources/bgppeer.mdx | 6 +++--- .../reference/resources/blockaffinity.mdx | 3 ++- .../reference/resources/caliconodestatus.mdx | 11 ++++++----- .../reference/resources/globalnetworkset.mdx | 2 +- .../version-23-2/reference/resources/ipamconfig.mdx | 2 +- .../version-23-2/reference/resources/networkset.mdx | 4 ++-- .../resources/stagedkubernetesnetworkpolicy.mdx | 2 +- .../version-23-2/reference/resources/tier.mdx | 2 +- .../version-23-2-sidebars.json | 1 + sidebars-calico-cloud.js | 1 + 22 files changed, 48 insertions(+), 42 deletions(-) diff --git a/calico-cloud/reference/resources/bgpconfig.mdx b/calico-cloud/reference/resources/bgpconfig.mdx index 8d57aa02ef..4913e97d04 100644 --- a/calico-cloud/reference/resources/bgpconfig.mdx +++ b/calico-cloud/reference/resources/bgpconfig.mdx @@ -4,8 +4,8 @@ description: Reference for the BGPConfiguration resource in Calico Cloud connect # BGP configuration -A BGP configuration resource (`BGPConfiguration`) represents BGP specific configuration options for the cluster or a -specific node. +A Border Gateway Protocol (BGP) configuration resource (`BGPConfiguration`) represents BGP configuration options +for the cluster or a specific node. For `kubectl` commands, the following case-insensitive aliases may be used to specify the resource type on the CLI: `bgpconfiguration.projectcalico.org`, `bgpconfigurations.projectcalico.org` as well as abbreviations such as `bgpconfiguration.p` and `bgpconfigurations.p`. diff --git a/calico-cloud/reference/resources/bgpfilter.mdx b/calico-cloud/reference/resources/bgpfilter.mdx index 1ef238cd40..04d556a89d 100644 --- a/calico-cloud/reference/resources/bgpfilter.mdx +++ b/calico-cloud/reference/resources/bgpfilter.mdx @@ -2,11 +2,11 @@ description: Reference for the BGPFilter resource in Calico Cloud connected clusters that filters routes imported from or exported to BGP peers. --- -# BGP Filter +# BGP filter -A BGP filter resource (`BGPFilter`) represents a way to control -routes imported by and exported to BGP peers specified using a -BGP peer resource (`BGPPeer`). +A Border Gateway Protocol (BGP) filter resource (`BGPFilter`) represents a way to control +routes imported by and exported to BGP peers +specified by a [BGP peer resource](bgppeer.mdx) (`BGPPeer`). The BGPFilter rules are applied sequentially: the `action` for the **first** rule that matches is executed immediately. diff --git a/calico-cloud/reference/resources/bgppeer.mdx b/calico-cloud/reference/resources/bgppeer.mdx index 8b8be1958a..4e98def488 100644 --- a/calico-cloud/reference/resources/bgppeer.mdx +++ b/calico-cloud/reference/resources/bgppeer.mdx @@ -6,10 +6,10 @@ description: Reference for the BGPPeer resource in Calico Cloud connected cluste import Selectors from '@site/calico-cloud/_includes/content/_selectors.mdx'; -A BGP peer resource (`BGPPeer`) represents a remote BGP peer with -which the node(s) in a $[prodname] cluster will peer. +A Border Gateway Protocol (BGP) peer resource (`BGPPeer`) represents a remote BGP peer +with which one or more nodes in a $[prodname] cluster exchange routes. Configuring BGP peers allows you to peer a $[prodname] network -with your datacenter fabric (e.g. ToR). For more +with your data center fabric, such as a top-of-rack (ToR) router. For more information on cluster layouts, see $[prodname]'s documentation on [$[prodname] over IP fabrics](../architecture/design/l3-interconnect-fabric.mdx). diff --git a/calico-cloud/reference/resources/blockaffinity.mdx b/calico-cloud/reference/resources/blockaffinity.mdx index a9c97ee98b..e44acdc384 100644 --- a/calico-cloud/reference/resources/blockaffinity.mdx +++ b/calico-cloud/reference/resources/blockaffinity.mdx @@ -4,7 +4,8 @@ description: Reference for the BlockAffinity resource in Calico Cloud connected # Block affinity -A block affinity resource (`BlockAffinity`) represents the affinity for an IPAM block. These are managed by Calico IPAM. +A block affinity resource (`BlockAffinity`) represents the affinity between a node and an IP address management (IPAM) block. +$[prodname] IPAM creates and manages these resources automatically; you don't normally need to create or modify them. ## Block affinity definition diff --git a/calico-cloud/reference/resources/caliconodestatus.mdx b/calico-cloud/reference/resources/caliconodestatus.mdx index 6bb69b852c..4a96ee0fbe 100644 --- a/calico-cloud/reference/resources/caliconodestatus.mdx +++ b/calico-cloud/reference/resources/caliconodestatus.mdx @@ -4,14 +4,15 @@ description: Reference for the CalicoNodeStatus resource in Calico Cloud connect # Calico node status -A Calico node status resource (`CalicoNodeStatus`) represents a collection of status information for a node that $[prodname] reports back to the user for use during troubleshooting. +A Calico node status resource (`CalicoNodeStatus`) reports status information for a node, for use during troubleshooting. +You create a `CalicoNodeStatus` resource for the node you want to inspect, and $[prodname] periodically writes the collected information to the resource's `status` field. -As of today, status of BGP agents, BGP sessions and routes exposed to BGP agents are collected from Linux nodes only. **Windows nodes are not supported at this time.** -Calico node status resource is only valid when $[prodname] BGP networking is in use. +Status of Border Gateway Protocol (BGP) agents, BGP sessions, and routes exposed to BGP agents is collected from Linux nodes only. **Windows nodes are not supported at this time.** +The resource is valid only when $[prodname] BGP networking is in use. -### Notes +## Notes -The updating of `CalicoNodeStatus` will have a small performance impact on CPU/Memory usage of the node as well as adding load to kubernetes apiserver. +Updating `CalicoNodeStatus` has a small performance impact on CPU and memory usage of the node, and adds load to the Kubernetes API server. In our testing on a ten node, full mesh cluster, a `CalicoNodeStatus` resource was created for each node where the update interval was set to ten seconds. On each node, this resulted in an increase in CPU use of 5% of a vCPU and an increase of 4MB of memory. The control plane node recorded an increase in CPU usage of 5% of a vCPU for these 10 nodes. diff --git a/calico-cloud/reference/resources/globalnetworkset.mdx b/calico-cloud/reference/resources/globalnetworkset.mdx index 1951401930..a96a269dba 100644 --- a/calico-cloud/reference/resources/globalnetworkset.mdx +++ b/calico-cloud/reference/resources/globalnetworkset.mdx @@ -6,7 +6,7 @@ description: Reference for the GlobalNetworkSet resource in Calico Cloud connect import DomainNames from '@site/calico-cloud/_includes/content/_domain-names.mdx'; -A global network set resource (GlobalNetworkSet) represents an arbitrary set of IP subnetworks/CIDRs, +A global network set resource (`GlobalNetworkSet`) represents an arbitrary set of IP subnetworks/CIDRs, allowing it to be matched by $[prodname] policy. Network sets are useful for applying policy to traffic coming from (or going to) external, non-$[prodname], networks. diff --git a/calico-cloud/reference/resources/ipamconfig.mdx b/calico-cloud/reference/resources/ipamconfig.mdx index af25d1fee9..7834072427 100644 --- a/calico-cloud/reference/resources/ipamconfig.mdx +++ b/calico-cloud/reference/resources/ipamconfig.mdx @@ -4,7 +4,7 @@ description: Reference for the IP address management configuration resource in C # IPAM configuration -An IPAM configuration resource (`IPAMConfiguration`) represents global IPAM configuration options. +An IP address management (IPAM) configuration resource (`IPAMConfiguration`) represents global IPAM configuration options. ## Sample YAML diff --git a/calico-cloud/reference/resources/networkset.mdx b/calico-cloud/reference/resources/networkset.mdx index 5ccdcccdee..b414ef6b11 100644 --- a/calico-cloud/reference/resources/networkset.mdx +++ b/calico-cloud/reference/resources/networkset.mdx @@ -6,11 +6,11 @@ description: Reference for the NetworkSet resource in Calico Cloud connected clu import DomainNames from '@site/calico-cloud/_includes/content/_domain-names.mdx'; -A network set resource (NetworkSet) represents an arbitrary set of IP subnetworks/CIDRs, +A network set resource (`NetworkSet`) represents an arbitrary set of IP subnetworks/CIDRs, allowing it to be matched by $[prodname] policy. Network sets are useful for applying policy to traffic coming from (or going to) external, non-$[prodname], networks. -`NetworkSet` is a namespaced resource. `NetworkSets` in a specific namespace +`NetworkSet` is a namespaced resource. A `NetworkSet` in a specific namespace only applies to [network policies](networkpolicy.mdx) in that namespace. Two resources are in the same namespace if the `namespace` value is set the same on both. (See [GlobalNetworkSet](globalnetworkset.mdx) for non-namespaced network sets.) diff --git a/calico-cloud/reference/resources/stagedkubernetesnetworkpolicy.mdx b/calico-cloud/reference/resources/stagedkubernetesnetworkpolicy.mdx index d439a7e6ca..22c30d274b 100644 --- a/calico-cloud/reference/resources/stagedkubernetesnetworkpolicy.mdx +++ b/calico-cloud/reference/resources/stagedkubernetesnetworkpolicy.mdx @@ -4,7 +4,7 @@ description: Reference for the StagedKubernetesNetworkPolicy resource in Calico # Staged Kubernetes network policy -A staged kubernetes network policy resource (`StagedKubernetesNetworkPolicy`) represents a staged version +A staged Kubernetes network policy resource (`StagedKubernetesNetworkPolicy`) represents a staged version of [Kubernetes network policy](https://kubernetes.io/docs/concepts/services-networking/network-policies). This is used to preview network behavior before actually enforcing the network policy. Once persisted, this will create a Kubernetes network policy backed by a $[prodname] diff --git a/calico-cloud/reference/resources/tier.mdx b/calico-cloud/reference/resources/tier.mdx index 55c11ffae4..a32a0d49ca 100644 --- a/calico-cloud/reference/resources/tier.mdx +++ b/calico-cloud/reference/resources/tier.mdx @@ -8,7 +8,7 @@ A tier resource (`Tier`) represents an ordered collection of [NetworkPolicies](n and/or [GlobalNetworkPolicies](globalnetworkpolicy.mdx). Tiers are used to divide these policies into groups of different priorities. These policies are ordered within a Tier: the additional hierarchy of Tiers provides more flexibility -because the `Pass` `action` in a Rule jumps to the next Tier. Some example use cases for this are. +because the `Pass` `action` in a Rule jumps to the next Tier. Some example use cases for this are: - Allowing privileged users to define security policy that takes precedence over other users. - Translating hierarchies of physical firewalls directly into $[prodname] policy. diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/bgpconfig.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/bgpconfig.mdx index 8d57aa02ef..4913e97d04 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/bgpconfig.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/bgpconfig.mdx @@ -4,8 +4,8 @@ description: Reference for the BGPConfiguration resource in Calico Cloud connect # BGP configuration -A BGP configuration resource (`BGPConfiguration`) represents BGP specific configuration options for the cluster or a -specific node. +A Border Gateway Protocol (BGP) configuration resource (`BGPConfiguration`) represents BGP configuration options +for the cluster or a specific node. For `kubectl` commands, the following case-insensitive aliases may be used to specify the resource type on the CLI: `bgpconfiguration.projectcalico.org`, `bgpconfigurations.projectcalico.org` as well as abbreviations such as `bgpconfiguration.p` and `bgpconfigurations.p`. diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/bgpfilter.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/bgpfilter.mdx index 1ef238cd40..04d556a89d 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/bgpfilter.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/bgpfilter.mdx @@ -2,11 +2,11 @@ description: Reference for the BGPFilter resource in Calico Cloud connected clusters that filters routes imported from or exported to BGP peers. --- -# BGP Filter +# BGP filter -A BGP filter resource (`BGPFilter`) represents a way to control -routes imported by and exported to BGP peers specified using a -BGP peer resource (`BGPPeer`). +A Border Gateway Protocol (BGP) filter resource (`BGPFilter`) represents a way to control +routes imported by and exported to BGP peers +specified by a [BGP peer resource](bgppeer.mdx) (`BGPPeer`). The BGPFilter rules are applied sequentially: the `action` for the **first** rule that matches is executed immediately. diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/bgppeer.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/bgppeer.mdx index a75f8ab3bb..6a13e1f3b4 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/bgppeer.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/bgppeer.mdx @@ -6,10 +6,10 @@ description: Reference for the BGPPeer resource in Calico Cloud connected cluste import Selectors from '@site/calico-cloud_versioned_docs/version-23-2/_includes/content/_selectors.mdx'; -A BGP peer resource (`BGPPeer`) represents a remote BGP peer with -which the node(s) in a $[prodname] cluster will peer. +A Border Gateway Protocol (BGP) peer resource (`BGPPeer`) represents a remote BGP peer +with which one or more nodes in a $[prodname] cluster exchange routes. Configuring BGP peers allows you to peer a $[prodname] network -with your datacenter fabric (e.g. ToR). For more +with your data center fabric, such as a top-of-rack (ToR) router. For more information on cluster layouts, see $[prodname]'s documentation on [$[prodname] over IP fabrics](../architecture/design/l3-interconnect-fabric.mdx). diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/blockaffinity.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/blockaffinity.mdx index a9c97ee98b..e44acdc384 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/blockaffinity.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/blockaffinity.mdx @@ -4,7 +4,8 @@ description: Reference for the BlockAffinity resource in Calico Cloud connected # Block affinity -A block affinity resource (`BlockAffinity`) represents the affinity for an IPAM block. These are managed by Calico IPAM. +A block affinity resource (`BlockAffinity`) represents the affinity between a node and an IP address management (IPAM) block. +$[prodname] IPAM creates and manages these resources automatically; you don't normally need to create or modify them. ## Block affinity definition diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/caliconodestatus.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/caliconodestatus.mdx index 6bb69b852c..4a96ee0fbe 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/caliconodestatus.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/caliconodestatus.mdx @@ -4,14 +4,15 @@ description: Reference for the CalicoNodeStatus resource in Calico Cloud connect # Calico node status -A Calico node status resource (`CalicoNodeStatus`) represents a collection of status information for a node that $[prodname] reports back to the user for use during troubleshooting. +A Calico node status resource (`CalicoNodeStatus`) reports status information for a node, for use during troubleshooting. +You create a `CalicoNodeStatus` resource for the node you want to inspect, and $[prodname] periodically writes the collected information to the resource's `status` field. -As of today, status of BGP agents, BGP sessions and routes exposed to BGP agents are collected from Linux nodes only. **Windows nodes are not supported at this time.** -Calico node status resource is only valid when $[prodname] BGP networking is in use. +Status of Border Gateway Protocol (BGP) agents, BGP sessions, and routes exposed to BGP agents is collected from Linux nodes only. **Windows nodes are not supported at this time.** +The resource is valid only when $[prodname] BGP networking is in use. -### Notes +## Notes -The updating of `CalicoNodeStatus` will have a small performance impact on CPU/Memory usage of the node as well as adding load to kubernetes apiserver. +Updating `CalicoNodeStatus` has a small performance impact on CPU and memory usage of the node, and adds load to the Kubernetes API server. In our testing on a ten node, full mesh cluster, a `CalicoNodeStatus` resource was created for each node where the update interval was set to ten seconds. On each node, this resulted in an increase in CPU use of 5% of a vCPU and an increase of 4MB of memory. The control plane node recorded an increase in CPU usage of 5% of a vCPU for these 10 nodes. diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/globalnetworkset.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/globalnetworkset.mdx index e491a34b4a..c907686a8a 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/globalnetworkset.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/globalnetworkset.mdx @@ -6,7 +6,7 @@ description: Reference for the GlobalNetworkSet resource in Calico Cloud connect import DomainNames from '@site/calico-cloud_versioned_docs/version-23-2/_includes/content/_domain-names.mdx'; -A global network set resource (GlobalNetworkSet) represents an arbitrary set of IP subnetworks/CIDRs, +A global network set resource (`GlobalNetworkSet`) represents an arbitrary set of IP subnetworks/CIDRs, allowing it to be matched by $[prodname] policy. Network sets are useful for applying policy to traffic coming from (or going to) external, non-$[prodname], networks. diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/ipamconfig.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/ipamconfig.mdx index af25d1fee9..7834072427 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/ipamconfig.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/ipamconfig.mdx @@ -4,7 +4,7 @@ description: Reference for the IP address management configuration resource in C # IPAM configuration -An IPAM configuration resource (`IPAMConfiguration`) represents global IPAM configuration options. +An IP address management (IPAM) configuration resource (`IPAMConfiguration`) represents global IPAM configuration options. ## Sample YAML diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/networkset.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/networkset.mdx index 3cb3a19c1b..f7c0a21cb7 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/networkset.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/networkset.mdx @@ -6,11 +6,11 @@ description: Reference for the NetworkSet resource in Calico Cloud connected clu import DomainNames from '@site/calico-cloud_versioned_docs/version-23-2/_includes/content/_domain-names.mdx'; -A network set resource (NetworkSet) represents an arbitrary set of IP subnetworks/CIDRs, +A network set resource (`NetworkSet`) represents an arbitrary set of IP subnetworks/CIDRs, allowing it to be matched by $[prodname] policy. Network sets are useful for applying policy to traffic coming from (or going to) external, non-$[prodname], networks. -`NetworkSet` is a namespaced resource. `NetworkSets` in a specific namespace +`NetworkSet` is a namespaced resource. A `NetworkSet` in a specific namespace only applies to [network policies](networkpolicy.mdx) in that namespace. Two resources are in the same namespace if the `namespace` value is set the same on both. (See [GlobalNetworkSet](globalnetworkset.mdx) for non-namespaced network sets.) diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/stagedkubernetesnetworkpolicy.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/stagedkubernetesnetworkpolicy.mdx index d439a7e6ca..22c30d274b 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/stagedkubernetesnetworkpolicy.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/stagedkubernetesnetworkpolicy.mdx @@ -4,7 +4,7 @@ description: Reference for the StagedKubernetesNetworkPolicy resource in Calico # Staged Kubernetes network policy -A staged kubernetes network policy resource (`StagedKubernetesNetworkPolicy`) represents a staged version +A staged Kubernetes network policy resource (`StagedKubernetesNetworkPolicy`) represents a staged version of [Kubernetes network policy](https://kubernetes.io/docs/concepts/services-networking/network-policies). This is used to preview network behavior before actually enforcing the network policy. Once persisted, this will create a Kubernetes network policy backed by a $[prodname] diff --git a/calico-cloud_versioned_docs/version-23-2/reference/resources/tier.mdx b/calico-cloud_versioned_docs/version-23-2/reference/resources/tier.mdx index 55c11ffae4..a32a0d49ca 100644 --- a/calico-cloud_versioned_docs/version-23-2/reference/resources/tier.mdx +++ b/calico-cloud_versioned_docs/version-23-2/reference/resources/tier.mdx @@ -8,7 +8,7 @@ A tier resource (`Tier`) represents an ordered collection of [NetworkPolicies](n and/or [GlobalNetworkPolicies](globalnetworkpolicy.mdx). Tiers are used to divide these policies into groups of different priorities. These policies are ordered within a Tier: the additional hierarchy of Tiers provides more flexibility -because the `Pass` `action` in a Rule jumps to the next Tier. Some example use cases for this are. +because the `Pass` `action` in a Rule jumps to the next Tier. Some example use cases for this are: - Allowing privileged users to define security policy that takes precedence over other users. - Translating hierarchies of physical firewalls directly into $[prodname] policy. diff --git a/calico-cloud_versioned_sidebars/version-23-2-sidebars.json b/calico-cloud_versioned_sidebars/version-23-2-sidebars.json index 45b73b8bca..2b415eb166 100644 --- a/calico-cloud_versioned_sidebars/version-23-2-sidebars.json +++ b/calico-cloud_versioned_sidebars/version-23-2-sidebars.json @@ -620,6 +620,7 @@ "reference/resources/networkset", "reference/resources/node", "reference/resources/packetcapture", + "reference/resources/policyrecommendations", "reference/resources/remoteclusterconfiguration", "reference/resources/securityeventwebhook", "reference/resources/stagedglobalnetworkpolicy", diff --git a/sidebars-calico-cloud.js b/sidebars-calico-cloud.js index eecf9d7a93..8e8e7425a7 100644 --- a/sidebars-calico-cloud.js +++ b/sidebars-calico-cloud.js @@ -490,6 +490,7 @@ module.exports = { 'reference/resources/networkset', 'reference/resources/node', 'reference/resources/packetcapture', + 'reference/resources/policyrecommendations', 'reference/resources/remoteclusterconfiguration', 'reference/resources/securityeventwebhook', 'reference/resources/stagedglobalnetworkpolicy',