REST Resource: projects.locations.clusters

Resource: Cluster

A Google Distributed Cloud Edge Kubernetes cluster.

JSON representation
{
  "name": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "fleet": {
    object (Fleet)
  },
  "networking": {
    object (ClusterNetworking)
  },
  "authorization": {
    object (Authorization)
  },
  "defaultMaxPodsPerNode": integer,
  "endpoint": string,
  "port": integer,
  "clusterCaCertificate": string,
  "maintenancePolicy": {
    object (MaintenancePolicy)
  },
  "controlPlaneVersion": string,
  "nodeVersion": string,
  "controlPlane": {
    object (ControlPlane)
  },
  "systemAddonsConfig": {
    object (SystemAddonsConfig)
  },
  "externalLoadBalancerIpv4AddressPools": [
    string
  ],
  "controlPlaneEncryption": {
    object (ControlPlaneEncryption)
  },
  "status": enum (Status),
  "maintenanceEvents": [
    {
      object (MaintenanceEvent)
    }
  ],
  "targetVersion": string,
  "releaseChannel": enum (ReleaseChannel),
  "survivabilityConfig": {
    object (SurvivabilityConfig)
  },
  "externalLoadBalancerIpv6AddressPools": [
    string
  ],
  "connectionState": {
    object (ConnectionState)
  }
}
Fields
name

string

Required. The resource name of the cluster.

createTime

string (Timestamp format)

Output only. The time when the cluster was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. The time when the cluster was last updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

labels

map (key: string, value: string)

Labels associated with this resource.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

fleet

object (Fleet)

Required. Fleet configuration.

networking

object (ClusterNetworking)

Required. Cluster-wide networking configuration.

authorization

object (Authorization)

Required. Immutable. RBAC policy that will be applied and managed by GEC.

defaultMaxPodsPerNode

integer

Optional. The default maximum number of pods per node used if a maximum value is not specified explicitly for a node pool in this cluster. If unspecified, the Kubernetes default value will be used.

endpoint

string

Output only. The IP address of the Kubernetes API server.

port

integer

Output only. The port number of the Kubernetes API server.

clusterCaCertificate

string

Output only. The PEM-encoded public certificate of the cluster's CA.

maintenancePolicy

object (MaintenancePolicy)

Optional. Cluster-wide maintenance policy configuration.

controlPlaneVersion

string

Output only. The control plane release version

nodeVersion

string

Output only. The lowest release version among all worker nodes. This field can be empty if the cluster does not have any worker nodes.

controlPlane

object (ControlPlane)

Optional. The configuration of the cluster control plane.

systemAddonsConfig

object (SystemAddonsConfig)

Optional. The configuration of the system add-ons.

externalLoadBalancerIpv4AddressPools[]

string

Optional. IPv4 address pools for cluster data plane external load balancing.

controlPlaneEncryption

object (ControlPlaneEncryption)

Optional. Remote control plane disk encryption options. This field is only used when enabling CMEK support.

status

enum (Status)

Output only. The current status of the cluster.

maintenanceEvents[]

object (MaintenanceEvent)

Output only. All the maintenance events scheduled for the cluster, including the ones ongoing, planned for the future and done in the past (up to 90 days).

targetVersion

string

Optional. The target cluster version. For example: "1.5.0".

releaseChannel

enum (ReleaseChannel)

Optional. The release channel a cluster is subscribed to.

survivabilityConfig

object (SurvivabilityConfig)

Optional. Configuration of the cluster survivability, e.g., for the case when network connectivity is lost. Note: This only applies to local control plane clusters.

externalLoadBalancerIpv6AddressPools[]

string

Optional. IPv6 address pools for cluster data plane external load balancing.

connectionState

object (ConnectionState)

Output only. The current connection state of the cluster.

Fleet

Fleet related configuration.

Fleets are a Google Cloud concept for logically organizing clusters, letting you use and manage multi-cluster capabilities and apply consistent policies across your systems.

JSON representation
{
  "project": string,
  "membership": string
}
Fields
project

string

Required. The name of the Fleet host project where this cluster will be registered.

Project names are formatted as projects/<project-number>.

membership

string

Output only. The name of the managed Hub Membership resource associated to this cluster.

Membership names are formatted as projects/<project-number>/locations/global/membership/<cluster-id>.

ClusterNetworking

Cluster-wide networking configuration.

JSON representation
{
  "clusterIpv4CidrBlocks": [
    string
  ],
  "servicesIpv4CidrBlocks": [
    string
  ]
}
Fields
clusterIpv4CidrBlocks[]

string

Required. All pods in the cluster are assigned an RFC1918 IPv4 address from these blocks. Only a single block is supported. This field cannot be changed after creation.

servicesIpv4CidrBlocks[]

string

Required. All services in the cluster are assigned an RFC1918 IPv4 address from these blocks. Only a single block is supported. This field cannot be changed after creation.

Authorization

RBAC policy that will be applied and managed by GEC.

JSON representation
{
  "adminUsers": {
    object (ClusterUser)
  }
}
Fields
adminUsers

object (ClusterUser)

