docs: edit text to match docs style guidelines

spectrocloud · Oct 18, 2024 · 42913b2 · 42913b2
1 parent d416463
commit 42913b2
Show file tree

Hide file tree

Showing 4 changed files with 90 additions and 94 deletions.
diff --git a/docs/deprecated/integrations/kubernetes.md b/docs/deprecated/integrations/kubernetes.md
@@ -427,29 +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 API server endpoint for MAAS clusters
+### Custom API Server Endpoint for MAAS Clusters
 
-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).
-
-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)
+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
 
-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 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 example shows how to specify a custom API server endpoint in the Kubernetes pack. Make sure the
+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}
@@ -464,8 +460,10 @@ cloud:
     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:
+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:
@@ -479,8 +477,6 @@ cloud:
     customEndpointPort: "6443"
 ```
 
-That way the profile can dynamically populate the endpoint name, without requiring the user to do it manually.
-
 </TabItem>
 
 <TabItem label="1.28.x" value="k8s_v1.28">
@@ -822,29 +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 API server endpoint for MAAS clusters
+### Custom API Server Endpoint for MAAS Clusters
 
-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).
-
-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)
+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
 
-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 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 example shows how to specify a custom API server endpoint in the Kubernetes pack. Make sure the
+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}
@@ -859,8 +851,10 @@ cloud:
     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:
+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:
@@ -874,8 +868,6 @@ cloud:
     customEndpointPort: "6443"
 ```
 
-That way the profile can dynamically populate the endpoint name, without requiring the user to do it manually.
-
 </TabItem>
 
 <TabItem label="1.27.x" value="k8s_v1.27">

diff --git a/docs/docs-content/clusters/data-center/maas/architecture.md b/docs/docs-content/clusters/data-center/maas/architecture.md
@@ -33,12 +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 API server endpoint for MAAS clusters
+## Custom API Server Endpoint for MAAS Clusters
 
-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.
+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 (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.
+<!-- 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 -->
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,15 +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 configure a custom API server endpoint for your cluster instead.
+
+<!-- prettier-ignore-start -->
 
-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). 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.
 
-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.
+<!-- prettier-ignore-end -->
 
 :::
 

diff --git a/docs/docs-content/integrations/kubernetes.md b/docs/docs-content/integrations/kubernetes.md
@@ -402,29 +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 API server endpoint for MAAS clusters
+### Custom API Server Endpoint for MAAS Clusters
 
-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).
-
-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)
+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
 
-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 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 example shows how to specify a custom API server endpoint in the Kubernetes pack. Make sure the
+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}
@@ -439,8 +435,10 @@ cloud:
     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:
+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:
@@ -454,8 +452,6 @@ cloud:
     customEndpointPort: "6443"
 ```
 
-That way the profile can dynamically populate the endpoint name, without requiring the user to do it manually.
-
 </TabItem>
 
 <TabItem label="1.28.x" value="k8s_v1.28">
@@ -763,29 +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 API server endpoint for MAAS clusters
+### Custom API Server Endpoint for MAAS Clusters
 
-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).
-
-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)
+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
 
-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 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 example shows how to specify a custom API server endpoint in the Kubernetes pack. Make sure the
+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}
@@ -800,8 +792,10 @@ cloud:
     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:
+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:
@@ -815,8 +809,6 @@ cloud:
     customEndpointPort: "6443"
 ```
 
-That way the profile can dynamically populate the endpoint name, without requiring the user to do it manually.
-
 </TabItem>
 
 <TabItem label="1.27.x" value="k8s_v1.27">