To list your clusters, you can use the Google Cloud console, the Google Cloud CLI,
the client library, or the Managed Kafka API. You can't use the open
source Apache Kafka API to list a cluster.

## Required roles and permissions to list your clusters


To get the permissions that
you need to list your clusters,

ask your administrator to grant you the
[Managed Kafka Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/managedkafka.md.txt#managedkafka.viewer) (`roles/managedkafka.viewer`) IAM role on your project.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


This predefined role contains

the permissions required to list your clusters. To see the exact permissions that are
required, expand the **Required permissions** section:


#### Required permissions

The following permissions are required to list your clusters:

- List clusters: `managedkafka.clusters.list`
- Get cluster details: `managedkafka.clusters.get`


You might also be able to get
these permissions
with [custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt) or
other [predefined roles](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#predefined).

## List your clusters

To list all your clusters in a project, follow these steps:

### Console

1. In the Google Cloud console, go to the **Clusters** page.


   [Go to Clusters](https://console.cloud.google.com/managedkafka/clusters)

   <br />

2. The clusters you created in a project are listed. The page lets you view
   the following cluster properties:

   - **Cluster name**: The unique identifier for your Managed Service for Apache Kafka cluster. You can use it to reference the cluster in various operations.
   - **Cluster state** : Indicates the current [operational status](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/rpc/google.cloud.managedkafka.v1.md.txt#google.cloud.managedkafka.v1.Cluster.State) of the cluster, such as **Active**.
   - **Region**: The geographical location where your cluster is hosted.
   - **Bootstrap URL** : The [bootstrap address](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/view-cluster.md.txt#view-bootstrap-address) that Kafka clients use to connect to the cluster.
   - **Memory**: The total amount of memory allocated to the cluster. This determines the capacity for handling message traffic and storage.
   - **vCPU**: The number of vCPUs assigned to the cluster. This affects the cluster's processing power and ability to handle concurrent operations.
   - **Labels**: Key-value pairs that you can attach to the cluster for organization, filtering, and automation purposes.
3. Optional: To find the cluster associated with a specific bootstrap
   address, enter the bootstrap URL in the **Filter** field.

### gcloud


1. In the Google Cloud console, activate Cloud Shell.

   [Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true)


   At the bottom of the Google Cloud console, a
   [Cloud Shell](https://docs.cloud.google.com/shell/docs/how-cloud-shell-works.md.txt)
   session starts and displays a command-line prompt. Cloud Shell is a shell environment
   with the Google Cloud CLI
   already installed and with values already set for
   your current project. It can take a few seconds for the session to initialize.
2. Run the [`gcloud managed-kafka clusters list`](https://docs.cloud.google.com/sdk/gcloud/reference/managed-kafka/clusters/list)
   command:

   ```bash
   gcloud managed-kafka clusters list --location=LOCATION \
       --limit=LIMIT
   ```

   To find the cluster associated with a specific bootstrap address, filter
   by the `bootstrapAddress` field:

   ```bash
   gcloud managed-kafka clusters list --location=LOCATION \
       --filter="bootstrapAddress:BOOTSTRAP_ADDRESS"
   ```

   Replace the following:
   - <var translate="no">LOCATION</var>: The location (region) of the cluster, such as `us-central1`. The region is also included as the third dot-separated segment of the bootstrap URL.
   - <var translate="no">LIMIT</var>: The maximum number of clusters to list.
   - <var translate="no">BOOTSTRAP_ADDRESS</var>: The bootstrap URL or hostname of the cluster.

### REST


Before using any of the request data,
make the following replacements:

- `PROJECT_ID`: your Google Cloud project ID
- `LOCATION`: the location of the cluster


HTTP method and URL:

```
GET https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters
```

To send your request, expand one of these options:

#### curl (Linux, macOS, or Cloud Shell)

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Execute the following command:

```
curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters"
```

#### PowerShell (Windows)

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Execute the following command:

```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters" | Select-Object -Expand Content
```

You should receive a JSON response similar to the following:

```
{
  "clusters": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID",
      "createTime": "CREATE_TIME",
      "updateTime": "UPDATE_TIME",
      "capacityConfig": {
        "vcpuCount": "CPU_COUNT",
        "memoryBytes": "MEMORY"
      },
      "rebalanceConfig": {},
      "gcpConfig": {
        "accessConfig": {
          "networkConfigs": [
            {
              "subnet": "projects/PROJECT_ID/locations/LOCATION/subnetworks/SUBNET_ID"
            }
          ]
        }
      },
      "state": "ACTIVE",
      "satisfiesPzi": false,
      "satisfiesPzs": false,
      "tlsConfig": {
        "trustConfig": {}
      },
      "updateOptions": {}
    }
  ]
}
```

<br />

### Go


Before trying this sample, follow the Go setup instructions in
[Install the client libraries](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/libraries.md.txt#install). For more information,
see the [Managed Service for Apache Kafka Go API reference documentation](https://docs.cloud.google.com/go/docs/reference/cloud.google.com/go/managedkafka/latest/apiv1.md.txt).

To authenticate to Managed Service for Apache Kafka, set up Application Default Credentials(ADC).
For more information,
see [Set up ADC for a local development environment](https://docs.cloud.google.com/docs/authentication/set-up-adc-local-dev-environment.md.txt).

```go
import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/managedkafka/apiv1/managedkafkapb"
	"google.golang.org/api/iterator"
	"google.golang.org/api/option"

	managedkafka "cloud.google.com/go/managedkafka/apiv1"
)

func listClusters(w io.Writer, projectID, region string, opts ...option.ClientOption) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	ctx := context.Background()
	client, err := managedkafka.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("managedkafka.NewClient got err: %w", err)
	}
	defer client.Close()

	locationPath := fmt.Sprintf("projects/%s/locations/%s", projectID, region)
	req := &managedkafkapb.ListClustersRequest{
		Parent: locationPath,
	}
	clusterIter := client.ListClusters(ctx, req)
	for {
		res, err := clusterIter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("clusterIter.Next() got err: %w", err)
		}
		fmt.Fprintf(w, "Got cluster: %v", res)
	}
	return nil
}
```

<br />

### Java


Before trying this sample, follow the Java setup instructions in
[Install the client libraries](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/libraries.md.txt#install). For more information,
see the [Managed Service for Apache Kafka Java API reference documentation](https://docs.cloud.google.com/java/docs/reference/google-cloud-managedkafka/latest/overview.md.txt).

To authenticate to Managed Service for Apache Kafka, set up Application Default Credentials.
For more information, see [Set up ADC for a local development environment](https://docs.cloud.google.com/docs/authentication/set-up-adc-local-dev-environment.md.txt).

```java
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.managedkafka.v1.Cluster;
import com.google.cloud.managedkafka.v1.LocationName;
import com.google.cloud.managedkafka.v1.ManagedKafkaClient;
import java.io.IOException;

public class ListClusters {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the example.
    String projectId = "my-project-id";
    String region = "my-region"; // e.g. us-east1
    listClusters(projectId, region);
  }

  public static void listClusters(String projectId, String region) throws Exception {
    try (ManagedKafkaClient managedKafkaClient = ManagedKafkaClient.create()) {
      LocationName locationName = LocationName.of(projectId, region);
      // This operation is being handled synchronously.
      for (Cluster cluster : managedKafkaClient.listClusters(locationName).iterateAll()) {
        System.out.println(cluster.getAllFields());
      }
    } catch (IOException | ApiException e) {
      System.err.printf("managedKafkaClient.listClusters got err: %s", e.getMessage());
    }
  }
}
```

<br />

### Python


Before trying this sample, follow the Python setup instructions in
[Install the client libraries](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/reference/libraries.md.txt#install). For more information,
see the [Managed Service for Apache Kafka Python API reference documentation](https://docs.cloud.google.com/python/docs/reference/google-cloud-managedkafka/latest.md.txt).

To authenticate to Managed Service for Apache Kafka, set up Application Default Credentials.
For more information,
see [Set up ADC for a local development environment](https://docs.cloud.google.com/docs/authentication/set-up-adc-local-dev-environment.md.txt).

```python
from google.cloud import managedkafka_v1

# TODO(developer)
# project_id = "my-project-id"
# region = "us-central1"

client = managedkafka_v1.ManagedKafkaClient()

request = managedkafka_v1.ListClustersRequest(
    parent=client.common_location_path(project_id, region),
)

response = client.list_clusters(request=request)
for cluster in response:
    print("Got cluster:", cluster)
```

<br />

## What's next?

- [Monitor your cluster](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/monitor-cluster.md.txt).

- [View your cluster](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/view-cluster.md.txt).

- [Create a topic within your cluster](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/create-topic.md.txt).

- [Edit a cluster](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/update-cluster.md.txt).

- [Delete your cluster](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/delete-cluster.md.txt).

*Apache Kafka® is a registered
trademark of The Apache Software Foundation or its affiliates in the United
States and/or other countries.*