or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/cloud.google.com/go/kms@v1.24.0

docs

autokey-client.mdcore-types.mdekm-client.mdenums.mdindex.mdinventory-clients.mditerators.mdkey-management-client.mdoperations.mdrequest-response-types.md
tile.json

tessl/golang-cloud-google-com--go--kms

tessl install tessl/golang-cloud-google-com--go--kms@1.24.0

Go Client Library for Google Cloud Key Management Service (KMS) API for managing cryptographic keys and performing cryptographic operations

autokey-client.mddocs/

Autokey Clients - Automated Key Provisioning

Overview

Cloud KMS Autokey automates the provisioning of CryptoKeys for Customer Managed Encryption Key (CMEK) use cases. The library provides two specialized clients:

  • AutokeyClient - Creates and manages KeyHandles that trigger automatic CryptoKey provisioning
  • AutokeyAdminClient - Manages folder-level Autokey configurations

Package: cloud.google.com/go/kms/apiv1

AutokeyClient

The AutokeyClient enables on-demand provisioning of CryptoKeys by creating KeyHandle resources. When a KeyHandle is created in a resource project, Cloud KMS Autokey automatically provisions a CryptoKey in the configured key project.

Client Creation

NewAutokeyClient

func NewAutokeyClient(ctx context.Context, opts ...option.ClientOption) (*AutokeyClient, error)

Creates a new autokey client based on gRPC. The returned client must be Closed when done.

NewAutokeyRESTClient

func NewAutokeyRESTClient(ctx context.Context, opts ...option.ClientOption) (*AutokeyClient, error)

Creates a new autokey REST client.

Example:

ctx := context.Background()
client, err := kms.NewAutokeyClient(ctx)
if err != nil {
    // Handle error
}
defer client.Close()

Client Type

type AutokeyClient struct {
    // CallOptions contains the retry settings for each method
    CallOptions *AutokeyCallOptions

    // LROClient is used internally to handle long-running operations.
    // It is exposed so that its CallOptions can be modified if required.
    // Users should not Close this client.
    LROClient *lroauto.OperationsClient

    // Has unexported fields
}

Methods

CreateKeyHandle

func (c *AutokeyClient) CreateKeyHandle(ctx context.Context, req *kmspb.CreateKeyHandleRequest, opts ...gax.CallOption) (*CreateKeyHandleOperation, error)

Creates a new KeyHandle, triggering the provisioning of a new CryptoKey for CMEK use with the given resource type in the configured key project and the same location. Use GetOperation to resolve the resulting long-running operation and get the resulting KeyHandle and CryptoKey.

Request:

type CreateKeyHandleRequest struct {
    Parent      string      // Required: "projects/{project}/locations/{location}"
    KeyHandleId string      // Optional: ID for the KeyHandle
    KeyHandle   *KeyHandle  // Required: KeyHandle with initial field values
}

Returns: *CreateKeyHandleOperation - Long-running operation handle

Example:

req := &kmspb.CreateKeyHandleRequest{
    Parent:      "projects/resource-project/locations/us-central1",
    KeyHandleId: "my-keyhandle",
    KeyHandle: &kmspb.KeyHandle{
        ResourceTypeSelector: "bigquery.googleapis.com/Dataset",
    },
}

op, err := client.CreateKeyHandle(ctx, req)
if err != nil {
    // Handle error
}

// Wait for operation to complete
keyHandle, err := op.Wait(ctx)
if err != nil {
    // Handle error
}
fmt.Printf("Created KeyHandle: %s\n", keyHandle.Name)
fmt.Printf("Provisioned CryptoKey: %s\n", keyHandle.KmsKey)

CreateKeyHandleOperation

func (c *AutokeyClient) CreateKeyHandleOperation(name string) *CreateKeyHandleOperation

Returns a new CreateKeyHandleOperation from a given name. The name must be that of a previously created CreateKeyHandleOperation, possibly from a different process.

GetKeyHandle

func (c *AutokeyClient) GetKeyHandle(ctx context.Context, req *kmspb.GetKeyHandleRequest, opts ...gax.CallOption) (*kmspb.KeyHandle, error)

Returns the KeyHandle.

Request:

type GetKeyHandleRequest struct {
    Name string // Required: "projects/{project}/locations/{location}/keyHandles/{keyHandle}"
}

ListKeyHandles

