Use Kubernetes beta APIs to access new features in your Google Kubernetes Engine (GKE) clusters. To use beta APIs introduced with version 1.24 or later, configure beta APIs.
How new features are introduced with the Kubernetes API
GKE clusters consist of a control plane and worker nodes. The control plane exposes the API server, which exposes the Kubernetes API so that end users, along with internal and external components, can communicate. This API evolves over time, with new features being introduced in Alpha or Beta stages, and then eventually either graduating to General Availability (GA) or being deprecated and removed in newer minor versions.
You can only use alpha APIs with alpha clusters, but you can use beta APIs with all types of GKE clusters. Starting with Kubernetes version 1.24, new beta APIs are, by default, disabled in new clusters. Existing clusters created running a version earlier than 1.24 keep existing beta APIs enabled, as automatically enabled (introduced earlier than 1.24) or manually enabled beta APIs (introduced 1.24 or later) cannot be disabled on existing clusters. For all clusters, existing beta APIs introduced before version 1.24 remain enabled by default, and new versions of existing beta APIs also remain enabled by default.
For example, if a v1beta1 API was introduced in Kubernetes version 1.22, then
a new version of this beta API, such as v1beta3, is introduced in Kubernetes
version 1.25, the API is automatically enabled. This happens because it is a new
version of an existing beta API, not a completely new beta API. However, a new
beta API with the v1beta1 version introduced in Kubernetes version 1.24 or
later is disabled by default.
To use beta APIs introduced with version 1.24 and later, you must configure beta APIs per resource per cluster. You can enable APIs on cluster creation or for an existing cluster. To see what beta APIs are available for your cluster's minor version, refer to the available beta APIs.
After you enable a beta API, it remains enabled until the beta API is deprecated and the cluster is upgraded to the minor version where the API is removed. To see which beta APIs your cluster has enabled, see Check which beta APIs are enabled.
Available beta APIs
You can enable a subset of Kubernetes beta APIs for your GKE clusters. Other beta APIs are not available for reasons such as the following:
- The beta API relies on non-GA Kubernetes features.
- The beta API is not secure.
- The beta API is not Autopilot compatible.
Refer to the following table for beta APIs and the corresponding minor version where they were introduced:
| Kubernetes version | Beta APIs added with this Kubernetes minor version | Available with GKE | Notes |
|---|---|---|---|
| 1.31 |
|
|
You must enable both |
| 1.29 |
|
|
You must enable both APIs at the same time. This enables the Validating Admission Policy beta feature. |
| 1.28 |
|
|
|
| 1.27 |
|
|
Considerations before using beta APIs
Kubernetes beta APIs are subject to the Kubernetes Deprecation Policy. When a beta API is deprecated, you must discontinue usage of it. To learn more, see Beta API deprecations.
Before you begin
Before you start, make sure you have performed the following tasks:
- Enable the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- If you want to use the Google Cloud CLI for this task,
install and then
initialize the
gcloud CLI. If you previously installed the gcloud CLI, get the latest
version by running
gcloud components update.
Configure beta APIs
Beta APIs are enabled per resource per cluster. You can enable APIs when you create a cluster or for an existing cluster.
To list a beta API resource for these commands, use the representation
{group}/{version}/{resource}. The version must be a beta version. An example of
this valid representation is authentication.k8s.io/v1beta1/selfsubjectreviews.
For the commands in the next section, replace the following variables:
CLUSTER_NAME: the name of the cluster you want to update.LIST_OF_APIS: the list of beta APIs you want to enable, in a comma-separated list.COMPUTE_REGION: the Compute Engine region for the new cluster. For zonal clusters, use--zone=COMPUTE_ZONE.
Create new cluster with beta APIs enabled
Create a new cluster with a list of beta APIs enabled:
gcloud container clusters create-auto CLUSTER_NAME \
--enable-kubernetes-unstable-apis=LIST_OF_APIS \
--region=COMPUTE_REGION
Enable beta APIs on an existing cluster
Enable a list of beta APIs on an existing cluster:
gcloud container clusters update CLUSTER_NAME \
--enable-kubernetes-unstable-apis=LIST_OF_APIS \
--region=COMPUTE_REGION
Disable beta APIs on an existing cluster
You cannot disable beta APIs that are already enabled on a cluster. Beta APIs remain available until they are deprecated and the cluster is upgraded to the minor version where the API is removed. To learn more, see Beta API deprecations.
Check which beta APIs are enabled
Check which beta APIs are enabled for your GKE cluster:
gcloud container clusters describe CLUSTER_NAME \
--region=COMPUTE_REGION \
--format="value(enableK8sBetaApis.enabledApis)"
Beta API deprecations
Once a beta API is enabled, it remains enabled until the beta API is deprecated and the cluster is upgraded to the minor version where the API is removed.
Beta APIs are typically available for three minor versions before they are deprecated in favor of a new beta version, a stable version, or with no replacement. Beta APIs versions are removed three minor versions after deprecation. If you are using a beta API that has been deprecated and is removed in an upcoming Kubernetes minor version, you need to migrate to supported APIs so that your cluster can be upgraded to the minor version where the beta API is removed. To learn more, see How Kubernetes deprecations work with GKE.
GKE makes this process easier by attempting to detect the usage of deprecated Kubernetes APIs. If GKE detects the usage of a deprecated API, it pauses automatic upgrades to the minor version where that API is removed. GKE also shares deprecation insights and recommendation to notify you of your cluster's usage of a deprecated API so that you can take action to let upgrades continue. To learn more, see Assess and mitigate exposure to upcoming Kubernetes deprecations.
See the Kubernetes API deprecations table for a complete list of deprecated APIs and whether GKE detects usage.