diff --git a/calico/reference/configure-calico-node.mdx b/calico/reference/configure-calico-node.mdx index d5c7cab14e..914d74901e 100644 --- a/calico/reference/configure-calico-node.mdx +++ b/calico/reference/configure-calico-node.mdx @@ -47,12 +47,12 @@ exist in the cluster. The following options control the parameters on the create | CALICO_IPV4POOL_IPIP | IPIP Mode to use for the IPv4 Pool created at start up. If set to a value other than `Never`, `CALICO_IPV4POOL_VXLAN` should not be set. [Default: `Never`] | Always, CrossSubnet, Never ("Off" is also accepted as a synonym for "Never") | | CALICO_IPV4POOL_VXLAN | VXLAN Mode to use for the IPv4 Pool created at start up. If set to a value other than `Never`, `CALICO_IPV4POOL_IPIP` should not be set. [Default: `Never`] | Always, CrossSubnet, Never | | CALICO_IPV4POOL_NAT_OUTGOING | Controls NAT Outgoing for the IPv4 Pool created at start up. [Default: `true`] | boolean | -| CALICO_IPV4POOL_NODE_SELECTOR | Controls the NodeSelector for the IPv4 Pool created at start up. [Default: `all()`] | [selector](resources/ippool.mdx#node-selector) | +| CALICO_IPV4POOL_NODE_SELECTOR | Controls the NodeSelector for the IPv4 Pool created at start up. [Default: `all()`] | [selector](resources/ippool.mdx#selector) | | CALICO_IPV6POOL_CIDR | The IPv6 Pool to create if none exists at start up. It is invalid to define this variable and NO_DEFAULT_POOLS. [Default: IPv6 `podSubnet` from the kubeadm-config ConfigMap if present, otherwise ``] | IPv6 CIDR | | CALICO_IPV6POOL_BLOCK_SIZE | Block size to use for the IPv6 POOL created at startup. Block size for IPv6 should be in the range 116-128 (inclusive) [Default: `122`] | int | | CALICO_IPV6POOL_VXLAN | VXLAN Mode to use for the IPv6 Pool created at start up. [Default: `Never`] | Always, CrossSubnet, Never | | CALICO_IPV6POOL_NAT_OUTGOING | Controls NAT Outgoing for the IPv6 Pool created at start up. [Default: `false`] | boolean | -| CALICO_IPV6POOL_NODE_SELECTOR | Controls the NodeSelector for the IPv6 Pool created at start up. [Default: `all()`] | [selector](resources/ippool.mdx#node-selector) | +| CALICO_IPV6POOL_NODE_SELECTOR | Controls the NodeSelector for the IPv6 Pool created at start up. [Default: `all()`] | [selector](resources/ippool.mdx#selector) | | CALICO_IPV4POOL_DISABLE_BGP_EXPORT | Disable exporting routes over BGP for the IPv4 Pool created at start up. [Default: `false`] | boolean | | CALICO_IPV6POOL_DISABLE_BGP_EXPORT | Disable exporting routes over BGP for the IPv6 Pool created at start up. [Default: `false`] | boolean | | NO_DEFAULT_POOLS | Prevents $[prodname] from creating a default pool if one does not exist. [Default: `false`] | boolean | diff --git a/calico/reference/resources/bgppeer.mdx b/calico/reference/resources/bgppeer.mdx index 5576416494..d2bcb209bb 100644 --- a/calico/reference/resources/bgppeer.mdx +++ b/calico/reference/resources/bgppeer.mdx @@ -1,6 +1,6 @@ --- description: Reference for the BGPPeer resource in Calico Open Source that defines a BGP neighbor relationship between Calico nodes and external routers. -content_type: unclassified +content_type: reference --- # BGP peer @@ -13,9 +13,14 @@ Configuring BGP peers allows you to peer a $[prodname] network 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). +`BGPPeer` is a cluster-scoped resource. + +For `kubectl` commands, you can use the case-insensitive aliases `bgppeer.projectcalico.org`, `bgppeers.projectcalico.org`, `bgppeer.p`, and `bgppeers.p`. ## Sample YAML +This sample peers one node with a router at 192.168.1.1 in AS 63400. + ```yaml apiVersion: projectcalico.org/v3 kind: BGPPeer @@ -27,26 +32,26 @@ spec: asNumber: 63400 ``` -## BGP peer definition +## Definition ### Metadata -| Field | Description | Accepted Values | Schema | -| ----- | ------------------------------------------------------------------ | --------------------------------------------------- | ------ | -| name | Unique name to describe this resource instance. Must be specified. | Lowercase alphanumeric string with optional `.` or `-`. | string | +| Field | Description | Accepted Values | Schema | Default | +| ----- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | +| name | The name of this BGP peer. Required. | Lowercase alphanumeric characters, `-`, or `.`. Must start and end with an alphanumeric character. Up to 253 characters. | string | | ### Spec | Field | Description | Accepted Values | Schema | Default | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------- | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------- | | node | If specified, the scope is node level, otherwise the scope is global. | The hostname of the node to which this peer applies. | string | | | peerIP | The IP address of this peer and an optional port number. If port number is not set, and peer is Calico node with `listenPort` set, then `listenPort` is used. | Valid IPv4 or IPv6 address. If port number is set use, `IPv4:port` or `[IPv6]:port` format. | string | | -| asNumber | The remote AS Number of the peer. | A valid AS Number. String values, including dotted notation, work through `calicoctl` or the $[prodname] API server, but not with `kubectl` on [native v3 CRDs](../../operations/native-v3-crds.mdx). | integer/string | -| localASNumber | Specifies AS Number $[prodname] uses as its local AS Number for this peer, overriding the global AS Number set in the default BGPConfiguration. | A valid AS Number. String values, including dotted notation, work through `calicoctl` or the $[prodname] API server, but not with `kubectl` on [native v3 CRDs](../../operations/native-v3-crds.mdx). | integer/string | -| nodeSelector | Selector for the nodes that should have this peering. When this is set, the `node` field must be empty. | | [selector](#selectors) | -| peerSelector | Selector for the remote nodes to peer with. When this is set, the `peerIP` and `asNumber` fields must be empty. | | [selector](#selectors) | -| localWorkloadSelector | Selector for the local workloads that the node should peer with. When this is set, the `peerSelector` and `peerIP` fields must be empty and the `localWorkloadPeeringIPV4` and/or `localWorkloadPeeringIPV6` fields in the `BGPConfiguration` resource must be configured. It is also important to configure appropriate import/export filters when using this feature. See the [guide](../../networking/configuring/bgp-to-workload.mdx) for details. | | [selector](#selectors) | | -| keepOriginalNextHop | Maintain and forward the original next hop BGP route attribute to a specific Peer within a different AS. Note: this field is deprecated. Users should use the nextHopMode field to control the next hop attribute for a BGP peer. | | boolean | +| asNumber | The remote AS Number of the peer. | A valid AS Number. String values, including dotted notation, work through `calicoctl` or the $[prodname] API server, but not with `kubectl` on [native v3 CRDs](../../operations/native-v3-crds.mdx). | integer/string | | +| localASNumber | Specifies AS Number $[prodname] uses as its local AS Number for this peer, overriding the global AS Number set in the default BGPConfiguration. | A valid AS Number. String values, including dotted notation, work through `calicoctl` or the $[prodname] API server, but not with `kubectl` on [native v3 CRDs](../../operations/native-v3-crds.mdx). | integer/string | | +| nodeSelector | Selector for the nodes that should have this peering. When this is set, the `node` field must be empty. | | [selector](#selector) | | +| peerSelector | Selector for the remote nodes to peer with. When this is set, the `peerIP` and `asNumber` fields must be empty. | | [selector](#selector) | | +| localWorkloadSelector | Selector for the local workloads that the node should peer with. When this is set, the `peerSelector` and `peerIP` fields must be empty and the `localWorkloadPeeringIPV4` and/or `localWorkloadPeeringIPV6` fields in the `BGPConfiguration` resource must be configured. It is also important to configure appropriate import/export filters when using this feature. See the [guide](../../networking/configuring/bgp-to-workload.mdx) for details. | | [selector](#selector) | | +| keepOriginalNextHop _(deprecated)_ | Maintain and forward the original next hop BGP route attribute to a specific Peer within a different AS. Use the `nextHopMode` field instead to control the next hop attribute for a BGP peer. | | boolean | | | password | BGP password for the peerings generated by this BGPPeer resource. | | [BGPPassword](#bgppassword) | `nil` (no password) | | sourceAddress | Specifies whether and how to configure a source address for the peerings generated by this BGPPeer resource. Default value "UseNodeIP" means to configure the node IP as the source address. "None" means not to configure a source address. | "UseNodeIP", "None" | string | "UseNodeIP" | | maxRestartTime | Restart time that is announced by BIRD in the BGP graceful restart capability and that specifies how long the neighbor would wait for the BGP session to re-establish after a restart before deleting stale routes. Note: extra care should be taken when changing this configuration, as it may break networking in your cluster. When not specified, BIRD uses the default value of 120 seconds. | `10s`, `120s`, `2m` etc. | [Duration string][parse-duration] | `nil` (empty config, BIRD will use the default value of `120s`) | @@ -81,19 +86,19 @@ is configured, the BGP sessions with that password will fail to be established. ::: -| Field | Description | Schema | -| ------------ | ------------------------------- | ----------------- | -| secretKeyRef | Get the password from a secret. | [KeyRef](#keyref) | +| Field | Description | Accepted Values | Schema | Default | +| ------------ | ------------------------------- | --------------- | ----------------- | ------- | +| secretKeyRef | Get the password from a secret. | | [KeyRef](#keyref) | | ### KeyRef KeyRef tells $[prodname] where to get a BGP password. The referenced Kubernetes secret must be in the same namespace as the $[nodecontainer] pod. -| Field | Description | Schema | -| ----- | ------------------------- | ------ | -| name | The name of the secret | string | -| key | The key within the secret | string | +| Field | Description | Accepted Values | Schema | Default | +| ----- | ------------------------- | --------------- | ------ | ------- | +| name | The name of the secret | | string | | +| key | The key within the secret | | string | | :::warning @@ -167,6 +172,12 @@ spec: ::: +### Selector + +The `nodeSelector` and `peerSelector` fields select over `Node` resources, and the `localWorkloadSelector` field selects over workload endpoints. + + + ## Peer scopes BGP Peers can exist at either global or node-specific scope. A peer's scope @@ -184,8 +195,11 @@ A BGP peer can also be node-specific. When the `node` field is included, only th will peer with it. When the `nodeSelector` field is included, the nodes with labels that match that selector will peer with it. -## Selectors +## Additional resources - +- [Configure BGP peering](../../networking/configuring/bgp.mdx) +- [BGP configuration](bgpconfig.mdx) +- [BGP filter](bgpfilter.mdx) +- [Node](node.mdx) [parse-duration]: https://golang.org/pkg/time/#ParseDuration diff --git a/calico/reference/resources/ippool.mdx b/calico/reference/resources/ippool.mdx index 5bcf5e62b4..2b00465942 100644 --- a/calico/reference/resources/ippool.mdx +++ b/calico/reference/resources/ippool.mdx @@ -1,6 +1,6 @@ --- description: Reference for the IPPool resource in Calico Open Source that defines CIDRs available for pod IP address allocation. -content_type: unclassified +content_type: reference --- # IP pool @@ -9,9 +9,14 @@ import Selectors from '@site/calico/_includes/content/_selectors.mdx'; An IP pool resource (`IPPool`) represents a collection of IP addresses from which $[prodname] expects endpoint IPs to be assigned. +`IPPool` is a cluster-scoped resource. + +For `kubectl` commands, you can use the case-insensitive aliases `ippool.projectcalico.org`, `ippools.projectcalico.org`, `ippool.p`, and `ippools.p`. ## Sample YAML +This sample creates a pool that uses IP-in-IP between subnets and masquerades traffic leaving the cluster. + ```yaml apiVersion: projectcalico.org/v3 kind: IPPool @@ -29,13 +34,13 @@ spec: assignmentMode: Automatic ``` -## IP pool definition +## Definition ### Metadata -| Field | Description | Accepted Values | Schema | -| ----- | ------------------------------------------- | --------------------------------------------------- | ------ | -| name | The name of this IPPool resource. Required. | Lowercase alphanumeric string with optional `.` or `-`. | string | +| Field | Description | Accepted Values | Schema | Default | +| ----- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | +| name | The name of this IP pool. Required. | Lowercase alphanumeric characters, `-`, or `.`. Must start and end with an alphanumeric character. Up to 253 characters. | string | | ### Spec @@ -48,10 +53,10 @@ spec: | natOutgoing | When enabled, packets sent from $[prodname] networked containers in this pool to destinations outside of any Calico IP pools, or in a `LoadBalancer` IP pool, will be masqueraded. | true, false | boolean | `false` | | disabled | When set to true, $[prodname] IPAM will not assign addresses from this pool. | true, false | boolean | `false` | | disableBGPExport _(since v3.21.0)_ | Disable exporting routes from this IP Pool’s CIDR over BGP. | true, false | boolean | `false` | -| nodeSelector | Selects the nodes that $[prodname] IPAM should assign addresses from this pool to. | | [selector](#node-selector) | all() | -| namespaceSelector | Selects the namespaces that $[prodname] IPAM should assign addresses from this pool to. If set, both `namespaceSelector` and `nodeSelector` must match. Cannot be used when `allowedUses` includes `Tunnel`. | | [selector](#node-selector) | | -| allowedUses _(since v3.21.0)_ | Controls whether the pool will be used for automatic assignments of certain types. See [below](#allowed-uses). | Workload, Tunnel, LoadBalancer | list of strings | `["Workload", "Tunnel"]` | -| assignmentMode | Controls whether the pool will be used for automatic assignments or only if requested manually | Automatic, Manual | string | `Automatic` | +| nodeSelector | Selects the nodes that $[prodname] IPAM should assign addresses from this pool to. | | [selector](#selector) | all() | +| namespaceSelector | Selects the namespaces that $[prodname] IPAM should assign addresses from this pool to. If set, both `namespaceSelector` and `nodeSelector` must match. Cannot be used when `allowedUses` includes `Tunnel`. | | [selector](#selector) | | +| allowedUses _(since v3.21.0)_ | Controls whether the pool will be used for automatic assignments of certain types. See [Allowed uses](#allowed-uses). | Workload, Tunnel, LoadBalancer | list of strings | `["Workload", "Tunnel"]` | +| assignmentMode | Controls whether the pool will be used for automatic assignments or only if requested manually. See [Assignment mode](#assignment-mode). | Automatic, Manual | string | `Automatic` | :::note @@ -61,7 +66,13 @@ IP pool by creating blocks of incorrect size. ::: -### Allowed uses +### Selector + +The `nodeSelector` field selects over `Node` resources, and the `namespaceSelector` field selects over namespaces. + + + +## Allowed uses When automatically assigning IP addresses to workloads, only pools with "Workload" in their `allowedUses` field are consulted. Similarly, when assigning IPs for tunnel devices, only "Tunnel" pools are eligible. @@ -80,13 +91,13 @@ workload addresses. Tunnel addresses from a pool that no longer allows "Tunnel" $[prodname] supports Kubernetes [annotations that force the use of specific IP addresses](../configure-cni-plugins.mdx#requesting-a-specific-ip-address). The `ipAddrs` annotation does not override the `allowedUses` field: the requested address must be in a pool that allows "Workload". -### CIDR overlap validation +## CIDR overlap validation In API server mode, creating an IPPool with a CIDR that overlaps an existing pool is rejected synchronously at creation time. When using [native v3 CRDs](../../operations/native-v3-crds.mdx), CIDR overlap validation for pools created with `kubectl` is **asynchronous**. Pools with overlapping CIDRs are created successfully but receive an `Allocatable` status condition set to `False` with reason `CIDROverlap`. IPAM does not allocate addresses from disabled pools. Check the IPPool status to identify any pools that have been disabled due to CIDR overlap. -### IPIP +## IPIP Routing of packets using IP-in-IP will be used when the destination IP address is in an IP Pool that has IPIP enabled. In addition, if the `ipipMode` is set to `CrossSubnet`, @@ -94,9 +105,6 @@ $[prodname] will only route using IP-in-IP if the IP address of the destination subnet. The subnet of each node is configured on the node resource (which may be automatically determined when running the `$[nodecontainer]` service). -For details on configuring IP-in-IP on your deployment, please refer to -[Configuring IP-in-IP](../../networking/configuring/vxlan-ipip.mdx). - :::note Setting `natOutgoing` is recommended on any IP Pool with `ipip` enabled. @@ -106,7 +114,7 @@ Hosts running $[prodname] is asymmetric and may cause traffic to be filtered due ::: -### VXLAN +## VXLAN Routing of packets using VXLAN will be used when the destination IP address is in an IP Pool that has VXLAN enabled. In addition, if the `vxlanMode` is set to `CrossSubnet`, @@ -123,7 +131,7 @@ Hosts running $[prodname] is asymmetric and may cause traffic to be filtered due ::: -### Block sizes +## Block sizes The default block sizes of `26` for IPv4 and `122` for IPv6 provide blocks of 64 addresses. This allows addresses to be allocated in groups to workloads running on the same host. By grouping addresses, fewer routes need to be exchanged between hosts and to other BGP peers. If a host allocates all of the addresses in a block then it will be allocated an additional block. If there are no more blocks available then the host can take addresses from blocks allocated to other hosts. Specific routes are added for the borrowed addresses which has an impact on route table size. @@ -131,20 +139,13 @@ Increasing the block size from the default (e.g., using `24` for IPv4 to give 25 Reducing the block size from the default (e.g., using `28` for IPv4 to give 16 addresses per block) means more blocks per host and therefore potentially more routes. This can be beneficial if it allows the blocks to be more fairly distributed amongst the hosts. -### Assignment Mode +## Assignment mode Determines if the IP pool should be used by Calico IPAM for automatic IP assignments. With `Automatic` assignmentMode, Calico IPAM automatically assigns IP addresses from this pool. If you set `assignmentMode` to `Manual`, Calico IPAM does not assign IP addresses from this pool unless the user specifies this pool. -### Node Selector - -For details on configuring IP pool node selectors, please read the -[Assign IP addresses based on topology guide.](../../networking/ipam/assign-ip-addresses-topology.mdx). - -#### Selector reference - - - -## See also +## Additional resources -The [`IPReservation` resource](ipreservation.mdx) allows for small parts of an IP pool to be reserved so that they will -not be used for automatic IPAM assignments. +- [IP reservation](ipreservation.mdx), which reserves small parts of an IP pool so that they aren't used for automatic IPAM assignments +- [Overlay networking](../../networking/configuring/vxlan-ipip.mdx) +- [Assign IP addresses based on topology](../../networking/ipam/assign-ip-addresses-topology.mdx) +- [Change IP pool block size](../../networking/ipam/change-block-size.mdx) diff --git a/calico/reference/resources/ipreservation.mdx b/calico/reference/resources/ipreservation.mdx index 94afa52e54..05ec485519 100644 --- a/calico/reference/resources/ipreservation.mdx +++ b/calico/reference/resources/ipreservation.mdx @@ -1,15 +1,20 @@ --- description: Reference for the IPReservation resource in Calico Open Source that excludes specific addresses or ranges from automatic allocation. -content_type: unclassified +content_type: reference --- # IP reservation An IP reservation resource (`IPReservation`) represents a collection of IP addresses that $[prodname] should not use when automatically assigning new IP addresses. It only applies when $[prodname] IPAM is in use. +`IPReservation` is a cluster-scoped resource. + +For `kubectl` commands, you can use the case-insensitive aliases `ipreservation.projectcalico.org`, `ipreservations.projectcalico.org`, `ipreservation.p`, and `ipreservations.p`. ## Sample YAML +This sample reserves two single addresses and one IPv6 range. + ```yaml apiVersion: projectcalico.org/v3 kind: IPReservation @@ -22,21 +27,21 @@ spec: - cafe:f00d::/123 ``` -## IP reservation definition +## Definition ### Metadata -| Field | Description | Accepted Values | Schema | -| ----- | -------------------------------------------------- | --------------------------------------------------- | ------ | -| name | The name of this IPReservation resource. Required. | Lowercase alphanumeric string with optional `.` or `-`. | string | +| Field | Description | Accepted Values | Schema | Default | +| ----- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | +| name | The name of this IP reservation. Required. | Lowercase alphanumeric characters, `-`, or `.`. Must start and end with an alphanumeric character. Up to 253 characters. | string | | ### Spec -| Field | Description | Accepted Values | Schema | Default | -| ------------- | --------------------------------------------------------------- | -------------------------------------------------- | ------ | ------- | -| reservedCIDRs | List of IP addresses and/or networks specified in CIDR notation | List of valid IPv4 and/or IPv6 CIDRs, such as `10.0.2.3/32` for a single address | list | | +| Field | Description | Accepted Values | Schema | Default | +| ------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------- | ------- | +| reservedCIDRs | List of IP addresses and/or networks specified in CIDR notation | List of valid IPv4 and/or IPv6 CIDRs, such as `10.0.2.3/32` for a single address | list of strings | | -### Notes +## How reservations are applied The implementation of `IPReservation`s is designed to handle reservation of a small number of IP addresses/CIDRs from (generally much larger) IP pools. If a significant portion of an IP pool is reserved (say more than 10%) then @@ -55,3 +60,8 @@ are in place. When Windows nodes claim blocks of IPs they automatically assign the first three IPs in each block and the final IP for internal purposes. These assignments cannot be blocked by an `IPReservation`. However, if a whole IPAM block is reserved with an `IPReservation`, Windows nodes will not claim such a block. + +## Additional resources + +- [IP pool](ippool.mdx) +- [Use a specific IP address with a pod](../../networking/ipam/use-specific-ip.mdx) diff --git a/contributors/content-types/content-types.md b/contributors/content-types/content-types.md index 3a848933dc..44e75fccf3 100644 --- a/contributors/content-types/content-types.md +++ b/contributors/content-types/content-types.md @@ -49,6 +49,7 @@ See [How-to guides](https://diataxis.fr/how-to-guides/). Readers consult it rather than read it from start to finish. It follows the structure of the product and must be accurate and complete. It describes; it doesn't instruct or explain. +Pages that describe one API resource follow a fixed structure, so that every resource page reads the same way. See [Reference](https://diataxis.fr/reference/). **Explanation.** An explanation page helps the reader understand a topic: how it works, why it's designed that way, and what the trade-offs and alternatives are. diff --git a/contributors/content-types/templates/reference.mdx b/contributors/content-types/templates/reference.mdx index d6a51e36b2..0b92cb480c 100644 --- a/contributors/content-types/templates/reference.mdx +++ b/contributors/content-types/templates/reference.mdx @@ -20,13 +20,11 @@ content_type: reference It doesn't tell the reader what to do, and it doesn't explain why. Link to how-to guides for tasks and to explanation pages for concepts. - Resource pages, such as those in reference/resources/, follow their own conventions. - When you write one, follow its sibling pages. + For a page that describes one projectcalico.org API resource, use resource.mdx instead of this template. - Don't hand-write a page that is generated from source, such as the CRD API reference. + Don't hand-write a page that is generated from source, such as the operator API reference. Good examples in our docs: - - calico/reference/resources/ippool.mdx, a resource - calico/reference/configure-calico-node.mdx, configuration options - calico-enterprise/reference/l2-bridge-support.mdx, what a feature supports diff --git a/contributors/content-types/templates/resource.mdx b/contributors/content-types/templates/resource.mdx new file mode 100644 index 0000000000..350fcce9ad --- /dev/null +++ b/contributors/content-types/templates/resource.mdx @@ -0,0 +1,244 @@ +--- +description: "[What the resource does, in one sentence of 130 to 160 characters: Reference for the Kind resource in Product that ...]" +content_type: reference +--- + +{/* + RESOURCE REFERENCE TEMPLATE + + Copy this file to a new .mdx file in reference/resources/ to start a resource reference page. + Replace the text in square brackets. + Delete the guidance comments, including this one, before you open a pull request. + + A resource reference page describes one projectcalico.org API resource: what it represents, its fields, their types, accepted values, and defaults. + Readers come to it while writing or reviewing a manifest. + They look up one field and leave, so the page has to be complete, accurate, and easy to scan. + + A resource reference page describes. + It doesn't tell the reader how to set the resource up, and it doesn't explain why the feature exists. + Link to how-to guides and explanation pages instead. + + Every resource page has the same sections, in the same order, with the same table columns. + A script checks the pages against the CRD, so keep the table shape exactly as shown here. + + For other kinds of reference page, such as configuration options or what a feature supports, use reference.mdx. + Don't hand-write a page for an API that is generated from source, such as the operator API. + + Good examples in our docs: + - calico/reference/resources/ipreservation.mdx, a small resource + - calico/reference/resources/ippool.mdx, a resource with behavior sections + - calico/reference/resources/bgppeer.mdx, a resource with nested types + + Read content-types.md for how reference fits with the other content types. +*/} + +{/* + OPTIONAL: User story + + Record who the page is for and what they need from it. + This comment can stay on the page. + + As a [role], I want the field-level definition of the [Kind] resource, so that I can write and review manifests precisely. +*/} + +# [Resource name] + +{/* + REQUIRED: Title + + Use the resource's name as a reader would say it, in sentence case: "IP pool", "BGP peer", "Network policy". + Don't use the kind as the title, and don't add "resource" or "reference". +*/} + +A [resource name] resource (`[Kind]`) represents [what it represents]. +[One or two sentences on what it's for and what it affects.] +`[Kind]` is a [cluster-scoped or namespaced] resource. + +{/* + REQUIRED: Lead paragraph + + Open with the sentence "A [resource name] resource (`Kind`) represents ...", so every page starts the same way. + Say whether the resource is cluster-scoped or namespaced. + Say who creates it, if not the reader: "$[prodname] IPAM creates and manages these resources. You don't normally create or change them." + Say what the reader can't do with it, if anything: "You can't create or delete this resource." + There is no Supported operations table; this paragraph does that job. + Link to the explanation page for the feature, and to the main how-to guide. + + If the resource is a tech preview or deprecated, set lifecycle_status in the front matter. + Don't write the notice by hand. +*/} + +For `kubectl` commands, you can use the case-insensitive aliases `[kind].projectcalico.org`, `[kinds].projectcalico.org`, `[kind].p`, and `[kinds].p`. + +{/* + REQUIRED: Aliases + + Use this one sentence, with the singular and plural resource names. + If the resource can't be managed with kubectl, write "This resource is not supported in `kubectl`." instead. + If calicoctl accepts short aliases too, list them in a second sentence of the same shape. +*/} + +## Sample YAML + +[One sentence that says what this sample does.] + +```yaml +apiVersion: projectcalico.org/v3 +kind: [Kind] +metadata: + name: [name] +spec: + [field]: [value] +``` + +{/* + REQUIRED: Sample YAML + + Show one short manifest that is valid as written, with the fields readers set most often. + Start with a sentence that says what the sample does. + If the resource has distinct modes that need different fields, use one ### subsection for each mode, with the mode in the heading. + Leave this section out only when the reader never creates the resource. +*/} + +## Definition + +{/* + REQUIRED: Definition + + Always use the heading "Definition". + Under it, put Metadata, then Spec, then one section for each nested type, then Status. + + Every field table has these columns, in this order: + + | Field | Description | Accepted Values | Schema | Default | + + Keep all five columns on every table, and leave a cell empty rather than drop a column. + Keep the same column order on nested type tables too. + + Field: the field name exactly as it appears in the manifest, and nothing else. + If the field was added in a version readers may not have, append the version: `fieldName _(since v3.21.0)_`. + If the field is deprecated, append `_(deprecated)_` and say in the description what to use instead. + Description: what the field does, in a sentence or two. + If the field is required, end with "Required." + If it's required only in some cases, say when: "Required when `mode` is `Manual`." + If it can't be combined with another field, say so: "Can't be set with `vxlanMode`." + Put limits and validation rules here, or in Accepted Values when they're a range. + Accepted Values: the values or ranges the API accepts, such as `Always`, `CrossSubnet`, `Never` or `20` to `32`. + Leave it empty when any value of the schema type is accepted. + Schema: the type: string, integer, boolean, float, list of strings, map of string to string, or a link to a nested type: [BGPPassword](#bgppassword), list of [Rule](#rule), [selector](#selector). + Default: the value the API uses when the field is omitted, in code format. + Leave it empty when there is no default. +*/} + +### Metadata + +| Field | Description | Accepted Values | Schema | Default | +| ----- | ----------- | --------------- | ------ | ------- | +| name | The name of this [resource name]. Required. | Lowercase alphanumeric characters, `-`, or `.`. Must start and end with an alphanumeric character. Up to 253 characters. | string | | +| namespace | The namespace this [resource name] belongs to. | | string | `default` | +| labels | Labels that selectors in other resources can match. | | map of string to string | | + +{/* + REQUIRED: Metadata + + Use these rows and this wording. + Keep the name rule accurate for this kind: tiers and policies have their own rules. + Include the namespace row only for a namespaced resource. + Include the labels row only when something selects this resource by its labels, such as nodes, endpoints, and network sets. +*/} + +### Spec + +| Field | Description | Accepted Values | Schema | Default | +| ----- | ----------- | --------------- | ------ | ------- | +| [field] | [What it does.] Required. | [values] | [type] | [default] | +| [field] | [What it does.] | [values] | [[TypeName](#typename)] | [default] | + +{/* + REQUIRED: Spec + + List every field in the spec, in the order they appear in the API. + A note that applies to the whole spec, such as a compatibility warning, goes after the table as an admonition. +*/} + +### [TypeName] + +| Field | Description | Accepted Values | Schema | Default | +| ----- | ----------- | --------------- | ------ | ------- | +| [field] | [What it does.] | [values] | [type] | [default] | + +{/* + REQUIRED, when the spec has nested types: One section for each nested type + + DECISION: the heading is the Go type name from the API, exactly as spelled there: "BGPPassword", "KeyRef", "EntityRule". + That's what the Schema column links to, and what the CRD check matches on. + + Add the sections in the order the types are first referenced. + Start with a sentence of context only if the table needs it. + If a type is used by more than one resource, such as Rule, EntityRule, or Selector, put its section in an include under _includes/content/, import it, and render it here, so every page shows the same text. +*/} + +### Selector + + + +{/* + REQUIRED, when any field is a selector: Selector + + Import the shared selector include at the top of the page and render it here, so the Schema column can link to #selector. + Add a sentence that says which resources each selector field selects over, if it isn't obvious. +*/} + +### Status + +| Field | Description | Accepted Values | Schema | Default | +| ----- | ----------- | --------------- | ------ | ------- | +| [field] | [What it reports.] | [values] | [type] | | + +{/* + REQUIRED, when the resource has a status: Status + + Put Status last under Definition. + Say which component writes it. + Use the same columns, and leave Default empty. +*/} + +## [Behavior detail] + +{/* + OPTIONAL: Behavior sections + + Use a ## section after Definition for behavior that needs more than a table cell: how overlapping values are resolved, what a mode does, what a limit is for. + Keep it factual, and keep it after Definition. + If it turns into an explanation of why, or into steps, move that to an explanation page or a how-to guide and link to it. +*/} + +## Additional resources + +{/* + RECOMMENDED: Additional resources + + Link to the explanation page for the feature, the how-to guides that use this resource, and the related resources. + Keep the list short. +*/} + +- [Link to an explanation page] +- [Link to a how-to guide] +- [Link to a related resource] + +{/* + REVIEWER CHECKLIST + + - The title is the resource name in sentence case, not the kind. + - The lead paragraph opens with "A [resource name] resource (`Kind`) represents", says whether the resource is cluster-scoped or namespaced, and says who creates it when that isn't the reader. + - The aliases sentence uses the standard wording, or says the resource isn't supported in kubectl. + - The sample manifest is valid as written. + - The heading is "Definition", with Metadata, Spec, nested types, and Status in that order. + - Every table has the columns Field, Description, Accepted Values, Schema, Default, in that order. + - Every field in the API is in a table, with its default where one applies, and "Required." where it's required. + - Nested type headings use the Go type name, and the Schema column links to them. + - Shared types come from an include. + - There is no Supported operations table. + - Behavior sections come after Definition and contain no steps. + - The page has no tech preview or deprecation notice written by hand. +*/}