func (c *AutokeyClient) ListKeyHandles(ctx context.Context, req *kmspb.ListKeyHandlesRequest, opts ...gax.CallOption) *KeyHandleIterator

Lists KeyHandles in a location.

Request:

type ListKeyHandlesRequest struct {
    Parent    string // Required: "projects/{project}/locations/{location}"
    PageSize  int32  // Optional: Max 1000, default 500
    PageToken string // Optional: Pagination token
    Filter    string // Optional: Filter expression
}

Example:

req := &kmspb.ListKeyHandlesRequest{
    Parent: "projects/my-project/locations/us-central1",
}

it := client.ListKeyHandles(ctx, req)
for {
    keyHandle, err := it.Next()
    if err == iterator.Done {
        break
    }
    if err != nil {
        // Handle error
    }
    fmt.Printf("KeyHandle: %s -> CryptoKey: %s\n", keyHandle.Name, keyHandle.KmsKey)
}

IAM Methods

func (c *AutokeyClient) GetIamPolicy(ctx context.Context, req *iampb.GetIamPolicyRequest, opts ...gax.CallOption) (*iampb.Policy, error)
func (c *AutokeyClient) SetIamPolicy(ctx context.Context, req *iampb.SetIamPolicyRequest, opts ...gax.CallOption) (*iampb.Policy, error)
func (c *AutokeyClient) TestIamPermissions(ctx context.Context, req *iampb.TestIamPermissionsRequest, opts ...gax.CallOption) (*iampb.TestIamPermissionsResponse, error)

Location Methods

func (c *AutokeyClient) GetLocation(ctx context.Context, req *locationpb.GetLocationRequest, opts ...gax.CallOption) (*locationpb.Location, error)
func (c *AutokeyClient) ListLocations(ctx context.Context, req *locationpb.ListLocationsRequest, opts ...gax.CallOption) *LocationIterator

Utility Methods

func (c *AutokeyClient) GetOperation(ctx context.Context, req *longrunningpb.GetOperationRequest, opts ...gax.CallOption) (*longrunningpb.Operation, error)
func (c *AutokeyClient) Close() error
func (c *AutokeyClient) Connection() *grpc.ClientConn // Deprecated

CallOptions

type AutokeyCallOptions struct {
    CreateKeyHandle    []gax.CallOption
    GetKeyHandle       []gax.CallOption
    ListKeyHandles     []gax.CallOption
    GetLocation        []gax.CallOption
    ListLocations      []gax.CallOption
    GetIamPolicy       []gax.CallOption
    SetIamPolicy       []gax.CallOption
    TestIamPermissions []gax.CallOption
    GetOperation       []gax.CallOption
}

AutokeyAdminClient

The AutokeyAdminClient manages Cloud KMS Autokey folder-level configurations. A configuration is inherited by all descendant projects and determines where Autokey provisions CryptoKeys.

Client Creation

NewAutokeyAdminClient

func NewAutokeyAdminClient(ctx context.Context, opts ...option.ClientOption) (*AutokeyAdminClient, error)

Creates a new autokey admin client based on gRPC.

NewAutokeyAdminRESTClient

func NewAutokeyAdminRESTClient(ctx context.Context, opts ...option.ClientOption) (*AutokeyAdminClient, error)

Creates a new autokey admin REST client.

Example:

ctx := context.Background()
client, err := kms.NewAutokeyAdminClient(ctx)
if err != nil {
    // Handle error
}
defer client.Close()

Client Type

type AutokeyAdminClient struct {
    // CallOptions contains the retry settings for each method
    CallOptions *AutokeyAdminCallOptions

    // Has unexported fields
}

Methods

UpdateAutokeyConfig

func (c *AutokeyAdminClient) UpdateAutokeyConfig(ctx context.Context, req *kmspb.UpdateAutokeyConfigRequest, opts ...gax.CallOption) (*kmspb.AutokeyConfig, error)

Updates the AutokeyConfig for a folder. The caller must have both cloudkms.autokeyConfigs.update permission on the parent folder and cloudkms.cryptoKeys.setIamPolicy permission on the provided key project. A KeyHandle creation in the folder's descendant projects will use this configuration to determine where to create the resulting CryptoKey.

Request:

type UpdateAutokeyConfigRequest struct {
    AutokeyConfig *AutokeyConfig         // Required: AutokeyConfig with updated values
    UpdateMask    *fieldmaskpb.FieldMask // Required: Fields to update
}

