<a id="cluster-registry"></a>

# Cluster Registry in Confluent Platform

Confluent Platform cluster registry provides a way for Confluent Platform cluster administrators to centrally
register Confluent Platform clusters in the metadata service (MDS) to enable a more
user-friendly RBAC role binding experience and to enable centralized audit logging.

Cluster registry enables you to register and identify your Confluent Platform clusters in the
MDS using a name of your choosing. The cluster name you specify is likely easier
to use and remember than a typical Confluent Platform cluster ID, which is a Confluent Platform GUID (globally
unique identifier) like `LRx92c9yQ+ws786HYosuBn`. After registering your
Confluent Platform cluster with the Confluent Platform cluster registry, you can use the new cluster name in your RBAC
role bindings. For example, if you are creating a role binding for a Connect
cluster, you only need to specify the registered cluster name (instead of both
the Confluent Platform cluster ID and Connect cluster ID).

#### NOTE
You can still use the “old” GUID cluster ID, which remains valid for backward
compatibility. However, using the GUID cluster ID defeats the purpose of
registering a new name in the cluster registry.

Changing the name of a cluster does not change any role bindings that
include that cluster because programmatically, the cluster name is actually
an alias.

For centralized audit logging, you can use the [Confluent Metadata API Reference for Confluent Platform](authorization/rbac/mds-api.md#mds-api) to leverage the cluster registry
to push audit log configuration updates to all of the Confluent Platform clusters registered with Confluent Platform cluster registry. Refer to
[Configure Audit Logs in Confluent Platform Using Confluent CLI](compliance/audit-logs/audit-logs-cli-config.md#audit-log-cli-config) and [MDS API Audit Log Configuration endpoints](authorization/rbac/mds-api.md#mds-api) for details.

<a id="relationship-cr-and-mds"></a>

## Cluster Registry and MDS

The cluster registry is stored as a dynamic broker configuration on the Confluent Platform cluster hosting
MDS. When you have multiple clusters and one serves as the MDS host cluster, it
is important to understand how the relationship between the clusters impacts the
way in which you register clusters.

For example, you have three clusters:

- **Cluster A** is hosting MDS.
- **Clusters B and C** are CP clusters used for RBAC or centralized audit logging, and managed by cluster A.

#### NOTE
If using [Centralized Audit Logging](compliance/audit-logs/mds-config-for-centralized-audit-logs.md#mds-config-for-centralized-audit-logs),
you must register the MDS cluster as the first cluster in the Cluster Registry,
before registering any other Centralized Audit Logging clusters. If you are
using RBAC only, you are not required to register the MDS cluster in the
Cluster Registry.

If clusters B and C are Connect, ksqlDB, or Schema Registry clusters that depend on
cluster A, then you must first boot those clusters (see steps below), retrieve their cluster
IDs, and register them in cluster A’s cluster registry before defining role bindings.

When booting up a new cluster that you want to register, the order of tasks is:

1. Start up the new cluster.
2. Retrieve the [cluster ID](authorization/rbac/rbac-get-cluster-ids.md#view-cluster-ids).
3. [Register the cluster ID with MDS in the Cluster Registry](#register-clusters-using-cli).
   As described above, MDS-dependent clusters should be registered in the cluster registry
   of the MDS host-cluster.
4. [Create the role bindings for components](#cluster-registry-rolebinding)
   (for example, ksqlDB, Connect, Schema Registry).

<a id="cluster-registry-prereqs"></a>

## Prerequisites

- You must have [MDS](../kafka/configure-mds/index.md#rbac-mds-config) configured with
  RBAC enabled.
- For bootstrap cluster registration, you must either be the MDS Confluent Platform cluster
  `super.user`, or have the SystemAdmin role on the MDS Confluent Platform cluster.

  #### NOTE
  *Bootstrapping a cluster* means that when you bring up a cluster for the very
  first time, you are linking to or relying on another server/cluster that
  already includes the correct host/information needed to start up, rather
  than having to enter all of the specific data each and every time you start
  up a new cluster. It saves time and resource, while providing a reliable
  cluster startup experience.
- For all other cluster registrations and updates, you must have either the
  SystemAdmin or ClusterAdmin role on the Confluent Platform cluster.

The difference between a bootstrap cluster registration and all other cluster
registrations is the gatekeeping logic used by cluster registry. A new cluster does not have
SystemAdmin or ClusterAdmin roles assigned to it. So there are two ways to
perform a bootstrap registration of a new cluster:

- The MDS super.user or SystemAdmin registers the cluster.
- The MDS super.user or SystemAdmin grants a role binding on the cluster
  (using the cluster ID) to another user (`user:"alice"`). Then that user
  registers the cluster.

<a id="cluster-registry-rules-requirements"></a>

## Cluster Registry rules and requirements

- Cluster names can only include characters from the English alphabet, numbers,
  underscores (`_`), and dashes (`-`).
- Cluster names are case-sensitive.
- You must have at least one host entry defined (using the IP/DNS and port
  identifier) for every cluster in the registry.

Violating either of the following rules will result in the cluster registry returning
a conflict error:

- Do not use the same name for two different physical clusters (as
  defined by the cluster IDs).
- Do not use two different names for the same physical cluster.

If you need to change the name of a registered cluster, refer to
[Updating entries in the cluster registry](#cluster-registry-update).

If you are scripting multiple cluster registrations one at a time using the
[Confluent Metadata API Reference for Confluent Platform](authorization/rbac/mds-api.md#mds-api) or CLI, to prevent data loss you must verify the response of each
call before making the next one. Alternatively, you can script multiple cluster registry
registrations using the API (for example, as part of an automated multi-cluster
deployment), which can process a list of clusters in a single transaction.

<a id="cluster-registry-registering"></a>

## Registering clusters

You can use either [curl commands](#register-clusters-curl) or the
Confluent Platform [CLI](https://docs.confluent.io/confluent-cli/current/command-reference/cluster/confluent_cluster_register.html) to register clusters.

When registering a Confluent Platform cluster in the cluster registry, you must specify following
information:

Cluster name
: The new name of the Confluent Platform cluster to be used in RBAC role bindings and
  centralized audit logs.

Cluster ID
: Refer to [View a cluster ID](authorization/rbac/rbac-get-cluster-ids.md#view-cluster-ids) if you need to locate the cluster ID.

Host name and port number
: The host and ports defined for a cluster should only include ports that
  support [RBAC token authentication](authentication/sasl/oauthbearer/overview.md#rbac-token-auth). For example, in
  Confluent Platform clusters, do not use the interbroker port or external Kerberos or mTLS
  ports. This is most important when using the [Confluent Metadata API Reference for Confluent Platform](authorization/rbac/mds-api.md#mds-api)
  because it leverages port information when pushing configuration updates out
  to known Confluent Platform clusters.

Protocol used by the hosts and ports
: The protocol should be SASL_SSL for Confluent Platform clusters (or SASL_PLAINTEXT for
  non-production Confluent Platform clusters), and HTTP
  or HTTPS for Connect, ksqlDB, and Schema Registry clusters.

Be sure to grant the appropriate [RBAC roles](authorization/rbac/rbac-predefined-roles.md#rbac-predefined-roles)
(ClusterAdmin and SystemAdmin) on newly-registered clusters so that users can
access and use them in other configurations. Also be sure to grant the AuditAdmin
role to principals who will be administering the centralized audit log
configuration. For details about granting roles on registered clusters,
see [Configuring role bindings for registered clusters](#cluster-registry-rolebinding).

#### IMPORTANT
If you plan to use registered clusters for
[centralized audit logging](compliance/audit-logs/audit-logs-cli-config.md#audit-log-cli-config), then you
must configure each registered cluster to be
[managed by MDS](../kafka/configure-mds/index.md#config-secondary-kafka-cluster-managed-by-primary-mds-cluster).
For details about configuring registered clusters for centralized audit
logging, refer to [Configure MDS to Manage Centralized Audit Logs](compliance/audit-logs/mds-config-for-centralized-audit-logs.md#mds-config-for-centralized-audit-logs). When you
register a cluster in the cluster registry, the endpoint that you
register must support [SASL_SSL or SASL_PLAINTEXT](security_tutorial.md#sec-tut-config-brokers),
and must use OAUTHBEARER authentication.

<a id="register-clusters-using-cli"></a>

### Registering clusters using the CLI

To register a new Confluent Platform cluster with MDS using the CLI:

1. Log in to a running MDS cluster:
   ```none
   # confluent login --url <protocol>://<host>:<port>
   confluent login --url http://localhost:8090
   ```
2. Register the new Confluent Platform cluster:
   ```none
   # Substitute the value in <> with your information
   confluent cluster register \
     --cluster-name <exampleKafka> \
     --kafka-cluster <kafka-ID> \
     --hosts <10.6.6.6:9000,10.3.3.3:9003> \
     --protocol SASL_PLAINTEXT
   ```

To register a new Connect cluster associated with a new Confluent Platform cluster:

```none
# Substitute the value in <> with your information
confluent cluster register \
  --cluster-name <exampleConnect> \
  --kafka-cluster <kafka-ID> \
  --connect-cluster-id <connect-ID> \
  --hosts <10.6.6.7:8443> \
  --protocol HTTP
```

<a id="register-clusters-curl"></a>

### Registering clusters using curl

To register a new Confluent Platform cluster with MDS using curl:

1. Retrieve an MDS authentication token to use for registration:
   ```none
   # Example
   TOKEN=$(curl -X GET "http://localhost:8090/security/1.0/authenticate" \
   -H "accept: application/json" \
   -u mds:mds | jq -r .auth_token)

   # Template
   TOKEN=$(curl -X GET "http://HOST:8090/security/1.0/authenticate" \
   -H "accept: application/json" \
   -u <ADMINUSER>:<PASSWORD> | jq -r .auth_token)
   ```
2. Register the cluster, which is named `exampleConnect`:
   ```none
   curl -X POST "http://localhost:8090/security/1.0/registry/clusters" \
   -H "Content-Type: application/json" -H "accept: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '[{"clusterName":"exampleConnect","scope":{"clusters":{"kafka-cluster":"kafka-Id","connect-cluster":"connect-Id"}},"hosts":[{"host":"10.6.6.7","port":8443},{"host":"10.3.3.3","port":9003}]}]'
   ```

<a id="cluster-registry-update"></a>

## Updating entries in the cluster registry

To update an existing cluster in the cluster registry, use the same steps specified in
[Registering clusters](#cluster-registry-registering). Whatever cluster name you specify will
overwrite the existing entry.

<a id="cluster-registry-view-entries"></a>

## Viewing cluster registry entries

Users with a SystemAdmin, ClusterAdmin, or Operator role on a cluster can view
the full cluster information:

```none
confluent cluster list
>       Name      |      Type       |  Kafka ID | Component ID |     Hosts                    |    Protocol
>+----------------+-----------------+-----------+--------------+------------------------------+----------------+
>  exampleConnect | connect-cluster | kafka-Id  | connect-Id   | 10.6.6.7:8443                | HTTP
>  exampleKafka   | kafka-cluster   | kafka-Id  |              | 10.6.6.6:9000,10.3.3.3:9003  | SASL_PLAINTEXT
```

Users with other roles (such as DeveloperRead) on the cluster can only view the
cluster name and cluster ID:

```none
confluent cluster list
>       Name      |      Type       |  Kafka ID | Component ID |     Hosts     |    Protocol
>+----------------+-----------------+-----------+--------------+---------------+----------------+
>  exampleConnect | connect-cluster | kafka-Id  | connect-Id   |               |
>  exampleKafka   | kafka-cluster   | kafka-Id  |              |               |
```

<a id="cluster-registry-unregister"></a>

## Unregistering a cluster

The same roles are required to register or unregister a cluster. For details, refer
to [Prerequisites](#cluster-registry-prereqs).

To unregister a cluster from the cluster registry:

```none
# Substitute the value in <> with your information
confluent cluster unregister --cluster-name <exampleConnect>
> Successfully unregistered the cluster exampleConnect from the Cluster Registry.
```

<a id="cluster-registry-rolebinding"></a>

## Configuring role bindings for registered clusters

After registering a cluster, you can use the new cluster name in RBAC role bindings.
Do not include the “old” GUID cluster ID, as you would in a role binding for an
unregistered cluster.

### Configuring role bindings for registered clusters using the CLI

The following CLI example shows how to create an RBAC role binding that grants the
ClusterAdmin role to the principal `alice` for the registered cluster
`exampleConnect`:

```none
# Substitute the value in <> with your information
confluent iam rbac role-binding create --role ClusterAdmin \
  --principal User:<alice> \
  --cluster-name <exampleConnect>
```

The following example shows howtocreate an RBAC role binding that grants the
AuditAdmin role to the principal `audit-admin`, who will be administering the
[centralized audit log configuration](compliance/audit-logs/audit-logs-cli-config.md#audit-log-cli-config) for a
managed registered Confluent Platform cluster:

```none
# Substitute the value in <> with your information
confluent iam rbac role-binding create --role AuditAdmin \
   --principal User:<audit-admin> \
   --cluster-name <managed-kafka-cluster-id>
```

### Configuring role bindings for registered clusters using curl

The following example shows how to create the same RBAC role binding using curl:

```none
curl -X POST "http://localhost:8090/security/1.0/principals/User:alice/roles/ClusterAdmin" \
-H "accept: application/json" -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"clusterName":"exampleConnect"}'
```

<a id="secure-registered-clusters"></a>

## Securing registered clusters

To enable security so that registered clusters can accept secure connections
from clients, specify the configuration in the `server.properties` file.

For additional details about configuring SASL_SSL, refer to
[Configure Confluent Server brokers](security_tutorial.md#sec-tut-config-brokers).

### SASL_SSL Configuration

```none
confluent.security.event.logger.destination.admin.bootstrap.servers=<logs1.example.com:9092,logs2.example.com:9092>
confluent.security.event.logger.destination.admin.security.protocol=SASL_SSL
confluent.security.event.logger.destination.admin.sasl.mechanism=PLAIN
confluent.security.event.logger.destination.admin.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
   username="<audit-log-admin-username>" \
   password="<audit-log-admin-password>";
confluent.security.event.logger.destination.admin.ssl.truststore.location=<path-to-truststore.jks>
confluent.security.event.logger.destination.admin.ssl.truststore.password=<truststore-password>
```