Use Kubernetes beta APIs with GKE clusters

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:

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

Ensure that nodes use the newly-enabled beta APIs

Some beta features require that the feature is also enabled on the kubelet running on the worker nodes.

To use these newly-enabled beta API features with workloads running on the worker nodes, GKE must apply the change to the nodes:

• For nodes in new Standard node pools and groups of Autopilot nodes, GKE enables the beta APIs.
• For new and existing nodes in existing Standard node pools, or existing groups of nodes in Autopilot, GKE applies the change when the nodes are recreated during node upgrades or other types of node updates. To apply the change immediately to existing nodes in a Standard cluster node pool, you can manually upgrade the node pool to a later GKE version. Performing an in-place upgrade doesn't apply the change.

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.

What's next

• GKE deprecations