# Connecting to multiple clusters with CloudHSM CLI
<a name="cloudhsm_cli-configs-multi-cluster"></a>

 With AWS CloudHSM Client SDK 5, you can configure CloudHSM CLI to allow connections to multiple CloudHSM clusters from a single CLI instance. 

The following topics describe how to use the CloudHSM CLI multi-cluster functionality to connect with multiple clusters.

**Topics**
+ [Prerequisites](cloudhsm_cli-multi-cluster-prereqs.md)
+ [Configure multi-cluster functionality](cloudhsm_cli-multi-cluster-config-run.md)
+ [Add a cluster](cloudhsm_cli-multi-cluster-add-cluster.md)
+ [Remove a cluster](cloudhsm_cli-multi-cluster-remove-cluster.md)
+ [Interact with clusters](cloudhsm_cli-multi-cluster-usage.md)

# Multi-cluster prerequisites for AWS CloudHSM
<a name="cloudhsm_cli-multi-cluster-prereqs"></a>

Before configuring your cluster in AWS CloudHSM to connect to multiple clusters, you must meet the following prerequisites: 
+ Two or more AWS CloudHSM clusters to which you’d like to connect to, along with their cluster certificates.
+ An EC2 instance with Security Groups correctly configured to connect to all of the clusters above. For more information about how to set up a cluster and the client instance, refer to [Getting started with AWS CloudHSM](getting-started.md).
+ To set up multi-cluster functionality, you must have already downloaded and installed the CloudHSM CLI. If you have not already done this, refer to the instructions in [Getting started with AWS CloudHSM Command Line Interface (CLI)](cloudhsm_cli-getting-started.md).
+  You will not be able to access a cluster configured with `./configure-cli[.exe] -a` since it will not be associated with a `cluster-id`. You can reconfigure it by following `config-cli add-cluster` as described in this guide. 

# Configure the CloudHSM CLI for multi-cluster functionality
<a name="cloudhsm_cli-multi-cluster-config-run"></a>

To configure your CloudHSM CLI for multi-cluster functionality, follow these steps:

1. Identify the clusters you want to connect to.

1. Add these clusters to your CloudHSM CLI configuration using the [configure-cli](configure-sdk-5.md) subcommand `add-cluster` as described below.

1. Restart any CloudHSM CLI processes in order for the new configuration to take effect.

# Add a cluster to your AWS CloudHSM configuration
<a name="cloudhsm_cli-multi-cluster-add-cluster"></a>

When connecting to multiple clusters, use the `configure-cli add-cluster` command to add a cluster to your configuration.

## Syntax
<a name="cloudhsm_cli-multi-cluster-add-cluster-syntax"></a>

```
configure-cli add-cluster [OPTIONS]
        --cluster-id <CLUSTER ID> 
        [--region <REGION>]
        [--endpoint <ENDPOINT>]
        [--hsm-ca-cert <HSM CA CERTIFICATE FILE>]
        [--client-cert-hsm-tls-file <CLIENT CERTIFICATE FILE>]
        [--client-key-hsm-tls-file <CLIENT KEY FILE>]
        [-h, --help]
```

## Examples
<a name="cloudhsm_cli-multi-cluster-add-cluster-examples"></a>

### Add a cluster using the `cluster-id` parameter
<a name="w2aac23c15c19b7c13b7b3b1"></a>

**Example**  
 Use the `configure-cli add-cluster` along with the `cluster-id` parameter to add a cluster (with the ID of `cluster-1234567`) to your configuration.   

```
$ sudo /opt/cloudhsm/bin/configure-cli add-cluster --cluster-id <cluster-1234567>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" add-cluster --cluster-id <cluster-1234567>
```

**Tip**  
If using `configure-cli add-cluster` with the `cluster-id` parameter doesn't result in the cluster being added, refer to the following example for a longer version of this command that also requires `--region` and `--endpoint` parameters to identify the cluster being added. If, for example, the region of the cluster is different than the one configured as your AWS CLI default, you should use the `--region` parameter to use the correct region. Additionally, you have the ability to specify the AWS CloudHSM API endpoint to use for the call, which may be necessary for various network setups, such as using VPC interface endpoints that don’t use the default DNS hostname for AWS CloudHSM.

### Add a cluster using `cluster-id`, `endpoint`, and `region` parameters
<a name="w2aac23c15c19b7c13b7b3b3"></a>

**Example**  
 Use the `configure-cli add-cluster` along with the `cluster-id`, `endpoint`, and `region` parameters to add a cluster (with the ID of `cluster-1234567`) to your configuration.   

```
$ sudo /opt/cloudhsm/bin/configure-cli add-cluster --cluster-id <cluster-1234567> --region <us-east-1> --endpoint <https://cloudhsmv2.us-east-1.amazonaws.com>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" add-cluster --cluster-id <cluster-1234567> --region <us-east-1> --endpoint <https://cloudhsmv2.us-east-1.amazonaws.com>
```

