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