From 3b2db866b5f9bef9a05981dcb1260af7c46c2a6c Mon Sep 17 00:00:00 2001 From: Kevin Reeuwijk Date: Fri, 18 Oct 2024 16:18:49 +0200 Subject: [PATCH 1/2] Rewrote MAAS custom endpoint docs (#4302) * Rewrote MAAS custom endpoint docs * ci: auto-formatting prettier issues * docs: edit text to match docs style guidelines * Apply suggestions from code review Co-authored-by: caroldelwing --------- Co-authored-by: kreeuwijk Co-authored-by: addetz <43963729+addetz@users.noreply.github.com> Co-authored-by: caroldelwing --- docs/deprecated/integrations/kubernetes.md | 92 +++++++++++++----- .../clusters/data-center/maas/architecture.md | 74 +++----------- .../maas/create-manage-maas-clusters.md | 18 ++++ docs/docs-content/integrations/kubernetes.md | 96 ++++++++++++++++--- 4 files changed, 184 insertions(+), 96 deletions(-) diff --git a/docs/deprecated/integrations/kubernetes.md b/docs/deprecated/integrations/kubernetes.md index 8fb6195aae..de5a2d4013 100644 --- a/docs/deprecated/integrations/kubernetes.md +++ b/docs/deprecated/integrations/kubernetes.md @@ -427,14 +427,25 @@ In this example, Palette is used as the IDP, and all users in the `dev-east-2` w ![A subject of the type group is assigned as the subject in a RoleBinding](/clusters_cluster-management_cluster-rbac_cluster-subject-group.webp) -### Custom MAAS Endpoint +### Custom API Server Endpoint for MAAS Clusters -You can specify a custom MAAS endpoint and port that instructs Palette to direct all MAAS API requests to the provided -endpoint URL. Use the `cloud.maas.customEndpoint` and `cloud.maas.customEndpointPort` parameters to specify the custom -MAAS API URL and port. This is useful in scenarios where the MAAS API endpoint is not resolvable outside of the MAAS -network. +By default, Palette registers a DNS record in MAAS for the deployed cluster and links it to the IP addresses of the +control plane nodes of the cluster. However, you may choose not to depend on MAAS for your cluster DNS record. The +Kubernetes pack allows you to configure a custom API server endpoint for your cluster instead. This feature is only +supported in Palette eXtended Kubernetes (PXK). -The following example shows how to specify a custom MAAS endpoint and port in the Kubernetes YAML file. Make sure the +:::warning + +The custom API server endpoint must exist before the cluster gets deployed. Otherwise, your cluster deployment will fail +as components will not be able to connect to the cluster API endpoint. + +When you configure a custom endpoint, a DNS record will not be created in MAAS and the configured endpoint will be used +instead. If you use this option, you are responsible for ensuring the Full Qualified Domain Name (FQDN) of the endpoint +can be resolved by your DNS infrastructure and that it can connect to the API server port on your control plane nodes. + +::: + +The following snippet demonstrates how to specify a custom API server endpoint in the Kubernetes pack. Note that the `cloud.maas` section is at the same level as the `pack` section. ```yaml hideClipboard {10-14} @@ -442,14 +453,27 @@ pack: k8sHardening: True podCIDR: "192.168.0.0/16" serviceClusterIpRange: "10.96.0.0/12" - palette: - config: - dashboard: - identityProvider: palette cloud: maas: - customEndpoint: "maas-api.example.maas.org" + customEndpoint: "cluster-123.baremetal.company.com" + customEndpointPort: "6443" +``` + +In order to prevent the need for per-cluster profile adjustments which can become difficult to maintain at scale, we +recommend to use a system macro to automatically populate the cluster name. This approach allows the cluster profile to +dynamically populate the endpoint name without requiring the user to do it manually. The following snippet demonstrates +how to use macros for endpoint specification. + +```yaml hideClipboard {10-14} +pack: + k8sHardening: True + podCIDR: "192.168.0.0/16" + serviceClusterIpRange: "10.96.0.0/12" + +cloud: + maas: + customEndpoint: "{{ .spectro.system.cluster.name }}.baremetal.company.com" customEndpointPort: "6443" ``` @@ -794,14 +818,25 @@ In this example, Palette is used as the IDP, and all users in the `dev-east-2` w ![A subject of the type group is assigned as the subject in a RoleBinding](/clusters_cluster-management_cluster-rbac_cluster-subject-group.webp) -### Custom MAAS Endpoint +### Custom API Server Endpoint for MAAS Clusters -You can specify a custom MAAS endpoint and port that instructs Palette to direct all MAAS API requests to the provided -endpoint URL. Use the `cloud.maas.customEndpoint` and `cloud.maas.customEndpointPort` parameters to specify the custom -MAAS API URL and port. This is useful in scenarios where the MAAS API endpoint is not resolvable outside of the MAAS -network. +By default, Palette registers a DNS record in MAAS for the deployed cluster and links it to the IP addresses of the +control plane nodes of the cluster. However, you may choose not to depend on MAAS for your cluster DNS record. The +Kubernetes pack allows you to configure a custom API server endpoint for your cluster instead. This feature is only +supported in Palette eXtended Kubernetes (PXK). -The following example shows how to specify a custom MAAS endpoint and port in the Kubernetes YAML file. Make sure the +:::warning + +The custom API server endpoint must exist before the cluster gets deployed. Otherwise, your cluster deployment will fail +as components will not be able to connect to the cluster API endpoint. + +When you configure a custom endpoint, a DNS record will not be created in MAAS and the configured endpoint will be used +instead. If you use this option, you are responsible for ensuring the Full Qualified Domain Name (FQDN) of the endpoint +can be resolved by your DNS infrastructure and that it can connect to the API server port on your control plane nodes. + +::: + +The following snippet demonstrates how to specify a custom API server endpoint in the Kubernetes pack. Note that the `cloud.maas` section is at the same level as the `pack` section. ```yaml hideClipboard {10-14} @@ -809,14 +844,27 @@ pack: k8sHardening: True podCIDR: "192.168.0.0/16" serviceClusterIpRange: "10.96.0.0/12" - palette: - config: - dashboard: - identityProvider: palette cloud: maas: - customEndpoint: "maas-api.example.maas.org" + customEndpoint: "cluster-123.baremetal.company.com" + customEndpointPort: "6443" +``` + +In order to prevent the need for per-cluster profile adjustments which can become difficult to maintain at scale, we +recommend to use a system macro to automatically populate the cluster name. This approach allows the cluster profile to +dynamically populate the endpoint name without requiring the user to do it manually. The following snippet demonstrates +how to use macros for endpoint specification. + +```yaml hideClipboard {10-14} +pack: + k8sHardening: True + podCIDR: "192.168.0.0/16" + serviceClusterIpRange: "10.96.0.0/12" + +cloud: + maas: + customEndpoint: "{{ .spectro.system.cluster.name }}.baremetal.company.com" customEndpointPort: "6443" ``` diff --git a/docs/docs-content/clusters/data-center/maas/architecture.md b/docs/docs-content/clusters/data-center/maas/architecture.md index 43b637bc40..eef1787518 100644 --- a/docs/docs-content/clusters/data-center/maas/architecture.md +++ b/docs/docs-content/clusters/data-center/maas/architecture.md @@ -32,70 +32,18 @@ using Canonical MAAS. Refer to the PCG deployment options section below to learn
-## PCG Deployment Options +## Custom API Server Endpoint for MAAS Clusters -Palette can communicate with MAAS using the following deployment options. +By default, Palette registers a DNS record in MAAS for the deployed cluster and links it to the IP addresses of the +control plane nodes of the cluster. However, you may choose not to depend on MAAS for your cluster DNS record. The +Kubernetes pack allows you to configure a custom API server endpoint for your cluster instead. -
+ -- **Private Cloud Gateway** +This feature is only supported in Palette eXtended Kubernetes (PXK). Refer to the +section for further guidance. -- **System Private Gateway** - -### Private Cloud Gateway - -When a user wants to deploy a new cluster on a bare metal cloud using MAAS with Palette, Palette needs connectivity to -MAAS. Often, MAAS is behind a firewall or a Network Address Translation (NAT) gateway, and Palette needs help to reach -MAAS directly. - -To address these network challenges, you can deploy a PCG. The PCG will maintain a connection to Palette and directly -connect to MAAS. The direct communication channel allows Palette to create clusters using the PCG to facilitate -communication with MAAS. The PCG also supports using a proxy server to access the internet if needed. - -Once Palette deploys clusters, the clusters require connectivity to Palette. The clusters communicate with Palette -directly via an internet gateway, or if a proxy has been configured on the PCG, the clusters will inherit the proxy -configuration. Deployed and active clusters maintain their connectivity with Palette. Any actions taken on these -clusters using Palette will not require PCG's participation. This means that if the PCG becomes unavailable, any -clusters that are currently deployed will remain operational and still be managed by Palette. - -All Palette deployed clusters will use the PCG cluster during the creation and deletion phase. Once a host cluster is -available, the internal Palette agent will communicate with Palette directly. The Palette agent inside each cluster is -the originator of all communication, so the network requests are outbound toward Palette. The exception is a host -cluster creation or deletion request, where the PCG must be involved because it needs to acquire and release machines -provided by MAAS. - -Typically, the PCG is used with Palette SaaS. However, a PCG is also required if you have a self-hosted Palette instance -and it does not have direct access to the MAAS environment. You can utilize the System Private Gateway if there is -direct network connectivity access with the MAAS environment. Refer to the -[System Private Gateway](#system-private-gateway) section to learn more. - -
- -### System Private Gateway - -A System Private Gateway can be used if a self-hosted Palette instance can communicate directly with a MAAS -installation. A System Private Gateway is a PCG service that is enabled inside the self-hosted Palette instance. - -
- -:::warning - -Only self-hosted Palette instances support the option of using the System Private Gateway. Use the default -[PCG deployment](#private-cloud-gateway) option if you have NAT gateways or network firewalls between Palette and MAAS. - -::: - -
- -When registering a MAAS cloud account with Palette, toggle on **Use System Private Gateway** to enable direct -communication between Palette and MAAS. Refer to the -[Register and Manage MAAS Cloud Account](register-manage-maas-cloud-accounts.md) guide to learn more. - -The following table explains the different use cases for when a PCG and System Private Gateway are eligible. - -
- -| Scenario | Use Private Cloud Gateway | Use System Private Gateway | -| --------------------------------------------------------------- | ------------------------- | -------------------------- | -| Firewall or NAT between MAAS and a self-hosted Palette instance | ✅ | ❌ | -| Direct connectivity between MAAS and a Palette instance | ✅ | ✅ | + diff --git a/docs/docs-content/clusters/data-center/maas/create-manage-maas-clusters.md b/docs/docs-content/clusters/data-center/maas/create-manage-maas-clusters.md index 5bbc81b55e..f4271dfb78 100644 --- a/docs/docs-content/clusters/data-center/maas/create-manage-maas-clusters.md +++ b/docs/docs-content/clusters/data-center/maas/create-manage-maas-clusters.md @@ -29,6 +29,24 @@ create a Kubernetes cluster in MAAS that is managed by Palette. your MAAS environment. Review the [How to use standard images](https://maas.io/docs/how-to-use-standard-images) for guidance on downloading OS images for MAAS. +:::info + +By default, Palette registers a DNS record in MAAS for the deployed cluster and links it to the IP addresses of the +control plane nodes of the cluster. However, you may choose not to depend on MAAS for your cluster DNS record. The +Kubernetes pack allows you to configure a custom API server endpoint for your cluster instead. + + + +This feature is only supported in Palette eXtended Kubernetes (PXK). Refer to the +section for further guidance. + + + +::: + ## Deploy a MAAS Cluster To deploy a new MAAS cluster: diff --git a/docs/docs-content/integrations/kubernetes.md b/docs/docs-content/integrations/kubernetes.md index 88a6c4fe88..c1b26f1c1d 100644 --- a/docs/docs-content/integrations/kubernetes.md +++ b/docs/docs-content/integrations/kubernetes.md @@ -379,14 +379,25 @@ In this example, Palette is used as the IDP, and all users in the `dev-east-2` w ![A subject of the type group is assigned as the subject in a RoleBinding](/clusters_cluster-management_cluster-rbac_cluster-subject-group.webp) -### Custom MAAS Endpoint +### Custom API Server Endpoint for MAAS Clusters -You can specify a custom MAAS endpoint and port that instructs Palette to direct all MAAS API requests to the provided -endpoint URL. Use the `cloud.maas.customEndpoint` and `cloud.maas.customEndpointPort` parameters to specify the custom -MAAS API URL and port. This is useful in scenarios where the MAAS API endpoint is not resolvable outside of the MAAS -network. +By default, Palette registers a DNS record in MAAS for the deployed cluster and links it to the IP addresses of the +control plane nodes of the cluster. However, you may choose not to depend on MAAS for your cluster DNS record. The +Kubernetes pack allows you to configure a custom API server endpoint for your cluster instead. This feature is only +supported in Palette eXtended Kubernetes (PXK). -The following example shows how to specify a custom MAAS endpoint and port in the Kubernetes YAML file. Make sure the +:::warning + +The custom API server endpoint must exist before the cluster gets deployed. Otherwise, your cluster deployment will fail +as components will not be able to connect to the cluster API endpoint. + +When you configure a custom endpoint, a DNS record will not be created in MAAS and the configured endpoint will be used +instead. If you use this option, you are responsible for ensuring the Full Qualified Domain Name (FQDN) of the endpoint +can be resolved by your DNS infrastructure and that it can connect to the API server port on your control plane nodes. + +::: + +The following snippet demonstrates how to specify a custom API server endpoint in the Kubernetes pack. Note that the `cloud.maas` section is at the same level as the `pack` section. ```yaml hideClipboard {10-14} @@ -394,14 +405,27 @@ pack: k8sHardening: True podCIDR: "192.168.0.0/16" serviceClusterIpRange: "10.96.0.0/12" - palette: - config: - dashboard: - identityProvider: palette cloud: maas: - customEndpoint: "maas-api.example.maas.org" + customEndpoint: "cluster-123.baremetal.company.com" + customEndpointPort: "6443" +``` + +In order to prevent the need for per-cluster profile adjustments which can become difficult to maintain at scale, we +recommend to use a system macro to automatically populate the cluster name. This approach allows the cluster profile to +dynamically populate the endpoint name without requiring the user to do it manually. The following snippet demonstrates +how to use macros for endpoint specification. + +```yaml hideClipboard {10-14} +pack: + k8sHardening: True + podCIDR: "192.168.0.0/16" + serviceClusterIpRange: "10.96.0.0/12" + +cloud: + maas: + customEndpoint: "{{ .spectro.system.cluster.name }}.baremetal.company.com" customEndpointPort: "6443" ``` @@ -712,6 +736,56 @@ In this example, Palette is used as the IDP, and all users in the `dev-east-2` w ![A subject of the type group is assigned as the subject in a RoleBinding](/clusters_cluster-management_cluster-rbac_cluster-subject-group.webp) +### Custom API Server Endpoint for MAAS Clusters + +By default, Palette registers a DNS record in MAAS for the deployed cluster and links it to the IP addresses of the +control plane nodes of the cluster. However, you may choose not to depend on MAAS for your cluster DNS record. The +Kubernetes pack allows you configure a custom API server endpoint for your cluster instead. This feature is only +supported in Palette eXtended Kubernetes (PXK). + +:::warning + +The custom API server endpoint must exist before the cluster gets deployed. Otherwise, your cluster deployment will fail +as components will not be able to connect to the cluster API endpoint. + +When you configure a custom endpoint, a DNS record will not be created in MAAS and the configured endpoint will be used +instead. If you use this option, you are responsible for ensuring the Full Qualified Domain Name (FQDN) of the endpoint +can be resolved by your DNS infrastructure and that it can connect to the API server port on your control plane nodes. + +::: + +The following snippet demonstrates how to specify a custom API server endpoint in the Kubernetes pack. Note that the +`cloud.maas` section is at the same level as the `pack` section. + +```yaml hideClipboard {10-14} +pack: + k8sHardening: True + podCIDR: "192.168.0.0/16" + serviceClusterIpRange: "10.96.0.0/12" + +cloud: + maas: + customEndpoint: "cluster-123.baremetal.company.com" + customEndpointPort: "6443" +``` + +In order to prevent the need for per-cluster profile adjustments which can become difficult to maintain at scale, we +recommend to use a system macro to automatically populate the cluster name. This approach allows the cluster profile to +dynamically populate the endpoint name without requiring the user to do it manually. The following snippet demonstrates +how to use macros for endpoint specification. + +```yaml hideClipboard {10-14} +pack: + k8sHardening: True + podCIDR: "192.168.0.0/16" + serviceClusterIpRange: "10.96.0.0/12" + +cloud: + maas: + customEndpoint: "{{ .spectro.system.cluster.name }}.baremetal.company.com" + customEndpointPort: "6443" +``` + From 0a269153a6e34ff7602ca81e0680c1c3e701e403 Mon Sep 17 00:00:00 2001 From: addetz <43963729+addetz@users.noreply.github.com> Date: Fri, 18 Oct 2024 15:59:42 +0100 Subject: [PATCH 2/2] docs: undo accidental text deletion --- .../clusters/data-center/maas/architecture.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/docs/docs-content/clusters/data-center/maas/architecture.md b/docs/docs-content/clusters/data-center/maas/architecture.md index eef1787518..1c8d3fb94f 100644 --- a/docs/docs-content/clusters/data-center/maas/architecture.md +++ b/docs/docs-content/clusters/data-center/maas/architecture.md @@ -32,6 +32,74 @@ using Canonical MAAS. Refer to the PCG deployment options section below to learn
+## PCG Deployment Options + +Palette can communicate with MAAS using the following deployment options. + +
+ +- **Private Cloud Gateway** + +- **System Private Gateway** + +### Private Cloud Gateway + +When a user wants to deploy a new cluster on a bare metal cloud using MAAS with Palette, Palette needs connectivity to +MAAS. Often, MAAS is behind a firewall or a Network Address Translation (NAT) gateway, and Palette needs help to reach +MAAS directly. + +To address these network challenges, you can deploy a PCG. The PCG will maintain a connection to Palette and directly +connect to MAAS. The direct communication channel allows Palette to create clusters using the PCG to facilitate +communication with MAAS. The PCG also supports using a proxy server to access the internet if needed. + +Once Palette deploys clusters, the clusters require connectivity to Palette. The clusters communicate with Palette +directly via an internet gateway, or if a proxy has been configured on the PCG, the clusters will inherit the proxy +configuration. Deployed and active clusters maintain their connectivity with Palette. Any actions taken on these +clusters using Palette will not require PCG's participation. This means that if the PCG becomes unavailable, any +clusters that are currently deployed will remain operational and still be managed by Palette. + +All Palette deployed clusters will use the PCG cluster during the creation and deletion phase. Once a host cluster is +available, the internal Palette agent will communicate with Palette directly. The Palette agent inside each cluster is +the originator of all communication, so the network requests are outbound toward Palette. The exception is a host +cluster creation or deletion request, where the PCG must be involved because it needs to acquire and release machines +provided by MAAS. + +Typically, the PCG is used with Palette SaaS. However, a PCG is also required if you have a self-hosted Palette instance +and it does not have direct access to the MAAS environment. You can utilize the System Private Gateway if there is +direct network connectivity access with the MAAS environment. Refer to the +[System Private Gateway](#system-private-gateway) section to learn more. + +
+ +### System Private Gateway + +A System Private Gateway can be used if a self-hosted Palette instance can communicate directly with a MAAS +installation. A System Private Gateway is a PCG service that is enabled inside the self-hosted Palette instance. + +
+ +:::warning + +Only self-hosted Palette instances support the option of using the System Private Gateway. Use the default +[PCG deployment](#private-cloud-gateway) option if you have NAT gateways or network firewalls between Palette and MAAS. + +::: + +
+ +When registering a MAAS cloud account with Palette, toggle on **Use System Private Gateway** to enable direct +communication between Palette and MAAS. Refer to the +[Register and Manage MAAS Cloud Account](register-manage-maas-cloud-accounts.md) guide to learn more. + +The following table explains the different use cases for when a PCG and System Private Gateway are eligible. + +
+ +| Scenario | Use Private Cloud Gateway | Use System Private Gateway | +| --------------------------------------------------------------- | ------------------------- | -------------------------- | +| Firewall or NAT between MAAS and a self-hosted Palette instance | ✅ | ❌ | +| Direct connectivity between MAAS and a Palette instance | ✅ | ✅ | + ## Custom API Server Endpoint for MAAS Clusters By default, Palette registers a DNS record in MAAS for the deployed cluster and links it to the IP addresses of the