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..1c8d3fb94f 100644 --- a/docs/docs-content/clusters/data-center/maas/architecture.md +++ b/docs/docs-content/clusters/data-center/maas/architecture.md @@ -99,3 +99,19 @@ The following table explains the different use cases for when a PCG and System P | --------------------------------------------------------------- | ------------------------- | -------------------------- | | 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 +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 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" +``` +