Container Cluster Operations

This guide shows you how to create and manage container clusters.

Creating a container cluster

You can create a container cluster by using the gcloud command-line tool or by using the Cloud Platform Console.

A container cluster is a set of Compute Engine instances called nodes. When you create a cluster, you can specify the number of instances and the type of the instances. You can also specify which network your instances belong to.

Container Engine creates a firewall for the network. It also creates routes for the nodes, so that containers running on the nodes can communicate with each other.

The Kubernetes API server does not run on your cluster nodes. Instead, Container Engine hosts the API server.

Console


You can create and delete container clusters in the Google Cloud Platform Console.

  1. Visit the Cloud Platform Console.
    Cloud Platform Console
  2. Click Create a container cluster. The following fields are required:

    • Name: The name of this container cluster. It must be unique within the project and the zone.
    • Zone: The Google Compute Engine zone in which to create the container cluster.
    • Cluster size: The number of instances to include in this container cluster. You must have enough resource quota for the number of nodes as well as sufficient route and firewall quota.
    • Machine type: The Compute Engine machine type to use for the instances. Each machine type is billed differently. For pricing information, review the price sheet.
  3. Click Create to create the container cluster.

gcloud


To create a container cluster with the gcloud command-line tool, use the gcloud container clusters command:

gcloud container clusters create NAME --zone ZONE

Optional flags:

  • --machine-type: The Google Compute Engine machine type (e.g. n1-standard-1) to use for instances in this container cluster. If unspecified, the default machine type is n1-standard-1.
  • --num-nodes: Specifies the number of nodes to create in the container cluster. Default is 3. Your Cloud Platform Console project must have enough quota for the number of nodes plus one (to include the master) as well as sufficient route and firewall quota.
  • --network: Specifies the Compute Engine network, in your project, that the cluster nodes belong to. Defaults to the default network.
  • --subnetwork: Specifies the Compute Engine subnetwork, in your project, that the cluster belongs to. If you specify a subnetwork, the network must be a subnet mode network.
  • --enable-autoscaling: Enables nodes autoscaling for the cluster's default node pool. If specified, the --min-nodes and --max-nodes parameters for controlling autoscaling should also be specified.

    Currently, this flag can only be used with gcloud alpha. See the gcloud alpha documentation for more information.

  • --enable-kubernetes-alpha: Enable Kubernetes alpha features on this cluster. See how to create an Alpha cluster.

    Currently, this flag can only be used with gcloud alpha. See the gcloud alpha documentation for more information.

  • --image-type: The base OS that nodes in the cluster runs on. The default image type and the list of valid image types can be listed using gcloud container get-server-config.

  • --cluster-ipv4-cidr: The IP address range for pods in this cluster in CIDR notation (e.g. 10.0.0.0/14). Must be in the 10.x.x.x range. Defaults to server-specified.
  • --local-ssd-count: The number of local SSDs to attach to each node.

    Currently, this flag can only be used with gcloud beta. See the gcloud beta documentation for more information.

  • --additional-zones: The set of additional zones in which the cluster's node footprint should be replicated. All zones must be in the same region as the cluster's primary zone. The same node footprint is replicated in all zones, so a cluster with 4 nodes and 2 additional zones would have 12 nodes total (4 in primary zone, 4 each in additional zones).

(For the full list of options, see gcloud container clusters create.)

A successful container cluster create request returns the cluster resource, with the output similar to the following:

