Key Management Service API overview

The Key Management Service (KMS) API uses Kubernetes custom resources to manage the lifecycle of the crypto keys.

To use the KMS API, use the GDC console. If your application uses your own libraries to call the API, adopt the example service endpoint in the following section, and the full API definitions to build your requests:

Service endpoint and discovery document

The KMS APIs are provided in two packages depending on zonal deployment or global deployment.

The API endpoints for the zonal and global KMS APIs are the following, respectively:

  • https://MANAGEMENT_API_SERVER_ENDPOINT/apis/kms.gdc.goog/v1
  • https://MANAGEMENT_API_SERVER_ENDPOINT/apis/kms.global.gdc.goog/v1

The MANAGEMENT_API_SERVER_ENDPOINT variable is the endpoint of the Management API server.

Using the kubectl proxy command, access the URL in your browser to obtain the discovery document for the KMS API. The kubectl proxy command opens up a proxy on 127.0.0.1:8001 to the Kubernetes API server on your local machine. After that command is running, access the documents at the following URLs:

  • http://127.0.0.1:8001/apis/kms.gdc.goog/v1
  • http://127.0.0.1:8001/apis/kms.global.gdc.goog/v1

Example resources

The following are sample resources. The namespace is a project namespace. View the Create a key section in the Create and delete keys page for more information on creating keys.

AEADKey resource

apiVersion: "kms.gdc.goog/v1"
kind: AEADKey
metadata:
  name: my-test-key
  namespace: user-kms-project
spec:
  algorithm: AES_256_GCM

SigningKey resource

apiVersion: "kms.gdc.goog/v1"
kind: SigningKey
metadata:
  name: my-test-key
  namespace: user-kms-project
spec:
  algorithm: EC_SIGN_P384_SHA384

KeyImport resource

apiVersion: "kms.gdc.goog/v1"
kind: KeyImport
metadata:
  name: my-test-key-import
  namespace: user-kms-project
spec:
  context:
    mechanism: ECDH_P521_AES256

KeyExport resource

apiVersion: "kms.gdc.goog/v1"
kind: KeyExport
metadata:
  name: my-test-key-export
  namespace: user-kms-project
spec:
  context:
    mechanism: ECDH_P521_AES256
    publicKey: pub_key_from_import
  keyToExport:
    kind: AEADKey
    name: key_name_to_export

RotationJob resource

apiVersion: "kms.gdc.goog/v1"
kind: RotationJob
metadata:
  name: my-test-rotate-job
spec:
  rootKeyResourceName: namespaces/kms-system/secrets/kms-key-ctm-root

MZAEADKey resource

apiVersion: "kms.global.gdc.goog/v1"
kind: MZAEADKey
metadata:
  name: my-test-mz-key
  namespace: user-kms-project
spec:
  algorithm: AES_256_GCM