secretsmanager

Documentation

Overview

Package secretsmanager provides an AWS Secrets Manager integration block. It exposes a clean API for retrieving, creating, rotating, and deleting secrets, with first-class support for JSON-structured secret values.

Index

• type Block
  • func New(name string, opts ...Option) *Block
  • func (b *Block) CreateSecret(ctx context.Context, name, value, description string) (string, error)
  • func (b *Block) CreateSecretJSON(ctx context.Context, name string, v any, description string) (string, error)
  • func (b *Block) DeleteSecret(ctx context.Context, name string, opts DeleteOptions) error
  • func (b *Block) GetSecret(ctx context.Context, name string) (string, error)
  • func (b *Block) GetSecretBinary(ctx context.Context, name string) ([]byte, error)
  • func (b *Block) GetSecretJSON(ctx context.Context, name string, v any) error
  • func (b *Block) GetSecretVersion(ctx context.Context, name, versionID string) (string, error)
  • func (b *Block) Init(ctx context.Context) error
  • func (b *Block) ListSecrets(ctx context.Context) ([]SecretMetadata, error)
  • func (b *Block) Name() string
  • func (b *Block) RotateSecret(ctx context.Context, name string) error
  • func (b *Block) Shutdown(_ context.Context) error
  • func (b *Block) UpdateSecret(ctx context.Context, name, value string) error
  • func (b *Block) UpdateSecretJSON(ctx context.Context, name string, v any) error
• type DeleteOptions
• type Option
  • func WithAWSConfig(cfg aws.Config) Option
  • func WithEndpoint(endpoint string) Option
  • func WithProfile(profile string) Option
  • func WithRegion(region string) Option
  • func WithVersionStage(stage string) Option
• type SecretMetadata

Types

type Block

type Block struct {
	// contains filtered or unexported fields
}

Block is an AWS Secrets Manager integration block.

func New

func New(name string, opts ...Option) *Block

New creates a new Secrets Manager Block.

block := secretsmanager.New("secrets",
    secretsmanager.WithRegion("us-east-1"),
)

func (*Block) CreateSecret

func (b *Block) CreateSecret(ctx context.Context, name, value, description string) (string, error)

CreateSecret creates a new string secret. description is optional; pass an empty string to omit it.

func (*Block) CreateSecretJSON

func (b *Block) CreateSecretJSON(ctx context.Context, name string, v any, description string) (string, error)

CreateSecretJSON marshals v to JSON and creates a new structured secret. Returns the ARN of the created secret.

func (*Block) DeleteSecret

func (b *Block) DeleteSecret(ctx context.Context, name string, opts DeleteOptions) error

DeleteSecret schedules a secret for deletion. By default a 30-day recovery window applies. Use DeleteOptions to customise the window or force an immediate, irreversible deletion.

func (*Block) GetSecret

func (b *Block) GetSecret(ctx context.Context, name string) (string, error)

GetSecret retrieves the current string value of a secret by name or ARN. For binary secrets, use GetSecretBinary instead.

func (*Block) GetSecretBinary

func (b *Block) GetSecretBinary(ctx context.Context, name string) ([]byte, error)

GetSecretBinary retrieves the current binary value of a secret.

func (*Block) GetSecretJSON

func (b *Block) GetSecretJSON(ctx context.Context, name string, v any) error

GetSecretJSON retrieves a secret and unmarshals its JSON value into v. This is the idiomatic way to work with structured secrets (database credentials, API keys with multiple fields, etc.).

type DBCreds struct { Host, User, Password string }
var creds DBCreds
if err := secrets.GetSecretJSON(ctx, "prod/db", &creds); err != nil { … }

func (*Block) GetSecretVersion

func (b *Block) GetSecretVersion(ctx context.Context, name, versionID string) (string, error)

GetSecretVersion retrieves a specific version of a secret. Useful for accessing a previous secret value during rotation.

func (*Block) Init

func (b *Block) Init(ctx context.Context) error

Init implements core.Block.

func (*Block) ListSecrets

func (b *Block) ListSecrets(ctx context.Context) ([]SecretMetadata, error)

ListSecrets returns metadata for all secrets in the account/region. Pagination is handled internally.

func (*Block) Name

func (b *Block) Name() string

Name implements core.Block.

func (*Block) RotateSecret

func (b *Block) RotateSecret(ctx context.Context, name string) error

RotateSecret immediately triggers the rotation Lambda associated with the secret. Rotation must have been previously configured.

func (*Block) Shutdown

func (b *Block) Shutdown(_ context.Context) error

Shutdown implements core.Block.

func (*Block) UpdateSecret

func (b *Block) UpdateSecret(ctx context.Context, name, value string) error

UpdateSecret replaces the value of an existing secret. Secrets Manager automatically creates a new version and stages it as AWSCURRENT while moving the previous value to AWSPREVIOUS.

func (*Block) UpdateSecretJSON

func (b *Block) UpdateSecretJSON(ctx context.Context, name string, v any) error

UpdateSecretJSON marshals v to JSON and updates an existing structured secret.

type DeleteOptions

type DeleteOptions struct {
	// ForceDelete skips the 7–30 day recovery window and immediately removes
	// the secret. Use with caution — this is irreversible.
	ForceDelete bool
	// RecoveryWindowDays sets a custom recovery window (7–30 days).
	// Ignored when ForceDelete is true.
	RecoveryWindowDays int32
}

DeleteOptions controls the behaviour of DeleteSecret.

type Option

type Option func(*blockConfig)

Option configures a Secrets Manager Block.

func WithAWSConfig

func WithAWSConfig(cfg aws.Config) Option

WithAWSConfig injects a pre-built aws.Config, bypassing automatic resolution.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint overrides the Secrets Manager endpoint (e.g. LocalStack).

func WithProfile

func WithProfile(profile string) Option

WithProfile selects a named AWS credentials profile.

func WithRegion

func WithRegion(region string) Option

WithRegion sets the AWS region.

func WithVersionStage

func WithVersionStage(stage string) Option

WithVersionStage sets the default version stage for GetSecret operations. Defaults to "AWSCURRENT" when not provided.

type SecretMetadata

type SecretMetadata struct {
	Name        string
	ARN         string
	Description string
	LastChanged time.Time
}

SecretMetadata holds summary information about a secret, as returned by ListSecrets.