Required. User that will be granted the cluster-admin role on the cluster, providing full access to the cluster. Currently, this is a singular field, but will be expanded to allow multiple admins in the future.

ClusterUser

A user principal for an RBAC policy.

JSON representation
{
  "username": string
}
Fields
username

string

Required. An active Google username.

MaintenancePolicy

Maintenance policy configuration.

JSON representation
{
  "window": {
    object (MaintenanceWindow)
  },
  "maintenanceExclusions": [
    {
      object (MaintenanceExclusionWindow)
    }
  ]
}
Fields
window

object (MaintenanceWindow)

Specifies the maintenance window in which maintenance may be performed.

maintenanceExclusions[]

object (MaintenanceExclusionWindow)

Optional. Exclusions to automatic maintenance. Non-emergency maintenance should not occur in these windows. Each exclusion has a unique name and may be active or expired. The max number of maintenance exclusions allowed at a given time is 3.

MaintenanceWindow

Maintenance window configuration

JSON representation
{
  "recurringWindow": {
    object (RecurringTimeWindow)
  }
}
Fields
recurringWindow

object (RecurringTimeWindow)

Configuration of a recurring maintenance window.

RecurringTimeWindow

Represents an arbitrary window of time that recurs.

JSON representation
{
  "window": {
    object (TimeWindow)
  },
  "recurrence": string
}
Fields
window

object (TimeWindow)

The window of the first recurrence.

recurrence

string

An RRULE (https://tools.ietf.org/html/rfc5545#section-3.8.5.3) for how this window recurs. They go on for the span of time between the start and end time.

TimeWindow

Represents an arbitrary window of time.

JSON representation
{
  "startTime": string,
  "endTime": string
}
Fields
startTime

string (Timestamp format)

The time that the window first starts.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

The time that the window ends. The end time must take place after the start time.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

MaintenanceExclusionWindow

Represents a maintenance exclusion window.

JSON representation
{
  "window": {
    object (TimeWindow)
  },
  "id": string
}
Fields
window

object (TimeWindow)

Optional. The time window.

id

string

Optional. A unique (per cluster) id for the window.

ControlPlane

Configuration of the cluster control plane.

JSON representation
{

  // Union field config can be only one of the following:
  "remote": {
    object (Remote)
  },
  "local": {
    object (Local)
  }
  // End of list of possible types for union field config.
}
Fields

Union field config.

config can be only one of the following:

remote

object (Remote)

Remote control plane configuration.

local

object (Local)

Local control plane configuration.

Warning: Local control plane clusters must be created in their own project. Local control plane clusters cannot coexist in the same project with any other type of clusters, including non-GDCE clusters. Mixing local control plane GDCE clusters with any other type of clusters in the same project can result in data loss.

Remote

This type has no fields.

Configuration specific to clusters with a control plane hosted remotely.

Local

Configuration specific to clusters with a control plane hosted locally.

Warning: Local control plane clusters must be created in their own project. Local control plane clusters cannot coexist in the same project with any other type of clusters, including non-GDCE clusters. Mixing local control plane GDCE clusters with any other type of clusters in the same project can result in data loss.

JSON representation
{
  "nodeLocation": string,
  "nodeCount": integer,
  "machineFilter": string,
  "sharedDeploymentPolicy": enum (SharedDeploymentPolicy)
}
Fields
nodeLocation

string

Name of the Google Distributed Cloud Edge zones where this node pool will be created. For example: us-central1-edge-customer-a.

nodeCount

integer

The number of nodes to serve as replicas of the Control Plane.

machineFilter

string

Only machines matching this filter will be allowed to host control plane nodes. The filtering language accepts strings like "name=", and is documented here: AIP-160.

sharedDeploymentPolicy

enum (SharedDeploymentPolicy)

Policy configuration about how user applications are deployed.

SharedDeploymentPolicy

Represents the policy configuration about how user applications are deployed.

Enums
SHARED_DEPLOYMENT_POLICY_UNSPECIFIED Unspecified.
ALLOWED User applications can be deployed both on control plane and worker nodes.
DISALLOWED User applications can not be deployed on control plane nodes and can only be deployed on worker nodes.

SystemAddonsConfig

Config that customers are allowed to define for GDCE system add-ons.

JSON representation
{
  "ingress": {
    object (Ingress)
  },
  "vmServiceConfig": {
    object (VMServiceConfig)
  }
}
Fields
ingress

object (Ingress)

Optional. Config for Ingress.

vmServiceConfig

object (VMServiceConfig)

Optional. Config for VM Service.

Ingress

Config for the Ingress add-on which allows customers to create an Ingress object to manage external access to the servers in a cluster. The add-on consists of istiod and istio-ingress.

JSON representation
{
  "disabled": boolean,
  "ipv4Vip": string
}
Fields
disabled

boolean

Optional. Whether Ingress is disabled.

ipv4Vip

string

Optional. Ingress VIP.

VMServiceConfig

VMServiceConfig defines the configuration for GDCE VM Service.

JSON representation
{
  "vmmEnabled": boolean
}
Fields
vmmEnabled

boolean

Optional. Whether VMM is enabled.

ControlPlaneEncryption

Configuration for Customer-managed KMS key support for control plane nodes.

JSON representation
{
  "kmsKey": string,
  "kmsKeyActiveVersion": string,
  "kmsKeyState": enum (KmsKeyState),
  "kmsStatus": {
    object (Status)
  }
}
Fields
kmsKey

string

Optional. The Cloud KMS CryptoKey e.g. projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey} to use for protecting control plane disks. If not specified, a Google-managed key will be used instead.