Example:

import "google.golang.org/protobuf/types/known/fieldmaskpb"

req := &kmspb.UpdateAutokeyConfigRequest{
    AutokeyConfig: &kmspb.AutokeyConfig{
        Name:       "folders/123456789/autokeyConfig",
        KeyProject: "projects/key-project-id",
    },
    UpdateMask: &fieldmaskpb.FieldMask{
        Paths: []string{"key_project"},
    },
}

config, err := client.UpdateAutokeyConfig(ctx, req)
if err != nil {
    // Handle error
}
fmt.Printf("Updated AutokeyConfig: %s\n", config.Name)

GetAutokeyConfig

func (c *AutokeyAdminClient) GetAutokeyConfig(ctx context.Context, req *kmspb.GetAutokeyConfigRequest, opts ...gax.CallOption) (*kmspb.AutokeyConfig, error)

Returns the AutokeyConfig for a folder.

Request:

type GetAutokeyConfigRequest struct {
    Name string // Required: "folders/{folder}/autokeyConfig"
}

Example:

req := &kmspb.GetAutokeyConfigRequest{
    Name: "folders/123456789/autokeyConfig",
}

config, err := client.GetAutokeyConfig(ctx, req)
if err != nil {
    // Handle error
}
fmt.Printf("Key Project: %s\n", config.KeyProject)
fmt.Printf("State: %s\n", config.State)

ShowEffectiveAutokeyConfig

func (c *AutokeyAdminClient) ShowEffectiveAutokeyConfig(ctx context.Context, req *kmspb.ShowEffectiveAutokeyConfigRequest, opts ...gax.CallOption) (*kmspb.ShowEffectiveAutokeyConfigResponse, error)

Returns the effective Cloud KMS Autokey configuration for a given project. The configuration is determined by checking the project's folder ancestry for an AutokeyConfig.

Request:

type ShowEffectiveAutokeyConfigRequest struct {
    Parent string // Required: "projects/{PROJECT_ID}" or "projects/{PROJECT_NUMBER}"
}

Response:

type ShowEffectiveAutokeyConfigResponse struct {
    KeyProject string // Name of the key project configured in the resource project's folder ancestry
}

Example:

req := &kmspb.ShowEffectiveAutokeyConfigRequest{
    Parent: "projects/my-resource-project",
}

resp, err := client.ShowEffectiveAutokeyConfig(ctx, req)
if err != nil {
    // Handle error
}
fmt.Printf("Effective key project: %s\n", resp.KeyProject)

IAM Methods

func (c *AutokeyAdminClient) GetIamPolicy(ctx context.Context, req *iampb.GetIamPolicyRequest, opts ...gax.CallOption) (*iampb.Policy, error)
func (c *AutokeyAdminClient) SetIamPolicy(ctx context.Context, req *iampb.SetIamPolicyRequest, opts ...gax.CallOption) (*iampb.Policy, error)
func (c *AutokeyAdminClient) TestIamPermissions(ctx context.Context, req *iampb.TestIamPermissionsRequest, opts ...gax.CallOption) (*iampb.TestIamPermissionsResponse, error)

Location Methods

func (c *AutokeyAdminClient) GetLocation(ctx context.Context, req *locationpb.GetLocationRequest, opts ...gax.CallOption) (*locationpb.Location, error)
func (c *AutokeyAdminClient) ListLocations(ctx context.Context, req *locationpb.ListLocationsRequest, opts ...gax.CallOption) *LocationIterator

Utility Methods

func (c *AutokeyAdminClient) GetOperation(ctx context.Context, req *longrunningpb.GetOperationRequest, opts ...gax.CallOption) (*longrunningpb.Operation, error)
func (c *AutokeyAdminClient) Close() error
func (c *AutokeyAdminClient) Connection() *grpc.ClientConn // Deprecated

CallOptions

type AutokeyAdminCallOptions struct {
    UpdateAutokeyConfig        []gax.CallOption
    GetAutokeyConfig           []gax.CallOption
    ShowEffectiveAutokeyConfig []gax.CallOption
    GetLocation                []gax.CallOption
    ListLocations              []gax.CallOption
    GetIamPolicy               []gax.CallOption
    SetIamPolicy               []gax.CallOption
    TestIamPermissions         []gax.CallOption
    GetOperation               []gax.CallOption
}

Autokey Resource Types

KeyHandle

