From 4c2ba1816c9a3f1136e6aec41e30ca3b0febd89c Mon Sep 17 00:00:00 2001 From: Kevin Reeuwijk Date: Fri, 18 Oct 2024 16:18:49 +0200 Subject: [PATCH] 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 (cherry picked from commit 43fd77c5388588483ff26ceb55aa1fd9e6b5f578) --- docs/deprecated/integrations/kubernetes.md | 92 ++++++++++++++----- .../clusters/data-center/maas/architecture.md | 19 +++- .../maas/create-manage-maas-clusters.md | 19 +++- docs/docs-content/integrations/kubernetes.md | 92 ++++++++++++++----- 4 files changed, 168 insertions(+), 54 deletions(-) diff --git a/docs/deprecated/integrations/kubernetes.md b/docs/deprecated/integrations/kubernetes.md index 4a9bb53c2a..66863eabcb 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 31c5235e90..4a43f4bab5 100644 --- a/docs/docs-content/clusters/data-center/maas/architecture.md +++ b/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. + + + +This feature is only supported in Palette eXtended Kubernetes (PXK). Refer to the +section for further guidance. + + 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 32d7c0bc0f..77a4e3416f 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,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. + + + +This feature is only supported in Palette eXtended Kubernetes (PXK). Refer to the +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. + ::: diff --git a/docs/docs-content/integrations/kubernetes.md b/docs/docs-content/integrations/kubernetes.md index 68f2388e46..7bfd1bb086 100644 --- a/docs/docs-content/integrations/kubernetes.md +++ b/docs/docs-content/integrations/kubernetes.md @@ -402,14 +402,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} @@ -417,14 +428,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" ``` @@ -735,14 +759,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 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} @@ -750,14 +785,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" ```