Skip to content

Commit

Permalink
Rewrote MAAS custom endpoint docs (#4302)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>

---------

Co-authored-by: kreeuwijk <[email protected]>
Co-authored-by: addetz <[email protected]>
Co-authored-by: caroldelwing <[email protected]>
  • Loading branch information
@kreeuwijk @addetz @caroldelwing
4 people committed Oct 18, 2024
1 parent 59c2085 commit f679f06
Show file tree
Hide file tree
Showing 4 changed files with 189 additions and 33 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
16 changes: 16 additions & 0 deletions docs/docs-content/clusters/data-center/maas/architecture.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,19 @@ using Canonical MAAS. Refer to the PCG deployment options section below to learn
![Network flow from an architectural perspective of how MAAS works with Palette](/maas_cluster_architecture.webp)

Refer to the [PCG Architecture](../../pcg/architecture.md) section to learn more about the PCG architecture.

## 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.

<!-- 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 -->
18 changes: 18 additions & 0 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,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.

<!-- 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 -->

:::

## Deploy a MAAS Cluster

To deploy a new MAAS cluster:
Expand Down
96 changes: 85 additions & 11 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,6 +759,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"
```

</TabItem>

<TabItem label="1.27.x" value="k8s_v1.27">
Expand Down

0 comments on commit f679f06

Please sign in to comment.