# REST Resource: projects.locations.clusters

- [Resource: Cluster](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#Cluster)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#Cluster.SCHEMA_REPRESENTATION)
- [GcpConfig](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#GcpConfig)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#GcpConfig.SCHEMA_REPRESENTATION)
- [AccessConfig](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#AccessConfig)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#AccessConfig.SCHEMA_REPRESENTATION)
- [NetworkConfig](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#NetworkConfig)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#NetworkConfig.SCHEMA_REPRESENTATION)
- [RebalanceConfig](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#RebalanceConfig)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#RebalanceConfig.SCHEMA_REPRESENTATION)
- [Mode](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#Mode)
- [State](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#State)
- [TlsConfig](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#TlsConfig)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#TlsConfig.SCHEMA_REPRESENTATION)
- [TrustConfig](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#TrustConfig)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#TrustConfig.SCHEMA_REPRESENTATION)
- [CertificateAuthorityServiceConfig](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#CertificateAuthorityServiceConfig)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#CertificateAuthorityServiceConfig.SCHEMA_REPRESENTATION)
- [UpdateOptions](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#UpdateOptions)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#UpdateOptions.SCHEMA_REPRESENTATION)
- [BrokerDetails](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#BrokerDetails)
  - [JSON representation](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#BrokerDetails.SCHEMA_REPRESENTATION)
- [Methods](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#METHODS_SUMMARY)

## Resource: Cluster

An Apache Kafka cluster deployed in a location.

| JSON representation |
|---|
| ``` { "name": string, "createTime": string, "updateTime": string, "labels": { string: string, ... }, "capacityConfig": { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/CapacityConfig`) }, "rebalanceConfig": { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#RebalanceConfig`) }, "state": enum (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#State`), "tlsConfig": { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#TlsConfig`) }, "updateOptions": { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#UpdateOptions`) }, "kafkaVersion": string, "brokerDetails": [ { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#BrokerDetails`) } ], // Union field `platform_config` can be only one of the following: "gcpConfig": { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#GcpConfig`) } // End of list of possible types for union field `platform_config`. "satisfiesPzi": boolean, "satisfiesPzs": boolean } ``` |

| Fields ||
|---|---|
| `name` | `string` Identifier. The name of the cluster. Structured like: projects/{projectNumber}/locations/{location}/clusters/{clusterId} |
| `createTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. The time when the cluster was created. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `updateTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. The time when the cluster was last updated. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `labels` | `map (key: string, value: string)` Optional. Labels as key value pairs. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |
| `capacityConfig` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/CapacityConfig`)`` Required. Capacity configuration for the Kafka cluster. |
| `rebalanceConfig` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#RebalanceConfig`)`` Optional. Rebalance configuration for the Kafka cluster. |
| `state` | ``enum (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#State`)`` Output only. The current state of the cluster. |
| `tlsConfig` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#TlsConfig`)`` Optional. TLS configuration for the Kafka cluster. |
| `updateOptions` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#UpdateOptions`)`` Optional. UpdateOptions represents options that control how updates to the cluster are applied. |
| `kafkaVersion` | `string` Output only. Only populated when FULL view is requested. The Kafka version of the cluster. |
| `brokerDetails[]` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#BrokerDetails`)`` Output only. Only populated when FULL view is requested. Details of each broker in the cluster. |
| Union field `platform_config`. Platform specific configuration properties for a Kafka cluster. `platform_config` can be only one of the following: ||
| `gcpConfig` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#GcpConfig`)`` Required. Configuration properties for a Kafka cluster deployed to Google Cloud Platform. |
| `satisfiesPzi` | `boolean` Output only. Reserved for future use. |
| `satisfiesPzs` | `boolean` Output only. Reserved for future use. |

## GcpConfig

Configuration properties for a Kafka cluster deployed to Google Cloud Platform.

| JSON representation |
|---|
| ``` { "accessConfig": { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#AccessConfig`) }, "kmsKey": string } ``` |

| Fields ||
|---|---|
| `accessConfig` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#AccessConfig`)`` Required. Access configuration for the Kafka cluster. |
| `kmsKey` | `string` Optional. Immutable. The Cloud KMS Key name to use for encryption. The key must be located in the same region as the cluster and cannot be changed. Structured like: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}. |

## AccessConfig

The configuration of access to the Kafka cluster.

| JSON representation |
|---|
| ``` { "networkConfigs": [ { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#NetworkConfig`) } ] } ``` |

| Fields ||
|---|---|
| `networkConfigs[]` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#NetworkConfig`)`` Required. Virtual Private Cloud (VPC) networks that must be granted direct access to the Kafka cluster. Minimum of 1 network is required. Maximum 10 networks can be specified. |

## NetworkConfig

The configuration of a Virtual Private Cloud (VPC) network that can access the Kafka cluster.

| JSON representation |
|---|
| ``` { "subnet": string } ``` |

| Fields ||
|---|---|
| `subnet` | `string` Required. Name of the VPC subnet in which to create Private Service Connect (PSC) endpoints for the Kafka brokers and bootstrap address. Structured like: projects/{project}/regions/{region}/subnetworks/{subnet_id} The subnet must be located in the same region as the Kafka cluster. The project may differ. Multiple subnets from the same parent network must not be specified. |

## RebalanceConfig

Defines rebalancing behavior of a Kafka cluster.

| JSON representation |
|---|
| ``` { "mode": enum (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#Mode`) } ``` |

| Fields ||
|---|---|
| `mode` | ``enum (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#Mode`)`` Optional. The rebalance behavior for the cluster. When not specified, defaults to `NO_REBALANCE`. |

