From 46b4b8fd936fc241584c5a9c916ba7022d3c994a Mon Sep 17 00:00:00 2001 From: Lenny Chen <55669665+lennessyy@users.noreply.github.com> Date: Tue, 24 Sep 2024 16:37:43 -0700 Subject: [PATCH 1/2] docs: modify calico instructions for multi-nic case (#4050) * docs: modify calico instructions for multi-nic case * docs: modify sample code * docs: identation --------- Co-authored-by: Lenny Chen (cherry picked from commit 59d4359b949c57aa1f454aac21d7f3c84e84cd1c) --- .../site-installation/cluster-deployment.md | 244 +++++++++--------- 1 file changed, 126 insertions(+), 118 deletions(-) diff --git a/docs/docs-content/clusters/edge/site-deployment/site-installation/cluster-deployment.md b/docs/docs-content/clusters/edge/site-deployment/site-installation/cluster-deployment.md index 467f1456a5..863a54c89d 100644 --- a/docs/docs-content/clusters/edge/site-deployment/site-installation/cluster-deployment.md +++ b/docs/docs-content/clusters/edge/site-deployment/site-installation/cluster-deployment.md @@ -70,8 +70,8 @@ Use the following steps to create a new host cluster so that you can add Edge ho a CIDR range that cannot routed through a proxy. In addition, ensure that this VIP does not overlap with any IP address already used by other hosts in your network, including your Edge hosts. -You can also select any SSH keys in case you need to remote into the host cluster. You can also provide a list of -Network Time Protocol (NTP) servers. Click on **Next**. + You can also select any SSH keys in case you need to remote into the host cluster. You can also provide a list of + Network Time Protocol (NTP) servers. Click on **Next**. 9. The node configuration page is where you can specify what Edge hosts make up the host cluster. Assign Edge hosts to the **control-plane-pool** and the **worker-pool**. When you have completed configuring the node pools, click on @@ -80,102 +80,107 @@ Network Time Protocol (NTP) servers. Click on **Next**. 10. (Optional) When you assign Edge hosts to node pools, you can optionally specify a static IP address for each Edge host. If you want to specify a static IP, toggle on **Static IP** and provide the following information: -| **Field** | **Description** | -| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| IP address | The static IP address assigned to your Edge host. This should be unique within your network. | -| Default gateway | The IP address of the default gateway for your cluster network. This gateway routes traffic from your cluster to external networks. | -| Subnet mask | The subnet mask of your cluster network. This defines the range of IP addresses within your cluster network. | -| DNS server | The IP address of the DNS server your cluster uses for domain resolution. | + | **Field** | **Description** | + | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | + | IP address | The static IP address assigned to your Edge host. This should be unique within your network. | + | Default gateway | The IP address of the default gateway for your cluster network. This gateway routes traffic from your cluster to external networks. | + | Subnet mask | The subnet mask of your cluster network. This defines the range of IP addresses within your cluster network. | + | DNS server | The IP address of the DNS server your cluster uses for domain resolution. | -If certain network information is already available, the corresponding fields will be pre-populated. + If certain network information is already available, the corresponding fields will be pre-populated. 11. (Optional) When you assign an Edge host to a node pool, if your Edge host has more than one NIC, you can optionally specify which Network Interface Controller (NIC) the Edge host will use to communicate with the cluster. When you select an Edge host, Palette displays a dropdown of all NICs present on the Edge host. -If the NIC is configured on the Edge host network, an IP address is displayed next to the name of the NIC. If the NIC is -not configured on the Edge host network, you can specify its IP address, default gateway, subnet mask, as well as DNS -server to configure it. + If the NIC is configured on the Edge host network, an IP address is displayed next to the name of the NIC. If the + NIC is not configured on the Edge host network, you can specify its IP address, default gateway, subnet mask, as + well as DNS server to configure it. -If you choose to change the default NIC used by your nodes in the control plane node pool, you need to make sure all the -NICs in the control plane node pool share the same name. You also must make corresponding changes in the Kubernetes -layer and the Container Network Interface (CNI) layer. + If you choose to change the default NIC used by your nodes in the control plane node pool, you need to make sure all + the NICs in the control plane node pool share the same name. You also must make corresponding changes in the + Kubernetes layer and the Container Network Interface (CNI) layer. -In the Kubernetes layer, enter a new parameter `cluster.kubevipArgs.vip_interface` and set its value to the name of the -NIC used by your control plane nodes. For example, if the NIC used by the nodes in your control plane pool is named -`ens32`, add the following two lines. + In the Kubernetes layer, enter a new parameter `cluster.kubevipArgs.vip_interface` and set its value to the name of + the NIC used by your control plane nodes. For example, if the NIC used by the nodes in your control plane pool is + named `ens32`, add the following two lines. -```yaml {3} -cluster: - kubevipArgs: -   vip_interface: "ens32" -``` + ```yaml {3} + cluster: +  kubevipArgs: +    vip_interface: "ens32" + ``` -In the CNI layer, depending on which CNI pack you choose for your cluster profile, you need to make changes in the -following locations. + In the CNI layer, depending on which CNI pack you choose for your cluster profile, you need to make changes in the + following locations. + + + + + + In the Calico pack YAML file default template, uncomment `manifests.calico.env.calicoNode.IP_AUTODETECTION_METHOD` + and set its value to `kubernetes-internal-ip`. This tells Calico to use the address assigned to the Kubernetes node. + + ```yaml {11} + manifests: + calico: + ... + env: + # Additional env variables for calico-node + calicoNode: + #IPV6: "autodetect" + #FELIX_IPV6SUPPORT: "true" + #CALICO_IPV6POOL_NAT_OUTGOING: "true" + #CALICO_IPV4POOL_CIDR: "192.168.0.0/16" + IP_AUTODETECTION_METHOD: "kubernetes-internal-ip" + ``` - - - - In the Calico pack YAML file default template, uncomment `manifests.calico.env.calicoNode.IP_AUTODETECTION_METHOD` and set its value to `interface=INTERFACE_NAME`. Replace `INTERFACE_NAME` with the name of the NIC in your control plane node pool. For example, set `IP_AUTODETECTION_METHOD` to `"interface=eno32"` if the NIC name of the nodes in your control plane pool is `eno32`. - - ```yaml {11} - manifests: - calico: - ... - env: - # Additional env variables for calico-node - calicoNode: - #IPV6: "autodetect" - #FELIX_IPV6SUPPORT: "true" - #CALICO_IPV6POOL_NAT_OUTGOING: "true" - #CALICO_IPV4POOL_CIDR: "192.168.0.0/16" - IP_AUTODETECTION_METHOD: "interface=eno32" - ``` + -In the Flannel pack YAML file, add a line `- "--iface=INTERFACE_NAME"` in the default template under -`charts.flannel.args`. Replace `INTERFACE_NAME` with the name of the NIC. For example, add the line `- "--iface=eno32` -if the NIC name of your control plane nodes is `eno32`. - -```yaml {8} -charts: - flannel: - ... - # flannel command arguments - args: - - "--ip-masq" - - "--kube-subnet-mgr" - - "--iface=eno32" -``` + In the Flannel pack YAML file, add a line `- "--iface=INTERFACE_NAME"` in the default template under + `charts.flannel.args`. Replace `INTERFACE_NAME` with the name of the NIC. For example, add the line `- "--iface=eno32` + if the NIC name of your control plane nodes is `eno32`. + + ```yaml {8} + charts: + flannel: + ... + # flannel command arguments + args: + - "--ip-masq" + - "--kube-subnet-mgr" + - "--iface=eno32" + ``` - You do not need to make any adjustments to the Cilium pack. + You do not need to make any adjustments to the Cilium pack. - If you are using other CNIs, refer to the documentation of your selected CNI and configure it to make sure that it picks the right NIC on your Edge hosts. + If you are using other CNIs, refer to the documentation of your selected CNI and configure it to make sure that it picks the right NIC on your Edge hosts. + -:::warning + :::warning -After you create the cluster, you will not be able to change the IP address or NIC of your existing Edge hosts unless -you remove and re-add them back to the cluster. + After you create the cluster, you will not be able to change the IP address or NIC of your existing Edge hosts unless + you remove and re-add them back to the cluster. -::: + ::: 12. The Settings page is where you can configure a patching schedule, security scans, backup settings, and set up Role-Based Access Control (RBAC). Review the settings and make changes if needed. Click on **Validate**. 13. Review the settings summary and click on **Finish Configuration** to deploy the cluster. -After you create the cluster, the Palette Edge Host agent will start the installation process. You can track the -installation progress in Palette. The cluster overview page displays a summary of the progress. Use the _Events_ tab to -review detailed logs. + After you create the cluster, the Palette Edge Host agent will start the installation process. You can track the + installation progress in Palette. The cluster overview page displays a summary of the progress. Use the _Events_ tab + to review detailed logs. ### Validate @@ -236,74 +241,77 @@ number of nodes. To learn more, check out the resource from the etcd documentati 8. (Optional) When you select your Edge host, you can optionally specify a static IP address for the Edge host. If you want to specify a static IP, toggle on **Static IP** and provide the following information: -| **Field** | **Description** | -| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| IP Address | The static IP address assigned to your Edge host. This should be unique within your network. | -| Default gateway | The IP address of the default gateway for your cluster network. This gateway routes traffic from your cluster to external networks. | -| Subnet mask | The subnet mask of your cluster network. This defines the range of IP addresses within your cluster network. | -| DNS server | The IP address of the DNS server your cluster uses for domain resolution. | + | **Field** | **Description** | + | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | + | IP Address | The static IP address assigned to your Edge host. This should be unique within your network. | + | Default gateway | The IP address of the default gateway for your cluster network. This gateway routes traffic from your cluster to external networks. | + | Subnet mask | The subnet mask of your cluster network. This defines the range of IP addresses within your cluster network. | + | DNS server | The IP address of the DNS server your cluster uses for domain resolution. | -If certain network information is already available, the corresponding fields will be pre-populated. + If certain network information is already available, the corresponding fields will be pre-populated. 9. (Optional) When you assign an Edge host to a node pool, if your Edge host has more than one NIC, you can optionally specify which Network Interface Controller (NIC) the Edge host will use to communicate with the cluster. When you select an Edge host, Palette displays a dropdown of all NICs present on the Edge host. -If the NIC is configured on the Edge host network, an IP address is displayed next to the name of the NIC. If the NIC is -not configured on the Edge host network, you can specify its IP address, default gateway, subnet mask, as well as DNS -server to configure it. + If the NIC is configured on the Edge host network, an IP address is displayed next to the name of the NIC. If the NIC + is not configured on the Edge host network, you can specify its IP address, default gateway, subnet mask, as well as + DNS server to configure it. -If you choose to change the default NIC used by your nodes, you need to make sure all the NICs in the control plane node -pool share the same name. You also must make corresponding changes in the Kubernetes layer and the CNI layer. + If you choose to change the default NIC used by your nodes, you need to make sure all the NICs in the control plane + node pool share the same name. You also must make corresponding changes in the Kubernetes layer and the CNI layer. -In the Kubernetes layer, enter a new parameter `cluster.kubevipArgs.vip_interface` and set its value to the name of the -NIC used by your control plane nodes. For example, if the NIC used by the nodes in your control plane pool is named -`ens32`, add the following two lines. + In the Kubernetes layer, enter a new parameter `cluster.kubevipArgs.vip_interface` and set its value to the name of + the NIC used by your control plane nodes. For example, if the NIC used by the nodes in your control plane pool is + named `ens32`, add the following two lines. -```yaml {2-3} -cluster: - kubevipArgs: -   vip_interface: "ens32" -``` + ```yaml {2-3} + cluster: +  kubevipArgs: +    vip_interface: "ens32" + ``` -In the CNI layer, depending on which CNI pack you choose for your cluster profile, you need to make changes in the -following locations. + In the CNI layer, depending on which CNI pack you choose for your cluster profile, you need to make changes in the + following locations. - In the Calico pack YAML file default template, uncomment `manifests.calico.env.calicoNode.IP_AUTODETECTION_METHOD` and set its value to `interface=INTERFACE_NAME`. Replace `INTERFACE_NAME` with the name of the NIC in your control plane node pool. For example, set `IP_AUTODETECTION_METHOD` to `"interface=eno32"` if the NIC name of the nodes in your control plane pool is `eno32`. + In the Calico pack YAML file default template, uncomment `manifests.calico.env.calicoNode.IP_AUTODETECTION_METHOD` + and set its value to `kubernetes-internal-ip`. This tells Calico to use the address assigned to the Kubernetes + node. - ```yaml {11} - manifests: - calico: - ... - env: - # Additional env variables for calico-node - calicoNode: - #IPV6: "autodetect" - #FELIX_IPV6SUPPORT: "true" - #CALICO_IPV6POOL_NAT_OUTGOING: "true" - #CALICO_IPV4POOL_CIDR: "192.168.0.0/16" - IP_AUTODETECTION_METHOD: "interface=eno32" - ``` + ```yaml {11} + manifests: + calico: + ... + env: + # Additional env variables for calico-node + calicoNode: + #IPV6: "autodetect" + #FELIX_IPV6SUPPORT: "true" + #CALICO_IPV6POOL_NAT_OUTGOING: "true" + #CALICO_IPV4POOL_CIDR: "192.168.0.0/16" + IP_AUTODETECTION_METHOD: "kubernetes-internal-ip" + ``` + -In the Flannel pack YAML file, add a line `- "--iface=INTERFACE_NAME"` in the default template under -`charts.flannel.args`. Replace `INTERFACE_NAME` with the name of the NIC. For example, add the line `- "--iface=eno32` -if the NIC name of your control plane nodes is `eno32`. - -```yaml {8} -charts: - flannel: - ... - # flannel command arguments - args: - - "--ip-masq" - - "--kube-subnet-mgr" - - "--iface=eno32" -``` + In the Flannel pack YAML file, add a line `- "--iface=INTERFACE_NAME"` in the default template under + `charts.flannel.args`. Replace `INTERFACE_NAME` with the name of the NIC. For example, add the line `- "--iface=eno32` + if the NIC name of your control plane nodes is `eno32`. + + ```yaml {8} + charts: + flannel: + ... + # flannel command arguments + args: + - "--ip-masq" + - "--kube-subnet-mgr" + - "--iface=eno32" + ``` @@ -325,8 +333,8 @@ them back to the cluster. 10. Confirm your changes. -The Palette Edge Host agent will start the installation process. You can track the installation progress in Palette. The -cluster overview page displays a summary of the progress. Use the **Events** tab to review detailed logs. + The Palette Edge Host agent will start the installation process. You can track the installation progress in Palette. + The cluster overview page displays a summary of the progress. Use the **Events** tab to review detailed logs. ### Validate From f768507e879a772f938a4eed0ec62d0dd3df91ed Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Wed, 25 Sep 2024 13:35:40 -0700 Subject: [PATCH 2/2] docs: fix broken links --- .../cluster-deployment.md | 40 ++++++++++++------- .../edge-host-registration.md | 2 +- 2 files changed, 26 insertions(+), 16 deletions(-) rename docs/docs-content/clusters/edge/site-deployment/{site-installation => }/cluster-deployment.md (88%) diff --git a/docs/docs-content/clusters/edge/site-deployment/site-installation/cluster-deployment.md b/docs/docs-content/clusters/edge/site-deployment/cluster-deployment.md similarity index 88% rename from docs/docs-content/clusters/edge/site-deployment/site-installation/cluster-deployment.md rename to docs/docs-content/clusters/edge/site-deployment/cluster-deployment.md index 863a54c89d..9266ad8038 100644 --- a/docs/docs-content/clusters/edge/site-deployment/site-installation/cluster-deployment.md +++ b/docs/docs-content/clusters/edge/site-deployment/cluster-deployment.md @@ -3,13 +3,13 @@ sidebar_label: "Create Cluster Definition" title: "Create Cluster Definition" description: "Define your Edge cluster using the Edge hosts that are registered and available." hide_table_of_contents: false -sidebar_position: 30 +sidebar_position: 70 tags: ["edge"] --- -To complete the Edge Installation process, an Edge host must become a member of a host cluster. You can add an Edge host -to an existing host cluster of type Edge Native, or you can create a new host cluster for Edge hosts and make the Edge -host a member. +Once the Edge host has been deployed and registered with Palette, it is ready to be assigned to a host cluster. You can +add an Edge host to an existing Edge cluster, or you can create a new host cluster for Edge hosts and make the Edge host +a member. This applies both to Edge hosts deployed to a physical site and Edge hosts deployed as Virtual Machines (VM). Select the workflow that best fits your needs. @@ -28,7 +28,8 @@ Use the following steps to create a new host cluster so that you can add Edge ho ### Prerequisites - One or more registered Edge host. For more information about Edge host registration, refer to - [Edge Host Registration](./edge-host-registration.md). + [Edge Host Registration](./site-installation/edge-host-registration.md). + - If you are using more than one Edge host to form a cluster, the hosts in the same cluster must be on the same network. - One IP address is required for the cluster's Virtual IP (VIP) address . - At least one IP address is required for each Edge host. @@ -39,7 +40,7 @@ Use the following steps to create a new host cluster so that you can add Edge ho - Use Dynamic Host Configuration Protocol (DHCP) reservations to reserve an IP address in a DHCP network. Contact your network administrator to reserve IP addresses for your Edge hosts in a DHCP network. - Enable network overlay on your Edge cluster. Network overlay can only be enabled during cluster creation. For more - information about network overlay, refer to [Enable Overlay Network](../../networking/vxlan-overlay.md). + information about network overlay, refer to [Enable Overlay Network](../networking/vxlan-overlay.md). :::warning @@ -61,7 +62,7 @@ Use the following steps to create a new host cluster so that you can add Edge ho 5. Give the cluster a name, description, and tags. Click on **Next**. 6. Select a cluster profile. If you don't have a cluster profile for Edge Native, refer to the - [Create Edge Native Cluster Profile](../model-profile.md) guide. Click on **Next** after you have selected a cluster + [Create Edge Native Cluster Profile](./model-profile.md) guide. Click on **Next** after you have selected a cluster profile. 7. Review your cluster profile values and make changes as needed. Click on **Next**. @@ -114,9 +115,9 @@ Use the following steps to create a new host cluster so that you can add Edge ho In the CNI layer, depending on which CNI pack you choose for your cluster profile, you need to make changes in the following locations. - + - + In the Calico pack YAML file default template, uncomment `manifests.calico.env.calicoNode.IP_AUTODETECTION_METHOD` and set its value to `kubernetes-internal-ip`. This tells Calico to use the address assigned to the Kubernetes node. @@ -193,7 +194,7 @@ Use the following steps to create a new host cluster so that you can add Edge ho 4. Review the **Cluster Status**. Ensure the **Cluster Status** field displays **Running**. You can also use the command `kubectl get nodes` to review the status of all nodes in the cluster. Check out the -[Access Cluster with CLI](../../../cluster-management/palette-webctl.md) guide to learn how to use `kubectl` with a host +[Access Cluster with CLI](../../cluster-management/palette-webctl.md) guide to learn how to use `kubectl` with a host cluster. ## Add an Edge Host to a Host Cluster @@ -209,15 +210,25 @@ node pool. ### Prerequisites -- A registered Edge host. +- An existing Edge cluster. + +- One or more registered Edge host on the same network as your existing cluster. For more information about Edge host + registration, refer to [Edge Host Registration](./site-installation/edge-host-registration.md). + +- You must ensure that the Edge hosts have stable IP addresses. You have the following options to do achieve stable IP + addressing for Edge hosts: -- A host cluster of type Edge Native. + - Use static IP addresses. Contact your network administrator to assign the Edge host a static IP address. + - Use Dynamic Host Configuration Protocol (DHCP) reservations to reserve an IP address in a DHCP network. Contact your + network administrator to reserve IP addresses for your Edge hosts in a DHCP network. + - Your Edge cluster has enabled network overlay. Network overlay can only be enabled during cluster creation. For more + information about network overlay, refer to [Enable Overlay Network](../networking/vxlan-overlay.md). :::warning When adding a new Edge host to an existing cluster, ensure you are not creating a scenario where [etcd](https://etcd.io/) could fail in establishing a quorum. Quorum failures typically result when there is an even -number of nodes. To learn more, check out the resource from the etcd documentation titled +number of control plane nodes. To learn more, check out the resource from the etcd documentation titled [Why an odd number of cluster members](https://etcd.io/docs/v3.3/faq/#why-an-odd-number-of-cluster-members). ::: @@ -347,5 +358,4 @@ them back to the cluster. 4. Review the **Cluster Status**. Ensure the **Cluster Status** field displays **Running**. You can also use the command `kubectl get nodes` to review the status of all nodes in the cluster. Check out the -[Access Cluster with CLI](../../../cluster-management/palette-webctl.md) to learn how to use `kubectl` with a host -cluster. +[Access Cluster with CLI](../../cluster-management/palette-webctl.md) to learn how to use `kubectl` with a host cluster. diff --git a/docs/docs-content/clusters/edge/site-deployment/site-installation/edge-host-registration.md b/docs/docs-content/clusters/edge/site-deployment/site-installation/edge-host-registration.md index 21679374fc..3e921c0d6c 100644 --- a/docs/docs-content/clusters/edge/site-deployment/site-installation/edge-host-registration.md +++ b/docs/docs-content/clusters/edge/site-deployment/site-installation/edge-host-registration.md @@ -265,5 +265,5 @@ Your Edge host is displayed and marked as **Registered** in the Edge hosts list. ## Next Steps The next step in the installation process is to add the Edge host to a cluster or to create an Edge Native host cluster. -Check out the [Create Cluster Definition](cluster-deployment.md) guide to complete the last step of the installation +Check out the [Create Cluster Definition](../cluster-deployment.md) guide to complete the last step of the installation process.