From 38d01eda6061d6ada8d31a471d6a55aefc8833db Mon Sep 17 00:00:00 2001 From: nhennigan Date: Tue, 12 Nov 2024 15:07:46 -0800 Subject: [PATCH 1/5] reformatted annotations table due to formatting issues the annotations table was quite unclear. Edited to make it more readable --- docs/src/snap/reference/annotations.md | 186 +++++++++++++++++++++---- 1 file changed, 160 insertions(+), 26 deletions(-) diff --git a/docs/src/snap/reference/annotations.md b/docs/src/snap/reference/annotations.md index 5a8ebf2b1..515b26a97 100644 --- a/docs/src/snap/reference/annotations.md +++ b/docs/src/snap/reference/annotations.md @@ -1,35 +1,169 @@ # Annotations This page outlines the annotations that can be configured during cluster -[bootstrap]. To do this, set the cluster-config/annotations parameter in +[bootstrap]. To do this, set the `cluster-config/annotations` parameter in the bootstrap configuration. -| Name | Description | Values | -|---------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| -| `k8sd/v1alpha/lifecycle/skip-cleanup-kubernetes-node-on-remove` | If set, only microcluster and file cleanup are performed. This is helpful when an external controller (e.g., CAPI) manages the Kubernetes node lifecycle. By default, k8sd will remove the Kubernetes node when it is removed from the cluster. | "true"\|"false" | -| `k8sd/v1alpha/lifecycle/skip-stop-services-on-remove` | If set, the k8s services will not be stopped on the leaving node when removing the node. This is helpful when an external controller (e.g., CAPI) manages the Kubernetes node lifecycle. By default, all services are stopped on leaving nodes. | "true"\|"false" | -| `k8sd/v1alpha1/csrsigning/auto-approve` | If set, certificate signing requests created by worker nodes are auto approved. | "true"\|"false" | -| `k8sd/v1alpha1/calico/apiserver-enabled` | Enable the installation of the Calico API server to enable management of Calico APIs using kubectl. | "true"\|"false" | -| `k8sd/v1alpha1/calico/encapsulation-v4` | The type of encapsulation to use on the IPv4 pool. | "IPIP"\|"VXLAN"\|"IPIPCrossSubnet"\|"VXLANCrossSubnet"\|"None" | -| `k8sd/v1alpha1/calico/encapsulation-v6` | The type of encapsulation to use on the IPv6 pool. | "IPIP"\|"VXLAN"\|"IPIPCrossSubnet"\|"VXLANCrossSubnet"\|"None" | -| `k8sd/v1alpha1/calico/autodetection-v4/firstFound` | Use default interface matching parameters to select an interface, performing best-effort filtering based on well-known interface names. | "true"\|"false" | -| `k8sd/v1alpha1/calico/autodetection-v4/kubernetes` | Configure Calico to detect node addresses based on the Kubernetes API. | "NodeInternalIP" | -| `k8sd/v1alpha1/calico/autodetection-v4/interface` | Enable IP auto-detection based on interfaces that match the given regex. | string | -| `k8sd/v1alpha1/calico/autodetection-v4/skipInterface` | Enable IP auto-detection based on interfaces that do not match the given regex. | string | -| `k8sd/v1alpha1/calico/autodetection-v4/canReach` | Enable IP auto-detection based on which source address on the node is used to reach the specified IP or domain. | string | -| `k8sd/v1alpha1/calico/autodetection-v4/cidrs` | Enable IP auto-detection based on which addresses on the nodes are within one of the provided CIDRs. | []string (comma separated) | -| `k8sd/v1alpha1/calico/autodetection-v6/firstFound` | Use default interface matching parameters to select an interface, performing best-effort filtering based on well-known interface names. | "true"\|"false" | -| `k8sd/v1alpha1/calico/autodetection-v6/kubernetes` | Configure Calico to detect node addresses based on the Kubernetes API. | "NodeInternalIP" | -| `k8sd/v1alpha1/calico/autodetection-v6/interface` | Enable IP auto-detection based on interfaces that match the given regex. | string | -| `k8sd/v1alpha1/calico/autodetection-v6/skipInterface` | Enable IP auto-detection based on interfaces that do not match the given regex. | string | -| `k8sd/v1alpha1/calico/autodetection-v6/canReach` | Enable IP auto-detection based on which source address on the node is used to reach the specified IP or domain. | string | -| `k8sd/v1alpha1/calico/autodetection-v6/cidrs` | Enable IP auto-detection based on which addresses on the nodes are within one of the provided CIDRs. | []string (comma separated) | -| `k8sd/v1alpha1/cilium/devices` | List of devices facing cluster/external network (used for BPF NodePort, BPF masquerading and host firewall); supports `+` as wildcard in device name, e.g. `eth+,ens+` | string | -| `k8sd/v1alpha1/cilium/direct-routing-device` | Device name used to connect nodes in direct routing mode (used by BPF NodePort, BPF host routing); if empty, automatically set to a device with k8s InternalIP/ExternalIP or with a default route. Bridge type devices are ignored in automatic selection | string | -| `k8sd/v1alpha1/cilium/vlan-bpf-bypass` | Comma separated list of VLAN tags to bypass eBPF filtering on native devices. Cilium enables firewalling on native devices and filters all unknown traffic, including VLAN 802.1q packets, which pass through the main device with the associated tag (e.g., VLAN device eth0.4000 and its main interface eth0). Supports `0` as wildcard for bypassing all VLANs. e.g. `4001,4002` | []string | -| `k8sd/v1alpha1/metrics-server/image-repo` | Override the default image repository for the metrics-server. | string | -| `k8sd/v1alpha1/metrics-server/image-tag` | Override the default image tag for the metrics-server. | string | +## `k8sd/v1alpha/lifecycle/skip-cleanup-kubernetes-node-on-remove` +| | | +|---|---| +| **Values**| "true"\|"false"| +| **Description**| If set, only microcluster and file cleanup are performed. This is helpful when an external controller (e.g., CAPI) manages the Kubernetes node lifecycle. By default, k8sd will remove the Kubernetes node when it is removed from the cluster. | + +## `k8sd/v1alpha/lifecycle/skip-cleanup-kubernetes-node-on-remove` + +| | | +|---|---| +|**Values**| "true"\|"false"| +|**Description**|If set, the k8s services will not be stopped on the leaving node when removing the node. This is helpful when an external controller (e.g., CAPI) manages the Kubernetes node lifecycle. By default, all services are stopped on leaving nodes.| + +## `k8sd/v1alpha1/csrsigning/auto-approve` + +| | | +|---|---| +|**Values**| "true"\|"false"| +|**Description**|If set, certificate signing requests created by worker nodes are auto approved.| + +## `k8sd/v1alpha1/calico/apiserver-enabled` + +| | | +|---|---| +|**Values**| "true"\|"false"| +|**Description**|Enable the installation of the Calico API server to enable management of Calico APIs using kubectl.| + +## `k8sd/v1alpha1/calico/encapsulation-v4` + +| | | +|---|---| +|**Values**| “IPIP”\|”VXLAN”\|”IPIPCrossSubnet”\|”VXLANCrossSubnet”\|”None”| +|**Description**|The type of encapsulation to use on the IPv4 pool.| + +## `k8sd/v1alpha1/calico/encapsulation-v6` + +| | | +|---|---| +|**Values**| “IPIP”\|”VXLAN”\|”IPIPCrossSubnet”\|”VXLANCrossSubnet”\|”None”| +|**Description**|The type of encapsulation to use on the IPv6 pool.| + +## `k8sd/v1alpha1/calico/autodetection-v4/firstFound` + +| | | +|---|---| +|**Values**| "true"\|"false"| +|**Description**|Use default interface matching parameters to select an interface, performing best-effort filtering based on well-known interface names.| + +## `k8sd/v1alpha1/calico/autodetection-v4/kubernetes` + +| | | +|---|---| +|**Values**| “NodeInternalIP”| +|**Description**|Configure Calico to detect node addresses based on the Kubernetes API.| + +## `k8sd/v1alpha1/calico/autodetection-v4/interface` + +| | | +|---|---| +|**Values**| string | +|**Description**|Enable IP auto-detection based on interfaces that match the given regex.| + +## `k8sd/v1alpha1/calico/autodetection-v4/skipInterface` + +| | | +|---|---| +|**Values**| string | +|**Description**|Enable IP auto-detection based on interfaces that do not match the given regex.| + +## `k8sd/v1alpha1/calico/autodetection-v4/canReach` + +| | | +|---|---| +|**Values**| string | +|**Description**|Enable IP auto-detection based on which source address on the node is used to reach the specified IP or domain.| + +## `k8sd/v1alpha1/calico/autodetection-v4/cidrs` + +| | | +|---|---| +|**Values**| []string (comma separated) | +|**Description**|Enable IP auto-detection based on which addresses on the nodes are within one of the provided CIDRs.| + +## `k8sd/v1alpha1/calico/autodetection-v6/firstFound` + +| | | +|---|---| +|**Values**| "true"\|"false" | +|**Description**|Use default interface matching parameters to select an interface, performing best-effort filtering based on well-known interface names.| + +## `k8sd/v1alpha1/calico/autodetection-v6/kubernetes` + +| | | +|---|---| +|**Values**| “NodeInternalIP” | +|**Description**|Configure Calico to detect node addresses based on the Kubernetes API.| + +## `k8sd/v1alpha1/calico/autodetection-v6/interface` + +| | | +|---|---| +|**Values**| string | +|**Description**|Enable IP auto-detection based on interfaces that match the given regex.| + +## `k8sd/v1alpha1/calico/autodetection-v6/skipInterface` + +| | | +|---|---| +|**Values**| string | +|**Description**|Enable IP auto-detection based on interfaces that do not match the given regex.| + +## `k8sd/v1alpha1/calico/autodetection-v6/canReach` + +| | | +|---|---| +|**Values**| string | +|**Description**|Enable IP auto-detection based on which source address on the node is used to reach the specified IP or domain.| + +## `k8sd/v1alpha1/calico/autodetection-v6/cidrs` + +| | | +|---|---| +|**Values**| []string (comma separated) | +|**Description**|Enable IP auto-detection based on which addresses on the nodes are within one of the provided CIDRs.| + +## `k8sd/v1alpha1/cilium/devices` + +| | | +|---|---| +|**Values**| string| +|**Description**|List of devices facing cluster/external network (used for BPF NodePort, BPF masquerading and host firewall); supports `+` as wildcard in device name, e.g. `eth+,ens+` | + +## `k8sd/v1alpha1/cilium/direct-routing-device` + +| | | +|---|---| +|**Values**| string| +|**Description**|Device name used to connect nodes in direct routing mode (used by BPF NodePort, BPF host routing); if empty, automatically set to a device with k8s InternalIP/ExternalIP or with a default route. Bridge type devices are ignored in automatic selection| + +## `k8sd/v1alpha1/cilium/vlan-bpf-bypass` + +| | | +|---|---| +|**Values**| []string| +|**Description**|Comma separated list of VLAN tags to bypass eBPF filtering on native devices. Cilium enables firewalling on native devices and filters all unknown traffic, including VLAN 802.1q packets, which pass through the main device with the associated tag (e.g., VLAN device eth0.4000 and its main interface eth0). Supports `0` as wildcard for bypassing all VLANs. e.g. `4001,4002`| + +## `k8sd/v1alpha1/metrics-server/image-repo` + +| | | +|---|---| +|**Values**| string| +|**Description**|Override the default image repository for the metrics-server.| + +## `k8sd/v1alpha1/metrics-server/image-tag` + +| | | +|---|---| +|**Values**| string| +|**Description**|Override the default image tag for the metrics-server.| From 88295dbeec0b6fc6d398f1c1b2b6b81f333207ab Mon Sep 17 00:00:00 2001 From: nhennigan Date: Thu, 14 Nov 2024 15:58:25 -0800 Subject: [PATCH 2/5] add cluster config eg adding example of how to include annotations in your cluster-config yaml file as requested in PR review --- docs/src/snap/reference/annotations.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/src/snap/reference/annotations.md b/docs/src/snap/reference/annotations.md index 515b26a97..9847ccd7a 100644 --- a/docs/src/snap/reference/annotations.md +++ b/docs/src/snap/reference/annotations.md @@ -4,6 +4,16 @@ This page outlines the annotations that can be configured during cluster [bootstrap]. To do this, set the `cluster-config/annotations` parameter in the bootstrap configuration. +For example: + +```yaml +cluster-config: +... + annotations: + k8sd/v1alpha/lifecycle/skip-cleanup-kubernetes-node-on-remove: true + k8sd/v1alpha/lifecycle/skip-stop-services-on-remove: true +``` + ## `k8sd/v1alpha/lifecycle/skip-cleanup-kubernetes-node-on-remove` | | | From 1f8795d76c235b311827b3a4e1eb64f03b2436b8 Mon Sep 17 00:00:00 2001 From: Nick Veitch Date: Fri, 15 Nov 2024 14:59:19 +0000 Subject: [PATCH 3/5] add hacky JS --- docs/src/snap/reference/annotations.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/src/snap/reference/annotations.md b/docs/src/snap/reference/annotations.md index 9847ccd7a..1fd3298db 100644 --- a/docs/src/snap/reference/annotations.md +++ b/docs/src/snap/reference/annotations.md @@ -175,6 +175,15 @@ cluster-config: |**Values**| string| |**Description**|Override the default image tag for the metrics-server.| + + + [bootstrap]: bootstrap-config-reference From 28cbd296c175e8c5bf986a1a6be666d56821af94 Mon Sep 17 00:00:00 2001 From: Niamh Hennigan Date: Fri, 15 Nov 2024 07:47:37 -0800 Subject: [PATCH 4/5] Update docs/src/snap/reference/annotations.md Co-authored-by: Nick Veitch --- docs/src/snap/reference/annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/snap/reference/annotations.md b/docs/src/snap/reference/annotations.md index 1fd3298db..af512eca2 100644 --- a/docs/src/snap/reference/annotations.md +++ b/docs/src/snap/reference/annotations.md @@ -178,7 +178,7 @@ cluster-config: From ddaaf1469333cd981cca0d29e0fb3b03819015f4 Mon Sep 17 00:00:00 2001 From: nhennigan Date: Fri, 15 Nov 2024 09:14:00 -0800 Subject: [PATCH 5/5] address review comments include link to kubernetes website with more info on annotations, make []string clearer to non golang users and include line between eg and list --- docs/src/snap/reference/annotations.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/src/snap/reference/annotations.md b/docs/src/snap/reference/annotations.md index af512eca2..71c4840e4 100644 --- a/docs/src/snap/reference/annotations.md +++ b/docs/src/snap/reference/annotations.md @@ -1,7 +1,7 @@ # Annotations This page outlines the annotations that can be configured during cluster -[bootstrap]. To do this, set the `cluster-config/annotations` parameter in +[bootstrap]. To do this, set the `cluster-config.annotations` parameter in the bootstrap configuration. For example: @@ -14,6 +14,8 @@ cluster-config: k8sd/v1alpha/lifecycle/skip-stop-services-on-remove: true ``` +Please refer to the [Kubernetes website] for more information on annnotations. + ## `k8sd/v1alpha/lifecycle/skip-cleanup-kubernetes-node-on-remove` | | | @@ -95,7 +97,7 @@ cluster-config: | | | |---|---| -|**Values**| []string (comma separated) | +|**Values**| \[] (string values comma separated) | |**Description**|Enable IP auto-detection based on which addresses on the nodes are within one of the provided CIDRs.| ## `k8sd/v1alpha1/calico/autodetection-v6/firstFound` @@ -137,7 +139,7 @@ cluster-config: | | | |---|---| -|**Values**| []string (comma separated) | +|**Values**| \[] (string values comma separated) | |**Description**|Enable IP auto-detection based on which addresses on the nodes are within one of the provided CIDRs.| ## `k8sd/v1alpha1/cilium/devices` @@ -158,7 +160,7 @@ cluster-config: | | | |---|---| -|**Values**| []string| +|**Values**| \[] (string values comma separated)| |**Description**|Comma separated list of VLAN tags to bypass eBPF filtering on native devices. Cilium enables firewalling on native devices and filters all unknown traffic, including VLAN 802.1q packets, which pass through the main device with the associated tag (e.g., VLAN device eth0.4000 and its main interface eth0). Supports `0` as wildcard for bypassing all VLANs. e.g. `4001,4002`| ## `k8sd/v1alpha1/metrics-server/image-repo` @@ -186,4 +188,5 @@ for(var i=0;i +[Kubernetes website]:https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/ [bootstrap]: bootstrap-config-reference