Creating cluster example...done.
Created [https://container.googleapis.com/v1/projects/container-engine-docs/zones/us-central1-f/clusters/example].
kubeconfig entry generated for example.
NAME       ZONE           MASTER_VERSION  MASTER_IP  MACHINE_TYPE   STATUS
example    us-central1-f  1.0.1           x.x.x.x    n1-standard-1  RUNNING

Switching between clusters

If you have multiple Container Engine clusters, you'll need to manage which of your commands are sent to each cluster. You can set a default cluster, and configure the kubectl command-line interface to target a specific cluster.

Setting the default cluster

To set the default cluster for gcloud container commands:

gcloud config set container/cluster NAME

Configuring kubectl

Google Container Engine uses the kubectl command to manage resources in your cluster. If you have more than one cluster, you must tell kubectl which cluster to target.

To tell kubectl to target a specific cluster, run the following command in your shell or terminal window:

gcloud container clusters get-credentials NAME

kubectl is configured to use Application Default Credentials to authenticate to the cluster. Ensure it has the right credentials by running

gcloud auth application-default login

This opens a browser window prompting you to log in with your desired account.

Viewing a container cluster

Console


To view your container clusters in the Cloud Platform Console:

  1. Visit the Cloud Platform Console.
    Cloud Platform Console

Your container clusters are listed. Click a cluster name for more information about that cluster.

gcloud


To view a particular container cluster, use the gcloud clusters describe command:

gcloud container clusters describe NAME --zone ZONE

To list the project's container clusters within a specific zone, use the clusters list sub-command:

gcloud container clusters list --zone ZONE

Updating a container cluster

gcloud


To update settings of a particular container cluster, use the gcloud clusters update command:

gcloud container clusters update NAME --zone ZONE

Choose one of the following update options:

  • --monitoring-service: The monitoring service to use for the cluster. Options are:
    • monitoring.googleapis.com (the Google Cloud Monitoring service),
    • none (no metrics are exported from the cluster).
  • --enable-autoscaling or `--no-enable-autoscaling: Enables or disables node autoscaling for the cluster's default node pool. If enabled, the --min-nodes and --max-nodes parameters for controlling autoscaling should also be specified.

    Currently, this flag can only be used with gcloud alpha. See the gcloud alpha documentation for more information.

  • --update-addons: Enable or disable optional cluster addons. Disabling this option makes the associated Kubernetes features unusable. Value for this flag should be one or more (comma separated) of the following:

    • HorizontalPodAutoscaling=ENABLED|DISABLED: Enable or disable the HPA controller. Disabling this option makes horizontal pod autoscalers unusable in your cluster.
    • HttpLoadBalancing=ENABLED|DISABLED: Enable or disable the Compute Engine Ingress controller. Disabling this option makes ingress resources unusable in your cluster.
  • --additional-zones: The set of additional zones in which the cluster's node footprint should be replicated. All zones must be in the same region as the cluster's primary zone. The same node footprint is replicated in all zones, so a cluster with 4 nodes and 2 additional zones would have 12 nodes total (4 in primary zone, 4 each in additional zones). Pass an empty string (--additional-zones="") to remove all zones other than the cluster's primary zone.

    Currently, this flag can only be used with gcloud beta. See the gcloud beta documentation for more information.

Deleting a container cluster

When you delete a container cluster, the following resources are deleted:

  • The master instance
  • All of the node instances in the cluster
  • Any pods that are running on those instances
  • Any firewalls and routes created by the Container Engine service at the time of container cluster creation

Any data in hostDir or emptyDir volumes of these pods is deleted, but any gcePersistentDisk volumes are not affected.

Console


To delete a container cluster using the Cloud Platform Console:

  1. Visit the Cloud Platform Console.
    Cloud Platform Console
  2. Select the checkbox next to the cluster to be deleted.
  3. Click Delete. At the confirmation prompt, click Delete again.

gcloud


To delete a container cluster with the gcloud command-line tool:

gcloud container clusters delete NAME --zone ZONE

Passing cluster credentials to kubectl

Once your cluster has been created, use the kubectl command to create and manage resources on the cluster.

If your cluster was created through the Cloud Platform Console, or with the gcloud command-line tool from a different machine, you need to run an additional command to make your credentials available to kubectl. Your default zone and cluster must be already set or should be passed as flags to the command.

    gcloud container clusters get-credentials NAME [--zone ZONE]

You only need to run this once per cluster per machine; for example, if you created your cluster from your laptop, you need to run get-credentials on your desktop in order to access the cluster from that machine.

Cluster Labels

Container Engine clusters support Google Cloud Platform's Labels feature. You can add labels to your container cluster when you create the cluster, or add labels to an existing cluster by using one of the following options:

  • Add labels using the Cloud Platform Console
  • Add labels using the Container Engine API
  • Add labels using the gcloud command-line interface.

See Cluster Labels for more information on using labels with your Container Engine clusters.

Examples

Create a cluster with autoscaling

gcloud


The following command creates a cluster of size 30, with node autoscaling based on cluster load that scales the cluster to a maximum of 50 nodes and a minimum of 15 nodes:

gcloud alpha container clusters create NAME --zone ZONE --num-nodes=30 \
  --enable-autoscaling --min-nodes=15 --max-nodes=50

Turn off cluster autoscaling

gcloud


The following command disables cluster autoscaling for a running cluster's default node pool. The cluster size is fixed at the cluster's current default node pool size, which can be manually updated.

gcloud alpha container clusters update NAME --zone ZONE --no-enable-autoscaling

Create a cluster with local SSD nodes

gcloud


The following command creates a cluster of ten 32-core nodes with four 375GB local SSD partitions attached to each node:

gcloud beta container clusters create NAME --zone ZONE \
  --num-nodes=10 --machine-type=n1-standard-32 --local-ssd-count=4

Update a running cluster to multi-zone

gcloud


The following commands create a cluster of size 5 in one zone then update it to replicate the node footprint across 3 zones. After the second command has finished, the cluster will have 15 nodes total (five in the default zone, five in each of the additional zones).

gcloud container clusters create NAME --zone us-central1-b \
  --num-nodes=5

gcloud beta container clusters update NAME --additional-zones=us-central1-f,us-central1-c

Create an Alpha cluster

gcloud


The following commands create an Alpha Cluster.

gcloud beta container clusters create NAME --zone us-central1-b \
  --enable-kubernetes-alpha

You are prompted to acknowlege a warning that the created cluster will not be upgraded and will be deleted after 30 days.

This will create a cluster with all Kubernetes Alpha features enabled.
- This cluster will not covered by the Container Engine SLA and should not be used for production workloads.
- You will not be able to upgrade the master or nodes.
- The cluster will be deleted after 30 days.

Do you want to continue (Y/n)?

Create a cluster with custom labels

gcloud


You can create a cluster with Kubernetes labels with the following command:

gcloud container clusters create NAME --zone us-central1-b \
  --node-labels=env=prod,type=cache

You can inspect the labels fields by using the kubectl describe nodes command. Here are some example label fields for a newly-created cluster.

Labels:         beta.kubernetes.io/arch=amd64
                beta.kubernetes.io/instance-type=n1-standard-1
                beta.kubernetes.io/os=linux
                cloud.google.com/gke-nodepool=default-pool
                env=prod
                failure-domain.beta.kubernetes.io/region=us-central1
                failure-domain.beta.kubernetes.io/zone=us-central1-b
                kubernetes.io/hostname=HOSTNAME
                type=cache

Create a cluster with preemptible VMs

gcloud


You can create a cluster with preemptible VMs with following command:

gcloud beta container clusters create NAME --zone us-central1-b --preemptible

All nodes in the new cluster are given a kubernetes label: cloud.google.com/gke-preemptible=true

Next steps

Learn more about Container Engine:

Send feedback about...

Container Engine Documentation