Listing all connectors running in a Connect cluster provides an overview of the
data integrations that are configured. You can monitor the health
and status of your connectors, identify potential issues, and manage your data
flows effectively.

To list all connectors in a Connect cluster, you can use the Google Cloud console,
the gcloud CLI, the Managed Service for Apache Kafka
client library, or the Managed Kafka API. You can't use the open
source Apache Kafka API to list the connectors.

## Required roles and permissions to list all connectors


To get the permissions that
you need to list all connectors,

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 all connectors. To see the exact permissions that are
required, expand the **Required permissions** section:


#### Required permissions

The following permissions are required to list all connectors:

- Grant the list connectors permission on the parent Connect cluster: `managedkafka.connectors.list`
- Grant the get connector details permission on the parent Connect cluster: `managedkafka.connectors.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).

## View all connectors

This view provides a quick way to monitor the status of your connectors
and identify any that require attention. You can then drill down into individual
connectors to view their details and configurations if needed.

### Console

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


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

   <br />

2. Click the Connect cluster for which you want to list the connectors.

   The **Connect cluster details** page is displayed.
3. The **Resources** tab displays a list of all connectors running in the
   cluster. The list includes the following information for each connector:

   - **Name**: The name of the connector.
   - **State**: The operational state of the connector. For example, Running, Failed.
   - **Connector type**: The type of connector plugin.

   You can use the **Filter** option to search for specific connectors by
   name.

### 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. Use the [`gcloud managed-kafka connectors list`](https://docs.cloud.google.com/sdk/gcloud/reference/managed-kafka/connectors/list)
   command to list connectors:

   ```bash
   gcloud managed-kafka connectors list CONNECT_CLUSTER_ID \
       --location=LOCATION
   ```
3. To further refine the list of connectors, you can use additional flags:

   ```bash
   gcloud managed-kafka connectors list CONNECT_CLUSTER_ID \
       --location=LOCATION \
       [--filter=EXPRESSION] \
       [--limit=LIMIT] \
       [--page-size=PAGE_SIZE] \
       [--sort-by=SORT_BY]
   ```

   Replace the following:
   - <var translate="no">CONNECT_CLUSTER_ID</var>: Required. The ID of the Connect cluster containing the connectors you want to list.
   - <var translate="no">LOCATION</var>: Required. The location of the [Connect cluster](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/connect-cluster/create-connect-cluster.md.txt) containing the connectors that you want to list.
   - <var translate="no">EXPRESSION</var>: (Optional) A Boolean filter
     expression to apply to the list. If the expression evaluates to
     `True`, the item is included in the list. For more details and
     examples, run `gcloud topic filters`.

     Examples:
     - To list only connectors that are in the 'RUNNING' state:

       ```bash
       --filter="state=RUNNING"
       ```
     - To list only 'Pub/Sub Sink' connectors:

       ```bash
       --filter="connector_plugin='Pub/Sub Sink'"
       ```
     - To list connectors with a name containing 'prod':

       ```bash
       --filter="name ~ 'prod'"
       ```
     - To list connectors that are either 'FAILED' or are 'Pub/Sub
       Source' plugins:

       ```bash
       --filter="state=FAILED OR connector_plugin='Pub/Sub Source'"
       ```
   - <var translate="no">LIMIT</var>: (Optional) The maximum number of
     connectors to display. If not specified, all connectors are listed.

   - <var translate="no">PAGE_SIZE</var>: (Optional) The number of results to
     display per page. If not specified, the service determines a
     suitable page size.

   - <var translate="no">SORT_BY</var>: (Optional) A comma-separated list of
     fields to sort by. The default sort order is ascending. To sort in
     descending order, prefix the field with `~`. Supported fields are
     likely `name` and `state`.

Example command with sorting:

```bash
gcloud managed-kafka connectors list test-connect-cluster \
    --location=us-central1 \
    --sort-by=~state,name
```

Example command with filtering and limiting:

```bash
gcloud managed-kafka connectors list test-connect-cluster \
    --location=us-central1 \
    --filter="state=RUNNING AND connector_plugin='Pub/Sub Sink'" \
    --limit=5
```

Example output:

    NAME                                    STATE     CONNECTOR_PLUGIN
    pubsub-sink-connector                   RUNNING   Pub/Sub Sink
    another-pubsub-sink                     RUNNING   Pub/Sub Sink
    prod-pubsub-sink                        RUNNING   Pub/Sub Sink

<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 listConnectors(w io.Writer, projectID, region, connectClusterID string, opts ...option.ClientOption) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// connectClusterID := "my-connect-cluster"
	ctx := context.Background()
	client, err := managedkafka.NewManagedKafkaConnectClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("managedkafka.NewManagedKafkaConnectClient got err: %w", err)
	}
	defer client.Close()

	parent := fmt.Sprintf("projects/%s/locations/%s/connectClusters/%s", projectID, region, connectClusterID)
	req := &managedkafkapb.ListConnectorsRequest{
		Parent: parent,
	}
	connectorIter := client.ListConnectors(ctx, req)
	for {
		connector, err := connectorIter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("connectorIter.Next() got err: %w", err)
		}
		fmt.Fprintf(w, "Got connector: %v", connector)
	}
	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.ConnectClusterName;
import com.google.cloud.managedkafka.v1.Connector;
import com.google.cloud.managedkafka.v1.ManagedKafkaConnectClient;
import java.io.IOException;

public class ListConnectors {

  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
    String clusterId = "my-connect-cluster";
    listConnectors(projectId, region, clusterId);
  }

  public static void listConnectors(String projectId, String region, String clusterId)
      throws IOException {
    try (ManagedKafkaConnectClient managedKafkaConnectClient = ManagedKafkaConnectClient.create()) {
      ConnectClusterName parent = ConnectClusterName.of(projectId, region, clusterId);
      // This operation is handled synchronously.
      for (Connector connector : managedKafkaConnectClient.listConnectors(parent).iterateAll()) {
        System.out.println(connector.getAllFields());
      }
    } catch (IOException | ApiException e) {
      System.err.printf("managedKafkaConnectClient.listConnectors got err: %s\n", 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
from google.cloud.managedkafka_v1.services.managed_kafka_connect import (
    ManagedKafkaConnectClient,
)
from google.api_core.exceptions import GoogleAPICallError

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

connect_client = ManagedKafkaConnectClient()

request = managedkafka_v1.ListConnectorsRequest(
    parent=connect_client.connect_cluster_path(project_id, region, connect_cluster_id),
)

try:
    response = connect_client.list_connectors(request=request)
    for connector in response:
        print("Got connector:", connector)
except GoogleAPICallError as e:
    print(f"Failed to list connectors with error: {e}")
```

<br />

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