User cluster configuration file 1.30 and higherStay organized with collectionsSave and categorize content based on your preferences.
This document describes the fields in the user cluster configuration file for
versions 1.30 and higher Google Distributed Cloud.
Generating a template for your configuration file
If you usedgkeadmto create your admin workstation, thengkeadmgenerated
a template for your user cluster configuration file. Alsogkeadmfilled in
some of the fields for you.
If you did not usegkeadmto create your admin workstation, you can usegkectlto generate a template for your user cluster configuration file.
To generate a template for your user cluster configuration file:
OUTPUT_FILENAME: a path of your choice for the
generated template. If you omit this flag,gkectlnames the fileuser-cluster.yamland puts it in the current directory.
VERSION: the Google Distributed Cloud version number. For example:gkectl create-config cluster --gke-on-prem-version=1.34.0-gke.566.
Template
Click to see the generated template for version 1.34.
apiVersion: v1
kind: UserCluster
# (Required) A unique name for this cluster
name: ""
# (Required) GKE on-prem version (example: 1.3.0-gke.16)
gkeOnPremVersion: 1.34.0-gke.566
# # (Optional) Specify the prepared secret configuration which can be added or edited
# # only during cluster creation
# preparedSecrets:
# # reference to the secret namespace for a group of secrets; it should be prepared
# # beforehand by 'gkectl prepare secrets' command; it is immutable.
# namespace: ""
# (Optional) Enable controlplane v2. Default is true
enableControlplaneV2: true
# (Optional) Enable advanced cluster options
enableAdvancedCluster: true
# # (Optional) vCenter configuration (default: inherit from the admin cluster)
# vCenter:
# # # (Optional) vCenter server to use. Controlplane v2 needs to be enabled when the address
# # # is different from that in the admin cluster configuration
# # address: ""
# datacenter: ""
# cluster: ""
# # Resource pool to use. Specify [VSPHERE_CLUSTER_NAME]/Resources to use the default
# # resource pool
# resourcePool: ""
# # Storage policy to use for cluster VM storage and default StorageClass. Do not
# # specify it together with datastore
# storagePolicyName: ""
# # # Datastore to use for cluster VM storage and default StorageClass. Do not specify
# # # it together with storagePolicyName
# # datastore: ""
# # Provide the path to vCenter CA certificate pub key for SSL verification
# caCertPath: ""
# # The credentials to connect to vCenter
# credentials:
# # reference to external credentials file
# fileRef:
# # read credentials from this file
# path: ""
# # entry in the credential file
# entry: ""
# # # (Optional) reference to the credential secret; it should be prepared beforehand
# # # by 'gkectl prepare secrets' command
# # secretRef:
# # # The version for this prepared secret; it can be specified as 'latest' or integer
# # # string; it will be defaulted to latest version if it is not specified when creating
# # # a cluster; it is allowed to be empty when creating a cluster; it is not allowed
# # # to be empty when rotating credentials
# # version: ""
# # (Optional) vSphere folder where cluster VMs will be located. Defaults to the the
# # datacenter wide folder if unspecified.
# folder: ""
# # (Optional) The absolute or relative path to the GCP service account key for pulling
# # GKE images (default: inherit from the admin cluster)
# componentAccessServiceAccountKeyPath: ""
# # (Optional) The prepared credentials for component access service account key
# componentAccessServiceAccountKey:
# # reference to the credential secret; it should be prepared beforehand by 'gkectl
# # prepare secrets' command
# secretRef:
# # The version for this prepared secret; it can be specified as 'latest' or integer
# # string; it will be defaulted to latest version if it is not specified when creating
# # a cluster; it is allowed to be empty when creating a cluster; it is not allowed
# # to be empty when rotating credentials
# version: ""
# # (Optional) Use a private registry to host GKE images
# privateRegistry:
# # Do not include the scheme with your registry address
# address: ""
# credentials:
# # reference to external credentials file
# fileRef:
# # read credentials from this file
# path: ""
# # entry in the credential file
# entry: ""
# # # (Optional) reference to the credential secret; it should be prepared beforehand
# # # by 'gkectl prepare secrets' command
# # secretRef:
# # # The version for this prepared secret; it can be specified as 'latest' or integer
# # # string; it will be defaulted to latest version if it is not specified when creating
# # # a cluster; it is allowed to be empty when creating a cluster; it is not allowed
# # # to be empty when rotating credentials
# # version: ""
# # The absolute or relative path to the CA certificate for this registry
# caCertPath: ""
# (Required) Network configuration; vCenter section is optional and inherits from
# the admin cluster if not specified
network:
# (Required when using "static" ipMode.type; "Seesaw" loadBalancer.kind; or setting
# enableControlplaneV2 to "true") This section overrides ipMode.ipBlockFilePath
# values when ipMode.type=static. It's also used for control-plane nodes when controlplane
# v2 is enabled and seesaw nodes
hostConfig:
# List of DNS servers
dnsServers:
- ""
# List of NTP servers
ntpServers:
- ""
# # List of DNS search domains
# searchDomainsForDNS:
# - ""
ipMode:
# (Required) Define what IP mode to use ("dhcp" or "static")
type: static
# (Required when using "static" mode) The absolute or relative path to the yaml
# file to use for static IP allocation. Hostconfig part will be overwritten by
# network.hostconfig if specified
ipBlockFilePath: ""
# (Required) The Kubernetes service CIDR range for the cluster. Must not overlap
# with the pod CIDR range
serviceCIDR: 10.96.0.0/20
# (Required) The Kubernetes pod CIDR range for the cluster. Must not overlap with
# the service CIDR range
podCIDR: 192.168.0.0/16
vCenter:
# vSphere network name
networkName: ""
# # (Optional) List of additional node network interfaces feature enabled by multipleNetworkInterfaces
# additionalNodeInterfaces:
# # vSphere network name
# - networkName: ""
# # (Required) Define what IP mode to use ("dhcp" "static" or "none")
# type: static
# # # (Required when using "static" mode) The absolute or relative path to the yaml file
# # # to use for static IP allocation. Hostconfig part will be overwritten by network.hostconfig
# # # if specified
# # ipBlockFilePath: ""
# (Required when setting enableControlplaneV2 to "true") Specify the IPs to use
# for control-plane nodes when controlplane v2 is enabled. 1 IP is needed for non-HA
# cluster and 3 for HA cluster. Non-empty controlPlaneIPBlock is not allowed when
# controlplane v2 is disabled
controlPlaneIPBlock:
netmask: ""
gateway: ""
ips:
- ip: ""
hostname: ""
- ip: ""
hostname: ""
- ip: ""
hostname: ""
# (Required) Load balancer configuration
loadBalancer:
# (Required) The VIPs to use for load balancing
vips:
# Used to connect to the Kubernetes API
controlPlaneVIP: ""
# Shared by all services for ingress traffic
ingressVIP: ""
# (Required) Which load balancer to use "ManualLB" or "MetalLB".
kind: MetalLB
# # (Required when using "ManualLB" kind) Specify pre-defined nodeports
# manualLB:
# # NodePort for ingress service's http (only needed for user cluster)
# ingressHTTPNodePort: 30243
# # NodePort for ingress service's https (only needed for user cluster)
# ingressHTTPSNodePort: 30879
# # NodePort for konnectivity server service (only needed for controlplane v1 user
# # cluster)
# konnectivityServerNodePort: 30563
# # NodePort for control plane service (not needed for HA admin cluster or controlplane
# # V2 user cluster)
# controlPlaneNodePort: 30562
# (Required when using "MetalLB" kind in user clusters) Specify the MetalLB configs
metalLB:
# (Required) A list of non-overlapping IP pools used by load balancer typed services.
# Must include ingressVIP of the cluster.
addressPools:
# (Required) Name of the address pool
- name: address-pool-1
# (Required) The addresses that are part of this pool. Each address must be
# either in the CIDR form (1.2.3.0/24) or range form (1.2.3.1-1.2.3.5).
addresses:
- ""
# # (Optional) Avoid using IPs ending in .0 or .255. This avoids buggy consumer devices
# # mistakenly dropping IPv4 traffic for those special IP addresses (default: false)
# avoidBuggyIPs: false
# # (Optional) Prevent IP addresses to be automatically assigned from this pool (default:
# # false)
# manualAssign: false
# (Optional) Enable dataplane v2
enableDataplaneV2: true
# # (Optional) DataplaneV2 configuration
# dataplaneV2:
# # (Optional) Specify dataplanev2 forward mode (snat or dsr)
# forwardMode: snat
# # (Optional) Enable support for multiple networking interfaces
# multipleNetworkInterfaces: false
# # (Optional) Enable advanced dataplane v2 networking features such as Egress NAT Gateway
# # and it requires enableDataplaneV2 to be set
# advancedNetworking: false
# # (Optional) Disable installation of bundled ingress
# disableBundledIngress: false
# # (Optional) Storage specification for the cluster
# storage:
# # # Whether to disable vSphere CSI components deployment. The feature is enabled by
# # # default
# # vSphereCSIDisabled: false
# (Optional) User cluster master nodes must have either 1 or 3 replicas (default:
# 4 CPUs; 8192 MB memory; 1 replica)
masterNode:
cpus: 4
memoryMB: 8192
# How many machines of this type to deploy
replicas: 3
# # (Optional/Preview) Topology domains that user cluster master nodes will be deployed
# # to. Only 1 element is allowed. Advanced cluster must be enabled and infraConfigFilePath
# # must be filled in admin cluster
# topologyDomains:
# - ""
# # Enable auto resizing on master
# autoResize:
# # Whether to enable auto resize for master. Defaults to false.
# enabled: false
# vsphere:
# # (Optional) vSphere datastore the master nodes will be created on (default: vCenter.datastore)
# datastore: ""
# # (Optional) Storage policy to use for user master VM storage and datadisk (default:
# # vCenter.storagePolicyName)
# storagePolicyName: ""
# # (Optional) Control plane load balancer configuration. Only supported when advanced
# # cluster is enabled
# controlPlaneLoadBalancer:
# # # (Optional) The control plane load balancer mode for advanced cluster. Possible values
# # # are bundled or manual. Default value is bundled for advanced cluster without topology
# # # domains; and is manual for advanced cluster with topology domains.
# # mode: ""
# (Required) List of node pools. The total un-tainted replicas across all node pools
# must be greater than or equal to 3
nodePools:
- name: pool-1
# # (Optional) GKE on-prem version (example: 1.13.0-gke.16); it will be defaulted to
# # cluster version if it is not specified; it can be used to roll back a node pool
# # if it is specified as the previous node pool version
# gkeOnPremVersion: ""
cpus: 4
memoryMB: 8192
# How many machines of this type to deploy
replicas: 3
# # (Optional/Preview) Topology domains that node pool nodes will be deployed to. Only
# # 1 element is allowed. Advanced cluster must be enabled and infraConfigFilePath must
# # be filled in admin cluster
# topologyDomains:
# - ""
# # (Optional) boot disk size; must be at least 40 (default: 40)
# bootDiskSizeGB: 40
# (Optional) Specify the type of OS image; available options can be set to "ubuntu"
# "ubuntu_containerd" "cos" "ubuntu_cgv2" "cos_cgv2" or "windows". Default is "ubuntu_containerd".
osImageType: ubuntu_cgv2
# # (Required when using "windows" osImageType) Specify the OS image template in vCenter
# osImage: ""
# # Labels to apply to Kubernetes Node objects
# labels: {}
# # Taints to apply to Kubernetes Node objects
# taints:
# - key: ""
# value: ""
# effect: ""
# vsphere:
# # (Optional) vSphere datastore the node pool will be created on (default: vCenter.datastore)
# datastore: ""
# # (Optional) Storage policy to use for nodepool (default: vCenter.storagePolicyName)
# storagePolicyName: ""
# # (Optional) Existing host groups used for VM/Host affinity. VM groups will be created
# # to bind with these host groups via vm-host affinity rules
# hostgroups:
# - ""
# # (Optional) vSphere tags to be attached to the virtual machines in the node pool.
# # It is supported in GKE on-prem version 1.7+
# tags:
# - category: ""
# name: ""
# # (Optional) Horizontal autoscaling for the nodepool; replicas should not be edited
# # while updating the nodepool if this is turned on
# autoscaling:
# # min number of replicas in the NodePool
# minReplicas: 0
# # max number of replicas in the NodePool
# maxReplicas: 0
# (Optional) Allow traffic of LoadBalancer typed services flow through nodes of
# this pool. This is only needed for MetalLB mode. Set it to true for at least one
# node pool in the cluster. Default is false.
enableLoadBalancer: true
# # (Optional/Preview) Update strategy for this node pool (it will overwrite nodePoolUpdatePolicy.updateStrategy
# # setting)
# updateStrategy:
# # # (Optional/Preview) Rolling update strategy for machines of the node pool
# # rollingUpdate:
# # # # (Optional/Preview) The maximum number of machines that can be scheduled simultaneously
# # # # during update/upgrade (default: 1)
# # # maxSurge: "1"
# Spread nodes across at least three physical hosts (requires at least three hosts)
antiAffinityGroups:
# Set to false to disable DRS rule creation
enabled: true
# # (Optional/Preview) Track user cluster VMs with vSphere tags
# enableVMTracking: false
# # Configure node pool update policy for the cluster
# nodePoolUpdatePolicy:
# # (Optional/Preview) Number of node pools to update at a time. 0 means no limit.
# # 1 means updating one by one.
# maximumConcurrentNodePoolUpdate: 0
# # # (Optional/Preview) Cluster wide default node pool update strategy. A node pool will
# # # use this setting if it doesn't set specific updateStrategy
# # updateStrategy:
# # # # (Optional/Preview) Rolling update strategy for machines of the node pool
# # # rollingUpdate:
# # # # # (Optional/Preview) The maximum number of machines that can be scheduled simultaneously
# # # # # during update/upgrade (default: 1)
# # # # maxSurge: "1"
# # (Optional) Additional configurations passed to kube-scheduler. Require advanced
# # cluster is enabled
# schedulerConfiguration:
# # (Optional) Default TopologySpreadConstraint rule applied to the pod scheduling.
# # See https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/
# # for details.
# defaultTopologySpreadConstraint:
# typemeta:
# kind: ""
# apiversion: ""
# defaultconstraints:
# - maxskew: 0
# topologykey: ""
# whenunsatisfiable: ""
# labelselector:
# matchlabels: {}
# matchexpressions:
# - key: ""
# operator: ""
# values:
# - ""
# mindomains: 0
# nodeaffinitypolicy: ""
# nodetaintspolicy: ""
# matchlabelkeys:
# - ""
# defaultingtype: ""
# # (Optional) Configure additional authentication.
# authentication:
# # (Optional) Provide an additional serving certificate for the API server
# sni:
# certPath: ""
# keyPath: ""
# # (Optional) Configure BinAuthz to enable deploy-time security control to the container
# # images.
# binaryAuthorization:
# # (Optional) Set value to string "disabled" or "project_singleton_policy_enforce".
# # Default is "disabled".
# evaluationMode: ""
# (Required) Specify which GCP project to register your GKE OnPrem cluster to
gkeConnect:
projectID: ""
# # (Optional) The location of the GKE Hub and Connect service where the cluster is
# # registered to. It can be any GCP region or "global". Default to "global" when unspecified.
# location: us-central1
# The absolute or relative path to the key file for a GCP service account used to
# register the cluster
registerServiceAccountKeyPath: ""
# # (Optional) The prepared credentials for register service account key
# registerServiceAccountKey:
# # reference to the credential secret; it should be prepared beforehand by 'gkectl
# # prepare secrets' command
# secretRef:
# # The version for this prepared secret; it can be specified as 'latest' or integer
# # string; it will be defaulted to latest version if it is not specified when creating
# # a cluster; it is allowed to be empty when creating a cluster; it is not allowed
# # to be empty when rotating credentials
# version: ""
# # (Optional) Specify if you wish to explicitly enable/disable the cloud hosted gkeonprem
# # API to enable/disable cluster lifecycle management from gcloud UI and Terraform.
# gkeOnPremAPI:
# enabled: false
# (Required) Specify which GCP project to connect your logs and metrics to
stackdriver:
# The project ID for logs and metrics. It should be the same with gkeconnect.projectID.
projectID: ""
# A GCP region where you would like to store logs and metrics for this cluster.
clusterLocation: us-central1
# The absolute or relative path to the key file for a GCP service account used to
# send logs and metrics from the cluster
serviceAccountKeyPath: ""
# # (Optional) The prepared credentials for stackdriver service account key
# serviceAccountKey:
# # reference to the credential secret; it should be prepared beforehand by 'gkectl
# # prepare secrets' command
# secretRef:
# # The version for this prepared secret; it can be specified as 'latest' or integer
# # string; it will be defaulted to latest version if it is not specified when creating
# # a cluster; it is allowed to be empty when creating a cluster; it is not allowed
# # to be empty when rotating credentials
# version: ""
# (Optional) Disable vsphere resource metrics collection from vcenter. False by
# default
disableVsphereResourceMetrics: false
# (Optional) Configure kubernetes apiserver audit logging
cloudAuditLogging:
# The project ID for logs and metrics. It should be the same with gkeconnect.projectID.
projectID: ""
# A GCP region where you would like to store audit logs for this cluster.
clusterLocation: us-central1
# The absolute or relative path to the key file for a GCP service account used to
# send audit logs from the cluster
serviceAccountKeyPath: ""
# # (Optional) The prepared credentials for cloud audit logging service account key
# serviceAccountKey:
# # reference to the credential secret; it should be prepared beforehand by 'gkectl
# # prepare secrets' command
# secretRef:
# # The version for this prepared secret; it can be specified as 'latest' or integer
# # string; it will be defaulted to latest version if it is not specified when creating
# # a cluster; it is allowed to be empty when creating a cluster; it is not allowed
# # to be empty when rotating credentials
# version: ""
# Enable auto repair for the cluster
autoRepair:
# Whether to enable auto repair feature. Set false to disable.
enabled: true
# # Encrypt Kubernetes secrets at rest
# secretsEncryption:
# # Secrets Encryption Mode. Possible values are: GeneratedKey
# mode: GeneratedKey
# # GeneratedKey Secrets Encryption config
# generatedKey:
# # # key version
# # keyVersion: 1
# # # disable secrets encryption
# # disabled: false
Required fields and default values
If a field is marked asRequired, then the completed configuration file must
have a value filled in for the field.
If aDefaultvalue is given for a field, then the cluster will use that value
if you don't enter anything for the field. You can override a default value by
entering a value.
If a field is not marked as Required, then the field is optional. You can fill
it in if it is relevant for you, but you don't have to fill it in.
Filling in your configuration file
In your configuration file, enter field values as described in the following
sections.
enableAdvancedCluster
1.33 and higher
All new clusters are created as advanced clusters. If you include this field
in your configuration file when creating a new cluster, it must be set totrue. If you set this field tofalse, cluster creation will be blocked.
SetenableAdvancedClustertofalseif you don't want to enable advanced
cluster when creating a new cluster. When this flag is set totrue(advanced
cluster enabled), the underlying Google Distributed Cloud software deploys controllers
that allow for a more extensible architecture. Enabling advanced cluster
gives you access to new features and capabilities, such astopology domains.
This field must have the same value as the admin cluster'senableAdvancedClusterfield.
Available only for new clusters Preview Optional Immutable Boolean Prepopulated: false Default: false
SetenableAdvancedClustertotrueif you want to enable advanced cluster
when creating a new cluster. When this flag is set totrue(advanced cluster
enabled), the underlying Google Distributed Cloud software deploys controllers
that allow for a more extensible architecture. Enabling advanced cluster
gives you access to new features and capabilities, such astopology domains.
This field must have the same value as the admin cluster'senableAdvancedClusterfield.
1.30 and lower
Not available.
name
RequiredString
A name of your choice for your user cluster. The name must:
contain at most 40 characters
contain only lowercase alphanumeric characters or a hyphen (-)
start with an alphabetic character
end with an alphanumeric character
Example:
name: "my-user-cluster"
gkeOnPremVersion
Required Mutable String
The Google Distributed Cloud version for your user cluster.
Example:
gkeOnPremVersion: "1.29.0-gke.1456"
preparedSecrets.namespace
IfinfraConfigFilePathis configured in the admin cluster configuration file, remove this field.
Otherwise, if you want to useprepared credentials,
fill in this field.
Immutable String Possible values: A string that begins with "gke-onprem-secrets-"
The name of a Kubernetes namespace in the admin cluster where prepared Secrets
are stored for this user cluster.
In version 1.30 and higher, Controlplane V2 is required for new user
clusters. If you include this field in your configuration file, it must
be set totrue.
With Controlplane V2, the control plane for a user cluster
runs on one or more nodes in the user cluster itself. The benefits of
Controlplane V2 include:
Architectural consistency between admin and user clusters.
Failure isolation. An admin cluster failure doesn't affect user clusters.
Operational separation. An admin cluster upgrade doesn't cause downtime for
user clusters.
Deployment separation. You can put the admin and user clusters in different
failure domains or geographical sites. For example, a user cluster in an edge
location could be in a different geographical site from the admin cluster.
1.29 and lower
Immutable BooleanPrepopulated: true Default: true
To enable Controlplane V2, setenableControlplaneV2totrueor remove the
setting from your user cluster configuration file. Otherwise, set it tofalse.
With Controlplane V2, the control plane for a user cluster runs on one or more
nodes in the user cluster itself. When Controlplane V2 isn't enabled, the user
cluster control plane runs in the admin cluster.
We recommend that you enable Controlplane V2.
Example:
enableControlplaneV2:true
vCenter
This section contains information about your vSphere environment and your
connection to vCenter Server.
IfinfraConfigFilePathis
configured in the admin cluster configuration file, remove this entire section.
If you included thevCentersection in the admin cluster configuration file:
If you want a field in this section to be the same as what you specified for
your admin cluster, remove the field or leave it commented out.
If you want a field to be different from what you specified for your admin
cluster, fill it in here. Any fields that you fill in here in thevCentersection override the corresponding fields in your admin cluster configuration
file.
vCenter.address
Immutable String Default: Inherit from the admin cluster
The IP address or the hostname of the instance of vCenter Server that you want
to use for this user cluster.
If you specify a value that is different from the instance of vCenter Server
used by the admin cluster, thenControlplane V2must be enabled, and you must provide values fornetwork.vCenter.networkNameand all the
required fields in thevCentersection.
The value you specify is relative to the root folder named/.
If your data center is in the root folder, the value is the name of the
data center.
Example:
vCenter:
datacenter: "my-uc-data-center"
Otherwise, the value is a relative path that includes one or more folders along
with the name of the data center.
Example:
vCenter:
datacenter: "data-centers/data-center-2"
vCenter.cluster
Immutable String Default: Inherit from the admin cluster
The relative path of avSphere clusterthat represents the ESXi hosts where your user cluster VMs will run. This vSphere
cluster represents a subset of the physical ESXi hosts in your vCenter data center.
If you specify a value for this field, then you must also specify:
The value you specify must be a name, not a path. Don't include any folders
in the value.
Example:
vCenter:
datastore: "my-datastore"
If you specify a value for this field, don't specify a value forvCenter.storagePolicyName. ThevCenter.datastorefield is immutable except
when you set the field to an empty string when youmigrate a datastore to Storage Policy Based Management (SPBM).
You can also specify a VM storage policy for the nodes in a particular node
pool. But the policy specified here applies to any node pool that doesn't have
its own policy.
The path of acredentials configuration filethat contains the username and password of your vCenter user account. The user
account must have the Administrator role or equivalent privileges. SeevSphere requirements.
You can usegkectl update credentialsto update this field in an existing
cluster. For more information, seeRotating service account keys.
String Possible values: An integer string or "latest" Default value: "latest"
If you provide a value forpreparedSecrets.namespace,
fill in this field. Otherwise, remove this field or leave it commented out.
The version of aprepared Secretin the admin cluster that contains the username and password for the instance of
vCenter Server that you intend to use for this user cluster.
Example:
vCenter:
credentials:
secretRef:
version: "1"
vCenter.folder
Immutable String Default: Inherit from the admin cluster
The relative path of a vSphere folder that you have already created. This folder
will hold your user cluster VMs.
If you do not specify a value, your user cluster VMs will be put in/.../DATA_CENTER/vm/.
If you specify a value, it is relative to/.../DATA_CENTER/vm/.
The value can be the name of a folder.
Example:
vCenter:
folder: "my-uc-folder"
Or the value can be a relative path that includes more than one folder.
Example:
vCenter:
folder: "folders/folder-2"
componentAccessServiceAccountKeyPath
Mutable String Default: Inherit from the admin cluster
The path of the JSON key file for your component access service account.
Fill in this section if your admin cluster is using aprivate container registry,
and you want your user cluster to use a different private registry or different
settings. If you want to use a different private registry address, your
cluster must haveControlplane V2enabled.
The new settings are picked up during cluster creation and update.
If you want to use the same settings as the admin cluster, remove this section
or leave it commented out.
privateRegistry.address
Immutable String Default: Inherit from the admin cluster
The IP address or FQDN (Fully Qualified Domain Name) of the machine that runs
your private Docker registry.
Examples:
privateRegistry:
address: "203.0.113.10"
privateRegistry:
address: "fqdn.example.com"
privateRegistry.credentials.fileRef.path
Mutable String Default: Inherit from the admin cluster
If you are planning to use prepared secret for the private registry, do not
provide a value for this field. Instead, provide a value forprivateRegistry.credentials.secretRef.version.
The path of acredentials configuration filethat contains the username and password of an account that Google Distributed Cloud
can use to access your private Docker registry.
Mutable String Default: Inherit from the admin cluster
The name of the credentials block, in yourcredentials configuration file,
that contains the username and password of your private Docker registry account.
String Possible values: An integer string or "latest" Default value: "latest"
If you provide a value forpreparedSecrets.namespaceand want to use
prepared secret for a private registry, fill in this field. Otherwise, remove this
field or leave it commented out.
The version of aprepared Secretin the admin cluster that contains the username and password for the instance of
vCenter Server that you intend to use for this user cluster.
Mutable String Default: Inherit from the admin cluster
When Docker pulls an image from your private registry, the registry must
prove its identity by presenting a certificate. The registry's certificate is
signed by a certificate authority (CA). Docker uses the CA's certificate to
validate the registry's certificate.
Set this field to the path of the CA's certificate.
This section contains information about your user cluster network.
network.hostConfig
1.30 and higher
This section holds information about NTP servers, DNS servers, and DNS search
domains used by the VMs that are your cluster nodes.
IfinfraConfigFilePathis configured in the admin cluster configuration file (available in 1.31 and
higher), remove this entire section. Otherwise, this section is required if
one or more of the following are true:
network.ipMode.typeis set tostatic.
enableControlplaneV2is set totrueor allowed to default totrue.
Note that Conrolplane V2 is required for new user clusters.
1.29 and lower
This section holds information about NTP servers, DNS servers, and DNS search
domains used by the VMs that are your cluster nodes. If you are using the
Seesaw load balancer, this information also applies to your Seesaw VMs.
This section is required if one or more of the following are true:
network.ipMode.typeis set tostatic.
enableControlplaneV2is set totrueor allowed to default totrue.
The Seesaw load balancer isn't supported on clusters with
Controlplane V2 enabled.
loadBalancer.kindis set to"Seesaw".
network.hostConfig.dnsServers
Required ImmutableArray of strings. The maximum number of elements in the array is three.
If you want your cluster nodes to get their IP address from a DHCP server, set
this to"dhcp". If you want your cluster nodes to have static IP addresses
chosen from a list that you provide, set this to"static". IfenableControlplaneV2is set totrue, this
setting applies to only worker nodes.
Example:
network:
ipMode:
type: "static"
network.ipMode.ipBlockFilePath
This field is required ifnetwork.ipMode.type=staticor ifinfraConfigFilePathis configured in the admin cluster configuration file.
ImmutableString
The absolute or relative path of theIP block filefor your cluster.
A range of IP addresses, in CIDR format, to be used for Pods in your
cluster. Must be at least a /18 range.
Example:
network:
podCIDR: "192.168.0.0/16"
The Service range must not overlap with the Pod range.
The Service and Pod ranges must not overlap with any address outside the cluster
that you want to reach from inside the cluster.
For example, suppose your Service range is 10.96.232.0/24, and your Pod range is
192.168.0.0/16. Any traffic sent from a Pod to an address in either of those
ranges will be treated as in-cluster and will not reach any destination outside
the cluster.
In particular, the Service and Pod ranges must not overlap with:
IP addresses of nodes in any cluster
IP addresses used by load balancer machines
VIPs used by control-plane nodes and load balancers
IP address of vCenter servers, DNS servers, and NTP servers
We recommend that your Service and Pod ranges be in theRFC 1918address space.
Here is one reason for the recommendation to use RFC 1918 addresses. Suppose
your Pod or Service range contains external IP addresses. Any traffic sent from
a Pod to one of those external addresses will be treated as in-cluster traffic
and will not reach the external destination.
network.vCenter.networkName
IfinfraConfigFilePathis configured in the admin cluster configuration file, remove this field.
Otherwise, this field is required ifvCenter.addressis different from the vCenter address you are using for the admin cluster.
ImmutableString
The name of the vSphere network for your user cluster nodes.
Example:
network:
vCenter:
networkName: "my-network"
If the name contains a special character, you must use an escape sequence for it.
Special characters
Escape sequence
Slash (/)
%2f
Backslash (\)
%5c
Percent sign (%)
%25
If the network name is not unique in your data center, you can specify a full
path.
Required ifenableControlplaneV2=true Immutable Array of objects, each of which has an IP address and a hostname. The hostname
is required for controlplane V2 migration, optional otherwise.
For a high-availability (HA) user cluster, the array has three elements. For a
non-HA user cluster, the array has one element.
The IP address that you have chosen to configure on the load balancer
for the ingress proxy.
Example:
loadBalancer:
vips:
ingressVIP: "203.0.113.4"
loadBalancer.kind
Specify the kind of load balancer to use.
1.32 and higher
Required ImmutableString Prepopulated: "MetalLB"
The kind of load balancer that you can use depends on whether you will
set up the cluster to usetopology domains. The
cluster is assumed to use topology domains if theinfraConfigFilePathfield is configured in the admin cluster configuration file.
With topology domains: set this to"ManualLB". You must configure a
third-party load balancer (such as F5 BIG-IP or Citrix) if you want to use
topology domains.
Without topology domains: set this to"ManualLB"or"MetalLB".
Use"ManualLB"if you have a third-party load balancer or"MetalLB"for
our bundled solution. Optionally, you can configure a different kind of
load balancer for control-plane traffic. For more information, seemasterNode.controlPlaneLoadBalancer.
1.31
Required ImmutableString Prepopulated: "MetalLB"
The kind of load balancer that you can use depends on whether you will
set up the cluster to usetopology domains. The
cluster is assumed to use topology domains if theinfraConfigFilePathfield is configured in the admin cluster configuration file.
With topology domains: set this to"ManualLB". You must
configure a third-party load balancer (such as F5 BIG-IP or
Citrix) if you want to use topology domains.
Without topology domains: set this to"ManualLB"or"MetalLB".
Use"ManualLB"if you have a third-party load balancer or"MetalLB"for
our bundled solution.
1.30
Required ImmutableString Prepopulated: "MetalLB"
Set this to"ManualLB"or"MetalLB". Use"ManualLB"if you have a
third-party load balancer (such as F5 BIG-IP or Citrix) or"MetalLB"for our
bundled solution.
Although you can upgrade a cluster that haskindset to"F5BigIP"or"Seesaw", you can't create new clusters. For information on migrating load
balancing configurations, seePlan cluster migration to recommended features.
Example:
loadBalancer:kind:"MetalLB"
1.29 and earlier
Required ImmutableString Prepopulated: "MetalLB"
Set this to"ManualLB","F5BigIP","Seesaw", or"MetalLB".
To enable Dataplane V2 and Controlplane V2, we recommend that you use"ManualLB"if you have a third-party load balancer (such as F5 BIG-IP or
Citrix) or"MetalLB"for our bundled solution.
Example:
loadBalancer:kind:"MetalLB"
When you create user clusters using the Google Cloud console, the
gcloud CLI, or Terraform, the kind of load balancer for the admin
cluster and its user clusters must be the same. The only exception is if the
admin cluster uses Seesaw, then the user clusters can use MetalLB. If you want
your admin and user clusters to use different kinds of load balancers, you must
create user clusters using thegkectlcommand-line tool.
loadBalancer.manualLB
If you setloadbalancer.kindto"manualLB", fill in this section. Otherwise,
remove this section or leave it commented out.
loadBalancer.manualLB.ingressHTTPNodePort
Required ifloadBalancer.kind=ManualLB(see Version note) Immutable Integer Prepopulated: 30243
The ingress proxy in a user cluster is exposed by aKubernetes Service of typeLoadBalancer.
The Service has aServicePortfor HTTP. Choose anodePortvalue for the HTTP ServicePort, and set this field
to thenodePortvalue.
Version note: In version 1.30 and higher, ingress node ports are optional
for clusters using Controlplane V2.
Required ifloadBalancer.kind=ManualLB (see Version note) Immutable Integer Prepopulated: 30879
The ingress proxy in a user cluster is exposed by a Service
of type LoadBalancer. The Service has a ServicePort for HTTPS. Choose anodePortvalue for the HTTPS ServicePort, and set this field to thenodePortvalue.
Version note: In version 1.30 and higher, ingress node ports are optional
for clusters using Controlplane V2.
The Kubernetes API server of a user cluster runs in the admin cluster,
and is exposed by a Service of typeLoadBalancer. You must choose anodePortvalue for the Service.
The Kubernetes API server of a user cluster that uses kubeception runs in the
admin cluster, and is exposed by a Service of typeLoadBalancer. The
Konnectivity server reuses this service with a differentnodePortvalue. You
must choose anodePortvalue for the Konnectivity server.
Set this field to thenodePortvalue for the Konnectivity server.
In 1.30 and higher, the value"F5BigIP"isn't allowed forloadbalancer.kindfor new user clusters. If theloadBalancer.f5BigIPsection is in your configuration file, remove it or comment it out.
You can still use your F5 BIG-IP load balancer with new user clusters,
but the configuration is different. For configuration details, seeEnabling manual load balancing mode.
If you setloadbalancer.kindto"F5BigIP", fill in this section. Otherwise,
remove this section or leave it commented out.
To enable new and advanced features, we recommend that you configure manual
load balancing for your F5 BIG-IP load balancer. To enable manual load
balancing, setloadbalancer.kindto"ManualLB"and fill in theloadBalancer.manualLBsection. For more
information, seeEnabling manual load balancing mode.
If you have an existing F5-BIG-IP load balancer and the cluster configuration
uses this section, after you have upgraded to 1.29 or higher, we recommend
that youmigrate to manual load balancing.
loadBalancer.f5BigIP.address
1.30 and higher
Not allowed for new clusters Required ifloadBalancer.kind="F5BigIP" String
The address of your F5 BIG-IP load balancer.
Example:
loadBalancer:f5BigIP:address:"203.0.113.2"
1.29 and lower
Required ifloadBalancer.kind="F5BigIP" String
The address of your F5 BIG-IP load balancer.
Example:
loadBalancer:f5BigIP:address:"203.0.113.2"
loadBalancer.f5BigIP.credentials.fileRef.path
1.30 and higher
Not allowed for new clusters Required ifloadBalancer.kind="F5BigIP" String
The path of acredentials filethat holds the username and password of an account that Google Distributed Cloud
can use to connect to your F5 BIG-IP load balancer.
The user account must have auser rolethat has sufficient permissions to set up and manage the load balancer. Either
the Administrator role or the Resource Administrator role is sufficient.
The path of acredentials filethat holds the username and password of an account that Google Distributed Cloud
can use to connect to your F5 BIG-IP load balancer.
The user account must have auser rolethat has sufficient permissions to set up and manage the load balancer. Either
the Administrator role or the Resource Administrator role is sufficient.
Not allowed for new clusters Required ifloadBalancer.kind="F5BigIP"and you are using SNAT String
The name of your SNAT pool.
Example:
loadBalancer:f5BigIP:snatPoolName:"my-snat-pool"
1.29 and lower
Required ifloadBalancer.kind="F5BigIP"and you are using SNAT String
The name of your SNAT pool.
Example:
loadBalancer:f5BigIP:snatPoolName:"my-snat-pool"
loadBalancer.seesaw
1.30 and higher
In 1.30 and higher, the value"Seesaw"isn't allowed forloadbalancer.kindfor new user clusters because this load balancer isn't
supported with new and advanced features. If theloadBalancer.seesawsection is in your configuration file, remove it or comment it out.
Instead, you can configure the bundled MetalLB load balancer. To enable the
MetalLB load balancer, setloadbalancer.kindto"MetalLB"and fill in theloadBalancer.metalLBsection. For more
information, seeBundled load balancing with MetalLB.
1.29 and lower
If you setloadbalancer.kindto"Seesaw", fill in this section. Otherwise,
remove this section or leave it commented out.
Note the following limitations with the SeeSaw load balancer:
To use these features, we recommend that you configure the MetalLB
load balancer. To enable the MetalLB load balancer, setloadbalancer.kindto"MetalLB"and fill in theloadBalancer.metalLBsection. For more
information, seeBundled load balancing with MetalLB.
loadBalancer.seesaw.ipBlockFilePath
1.30 and higher
Not allowed for new clusters Required ifloadBalancer.kind=Seesaw Immutable String
Not allowed for new clusters Required ifloadBalancer.kind=Seesaw Mutable Integer Prepopulated: 3072
The number of mebibytes of memory for each of your Seesaw VMs.
Example:
loadBalancer:seesaw:memoryMB:8192
Note: This field specifies the number of mebibytes of memory, not the
number of megabytes. One mebibyte is 220= 1,048,576 bytes. One
megabyte is 106= 1,000,000 bytes.
The number of mebibytes of memory for each of your Seesaw VMs.
Example:
loadBalancer:seesaw:memoryMB:8192
Note: This field specifies the number of mebibytes of memory, not the
number of megabytes. One mebibyte is 220= 1,048,576 bytes. One
megabyte is 106= 1,000,000 bytes.
loadBalancer.seesaw.vCenter.networkName
1.30 and higher
Not allowed for new clusters ImmutableString Default: Same as the cluster nodes
The name of the vCenter network that contains your Seesaw VMs.
Not allowed for new clusters Immutable Relevant ifloadBalancer.kind=Seesaw Boolean Prepopulated: false Default: false
If you want to create a high-availability (HA) Seesaw load balancer, set this
totrue. Otherwise set this tofalse. An HA Seesaw load balancer uses
a(Master, Backup) pairof VMs.
If you want to create a high-availability (HA) Seesaw load balancer, set this
totrue. Otherwise set this tofalse. An HA Seesaw load balancer uses
a(Master, Backup) pairof VMs.
Example:
loadBalancer:seesaw:enableHA:true
loadBalancer.seesaw.disableVRRPMAC
1.30 and higher
Not allowed for new clusters Immutable Relevant ifloadBalancer.kind=Seesaw Boolean Prepopulated: true Default: true
If set totrue(recommended), the Seesaw load balancer doesn't useMAC learningfor failover. Instead, it usesgratuitous ARP.
If this field is set this tofalse, the Seesaw load balancer uses MAC
learning. If you are using vSphere 7 or later, and you have a
high-availability Seesaw load balancer, then this field must be set totrue.
If you set this totrue(recommended), the Seesaw load balancer doesn't useMAC learningfor failover. Instead, it usesgratuitous ARP.
If you set this tofalse, the Seesaw load balancer uses MAC learning. If you
are using vSphere 7 or later, and you have a high-availability Seesaw load
balancer, then you must set this totrue.
Example:
loadBalancer:seesaw:disableVRRPMAC:true
loadBalancer.metalLB
If you setloadbalancer.kindto"MetalLB", fill in this section. Otherwise,
remove this section or leave it commented out.
Required ifloadBalancer.kind=MetalLB Mutable (see exception)
Array of objects, each of which contains information about an address pool
to be used by the MetalLB load balancer.
1.32 and higher
The behavior of this field is the same whenenableAdvancedClusteris set totrue(advanced cluster enabled) orfalse(advanced cluster isn't enabled).
In both cases, the array isn't totally mutable. You can add address pools, but
removing address pools from an existing address pool array isn't supported.
1.31
The behavior of this field depends on whetherenableAdvancedClusteris set totrue(advanced cluster enabled) orfalse(advanced cluster isn't enabled):
If advanced cluster is enabled: the array isn't totally mutable. You can
add address pools, but removing address pools from an existing address pool
array isn't supported.
If advanced cluster isn't enabled: the array is mutable. You can add and
remove address pools from an existing address pool array.
1.30 and earlier
You can add and remove address pools from an existing address pool
array.
loadBalancer.metalLB.addressPools[i].name
Required ifloadBalancer.kind=MetalLB Mutable (see exception) String
A name of your choice for the address pool.
1.32 and higher
The behavior of this field is the same as whenenableAdvancedClusteris set totrue(advanced cluster enabled) orfalse(advanced cluster isn't enabled).
In both cases, changing the name after the cluster is created isn't
supported.
1.31
The behavior of this field depends on whetherenableAdvancedClusteris set totrue(advanced cluster enabled) orfalse(advanced cluster isn't enabled):
If advanced cluster is enabled: changing the name after the cluster is
created isn't supported.
If advanced cluster isn't enabled: you can change the name of the pool
after the cluster is created.
1.30 and earlier
You can change the name of the pool after the cluster is created.
Required ifloadBalancer.kind=MetalLB Mutable (see exception)
Array of strings, each of which is a range of addresses. Each range must
be in CIDR format or hyphenated range format.
1.32 and higher
The behavior of this field is the same as whenenableAdvancedClusteris set totrue(advanced cluster enabled) orfalse(advanced cluster isn't enabled).
In both cases, you can add addresses to an existing address pool, but removing
addresses isn't supported.
1.31
The behavior of this field depends on whetherenableAdvancedClusteris set totrue(advanced cluster enabled) orfalse(advanced cluster isn't enabled):
If advanced cluster is enabled: you can add addresses to an existing
address pool, but removing addresses isn't supported.
If advanced cluster isn't enabled: you can add and remove addresses from an
existing address pool.
1.30 and earlier
You can add and remove addresses from an existing address pool.
If you set this totrue, the MetalLB controller will not assign IP
addresses ending in .0 or .255 to Services. This avoids the problem of buggy
consumer devices mistakenly dropping traffic sent to those special IP addresses.
If you do not want the MetalLB controller to automatically assign IP addresses
from this pool to Services, set this totrue. Then a developer can create a
Service of typeLoadBalancerand manually specify one of the addresses from
the pool.
This field controls the Container Network Interface (CNI) that the cluster
uses. Enabling Dataplane V2 is required to use Controlplane V2. You can
change the field fromfalsetotrueto enable Dataplane V2, but
disabling Dataplane V2 isn't allowed.
In version 1.31, Dataplane V2 is required for all clusters. Before upgrading
to 1.31, follow the steps inEnable Dataplane V2.
The benefits of Dataplane V2 include the following:
Dataplane V2 provides you with a more advanced and capable Container Network
Interface (CNI) when compared with the previous CNI option,Calico. Calico is in maintenance
mode, which means it receives only critical bug fixes and security updates,
but no new feature development. In contrast, Dataplane V2 is actively
developed and enhanced, ensuring that you have access to the latest
networking innovations and capabilities.
Dataplane V2 is the preferred CNI for GKE and other
Google Distributed Cloud products.
Mutable String Possible values: "snat", "dsr" Prepopulated: "snat" Default: "snat"
The forwarding mode for a cluster that has Dataplane V2 enabled.
With source network address translation (SNAT) mode, a packet is SNAT-translated
when it is forwarded from a load balancer node to a backend Pod. The Pod cannot
see the original source IP address, and the return packet must pass through the
load balancer node.
With direct server return (DSR) mode, a packet retains its original source IP
address when it is forwarded from a load balancer node to a backend Pod. The
Pod can see the original source IP address, and the return packet goes directly
to the client without passing through the load balancer node.
If you plan to create anegress NAT gateway, set this totrue. Otherwise set it tofalse.
If you set this field totrue, you must also setenableDataplaneV2totrue.
Example:
advancedNetworking: true
disableBundledIngress
Set this totrueif you want todisable bundled ingressfor the cluster. Otherwise, set it tofalse.
Boolean MutablePrepopulated: false Default: false
Example:
disableBundledIngress: true
storage.vSphereCSIDisabled
If you want to disable the deployment of vSphere CSI components, set this totrue. Otherwise, set it tofalse.
IfinfraConfigFilePathis
configured in the admin cluster configuration file, this field must betrue.
Mutable BooleanPrepopulated: false Default: false
Example:
storage:
vSphereCSIDisabled: false
masterNode
This section contains information about the nodes that
serve as control-plane nodes for this user cluster.
masterNode.controlPlaneLoadBalancer
1.32 and higher
Optionally, include this section to specify the kind of load balancer to use
for control-plane traffic in the user cluster. IncludemasterNode.controlPlaneLoadBalancer.modein your configuration file
if you want to explicitly set the kind of load balancer to use rather than
relying on the default value. Additionally, you must setloadBalancer.kindin your configuration file
to specify the kind of load balancer to use for the data plane.
masterNode.controlPlaneLoadBalancer.mode
Optional ImmutableString Default: Depends on whether the cluster uses topology domains
The kind of load balancer that you can use depends on whether you will
set up the cluster to usetopology domains. The
cluster is assumed to use topology domains if theinfraConfigFilePathfield is configured in the admin cluster configuration file.
With topology domains: specify"manual", which is the default
value. You must configure a third-party load balancer (such as F5 BIG-IP or
Citrix) if you want to usetopology domains.
Without topology domains: specify either"manual"or"bundled".
Use"manual"if you have a third-party load balancer or"bundled"for
our bundled solution, which useskeepalived+haproxyrunning on the control-plane nodes. The default value is "bundled".
This section is unavailable. Instead, useloadBalancer.kindto specify the kind of
load balancer for the user cluster to use.
masterNode.cpus
Mutable IntegerPrepopulated: 4 Default: 4
The number of CPUs for each node that serves as a control plane
for this user cluster.
Example:
masterNode:
cpus: 8
masterNode.memoryMB
Mutable IntegerPrepopulated: 8192 Default: 8192
The mebibytes of memory for each node that serves as a
control plane for this user cluster. Must be a multiple of 4.
Example:
masterNode:
memoryMB: 8192
Note:This field specifies the number of mebibytes of memory, not the number
of megabytes. One mebibyte is 2^20 = 1,048,576 bytes. One megabyte is
10^6 = 1,000,000 bytes.
masterNode.replicas
Immutable Integer Possible values: 1 or 3 Prepopulated: 1 Default: 1
The number of control-plane nodes for this user cluster. This number cannot be
changed once you have created the cluster. If you want to update the number of
replicas later, you must recreate the user cluster.
If theenableAdvancedClusterfield istrue, then you must set this field to3. Only highly-available (HA) user
clusters are supported on advanced clusters.
Example:
masterNode:
replicas: 3
masterNode.autoResize.enabled
Mutable BooleanPrepopulated: false Default: false
Set this totrueto enable automatic resizing of the control-plane
nodes for the user cluster. Otherwise, set this tofalse.
If you specify a value for this field, don't specify a value formasterNode.vsphere.storagePolicyName. ThemasterNode.vsphere.datastorefield
is immutable except when you set the field to an empty string when youmigrate a datastore to Storage Policy Based Management (SPBM).
masterNode.vsphere.storagePolicyName
Optional Immutable String Default: The value ofvCenter.storagePolicyName
If you specify a value for this field, don't specify a value formasterNode.vsphere.datastore.
masterNode.topologyDomains
1.32 and higher
Preview Optional Array of strings | Allows one element or three different elements Immutable Default:vSphereInfraConfig.defaultTopologyDomainif specified in thevSphere infrastructure configuration file
An array of topology domains. IfinfraConfigFilePathis configured in the admin cluster configuration file
(which indicates the cluster will usetopology domains), optionally
include this field. The number of topology domains in the array determines
how the user cluster control-plane nodes are deployed, as follows:
One element: all user cluster control-plane nodes will be
deployed in the specified topology domain.
Three elements: each user cluster control-plane node will be deployed
in a different topology domain (that is, one node per topology domain).
1.31
Preview Optional Array of strings | But only one element is supported Immutable Default:vSphereInfraConfig.defaultTopologyDomainif specified in thevSphere infrastructure configuration file
An array of topology domains.
IfinfraConfigFilePathis configured in the admin cluster configuration file (which indicates the
cluster will usetopology domains), optionally
include this field. The user cluster control-plane nodes will be deployed in
the specified topology domain.
1.30 and lower
Not available.
nodePools
Required Mutable Array of objects, each of which describes a node pool.
A name of your choice for the node pool. The name must:
contain at most 40 characters
contain only lowercase alphanumeric characters or a hyphen (-)
start with an alphabetic character
end with an alphanumeric character
Example:
nodePools:
- name: "my-node-pool-1"
nodePools[i].gkeOnPremVersion
When you upgrade a user cluster, you can specify that selected node pools remain
at the previous version.
If you want this node pool to remain at the previous version, set this to the
previous version. Otherwise, remove this field or set it to the empty string.
For more information, seeUpgrade a user cluster.
Mutable String Default: The clustergkeOnPremVersion
The mebibytes of memory for each node in the pool. Must be a multiple of 4.
Example:
nodePools"
- name: "my-node-pool"
memoryMB: 8192
Note:This field specifies the number of mebibytes of memory, not the number
of megabytes. One mebibyte is 2^20 = 1,048,576 bytes. One megabyte is
10^6 = 1,000,000 bytes.
nodePools[i].replicas
Required Mutable Integer Prepopulated: 3 Possible values: The total number of untainted nodes across all node pools in
the cluster must be at least 3.
The number of nodes in the pool.
Example:
nodePools:
- name: "my-node-pool"
replicas: 5
nodePools[i].bootDiskSizeGB
Mutable IntegerPrepopulated: 40 Default: 40
The size of the boot disk in gibibytes for each node in the pool.
The type of OS image to run on the VMs in the node pool.
In version 1.32, Windows Server node pools are deprecated and will be
unavailable in version 1.33 and higher. Support for Windows Server node pools
ends on May 5, 2026. We recommend that you don't use "windows" as the OS image
type on new clusters.
Note the following limitation with advanced clusters:
Version 1.31: if theenableAdvancedClusterfield istrue, onlyubuntu-cgroupv2andubuntu_containerdare supported
on advanced clusters.
Version 1.32: All OS image types except "windows" are supported on advanced
clusters.
The kubelet can't apply labels to itself in certain namespaces for
security reasons.
The reserved node label namespaces are :kubernetes.io,k8s.io,googleapis.com.
nodePools[i].taints
Mutable Array of objects, each of which describes aKubernetes taintthat is applied to each
node in the pool. Taints are key-value pairs associated with aneffect. Taints
are used with tolerations for Pod scheduling. Specify one of the
following for theeffect:NoSchedule,PreferNoSchedule,NoExecute.
IfinfraConfigFilePathis configured in the admin cluster configuration file, remove all fields
in thenodePools[i].vspheresection except fornodePools[i].vsphere.tags.
nodePools[i].vsphere.datastore
Mutable String Default: The value ofvCenter.datastore
The name of the vCenter datastore where the nodes will be created.
The behavior of this field is the same whenenableAdvancedClusteris set totrue(advanced cluster enabled) orfalse(advanced cluster isn't enabled).
In both cases, set this totrueif you want to allow the MetalLB speaker to
run on the nodes in the pool. Otherwise, set it tofalse.
1.31
The behavior of this field depends on whetherenableAdvancedClusteris set totrue(advanced cluster enabled) orfalse(advanced cluster isn't enabled):
If advanced cluster is enabled: this field has no effect because the
MetalLB speaker will always run on the user cluster's control-plane nodes.
If advanced cluster isn't enabled: set this totrueif you want to allow
the MetalLB speaker to run on the nodes in the pool. Otherwise, set it tofalse.
1.29 and lower
Set this totrueif you want to allow the MetalLB speaker to run on the
nodes in the pool. Otherwise, set it tofalse.
Array of strings | But only one element is supported Immutable Default:vSphereInfraConfig.defaultTopologyDomainif specified in thevSphere infrastructure configuration file
Nodes in this node pool will be put into the topology domain specified
by this field. For each node pool, only one topology domain is allowed.
All nodes in a node pool will be put into a single topology domain.
1.30 and lower
Not available.
schedulerConfiguration
1.32 and higher
Preview Optional
When setting uptopology domains,
you can optionally set up additional configurations that will be passed tokube-scheduler.
An object that defines a cluster-level default topology spread constraint rule
that is applied to Pod scheduling. When the user cluster is created with
topology domains, if this rule is configured, thekube-schedulertakes
the default topology key and spreads Pods of Deployments, Statefulsets,
and Replicasets on it by default. The structure is the same as the Kubernetes
cluster-level default constraints.
If this field istrueGoogle Distributed Cloud creates VMwareDistributed Resource Scheduler(DRS) anti-affinity rules for your user cluster's nodes, causing them to be
spread across at least three physical ESXi hosts in your datacenter.
This feature requires that your vSphere environment meets the following
conditions:
VMware DRS is enabled. VMware DRS requires vSphere Enterprise Plus license
edition.
Even though the rule requires that the cluster nodes are spread across three
ESXi hosts, we strongly recommend that you have at least four ESXi hosts
available.
If you don't have DRS enabled, or if you don't have at least four hosts where
vSphere VMs can be scheduled, setantiAffinityGroups.enabledtofalse.
Note the following limitation with advanced clusters:
Version 1.31: if theenableAdvancedClusterfield istrue,
anti-affinity rules aren't supported on advanced clusters, and you must setantiAffinityGroups.enabledtofalse.
Version 1.32: anti-affinity rules are supported on advanced clusters.
Example:
antiAffinityGroups:
enabled: false
enableVMTracking
Preview Immutable Prepopulated: false
Set this totrueto enable VM tracking with vSphere tags. Otherwise, set it
tofalse.
Mutable IntegerPossible values: 0 or 1 Prepopulated: 0
Default: 0
The number of node pools to update at a time. A value of1specifies that one
node pool can be updated at a time. A value of0specifies that an unlimited
number of node pools can be updated at a time.
Note the following limitation with advanced clusters:
Version 1.31: if theenableAdvancedClusterfield istrue,
node pool update policies aren't supported on advanced clusters, so remove
this section from your configuration file.
Version 1.32: node pool update policies are supported on advanced clusters.
The maximum number of machines in a node pool that can be updated simultaneously
during an update or upgrade. Applies to any node pool that doesn't specify its
ownupdate strategy.
If you want to provide an additional serving certificate for the cluster's
Kubernetes API server, fill in this section. Otherwise, remove this section or
leave it commented out.
authentication.sni.certPath
String
The path of a serving certificate for the Kubernetes API server.
This section contains information about the Google Cloud project and service account
you want to use toregister your clusterto a Google Cloud fleet.
gkeConnect.projectID
Required Immutable String
The ID of yourfleet host project.
For new clusters, this project ID must be the same as the ID set instackdriver.projectIDandcloudAuditLogging.projectID. If the project IDs
aren't the same, cluster creation fails. This requirement isn't applied to
existing clusters.
Example:
gkeConnect:
projectID: "my-fleet-host-project"
gkeConnect.location
Immutable String Default: global
Each cluster's fleet membership is managed by the Fleet service
(gkehub.googleapis.com) and the Connect service
(gkeconnect.googleapis.com). The location of the services can be global
or regional. In 1.28 and later, you can optionally specify the Google Cloud
region in which the Fleet and the Connect services run. If not specified,
the global instances of the services are used. Note the following:
User clusters created prior to 1.28 are managed by the global Fleet and
Connect services.
New clusters created usingthe GKE On-Prem API clients—
the Google Cloud console, the Google Cloud CLI, or Terraform—use the same
region that you specify for the GKE On-Prem API.
For new clusters, if you include this field, the region that you specify must
be the same as the region configured incloudAuditLogging.clusterLocation,stackdriver.clusterLocation, andgkeOnPremAPI.location. If the regions
aren't the same, cluster creation fails.
In 1.16 and later, if the GKE On-Prem API is enabled in your
Google Cloud project, all clusters in the project areenrolled in the GKE On-Prem APIautomatically in the region configured instackdriver.clusterLocation.
If you want to enroll all clusters in the project in the GKE On-Prem API,
be sure to do the steps inBefore you beginto
activate and use the GKE On-Prem API in the project.
If you don't want to enroll the cluster in the GKE On-Prem API, include
this section and setgkeOnPremAPI.enabledtofalse. If you don't
want to enroll any clusters in the project, disablegkeonprem.googleapis.com(the service name for the GKE On-Prem API)
in the project. For instructions, seeDisabling services.
Enrolling your user cluster in the GKE On-Prem API lets you use
the standard tools—the Google Cloud console, the Google Cloud CLI, andTerraform— to manage the
lifecycle of the cluster. Additionally, enrolling the cluster lets you
use the console or the gcloud CLI to view
cluster details. For example, you run cangcloudcommands toget information about your user cluster.
After you add this section and create or update the cluster, if subsequently
you remove the section and update the cluster, the update will fail.
gkeOnPremAPI.enabled
Mutable Boolean Default:true
By default, the cluster is enrolled in the GKE On-Prem API if the
GKE On-Prem API is enabled in your project. Set tofalseif you
don't want to enroll the cluster.
After the cluster is enrolled in the GKE On-Prem API, if you need to
unenroll the cluster, make the following change and then update the cluster:
The Google Cloud region where the GKE On-Prem API runs and stores
cluster metadata. Choose one of thesupported regions.
You must use the same region that is configured ingkeConnect.location,stackdriver.clusterLocationandcloudAuditLogging.clusterLocation. IfgkeOnPremAPI.enabledisfalse, don't include this field.
Required for Logging and Monitoring Immutable String
The ID of yourfleet host project.
For new clusters, this project ID must be the same as the ID set ingkeConnect.projectIDandcloudAuditLogging.projectID. If the project IDs
aren't the same, cluster creation fails. This requirement isn't applied to
existing clusters.
If needed, you can configure a log router in this project to route logs into
log buckets in another project. For information on how to configure the log
router, seeSupported destinations.
Example:
stackdriver:
projectID: "my-fleet-host-project"
stackdriver.clusterLocation
Required for Logging and Monitoring ImmutableString Prepopulated: "us-central1"
The Google Cloud region where you want to route and store
Cloud Monitoring metrics. We recommend that you choose a region that's near
your on-premises data center.
You specify the Cloud Logging logs routing and storage location in the
Log Router configuration. For more information about logs routing, seeRouting and storage overview.
The Stackdriver Operator (stackdriver-operator) attaches the value from this
field to each log entry and metric before they're routed to Google Cloud. These
attached labels can be useful for filtering your logs and metrics in the
Logs Explorer and Metrics Explorer respectively.
For new clusters, if you include thegkeOnPremAPIandcloudAuditLoggingsections in the configuration file, the region that you set here must be
the same region that you set ingkeConnect.location,gkeOnPremAPI.location,
andcloudAuditLogging.clusterLocation. If the regions aren't the same,
cluster creation fails.
Example:
stackdriver:
clusterLocation: "us-central1"
stackdriver.enableVPC
Immutable Boolean Prepopulated: false
If your cluster's network is controlled by aVPC, set this totrue.
This ensures that all telemetry flows through Google's restricted IP addresses.
Otherwise, set this tofalse.
Example:
stackdriver:
enableVPC: false
stackdriver.serviceAccountKeyPath
Required for Logging and Monitoring Mutable String
The path of the JSON key file for your logging-monitoring service account.
To update the value of this field, usegkectl update cluster.
Set this totrueto disable the collection of metrics from vSphere.
Otherwise, set it tofalse.
Example:
stackdriver:
disableVsphereResourceMetrics: true
usageMetering
1.32 and higher
The usage metering feature is unsupported in version 1.32 and higher.
Don't include this section when you create new clusters. However, existing
clusters using this feature will continue to function. As the alternative, we
recommend that you use the predefined dashboard,Anthos Cluster Utilization Metering,
to understand resource usage at different levels. Contact Cloud Customer Care if
the alternative does not satisfy your use cases.
1.30 and 1.31
We recommend that you don't use this preview feature when you create new
clusters. However, existing clusters using this feature will continue to
function. As the alternative, we recommend that you use the predefined
dashboard,Anthos Cluster Utilization Metering,
to understand resource usage at different levels.
If theenableAdvancedClusterfield istrue, remove this section. Usage metering isn't supported on advanced
clusters.
1.29 and lower
PreviewImmutable
We recommend that you don't use this preview feature when you create new
clusters. However, existing clusters using this feature will continue to
function. As the alternative, we recommend that you use the predefined
dashboard,Anthos Cluster Utilization Metering,
to understand resource usage at different levels.
usageMetering.bigQueryProjectID
Preview Required for usage meteringImmutable String
The ID of the Google Cloud project where you want to store usage metering
data.
Example:
usageMetering:
bigQueryProjectID: "my-bq-project"
usageMetering.bigQueryDatasetID
Preview Required for usage meteringImmutable String
The ID of the BigQuery dataset where you want to store usage metering data.
Example:
usageMetering:
bigQueryDatasetID: "my-bq-dataset"
usageMetering.bigQueryServiceAccountKeyPath
Preview Required for usage meteringImmutable String.
The path of the JSON key file for your BigQuery service account.
To update the value of this field, usegkectl update cluster.
Preview Required for usage metering Immutable Boolean Prepopulated: false
Set this totrueif you want to enable consumption-based metering.
Otherwise set this to false.
Example:
usageMetering:
enableConsumptionMetering: true
cloudAuditLogging
If you want to integrate the audit logs from your cluster's Kubernetes API
server with Cloud Audit Logs, fill in this section. Otherwise, remove this
section or leave it commented out.
cloudAuditLogging.projectID
Required for Cloud Audit Logs Immutable String
The ID of yourfleet host project.
For new clusters, this project ID must be the same as the ID set ingkeConnect.projecIDandstackdriver.projectID. If the project IDs
aren't the same, cluster creation fails. This requirement isn't applied to
existing clusters.
If needed, you can configure a log router in this project to route logs into
log buckets in another project. For information on how to configure the log
router, seeSupported destinations.
The Google Cloud region where you want to store audit logs. It is
a good idea to choose a region that is near your on-premises data center
For new clusters, if you include thegkeOnPremAPIandstackdriversections in the configuration file, the region that you set here must be
the same region that you set ingkeConnect.location,gkeOnPremAPI.location, andstackdriver.clusterLocation. If the regions
aren't the same, cluster creation fails.
Example:
cloudAuditLogging:
clusterLocation: "us-central1"
cloudAuditLogging.serviceAccountKeyPath
Required for Cloud Audit Logs Mutable String
The path of the JSON key file for your audit-logging service account.
Set this totrueto enable node auto repair. Otherwise, set it tofalse.
Example:
autoRepair:
enabled: true
secretsEncryption
If you want to encrypt Secrets without the need for an external KMS
(Key Management Service), or any other dependencies, fill in this section.
Otherwise, remove this section or leave it commented out.
If you will be creating the cluster withenableAdvancedClusterset totrue(which is required forsetting up topology domains),
then remove this section. This feature isn't supported with advanced clusters.
secretsEncryption.mode
Required for Secrets encryption Immutable String Possible value: "GeneratedKey" Prepopulated: "GeneratedKey"
The Secret encryption mode.
secretsEncryption:
mode: "GeneratedKey"
secretsEncryption.generatedKey.keyVersion
Required for Secrets encryption MutableInteger Prepopulated: 1
An integer of your choice to use for the key version number. We recommend that
you start with1.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-12-17 UTC."],[],[]]