diff --git a/docs/api/extension-apiserver.md b/docs/api/extension-apiserver.md index 8f8786bd328..b80de8af261 100644 --- a/docs/api/extension-apiserver.md +++ b/docs/api/extension-apiserver.md @@ -8,8 +8,12 @@ title: Extension API Server Rancher extends Kubernetes with additional APIs by registering an extension API server using the [Kubernetes API Aggregation Layer](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/). -## Disabling the extension API server +## Aggregation Layer is Required -The [aggregation layer must be configured](https://kubernetes.io/docs/tasks/extend-kubernetes/configure-aggregation-layer/) on the local Kubernetes cluster for the `imperative-api-extension` feature to be enabled and to work correctly. The feature assumes this is configured and is enabled by default. If it is not possible to configure the aggregation layer for your local Kubernetes cluster, then you must disable the feature. The `imperative-api-extension` feature flag can be disabled by either using the [Rancher UI](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md#disabling-features-with-the-rancher-ui) or [Rancher API](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md#disabling-features-with-the-rancher-api). +The API aggregation layer must be configured on the local Kubernetes cluster for the `v1.ext.cattle.io` `APIService` to work correctly. If the `APIService` does not receive a registration request after the Rancher server starts, the pod will crash with a log entry indicating the error. If your pods are consistently failing to detect registration despite having a correctly configured cluster, you can increase the timeout by setting the `.Values.aggregationRegistrationTimeout` in Helm. -It will still be possible to access the additional APIs when the feature is disabled. The additional APIs are available at `https:///ext` and they are compatible with the Kubernetes apiserver. This means you can use `curl` or `kubectl` to interact with the APIs. +All versions of Kubernetes supported by Rancher with the feature will have the aggregation layer configured by default. However, if you suspect that your cluster configuration is incorrect, refer to the [Kubernetes Aggregation Layer documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/configure-aggregation-layer/) for information on configuring the aggregation layer. + +:::note +If the underlying Kubernetes distribution does not support the aggregation layer, you must migrate to a Kubernetes distribution that does before upgrading. +::: \ No newline at end of file diff --git a/docs/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md b/docs/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md index 878db7c657b..609e50db399 100644 --- a/docs/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md +++ b/docs/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md @@ -23,6 +23,8 @@ See our page on [best practices](../../../reference-guides/best-practices/ranche Rancher needs to be installed on a supported Kubernetes version. Consult the [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) to ensure that your intended version of Kubernetes is supported. +Regardless of version and distrobution, the kubernetes cluster must have the aggregation api layer properlly configured to support the [extension api](../../../api/extension-apiserver.md) used by rancher. + ### Install Rancher on a Hardened Kubernetes cluster If you install Rancher on a hardened Kubernetes cluster, check the [Exempting Required Rancher Namespaces](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md#exempting-required-rancher-namespaces) section for detailed requirements. diff --git a/versioned_docs/version-2.12/api/extension-apiserver.md b/versioned_docs/version-2.12/api/extension-apiserver.md index 8f8786bd328..b80de8af261 100644 --- a/versioned_docs/version-2.12/api/extension-apiserver.md +++ b/versioned_docs/version-2.12/api/extension-apiserver.md @@ -8,8 +8,12 @@ title: Extension API Server Rancher extends Kubernetes with additional APIs by registering an extension API server using the [Kubernetes API Aggregation Layer](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/). -## Disabling the extension API server +## Aggregation Layer is Required -The [aggregation layer must be configured](https://kubernetes.io/docs/tasks/extend-kubernetes/configure-aggregation-layer/) on the local Kubernetes cluster for the `imperative-api-extension` feature to be enabled and to work correctly. The feature assumes this is configured and is enabled by default. If it is not possible to configure the aggregation layer for your local Kubernetes cluster, then you must disable the feature. The `imperative-api-extension` feature flag can be disabled by either using the [Rancher UI](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md#disabling-features-with-the-rancher-ui) or [Rancher API](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md#disabling-features-with-the-rancher-api). +The API aggregation layer must be configured on the local Kubernetes cluster for the `v1.ext.cattle.io` `APIService` to work correctly. If the `APIService` does not receive a registration request after the Rancher server starts, the pod will crash with a log entry indicating the error. If your pods are consistently failing to detect registration despite having a correctly configured cluster, you can increase the timeout by setting the `.Values.aggregationRegistrationTimeout` in Helm. -It will still be possible to access the additional APIs when the feature is disabled. The additional APIs are available at `https:///ext` and they are compatible with the Kubernetes apiserver. This means you can use `curl` or `kubectl` to interact with the APIs. +All versions of Kubernetes supported by Rancher with the feature will have the aggregation layer configured by default. However, if you suspect that your cluster configuration is incorrect, refer to the [Kubernetes Aggregation Layer documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/configure-aggregation-layer/) for information on configuring the aggregation layer. + +:::note +If the underlying Kubernetes distribution does not support the aggregation layer, you must migrate to a Kubernetes distribution that does before upgrading. +::: \ No newline at end of file diff --git a/versioned_docs/version-2.12/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md b/versioned_docs/version-2.12/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md index 878db7c657b..609e50db399 100644 --- a/versioned_docs/version-2.12/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md +++ b/versioned_docs/version-2.12/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md @@ -23,6 +23,8 @@ See our page on [best practices](../../../reference-guides/best-practices/ranche Rancher needs to be installed on a supported Kubernetes version. Consult the [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) to ensure that your intended version of Kubernetes is supported. +Regardless of version and distrobution, the kubernetes cluster must have the aggregation api layer properlly configured to support the [extension api](../../../api/extension-apiserver.md) used by rancher. + ### Install Rancher on a Hardened Kubernetes cluster If you install Rancher on a hardened Kubernetes cluster, check the [Exempting Required Rancher Namespaces](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md#exempting-required-rancher-namespaces) section for detailed requirements.