kmsKeyActiveVersion

string

Output only. The Cloud KMS CryptoKeyVersion currently in use for protecting control plane disks. Only applicable if kmsKey is set.

kmsKeyState

enum (KmsKeyState)

Output only. Availability of the Cloud KMS CryptoKey. If not KEY_AVAILABLE, then nodes may go offline as they cannot access their local data. This can be caused by a lack of permissions to use the key, or if the key is disabled or deleted.

kmsStatus

object (Status)

Output only. Error status returned by Cloud KMS when using this key. This field may be populated only if kmsKeyState is not KMS_KEY_STATE_KEY_AVAILABLE. If populated, this field contains the error status reported by Cloud KMS.

Status

Indicates the status of the cluster.

Enums
STATUS_UNSPECIFIED Status unknown.
PROVISIONING The cluster is being created.
RUNNING The cluster is created and fully usable.
DELETING The cluster is being deleted.
ERROR The status indicates that some errors occurred while reconciling/deleting the cluster.
RECONCILING The cluster is undergoing some work such as version upgrades, etc.

MaintenanceEvent

A Maintenance Event is an operation that could cause temporary disruptions to the cluster workloads, including Google-driven or user-initiated cluster upgrades, user-initiated cluster configuration changes that require restarting nodes, etc.

JSON representation
{
  "uuid": string,
  "targetVersion": string,
  "operation": string,
  "type": enum (Type),
  "schedule": enum (Schedule),
  "state": enum (State),
  "createTime": string,
  "startTime": string,
  "endTime": string,
  "updateTime": string
}
Fields
uuid

string

Output only. UUID of the maintenance event.

targetVersion

string

Output only. The target version of the cluster.

operation

string

Output only. The operation for running the maintenance event. Specified in the format projects/*/locations/*/operations/*. If the maintenance event is split into multiple operations (e.g. due to maintenance windows), the latest one is recorded.

type

enum (Type)

Output only. The type of the maintenance event.

schedule

enum (Schedule)

Output only. The schedule of the maintenance event.

state

enum (State)

Output only. The state of the maintenance event.

createTime

string (Timestamp format)

Output only. The time when the maintenance event request was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

startTime

string (Timestamp format)

Output only. The time when the maintenance event started.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

Output only. The time when the maintenance event ended, either successfully or not. If the maintenance event is split into multiple maintenance windows, endTime is only updated when the whole flow ends.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. The time when the maintenance event message was updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Type

Indicates the maintenance event type.

Enums
TYPE_UNSPECIFIED Unspecified.
USER_INITIATED_UPGRADE Upgrade initiated by users.
GOOGLE_DRIVEN_UPGRADE Upgrade driven by Google.

Schedule

Indicates when the maintenance event should be performed.

Enums
SCHEDULE_UNSPECIFIED Unspecified.
IMMEDIATELY Immediately after receiving the request.

State

Indicates the maintenance event state.

Enums
STATE_UNSPECIFIED Unspecified.
RECONCILING The maintenance event is ongoing. The cluster might be unusable.
SUCCEEDED The maintenance event succeeded.
FAILED The maintenance event failed.

ReleaseChannel

The release channel a cluster is subscribed to.

Enums
RELEASE_CHANNEL_UNSPECIFIED Unspecified release channel. This will default to the REGULAR channel.
NONE No release channel.
REGULAR Regular release channel.

SurvivabilityConfig

Configuration of the cluster survivability, e.g., for the case when network connectivity is lost.

JSON representation
{
  "offlineRebootTtl": string
}
Fields
offlineRebootTtl

string (Duration format)

Optional. Time period that allows the cluster nodes to be rebooted and become functional without network connectivity to Google. The default 0 means not allowed. The maximum is 7 days.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

ConnectionState

ConnectionState holds the current connection state from the cluster to Google.

JSON representation
{
  "state": enum (State),
  "updateTime": string
}
Fields
state

enum (State)

Output only. The current connection state.

updateTime

string (Timestamp format)

Output only. The time when the connection state was last changed.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

State

The connection state.

Enums
STATE_UNSPECIFIED Unknown connection state.
DISCONNECTED This cluster is currently disconnected from Google.
CONNECTED This cluster is currently connected to Google.
CONNECTED_AND_SYNCING This cluster is currently connected to Google, but may have recently reconnected after a disconnection. It is still syncing back.

Methods

create

Creates a new Cluster in a given project and location.

delete

Deletes a single Cluster.

generateAccessToken

Generates an access token for a Cluster.

generateOfflineCredential

Generates an offline credential for a Cluster.

get

Gets details of a single Cluster.

list

Lists Clusters in a given project and location.

patch

Updates the parameters of a single Cluster.

upgrade

Upgrades a single cluster.