# Storing secrets in Vault

Starting with release 3.5.0, CMA is able to store secrets in a local Vault instance managed by CMA. 
If it is configured, no credentials are stored in the database, and the files created during the migration process contain only Vault paths.
An additional benefit is that the credentials are also masked on the UI in this case.

> **_NOTE:_** This feature is in technical preview and may change in a future release. 

## Local Deployment

### Starting CMA with Vault for the first time
 
Starting the CMA with the **_--vault_** option will start and configure a local Vault server and configure the CMA Server to connect to it.
Once the connection is set up, the CMA will store the credentials on the Vault Server.

1. When CMA Server is not running
    ```shell
    cma-4.1.1-b12/bin/cma start --vault
    ```
2. When CMA Server is already running
    ```shell
    cma-4.1.1-b12/bin/cma restart --vault
    ```

> **_NOTE:_** After the initial configuration is complete, CMA Server and Vault Server can be started/stopped/restarted separately.

### Restart Vault Server
```shell
cma-4.1.1-b12/bin/cma vault restart
```

### Stop Vault Server

After the initial configuration is complete, CMA Server expects Vault Server to be running. 
So if you want to stop the Vault, we recommend that you stop CMA as well.

```shell
cma-4.1.1-b12/bin/cma vault stop
cma-4.1.1-b12/bin/cma stop
```

## Docker Deployment

### Starting CMA with Vault 

Starting the CMA with the **_--vault_** option will start and configure a local Vault server and configure the CMA Server to connect to it.
Once the connection is set up, the CMA will store the credentials on the Vault Server.

1. When CMA Server is not running
    ```shell
    cma-4.1.1-b12/bin/cma docker start --vault
    ```
2. When CMA Server is already running
    ```shell
    cma-4.1.1-b12/bin/cma docker restart --vault
    ```

> **_NOTE:_** In the docker deployment, the Vault runs in the CMA container so it cannot be started/stopped/restarted without the CMA. 

## Parcel Deployment

There are two options for enabling Vault in a parcel deployment: using a CM-managed Vault service, or configuring an external Vault instance.

### Option 1: CM-managed Vault Service

If the Vault CSD and parcel are deployed in Cloudera Manager, CMA auto-detects the Vault service dependency.

1. Deploy the Vault parcel and add the Vault service in Cloudera Manager
2. In **CMA Master → CMA Server → Configuration**, set:
   - **Vault Role ID (AppRole auth)**
   - **Vault Secret ID (AppRole auth)**
3. Restart the CMA Master service

> **_NOTE:_** After the initial configuration is complete, CMA Server and Vault Server roles can be started/stopped/restarted separately in CM.

### Option 2: External Vault (using CMA-bundled Vault binary)

The CMA parcel ships with a bundled Vault binary and setup scripts. You can use these to run a local Vault instance on the CMA Server host without deploying a separate Vault parcel.

#### Prerequisites

- SSH (root) access to the CMA Server host
- The CMA parcel is installed and activated
- `python3`, `wget`, and `unzip` are available on the host
- Outbound HTTPS access to `releases.hashicorp.com` (for Vault binary download)

#### Step 1: Install and start Vault

SSH into the CMA Server host and run:

```shell
export VAULT_HOME=/opt/cloudera/parcels/cma/vault-local
export SCRIPT_PATH=$VAULT_HOME/scripts/bin
export PYTHON_EXECUTABLE=python3

cd $VAULT_HOME/scripts/bin

# Download and install the Vault binary
bash vault-server.sh setup

# Start Vault (initializes, unseals, and enables KV v2 secret engine)
bash vault-server.sh start
```

By default, Vault will listen on `http://127.0.0.1:8210`. The port can be changed via the `VAULT_SERVER_PORT` environment variable.

#### Step 2: Configure AppRole authentication

Set up the Vault environment and create an AppRole for CMA:

```shell
export VAULT_ADDR=http://127.0.0.1:8210
export VAULT_TOKEN=$(python3 -c "import json; print(json.load(open('$HOME/.vault_data/conf/.vault'))['root_token'])")

VAULT_BIN=/opt/cloudera/parcels/cma/vault-local/vault/vault

# Enable AppRole auth method
$VAULT_BIN auth enable approle

# Create a policy granting CMA access to secrets
$VAULT_BIN policy write cma-policy - <<'EOF'
path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

# Create an AppRole for CMA
$VAULT_BIN write auth/approle/role/cma-role \
  token_policies=cma-policy \
  token_ttl=1h \
  token_max_ttl=4h

# Retrieve the role_id (note down the value)
$VAULT_BIN read auth/approle/role/cma-role/role-id

# Generate a secret_id (note down the value)
$VAULT_BIN write -f auth/approle/role/cma-role/secret-id
```

Note down the `role_id` and `secret_id` values from the output — these are needed in the next step.

#### Step 3: Configure CMA Master in Cloudera Manager

In **CMA Master → CMA Server → Configuration**, set the following parameters:

| Parameter | Description |
|-----------|-------------|
| **External Vault URL** | The Vault address (e.g., `http://127.0.0.1:8210`) |
| **Vault Role ID (AppRole auth)** | The `role_id` from Step 2 |
| **Vault Secret ID (AppRole auth)** | The `secret_id` from Step 2 |

#### Step 4: Restart CMA Master

Restart the CMA Master service from Cloudera Manager. Verify that the `vault` profile is active by checking the CMA server log on the CMA Server host:

```shell
grep 'profiles are active' /var/log/cma/cma-server.log | tail -1
```

The output should include `vault` among the active profiles. Additionally, confirm the Vault extension loaded:

```shell
grep 'vault-ext' /var/log/cma/cma-server.log | tail -1
```

Expected output: `Loaded extension: vault-ext v1.0.0`

#### Managing Vault after setup

**Restart Vault** (e.g., after a host reboot):
```shell
export VAULT_HOME=/opt/cloudera/parcels/cma/vault-local
export PYTHON_EXECUTABLE=python3
cd $VAULT_HOME/scripts/bin
bash vault-server.sh start
```

**Stop Vault:**
```shell
cd /opt/cloudera/parcels/cma/vault-local/scripts/bin
bash vault-server.sh stop
```

> **_NOTE:_** The Vault server runs as a background process. If the host reboots, Vault must be restarted before CMA starts. The CMA Server expects Vault to be available when the `vault` profile is active.

