diff --git a/docs/deprecated/integrations/kubernetes.md b/docs/deprecated/integrations/kubernetes.md index 4a9bb53c2a..6ba52313c2 100644 --- a/docs/deprecated/integrations/kubernetes.md +++ b/docs/deprecated/integrations/kubernetes.md @@ -427,14 +427,23 @@ 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 will register a DNS record in MAAS for the deployed cluster, linking it to the IP address(es) of the control plane node(s) of the cluster. However you may not want to depend on MAAS for your cluster DNS record. The Kubernetes pack provides an option 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 +When you configure this option, 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 endpoint FQDN can be resolved by your DNS infrastructure +* Ensuring the endpoint connects to the API server port on your control plane node(s), by either: + * pointing directly to the IP address(es) of your control plane node(s), or + * pointing to a load balancer that balances traffic to your control plane node(s) + +:::warning + +This endpoint must exist before the cluster gets deployed, otherwise deployment will fail as components will not be able to connect to the cluster API endpoint. + +::: + +The following example shows how to specify a custom API server endpoint in the Kubernetes pack. Make sure the `cloud.maas` section is at the same level as the `pack` section. ```yaml hideClipboard {10-14} @@ -442,17 +451,29 @@ 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 needing per-cluster profile adjustments (which can become difficult to deal with at scale), it is recommend to use a system macro to automatically populate the cluster name: + +```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" +``` + +That way the profile can dynamically populate the endpoint name, without requiring the user to do it manually. + @@ -794,14 +815,23 @@ 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 will register a DNS record in MAAS for the deployed cluster, linking it to the IP address(es) of the control plane node(s) of the cluster. However you may not want to depend on MAAS for your cluster DNS record. The Kubernetes pack provides an option 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 +When you configure this option, 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 endpoint FQDN can be resolved by your DNS infrastructure +* Ensuring the endpoint connects to the API server port on your control plane node(s), by either: + * pointing directly to the IP address(es) of your control plane node(s), or + * pointing to a load balancer that balances traffic to your control plane node(s) + +:::warning + +This endpoint must exist before the cluster gets deployed, otherwise deployment will fail as components will not be able to connect to the cluster API endpoint. + +::: + +The following example shows how to specify a custom API server endpoint in the Kubernetes pack. Make sure the `cloud.maas` section is at the same level as the `pack` section. ```yaml hideClipboard {10-14} @@ -809,17 +839,29 @@ 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 needing per-cluster profile adjustments (which can become difficult to deal with at scale), it is recommend to use a system macro to automatically populate the cluster name: + +```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" +``` + +That way the profile can dynamically populate the endpoint name, without requiring the user to do it manually. + diff --git a/docs/docs-content/clusters/data-center/maas/architecture.md b/docs/docs-content/clusters/data-center/maas/architecture.md index 31c5235e90..18c353ac2f 100644 --- a/docs/docs-content/clusters/data-center/maas/architecture.md +++ b/docs/docs-content/clusters/data-center/maas/architecture.md @@ -33,9 +33,10 @@ 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 +By default, Palette will register a DNS record in MAAS for the deployed cluster, linking it to the IP address(es) of the control plane node(s) of the cluster. However you may not want to depend on MAAS for your cluster DNS record. The Kubernetes pack provides an option to configure a custom API server endpoint for your cluster instead. + +This feature is only supported in Palette eXtended Kubernetes (PKX). For more +information, refer to the [Custom API server endpoint for MAAS clusters](../../../integrations/kubernetes.md#custom-api-server-endpoint-for-maas-clusters) section of the PXK reference page. 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..3963a39df8 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 @@ -31,9 +31,10 @@ create a Kubernetes cluster in MAAS that is managed by Palette. :::warning -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 +By default, Palette will register a DNS record in MAAS for the deployed cluster, linking it to the IP address(es) of the control plane node(s) of the cluster. However you may not want to depend on MAAS for your cluster DNS record. The Kubernetes pack provides an option to configure a custom API server endpoint for your cluster instead. + +This feature is only supported in Palette eXtended Kubernetes (PXK). For more +information, refer to the [Custom API server endpoint for MAAS clusters](../../../integrations/kubernetes.md#custom-api-server-endpoint-for-maas-clusters) section of the PXK reference page. ::: diff --git a/docs/docs-content/integrations/kubernetes.md b/docs/docs-content/integrations/kubernetes.md index 68f2388e46..c8a222c13f 100644 --- a/docs/docs-content/integrations/kubernetes.md +++ b/docs/docs-content/integrations/kubernetes.md @@ -402,14 +402,23 @@ 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 will register a DNS record in MAAS for the deployed cluster, linking it to the IP address(es) of the control plane node(s) of the cluster. However you may not want to depend on MAAS for your cluster DNS record. The Kubernetes pack provides an option 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 +When you configure this option, 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 endpoint FQDN can be resolved by your DNS infrastructure +* Ensuring the endpoint connects to the API server port on your control plane node(s), by either: + * pointing directly to the IP address(es) of your control plane node(s), or + * pointing to a load balancer that balances traffic to your control plane node(s) + +:::warning + +This endpoint must exist before the cluster gets deployed, otherwise deployment will fail as components will not be able to connect to the cluster API endpoint. + +::: + +The following example shows how to specify a custom API server endpoint in the Kubernetes pack. Make sure the `cloud.maas` section is at the same level as the `pack` section. ```yaml hideClipboard {10-14} @@ -417,17 +426,29 @@ 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 needing per-cluster profile adjustments (which can become difficult to deal with at scale), it is recommend to use a system macro to automatically populate the cluster name: + +```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" +``` + +That way the profile can dynamically populate the endpoint name, without requiring the user to do it manually. + @@ -735,14 +756,23 @@ 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 will register a DNS record in MAAS for the deployed cluster, linking it to the IP address(es) of the control plane node(s) of the cluster. However you may not want to depend on MAAS for your cluster DNS record. The Kubernetes pack provides an option 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 +When you configure this option, 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 endpoint FQDN can be resolved by your DNS infrastructure +* Ensuring the endpoint connects to the API server port on your control plane node(s), by either: + * pointing directly to the IP address(es) of your control plane node(s), or + * pointing to a load balancer that balances traffic to your control plane node(s) + +:::warning + +This endpoint must exist before the cluster gets deployed, otherwise deployment will fail as components will not be able to connect to the cluster API endpoint. + +::: + +The following example shows how to specify a custom API server endpoint in the Kubernetes pack. Make sure the `cloud.maas` section is at the same level as the `pack` section. ```yaml hideClipboard {10-14} @@ -750,17 +780,29 @@ 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 needing per-cluster profile adjustments (which can become difficult to deal with at scale), it is recommend to use a system macro to automatically populate the cluster name: + +```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" +``` + +That way the profile can dynamically populate the endpoint name, without requiring the user to do it manually. +