---
layout: docs
page_title: Setup guide - GCP Cloud KMS
description: Configure the key management secrets engine, and distribute the Vault-managed keys to the target GCP Cloud KMS.
---

# Setup guide - GCP Cloud KMS 

To manage the lifecycle of the GCP Cloud KMS key rings, you need to setup the
key management secrets engine using `gcpckms` provider.

## Setup

1. Enable the key management secrets engine.

    ```shell-session
    $ vault secrets enable keymgmt
    ```

1. Configure the KMS provider resource named, `example-kms`.

    ```shell-session
    $ vault write keymgmt/kms/example-kms \
        provider="gcpckms" \
        key_collection="projects/<project-id>/locations/<location>/keyRings/<keyring>" \
        credentials=service_account_file="/path/to/service_account/credentials.json"
    ```

    The command specified the following:

    - The full path to this KMS provider instance in Vault
      (`keymgmt/kms/example-kms`).
    - The KMS provider type is set to `gcpckms`.
    - A key collection, which refers to the [resource
      ID](https://cloud.google.com/kms/docs/resource-hierarchy#retrieve_resource_id)
      of an existing GCP Cloud KMS key ring; this value cannot be changed after
      creation.
    - Credentials file to use for authentication with GCP Cloud KMS. Supplying
      values for this parameter is optional, as credentials may also be
      specified as the `GOOGLE_CREDENTIALS` environment variable or default
      application credentials.


<Tip title="API documentation">

Refer to the GCP Cloud KMS [API
documentation](/vault/api-docs/secret/key-management/gcpkms) for a detailed
description of individual configuration parameters.

</Tip>

## Usage 

1. Write a new key of type **aes256-gcm96** to the path `keymgmt/key/aes256-gcm96`. 

    ```shell-session
    $ vault write keymgmt/key/aes256-gcm96 type="aes256-gcm96"
    ```

1. Read the **aes256-gcm96** key, use JSON as the output, and pipe that into `jq`.

    ```shell-session
    $ vault read -format=json keymgmt/key/aes256-gcm96 | jq
    ```

    **Example output:**

    <CodeBlockConfig hideClipboard>

    ```json
    {
        "request_id": "631f98de-b755-9863-40db-f789ff9ff10a",
        "lease_id": "",
        "lease_duration": 0,
        "renewable": false,
        "data": {
            "deletion_allowed": false,
            "latest_version": 1,
            "min_enabled_version": 1,
            "name": "aes256-gcm96",
            "type": "aes256-gcm96",
            "versions": {
            "1": {
                "creation_time": "2021-11-16T13:07:17.878864-05:00"
            }
            }
        },
        "warnings": null
    }
    ```

    </CodeBlockConfig>

    Notice the value of `versions`; it is **1** since this is the first version
    of the key that Vault knows about. This will figure into the example on key
    rotation later.

1. To use the keys you wrote, you must distribute them to the Cloud KMS. Add the
   **aes256-gcm96** key to the Cloud KMS at the path
   `keymgmt/kms/example-kms/key/aes256-gcm96`.

    ```shell-session
    $ vault write keymgmt/kms/example-kms/key/aes256-gcm96 \
        purpose="encrypt,decrypt" \
        protection="hsm"
    ```

1. List the keys that have been distributed to the Cloud KMS instance.

    ```shell-session
    $ vault list keymgmt/kms/gcpckms/key/
    Keys
    ----
    aes256-gcm96
    ```

1. Rotate the key.

    ```shell-session
    $ vault write -f keymgmt/key/aes256-gcm96/rotate
    ```

1. Confirm successful key rotation by reading the key, and get the value of
   `.data.latest_version`.

    ```shell-session
    $  vault read -format=json keymgmt/key/aes256-gcm96 | jq '.data.latest_version'
    2
    ``` 

    The key is now at version 2; in the Cloud Console, the key will be expected
    to have a different version string than the original value under **Primary
    version** as shown in the Cloud Console UI screenshot.
