gcpsecretmanager

Documentation

Overview

Package gcpsecretmanager provides a runtimevar implementation with secrets read from GCP Secret Manager (https://cloud.google.com/secret-manager). Use OpenVariable to construct a *runtimevar.Variable.

URLs

For runtimevar.OpenVariable, gcpsecretmanager registers for the scheme "gcpsecretmanager". The default URL opener will creating a connection using use default credentials from the environment, as described in https://cloud.google.com/docs/authentication/production. To customize the URL opener, or for more details on the URL format, see URLOpener. See https://gocloud.dev/concepts/urls/ for background information.

As

gcpsecretmanager exposes the following types for As:

• Snapshot: *secretmanagerpb.AccessSecretVersionResponse
• Error: *status.Status

Example (OpenVariableFromURL)

package main

import (
	"context"
	"log"

	"gocloud.dev/runtimevar"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/runtimevar/gcpsecretmanager"
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	// runtimevar.OpenVariable creates a *runtimevar.Variable from a URL.
	// The URL Host+Path are used as the GCP Secret Manager secret key;
	// see https://cloud.google.com/secret-manager
	// for more details.

	v, err := runtimevar.OpenVariable(ctx, "gcpsecretmanager://projects/myproject/secrets/mysecret?decoder=string")
	if err != nil {
		log.Fatal(err)
	}
	defer v.Close()
}

Index

• Constants
• Variables
• func Dial(ctx context.Context, ts gcp.TokenSource) (*secretmanager.Client, func(), error)
• func OpenVariable(client *secretmanager.Client, secretKey string, decoder *runtimevar.Decoder, ...) (*runtimevar.Variable, error)
• func SecretKey(projectID gcp.ProjectID, secretID string) string
• type Options
• type URLOpener
  • func (o *URLOpener) OpenVariableURL(ctx context.Context, u *url.URL) (*runtimevar.Variable, error)

Examples

• Package (OpenVariableFromURL)
• OpenVariable

Constants

const Scheme = "gcpsecretmanager"

Scheme is the URL scheme gcpsecretmanager registers its URLOpener under on runtimevar.DefaultMux.

Variables

var Set = wire.NewSet(
	Dial,
	wire.Struct(new(URLOpener), "Client"),
)

Set holds Wire providers for this package.

Functions

func Dial

func Dial(ctx context.Context, ts gcp.TokenSource) (*secretmanager.Client, func(), error)

Dial opens a gRPC connection to the Secret Manager API using credentials from ts. It is provided as an optional helper with useful defaults.

The second return value is a function that should be called to clean up the connection opened by Dial.

func OpenVariable

func OpenVariable(client *secretmanager.Client, secretKey string, decoder *runtimevar.Decoder, opts *Options) (*runtimevar.Variable, error)

OpenVariable constructs a *runtimevar.Variable backed by secretKey in GCP Secret Manager.

A secretKey will look like:

projects/[project_id]/secrets/[secret_id]

A project ID is a unique, user-assigned ID of the Project. It must be 6 to 30 lowercase letters, digits, or hyphens. It must start with a letter. Trailing hyphens are prohibited.

A secret ID is a string with a maximum length of 255 characters and can contain uppercase and lowercase letters, numerals, and the hyphen (`-`) and underscore (`_`) characters.

gcpsecretmanager package will always use the latest secret value, so `/version/latest` postfix must NOT be added to the secret key.

You can use the full string (e.g., copied from the GCP Console), or construct one from its parts using SecretKey.

See https://cloud.google.com/secret-manager for more details.

Secret Manager returns raw bytes; provide a decoder to decode the raw bytes into the appropriate type for runtimevar.Snapshot.Value. See the runtimevar package documentation for examples of decoders.

Example

package main

import (
	"context"
	"log"

	"gocloud.dev/gcp"
	"gocloud.dev/runtimevar"
	"gocloud.dev/runtimevar/gcpsecretmanager"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	// Your GCP credentials.
	// See https://cloud.google.com/docs/authentication/production
	// for more info on alternatives.
	creds, err := gcp.DefaultCredentials(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Connect to the GCP Secret Manager service.
	client, cleanup, err := gcpsecretmanager.Dial(ctx, creds.TokenSource)
	if err != nil {
		log.Fatal(err)
	}
	defer cleanup()

	// You can use the SecretKey helper to construct a secret key from
	// your project ID and the secret ID; alternatively,
	// you can construct the full string yourself (e.g.,
	// "projects/gcp-project-id/secrets/secret-id").
	// gcpsecretmanager package will always use the latest secret value,
	// so `/version/latest` postfix must NOT be added to the secret key.
	// See https://cloud.google.com/secret-manager
	// for more details.
	//
	// For this example, the GCP Secret Manager secret being
	// referenced should have a JSON string that decodes into MyConfig.
	variableKey := gcpsecretmanager.SecretKey("gcp-project-id", "secret-id")

	// Construct a *runtimevar.Variable that watches the variable.
	v, err := gcpsecretmanager.OpenVariable(client, variableKey, runtimevar.StringDecoder, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer v.Close()
}

func SecretKey

func SecretKey(projectID gcp.ProjectID, secretID string) string

SecretKey constructs a GCP Secret Manager secret key from component parts. See https://cloud.google.com/secret-manager for more details.

Types

type Options

type Options struct {
	// WaitDuration controls the rate at which Secret Manager is polled.
	// Defaults to 30 seconds.
	WaitDuration time.Duration
}

Options sets options.

type URLOpener

type URLOpener struct {
	// Client must be set to a non-nil client authenticated with
	// Secret Manager scope or equivalent.
	Client *secretmanager.Client

	// Decoder specifies the decoder to use if one is not specified in the URL.
	// Defaults to runtimevar.BytesDecoder.
	Decoder *runtimevar.Decoder

	// Options specifies the options to pass to New.
	Options Options
}

URLOpener opens gcpsecretmanager URLs like "gcpsecretmanager://projects/[project_id]/secrets/[secret_id]".

The URL Host+Path are used as the GCP Secret Manager secret key; see https://cloud.google.com/secret-manager for more details.

The following query parameters are supported:

• decoder: The decoder to use. Defaults to URLOpener.Decoder, or runtimevar.BytesDecoder if URLOpener.Decoder is nil. See runtimevar.DecoderByName for supported values.
• wait: The poll interval, in time.ParseDuration formats. Defaults to 30s.

func (*URLOpener) OpenVariableURL

func (o *URLOpener) OpenVariableURL(ctx context.Context, u *url.URL) (*runtimevar.Variable, error)

OpenVariableURL opens a gcpsecretmanager Secret.