---
layout: docs
page_title: Google Cloud Platform Key Management Service Keyring Configuration
description: >-
  Configure a Google Cloud Platform Key Management Service (GCP Cloud KMS) keyring in the `keyring "gcpckms"` block of a Nomad agent configuration. Configure GCP credentials, project, region, key ring, and crypto key. Learn how Nomad supports rotating keys defined in GCP Cloud KMS.
---

# Google Cloud Platform Key Management Service Keyring Configuration

This page provides reference information for configuring a Google Cloud Platform
Key Management Service (GCP Cloud KMS) keyring in the `keyring "gcpckms"` block
of a Nomad agent configuration. Configure GCP credentials, project, region, key
ring, and crypto key. Learn how Nomad supports rotating keys defined in GCP
Cloud KMS.

The GCP Cloud KMS keyring configures Nomad to use GCP Cloud KMS to wrap its
keyring. This example shows configuring GCP Cloud KMS keyring through the Nomad
configuration file by providing all the required values.

```hcl
keyring "gcpckms" {
  active = true
  name   = "example"

  credentials = "/etc/nomad.d/nomad-user-creds.json"
  project     = "nomad-project"
  region      = "global"
  key_ring    = "nomad-keyring"
  crypto_key  = "nomad-key"
}
```

## `gcpckms` parameters

These parameters apply to the `keyring` stanza in the Nomad configuration file:

- `credentials` `(string: <required>)`: The path to the credentials JSON file to
  use. Alternately specify via the `GOOGLE_CREDENTIALS` or
  `GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if
  running under Google Compute Engine.

- `project` `(string: <required>)`: The GCP project ID to use. Alternately
  specify via the `GOOGLE_PROJECT` environment variable.

- `region` `(string: <required>)`: The GCP region/location where the key ring
  lives. Alternately specify via the `GOOGLE_REGION` environment variable.

- `key_ring` `(string: <required>)`: The GCP KMS key ring to use.

- `crypto_key` `(string: <required>)`: The GCP KMS crypto key to use for
  encryption and decryption.

## Authentication &amp; permissions

You must provide authentication-related values either as environment
variables or as configuration parameters.

GCP authentication values:

- `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS`
- `GOOGLE_PROJECT`
- `GOOGLE_REGION`

Note: The client uses the official Google SDK and the specified credentials,
environment credentials, or [application default credentials][] in that order,
if you do not provide the aforementioned GCP-specific values.

The service account needs the following minimum permissions on the crypto key:

```text
cloudkms.cryptoKeyVersions.useToEncrypt
cloudkms.cryptoKeyVersions.useToDecrypt
cloudkms.cryptoKeys.get
```

These permissions can be described with the following role:

```text
roles/cloudkms.cryptoKeyEncrypterDecrypter
cloudkms.cryptoKeys.get
```

Use `cloudkms.cryptoKeys.get` permission for retrieving metadata information of
keys from CloudKMS within this engine initialization process.

## Key rotation

This keyring supports rotating keys defined in Google Cloud KMS
[doc][rotating_keys]. Both scheduled rotation and manual rotation is supported
for CKMS since the key information. Old keys version must not be disabled or
deleted and are used to decrypt older data. Any new or updated data is encrypted
with the primary key version.


[application default credentials]: https://developers.google.com/identity/protocols/application-default-credentials
[rotating_keys]: https://cloud.google.com/kms/docs/rotating-keys
