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 <[email protected]> --------- Co-authored-by: kreeuwijk <[email protected]> Co-authored-by: addetz <[email protected]> Co-authored-by: caroldelwing <[email protected]>
spectrocloud · Oct 18, 2024 · 3b2db86 · 3b2db86
1 parent c8db9a4
commit 3b2db86
Show file tree

Hide file tree

Showing 4 changed files with 184 additions and 96 deletions.
diff --git a/docs/deprecated/integrations/kubernetes.md b/docs/deprecated/integrations/kubernetes.md
@@ -427,29 +427,53 @@ 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}
 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,29 +818,53 @@ 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}
 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
@@ -32,70 +32,18 @@ using Canonical MAAS. Refer to the PCG deployment options section below to learn
 
   <br />
 
-## 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.
 
-<br />
+<!-- prettier-ignore-start -->
 
-- **Private Cloud Gateway**
+This feature is only supported in Palette eXtended Kubernetes (PXK). Refer to the <VersionedLink
+  text="Custom API Server Endpoint for MAAS Clusters"
+  url="/integrations/packs/?pack=kubernetes#custom-api-server-endpoint-for-maas-clusters"
+/>
+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.
-
-<br />
-
-### 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.
-
-<br />
-
-:::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.
-
-:::
-
-<br />
-
-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.
-
-<br />
-
-| 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         | ✅                        | ✅                         |
+<!-- prettier-ignore-end -->
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
@@ -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.
+
+<!-- prettier-ignore-start -->
+
+This feature is only supported in Palette eXtended Kubernetes (PXK). Refer to the <VersionedLink
+  text="Custom API Server Endpoint for MAAS Clusters"
+  url="/integrations/packs/?pack=kubernetes#custom-api-server-endpoint-for-maas-clusters"
+/>
+section for further guidance.
+
+<!-- prettier-ignore-end -->
+
+:::
+
 ## 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
@@ -379,29 +379,53 @@ 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}
 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"
+```
+
 </TabItem>
 
 <TabItem label="1.27.x" value="k8s_v1.27">