Rewrote MAAS custom endpoint docs

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"
 ```
 

docs/docs-content/clusters/data-center/maas/architecture.md

@@ -33,9 +33,18 @@ using Canonical MAAS. Refer to the PCG deployment options section below to learn
 
 Refer to the [PCG Architecture](../../pcg/architecture.md) section to learn more about the PCG architecture.
 
-## Custom MAAS Endpoint
+## Custom API Server Endpoint for MAAS Clusters
 
-If the MAAS API server URL is not resolvable outside of the MAAS environment, you can specify a different URL in the
-cluster profile's Kubernetes YAML. This feature is only supported in Palette eXtented Kubernetes (PKX). For more
-information, refer to the [Custom MAAS Endpoint](../../../integrations/kubernetes.md#custom-maas-endpoint) section of
-the PXK reference page.
+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 -->

docs/docs-content/clusters/data-center/maas/create-manage-maas-clusters.md

@@ -29,12 +29,21 @@ 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.
 
-:::warning
+:::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.
 
-If the MAAS API server URL is not resolvable outside of the MAAS environment, you can specify a different URL in the
-cluster profile's Kubernetes YAML. This feature is only supported in Palette eXtented Kubernetes (PXK). For more
-information, refer to the [Custom MAAS Endpoint](../../../integrations/kubernetes.md#custom-maas-endpoint) section of
-the PXK reference page.
+<!-- prettier-ignore-end -->
 
 :::
 

docs/docs-content/integrations/kubernetes.md

@@ -402,29 +402,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"
 ```
 
@@ -735,29 +759,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 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"
 ```