Skip to content

Commit

Permalink
[version-4-3] Rewrote MAAS custom endpoint docs (#4302) (#4335)
Browse files Browse the repository at this point in the history 
* 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 <carolina.delwing@spectrocloud.com>

---------

Co-authored-by: kreeuwijk <kreeuwijk@users.noreply.github.com>
Co-authored-by: addetz <43963729+addetz@users.noreply.github.com>
Co-authored-by: caroldelwing <carolina.delwing@spectrocloud.com>
(cherry picked from commit 43fd77c)

* docs: fix broken link in release notes

---------

Co-authored-by: Kevin Reeuwijk <kevin.reeuwijk@spectrocloud.com>
Co-authored-by: addetz <43963729+addetz@users.noreply.github.com>
  • Loading branch information
@vault-token-factory-spectrocloud @kreeuwijk @addetz
3 people authored Oct 18, 2024
1 parent c1b1f3e commit 5d6cee0
Show file tree
Hide file tree
Showing 5 changed files with 173 additions and 55 deletions.
92 changes: 70 additions & 22 deletions docs/deprecated/integrations/kubernetes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
```

Expand Down Expand Up @@ -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"
```

Expand Down
19 changes: 14 additions & 5 deletions docs/docs-content/clusters/data-center/maas/architecture.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
19 changes: 14 additions & 5 deletions docs/docs-content/clusters/data-center/maas/create-manage-maas-clusters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->

:::

Expand Down
92 changes: 70 additions & 22 deletions docs/docs-content/integrations/kubernetes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
```

Expand Down Expand Up @@ -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"
```

Expand Down
6 changes: 5 additions & 1 deletion docs/docs-content/release-notes/release-notes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,15 @@ the following sections for a complete list of features, improvements, and known
Check out [Cluster Profile Variables](../profiles/cluster-profiles/create-cluster-profiles/define-profile-variables.md) to learn more about
profile variables.

<!-- prettier-ignore-start -->

- MAAS clusters using Palette eXtended Kubernetes (PXK) now support the ability to specify a custom MAAS API endpoint
URL and port during cluster creation. This feature allows you to use a custom DNS server or Virtual IP (VIP) that is
not resolvable outside of the MAAS network. Refer to the [PXK](../integrations/kubernetes.md#custom-maas-endpoint)
not resolvable outside of the MAAS network. Refer to the <VersionedLink text="PXK" url="/integrations/packs/?pack=kubernetes#custom-api-server-endpoint-for-maas-clusters"/>
documentation for more details.

<!-- prettier-ignore-end -->

- Support for <VersionedLink text="Konvoy" url="/integrations/packs/?pack=kubernetes-konvoy"/> is now available in Palette. You can create a custom image using the
Konvoy image builder project and use it to deploy a Konvoy cluster. Check out the
[Red Hat Linux Enterprise and Konvoy](../byoos/usecases/vmware/konvoy.md) guide to learn how to create a custom image
Expand Down

0 comments on commit 5d6cee0

Please sign in to comment.