type KeyHandle struct {
    Name                 string                 // Output only: "projects/{project}/locations/{location}/keyHandles/{keyHandle}"
    KmsKey               string                 // Output only: Name of provisioned CryptoKey
    ResourceTypeSelector string                 // Required: Intended resource type (e.g., "bigquery.googleapis.com/Dataset")
    CreateTime           *timestamppb.Timestamp // Output only: Creation time
}

A KeyHandle is a resource-oriented representation of a request to Cloud KMS Autokey and the resulting provisioning of a CryptoKey.

Resource Type Selector Examples:

  • "bigquery.googleapis.com/Dataset"
  • "storage.googleapis.com/Bucket"
  • "compute.googleapis.com/Disk"
  • "pubsub.googleapis.com/Topic"

AutokeyConfig

type AutokeyConfig struct {
    Name       string                 // Identifier: "folders/{folder}/autokeyConfig"
    KeyProject string                 // Optional: "projects/{PROJECT_ID}" or "projects/{PROJECT_NUMBER}"
    State      AutokeyConfig_State    // Output only: Current state
}

Cloud KMS Autokey configuration for a folder. Specifies where CryptoKeys should be created for descendant projects.

AutokeyConfig_State

type AutokeyConfig_State int32

const (
    AutokeyConfig_STATE_UNSPECIFIED    AutokeyConfig_State = 0 // Not specified
    AutokeyConfig_ACTIVE               AutokeyConfig_State = 1 // Autokey is enabled and functioning
    AutokeyConfig_KEY_PROJECT_DELETED  AutokeyConfig_State = 2 // Disabled because key project was deleted
    AutokeyConfig_UNINITIALIZED        AutokeyConfig_State = 3 // Autokey is not configured
)

Complete Autokey Workflow

package main

import (
    "context"
    "fmt"
    "log"

    kms "cloud.google.com/go/kms/apiv1"
    "cloud.google.com/go/kms/apiv1/kmspb"
    "google.golang.org/protobuf/types/known/fieldmaskpb"
)

func setupAutokey() {
    ctx := context.Background()

    // Step 1: Configure Autokey at folder level
    adminClient, err := kms.NewAutokeyAdminClient(ctx)
    if err != nil {
        log.Fatal(err)
    }
    defer adminClient.Close()

    // Update AutokeyConfig to specify key project
    _, err = adminClient.UpdateAutokeyConfig(ctx, &kmspb.UpdateAutokeyConfigRequest{
        AutokeyConfig: &kmspb.AutokeyConfig{
            Name:       "folders/123456789/autokeyConfig",
            KeyProject: "projects/my-key-project",
        },
        UpdateMask: &fieldmaskpb.FieldMask{
            Paths: []string{"key_project"},
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Step 2: Verify effective configuration for a project
    resp, err := adminClient.ShowEffectiveAutokeyConfig(ctx, &kmspb.ShowEffectiveAutokeyConfigRequest{
        Parent: "projects/my-resource-project",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Effective key project: %s\n", resp.KeyProject)

    // Step 3: Create KeyHandle to provision CryptoKey
    client, err := kms.NewAutokeyClient(ctx)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    op, err := client.CreateKeyHandle(ctx, &kmspb.CreateKeyHandleRequest{
        Parent: "projects/my-resource-project/locations/us-central1",
        KeyHandle: &kmspb.KeyHandle{
            ResourceTypeSelector: "bigquery.googleapis.com/Dataset",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Wait for CryptoKey to be provisioned
    keyHandle, err := op.Wait(ctx)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created KeyHandle: %s\n", keyHandle.Name)
    fmt.Printf("Provisioned CryptoKey: %s\n", keyHandle.KmsKey)
    // Now use keyHandle.KmsKey for CMEK operations
}

Best Practices

  1. Configure Autokey at the folder level before creating KeyHandles in descendant projects
  2. Use ShowEffectiveAutokeyConfig to verify configuration inheritance
  3. Grant appropriate IAM permissions:
    • cloudkms.autokeyConfigs.update on the folder
    • cloudkms.cryptoKeys.setIamPolicy on the key project
  4. Specify resource type selectors that match your use case
  5. Handle long-running operations properly using Wait() or Poll()
  6. Monitor AutokeyConfig state to detect if the key project is deleted

See Also

  • Long-Running Operations
  • Core Types
  • Iterators
  • KeyManagementClient