This page explains how to perform an IP rotation for your control plane in Google Kubernetes Engine.
You can perform an IP rotation to change the IP address that your cluster's control plane (master) uses to serve requests from the Kubernetes API.
IP rotation also changes the SSL certificate and cluster certificate authority, which limits the ability to connect the previous address with the new one.
Before you begin
Before you start, make sure you have performed the following tasks:
- Ensure that you have enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Cloud SDK.
Set up default
gcloud settings using one of the following methods:
gcloud init, if you want to be walked through setting defaults.
gcloud config, to individually set your project ID, zone, and region.
Using gcloud init
If you receive the error
One of [--zone, --region] must be supplied: Please specify
location, complete this section.
gcloud initand follow the directions:
If you are using SSH on a remote server, use the
--console-onlyflag to prevent the command from launching a browser:
gcloud init --console-only
Follow the instructions to authorize
gcloudto use your Google Cloud account.
- Create a new configuration or select an existing one.
- Choose a Google Cloud project.
- Choose a default Compute Engine zone for zonal clusters or a region for regional or Autopilot clusters.
Using gcloud config
- Set your default project ID:
gcloud config set project PROJECT_ID
- If you are working with zonal clusters, set your default compute zone:
gcloud config set compute/zone COMPUTE_ZONE
- If you are working with Autopilot or regional clusters, set your default compute region:
gcloud config set compute/region COMPUTE_REGION
gcloudto the latest version:
gcloud components update
How IP rotation works
IP rotation is a multi-step process:
- When you initiate an IP rotation, your control plane begins serving on the new IP address in addition to the original IP address.
- After you initiate a rotation, you must update your cluster's API clients
(such as development machines using the
kubectlcommand-line interface) to begin communicating with the control plane over the new IP address.
- When you complete the rotation, the control plane ceases serving traffic over the previous IP address.
Performing an IP rotation
The following sections explain how to perform an IP rotation.
Initiating the rotation
To initiate an IP rotation, run the following command:
gcloud container clusters update [CLUSTER_NAME] --start-ip-rotation
[CLUSTER_NAME] is the name of the cluster
This command configures the control plane for the cluster to serve on two IP addresses, its original address and a new address. This causes brief downtime for the cluster API.
The command returns the following output:
This will start an IP Rotation on cluster [CLUSTER-NAME]. The master will be updated to serve on a new IP address in addition to the current IP address. GKE schedule recreation of all nodes to point to the new IP address. If maintenence window is used, nodes are not recreated until a maintenance window occurs. See documentation https://cloud.google.com/kubernetes-engine/docs/how-to/ip-rotation on how to manually update nodes. This operation is long-running and will block other operations on the cluster (including delete) until it has run to completion. Do you want to continue (Y/n)?
After you confirm, leave your shell open until the operation is complete.
Once the control plane has been reconfigured, GKE schedules an update for your cluster's nodes to use the new IP address. Each node pool is marked as "requires recreation." GKE does not finish the IP rotation until the automatic recreation is complete.
Inspecting the rotation
To monitor the update operation, run the following command:
gcloud container operations list --filter="UPGRADE_NODES RUNNING"
This command returns the operation ID for the update operation.
To poll the operation, pass the operation ID to the following command:
gcloud container operations wait [OPERATION_ID]
Node pools are recreated one-by-one, and each has its own operation. If you have multiple node pools, you can use the above instructions to poll each operation.
Updating API clients
Once IP rotation has been initiated, you must update all API clients outside of
the cluster (such as
kubectl on developer machines) to point to the new
To update your API clients, run the following command for each client:
gcloud container clusters get-credentials [CLUSTER_NAME]
Completing the rotation
To complete the rotation, run the following command:
gcloud container clusters update [CLUSTER_NAME] --complete-ip-rotation
The command returns the following output:
This will complete the in-progress IP Rotation on cluster [CLUSTER_NAME]. The master will be updated to stop serving on the old IP address and only serve on the new IP address. Make sure all API clients have been updated to communicate with the new IP address (e.g. by running `gcloud container clusters get-credentials --project [PROJECT-ID] --zone [COMPUTE-ZONE] [CLUSTER-NAME]`). This operation is long-running and will block other operations on the cluster (including delete) until it has run to completion.
This command configures the control plane to serve only on its new IP address. This causes brief downtime for the cluster API.
- Learn about Alias IPs.
- Learn about IP masquerade agent.
- Learn about configuring authorized networks.