## Mode

The partition rebalance mode for the cluster.

| Enums ||
|---|---|
| `MODE_UNSPECIFIED` | A mode was not specified. Do not use. |
| `NO_REBALANCE` | Do not rebalance automatically. |
| `AUTO_REBALANCE_ON_SCALE_UP` | Automatically rebalance topic partitions among brokers when the cluster is scaled up. |

## State

The state of the cluster.

| Enums ||
|---|---|
| `STATE_UNSPECIFIED` | A state was not specified. |
| `CREATING` | The cluster is being created. |
| `ACTIVE` | The cluster is active. |
| `DELETING` | The cluster is being deleted. |
| `UPDATING` | The cluster is being updated. |

## TlsConfig

The TLS configuration for the Kafka cluster.

| JSON representation |
|---|
| ``` { "trustConfig": { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#TrustConfig`) }, "sslPrincipalMappingRules": string } ``` |

| Fields ||
|---|---|
| `trustConfig` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#TrustConfig`)`` Optional. The configuration of the broker truststore. If specified, clients can use mTLS for authentication. |
| `sslPrincipalMappingRules` | `string` Optional. A list of rules for mapping from SSL principal names to short names. These are applied in order by Kafka. Refer to the Apache Kafka documentation for `ssl.principal.mapping.rules` for the precise formatting details and syntax. Example: "RULE:\^CN=(.\*?),OU=ServiceUsers.\*$/$1@example.com/,DEFAULT" This is a static Kafka broker configuration. Setting or modifying this field will trigger a rolling restart of the Kafka brokers to apply the change. An empty string means no rules are applied (Kafka default). |

## TrustConfig

Sources of CA certificates to install in the broker's truststore.

| JSON representation |
|---|
| ``` { "casConfigs": [ { object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#CertificateAuthorityServiceConfig`) } ] } ``` |

| Fields ||
|---|---|
| `casConfigs[]` | ``object (`https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters#CertificateAuthorityServiceConfig`)`` Optional. Configuration for the Google Certificate Authority Service. Maximum 10. |

## CertificateAuthorityServiceConfig

A configuration for the Google Certificate Authority Service.

| JSON representation |
|---|
| ``` { "caPool": string } ``` |

| Fields ||
|---|---|
| `caPool` | `string` Required. The name of the CA pool to pull CA certificates from. Structured like: projects/{project}/locations/{location}/caPools/{caPool}. The CA pool does not need to be in the same project or location as the Kafka cluster. |

## UpdateOptions

UpdateOptions specifies options that influence how a cluster update is applied. These options control the behavior of the update process, rather than defining the desired end-state of a cluster.

| JSON representation |
|---|
| ``` { "allowBrokerDownscaleOnClusterUpscale": boolean } ``` |

| Fields ||
|---|---|
| `allowBrokerDownscaleOnClusterUpscale` | `boolean` Optional. If true, allows an update operation that increases the total vCPU and/or memory allocation of the cluster to significantly decrease the per-broker vCPU and/or memory allocation. This can result in reduced performance and availability. By default, the update operation will fail if an upscale request results in a vCPU or memory allocation for the brokers that is smaller than 90% of the current broker size. |

## BrokerDetails

Details of a broker in the Kafka cluster.

| JSON representation |
|---|
| ``` { "rack": string, "brokerIndex": string, "nodeId": string } ``` |

| Fields ||
|---|---|
| `rack` | `string` Output only. The rack of the broker. |
| `brokerIndex` | `string (https://developers.google.com/discovery/v1/type-format format)` Output only. The index of the broker. |
| `nodeId` | `string (https://developers.google.com/discovery/v1/type-format format)` Output only. The node id of the broker. |

| ## Methods ||
|---|---|
| ### `https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters/create` | Creates a new cluster in a given project and location. |
| ### `https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters/delete` | Deletes a single cluster. |
| ### `https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters/get` | Returns the properties of a single cluster. |
| ### `https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters/list` | Lists the clusters in a given project and location. |
| ### `https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rest/v1/projects.locations.clusters/patch` | Updates the properties of a single cluster. |