For more information about the `--cluster-id`, `--region`, and `--endpoint` parameters, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md).

## Parameters
<a name="cloudhsm_cli-multi-cluster-add-cluster-parameters"></a>

**--cluster-id *<Cluster ID>***  
 Makes a `DescribeClusters` call to find all of the HSM elastic network interface (ENI) IP addresses in the cluster associated with the cluster ID. The system adds the ENI IP addresses to the AWS CloudHSM configuration files.  
If you use the `--cluster-id` parameter from an EC2 instance within a VPC that does not have access to the public internet, then you must create an interface VPC endpoint to connect with AWS CloudHSM. For more information about VPC endpoints, see [AWS CloudHSM and VPC endpoints](cloudhsm-vpc-endpoint.md).
Required: Yes

**--endpoint *<Endpoint>***  
Specify the AWS CloudHSM API endpoint used for making the `DescribeClusters` call. You must set this option in combination with `--cluster-id`.   
Required: No

**--hsm-ca-cert *<HsmCA Certificate Filepath>***  
Specifies the filepath to the HSM CA certificate.  
Required: No

**--region *<Region>***  
Specify the region of your cluster. You must set this option in combination with `--cluster-id`.  
If you don’t supply the `--region` parameter, the system chooses the region by attempting to read the `AWS_DEFAULT_REGION` or `AWS_REGION` environment variables. If those variables aren’t set, then the system checks the region associated with your profile in your AWS config file (typically `~/.aws/config`) unless you specified a different file in the `AWS_CONFIG_FILE` environment variable. If none of the above are set, the system defaults to the `us-east-1` region.  
Required: No

**--client-cert-hsm-tls-file *<client certificate hsm tls path>***  
 Path to the client certificate used for TLS client-HSM mutual authentication.   
 Only use this option if you have registered at least one trust anchor onto HSM with CloudHSM CLI. You must set this option in combination with `--client-key-hsm-tls-file`.   
Required: No

**--client-key-hsm-tls-file *<client key hsm tls path>***  
 Path to the client key used for TLS client-HSM mutual authentication.   
 Only use this option if you have registered at least one trust anchor onto HSM with CloudHSM CLI. You must set this option in combination with `--client-cert-hsm-tls-file`.   
Required: No

# Remove a cluster from your AWS CloudHSM configuration
<a name="cloudhsm_cli-multi-cluster-remove-cluster"></a>

When connecting to multiple clusters with CloudHSM CLI, use the `configure-cli remove-cluster` command to remove a cluster from your configuration.

## Syntax
<a name="cloudhsm_cli-multi-cluster-remove-cluster-syntax"></a>

```
configure-cli remove-cluster [OPTIONS]
        --cluster-id <CLUSTER ID>
        [-h, --help]
```

## Examples
<a name="cloudhsm_cli-multi-cluster-remove-cluster-examples"></a>

### Remove a cluster using the `cluster-id` parameter
<a name="w2aac23c15c19b7c15b7b3b1"></a>

**Example**  
 Use the `configure-cli remove-cluster` along with the `cluster-id` parameter to remove a cluster (with the ID of `cluster-1234567`) from your configuration.   

```
$ sudo /opt/cloudhsm/bin/configure-cli remove-cluster --cluster-id <cluster-1234567>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-cli.exe" remove-cluster --cluster-id <cluster-1234567>
```

For more information about the `--cluster-id` parameter, see [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md).

## Parameter
<a name="cloudhsm_cli-multi-cluster-remove-cluster-parameters"></a>

**--cluster-id *<Cluster ID>***  
The ID of the cluster to remove from the configuration.  
Required: Yes

# Interact with multiple clusters in AWS CloudHSM
<a name="cloudhsm_cli-multi-cluster-usage"></a>

After configuring multiple clusters with CloudHSM CLI, use the `cloudhsm-cli` command to interact with them.

## Examples
<a name="cloudhsm_cli-multi-cluster-cluster-usage-examples"></a>

### Setting a default `cluster-id` when using interactive mode
<a name="w2aac23c15c19b7c17b5b3b1"></a>

**Example**  
 Use the [Interactive mode](cloudhsm_cli-modes.md#cloudhsm_cli-mode-interactive) along with the `cluster-id` parameter to set a default cluster (with the ID of `cluster-1234567`) from your configuration.   

```
$ cloudhsm-cli interactive --cluster-id <cluster-1234567>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" interactive --cluster-id <cluster-1234567>
```

### Setting the `cluster-id` when running a single command
<a name="w2aac23c15c19b7c17b5b5b1"></a>

**Example**  
 Use the `cluster-id` parameter to set the cluster (with the ID of `cluster-1234567`) to get [List HSMs with CloudHSM CLI](cloudhsm_cli-cluster-hsm-info.md) from.   

```
$ cloudhsm-cli cluster hsm-info --cluster-id <cluster-1234567>
```

```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cloudhsm-cli.exe" cluster hsm-info --cluster-id <cluster-1234567>
```