configuration

package
v0.219.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 20, 2024 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package configuration is the FTL configuration and secret management API.

The full design is documented here.

A Manager is the high-level interface to storing, listing, and retrieving secrets and configuration. A Resolver is the next layer, mapping names to a storage location key such as environment variables, keychain, etc. The Provider is the final layer, responsible for actually storing and retrieving values in concrete storage.

A constructed Manager and its providers are parametric on either secrets or configuration and thus cannot be used interchangeably.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = errors.New("not found")

ErrNotFound is returned when a configuration entry is not found or cannot be resolved.

Functions

func ConfigFromEnvironment added in v0.201.0 

func ConfigFromEnvironment() []string

func ContextWithConfig added in v0.138.0 

func ContextWithConfig(ctx context.Context, configManager *Manager[Configuration]) context.Context

ContextWithConfig adds a configuration manager to the given context.

func ContextWithSecrets added in v0.138.0 

func ContextWithSecrets(ctx context.Context, secretsManager *Manager[Secrets]) context.Context

ContextWithSecrets adds a secrets manager to the given context.

Types

type Configuration added in v0.138.0 

type Configuration struct{}

func (Configuration) String added in v0.145.0 

func (Configuration) String() string

type DefaultConfigMixin added in v0.138.0 

type DefaultConfigMixin struct {
	InlineProvider[Configuration]
	EnvarProvider[Configuration]
}

DefaultConfigMixin is a Kong mixin that provides the default configuration manager.

func (DefaultConfigMixin) NewConfigurationManager added in v0.138.0 

func (d DefaultConfigMixin) NewConfigurationManager(ctx context.Context, resolver Resolver[Configuration]) (*Manager[Configuration], error)

NewConfigurationManager creates a new configuration manager with the default configuration providers.

type DefaultSecretsMixin added in v0.138.0 

type DefaultSecretsMixin struct {
	InlineProvider[Secrets]
	EnvarProvider[Secrets]
	KeychainProvider
	OnePasswordProvider
}

DefaultSecretsMixin is a Kong mixin that provides the default secrets manager.

func (DefaultSecretsMixin) NewSecretsManager added in v0.138.0 

func (d DefaultSecretsMixin) NewSecretsManager(ctx context.Context, resolver Resolver[Secrets]) (*Manager[Secrets], error)

NewSecretsManager creates a new secrets manager with the default secret providers.

type Entry 

type Entry struct {
	Ref
	Accessor *url.URL
}

Entry in the configuration store.

type EnvarProvider 

type EnvarProvider[R Role] struct {
	Envar bool `help:"Print configuration as environment variables." xor:"configwriter" group:"Provider:"`
}

EnvarProvider is a configuration provider that reads secrets or configuration from environment variables.

func (EnvarProvider[R]) Delete 

func (e EnvarProvider[R]) Delete(ctx context.Context, ref Ref) error

func (EnvarProvider[R]) Key 

func (EnvarProvider[R]) Key() string

func (EnvarProvider[R]) Load 

func (e EnvarProvider[R]) Load(ctx context.Context, ref Ref, key *url.URL) ([]byte, error)

func (EnvarProvider[R]) Role added in v0.145.0 

func (EnvarProvider[R]) Role() R

func (EnvarProvider[R]) Store 

func (e EnvarProvider[R]) Store(ctx context.Context, ref Ref, value []byte) (*url.URL, error)

func (EnvarProvider[R]) Writer 

func (e EnvarProvider[R]) Writer() bool

type InlineProvider 

type InlineProvider[R Role] struct {
	Inline bool `help:"Write values inline in the configuration file." group:"Provider:" xor:"configwriter"`
}

InlineProvider is a configuration provider that stores configuration in its key.

func (InlineProvider[R]) Delete 

func (InlineProvider[R]) Delete(ctx context.Context, ref Ref) error

func (InlineProvider[R]) Key 

func (InlineProvider[R]) Key() string

func (InlineProvider[R]) Load 

func (InlineProvider[R]) Load(ctx context.Context, ref Ref, key *url.URL) ([]byte, error)

func (InlineProvider[R]) Role added in v0.145.0 

func (InlineProvider[R]) Role() R

func (InlineProvider[R]) Store 

func (InlineProvider[R]) Store(ctx context.Context, ref Ref, value []byte) (*url.URL, error)

func (InlineProvider[R]) Writer 

func (i InlineProvider[R]) Writer() bool

type KeychainProvider 

type KeychainProvider struct {
	Keychain bool `help:"Write to the system keychain." group:"Provider:" xor:"configwriter"`
}

func (KeychainProvider) Delete 

func (k KeychainProvider) Delete(ctx context.Context, ref Ref) error

func (KeychainProvider) Key 

func (k KeychainProvider) Key() string

func (KeychainProvider) Load 

func (k KeychainProvider) Load(ctx context.Context, ref Ref, key *url.URL) ([]byte, error)

func (KeychainProvider) Role added in v0.145.0 

func (KeychainProvider) Role() Secrets

func (KeychainProvider) Store 

func (k KeychainProvider) Store(ctx context.Context, ref Ref, value []byte) (*url.URL, error)

func (KeychainProvider) Writer 

func (k KeychainProvider) Writer() bool

type Manager 

type Manager[R Role] struct {
	// contains filtered or unexported fields
}

Manager is a high-level configuration manager that abstracts the details of the Resolver and Provider interfaces.

func ConfigFromContext added in v0.138.0 

func ConfigFromContext(ctx context.Context) *Manager[Configuration]

ConfigFromContext retrieves the configuration.Manager previously added to the context with ContextWithConfig.

func New 

func New[R Role](ctx context.Context, resolver Resolver[R], providers []Provider[R]) (*Manager[R], error)

New configuration manager.

func NewConfigurationManager added in v0.138.0 

func NewConfigurationManager(ctx context.Context, resolver Resolver[Configuration]) (*Manager[Configuration], error)

NewConfigurationManager constructs a new Manager with the default providers for configuration.

func NewDefaultConfigurationManagerFromConfig added in v0.201.0 

func NewDefaultConfigurationManagerFromConfig(ctx context.Context, config []string) (*Manager[Configuration], error)

NewDefaultConfigurationManagerFromConfig creates a new configuration manager from the project config found in the config paths.

func NewDefaultSecretsManagerFromConfig added in v0.201.0 

func NewDefaultSecretsManagerFromConfig(ctx context.Context, config []string) (*Manager[Secrets], error)

NewDefaultSecretsManagerFromConfig creates a new secrets manager from the project config found in the config paths.

func NewSecretsManager added in v0.138.0 

func NewSecretsManager(ctx context.Context, resolver Resolver[Secrets]) (*Manager[Secrets], error)

NewSecretsManager constructs a new Manager with the default providers for secrets.

func SecretsFromContext added in v0.138.0 

func SecretsFromContext(ctx context.Context) *Manager[Secrets]

SecretsFromContext retrieves the secrets configuration.Manager previously added to the context with ContextWithConfig.

func (*Manager[R]) Get 

func (m *Manager[R]) Get(ctx context.Context, ref Ref, value any) error

Get a configuration value from the active providers.

"value" must be a pointer to a Go type that can be unmarshalled from JSON.

func (*Manager[R]) List 

func (m *Manager[R]) List(ctx context.Context) ([]Entry, error)

func (*Manager[R]) MapForModule added in v0.184.2 

func (m *Manager[R]) MapForModule(ctx context.Context, module string) (map[string][]byte, error)

MapForModule combines all configuration values visible to the module. Local values take precedence.

func (*Manager[R]) Mutable 

func (m *Manager[R]) Mutable() error

Mutable returns an error if the configuration manager doesn't have a writeable provider configured.

func (*Manager[R]) Set 

func (m *Manager[R]) Set(ctx context.Context, ref Ref, value any) error

Set a configuration value.

func (*Manager[R]) Unset 

func (m *Manager[R]) Unset(ctx context.Context, ref Ref) error

Unset a configuration value in all providers.

type MutableProvider 

type MutableProvider[R Role] interface {
	Provider[R]
	// Writer returns true if this provider should be used to store configuration.
	//
	// Only one provider should return true.
	//
	// To be usable from the CLI, each provider must be a Kong-compatible struct
	// containing a flag that this method should return. For example:
	//
	// 	type InlineProvider struct {
	// 		Inline bool `help:"Write values inline." group:"Provider:" xor:"configwriter"`
	// 	}
	//
	//	func (i InlineProvider) Writer() bool { return i.Inline }
	//
	// The "xor" tag is used to ensure that only one writer is selected.
	Writer() bool
	// Store a configuration value and return its key.
	Store(ctx context.Context, ref Ref, value []byte) (*url.URL, error)
	// Delete a configuration value.
	Delete(ctx context.Context, ref Ref) error
}

A MutableProvider is a Provider that can update configuration.

type OnePasswordProvider 

type OnePasswordProvider struct {
	OnePassword bool `name:"op" help:"Write 1Password secret references - does not write to 1Password." group:"Provider:" xor:"configwriter"`
}

OnePasswordProvider is a configuration provider that reads passwords from 1Password vaults via the "op" command line tool.

func (OnePasswordProvider) Delete 

func (o OnePasswordProvider) Delete(ctx context.Context, ref Ref) error

func (OnePasswordProvider) Key 

func (o OnePasswordProvider) Key() string

func (OnePasswordProvider) Load 

func (o OnePasswordProvider) Load(ctx context.Context, ref Ref, key *url.URL) ([]byte, error)

Load returns either a single field if the op:// reference specifies a field, or all fields if not.

A single value/password: op://Personal/With Spaces/username op --format json item get --vault Personal "With Spaces" --fields=username { id, value, ... } "value"

All fields: op://Personal/With Spaces op --format json item get --vault Personal "With Spaces" { fields: [ { id, value, ... } ], ... } { id: value, ... }

func (OnePasswordProvider) Role added in v0.145.0 

func (OnePasswordProvider) Role() Secrets

func (OnePasswordProvider) Store 

func (o OnePasswordProvider) Store(ctx context.Context, ref Ref, value []byte) (*url.URL, error)

func (OnePasswordProvider) Writer 

func (o OnePasswordProvider) Writer() bool

type ProjectConfigResolver 

type ProjectConfigResolver[R Role] struct {
	Config []string `` /* 139-byte string literal not displayed */
}

ProjectConfigResolver is parametric Resolver that loads values from either a project's configuration or secrets maps based on the type parameter.

See the [projectconfig] package for details on the configuration file format.

func (ProjectConfigResolver[R]) Get 

func (p ProjectConfigResolver[R]) Get(ctx context.Context, ref Ref) (*url.URL, error)

func (ProjectConfigResolver[R]) List 

func (p ProjectConfigResolver[R]) List(ctx context.Context) ([]Entry, error)

func (ProjectConfigResolver[R]) Role added in v0.145.0 

func (p ProjectConfigResolver[R]) Role() R

func (ProjectConfigResolver[R]) Set 

func (p ProjectConfigResolver[R]) Set(ctx context.Context, ref Ref, key *url.URL) error

func (ProjectConfigResolver[From]) Unset 

func (p ProjectConfigResolver[From]) Unset(ctx context.Context, ref Ref) error

type Provider 

type Provider[R Role] interface {
	Role() R
	Key() string
	Load(ctx context.Context, ref Ref, key *url.URL) ([]byte, error)
}

Provider is a generic interface for storing and retrieving configuration and secrets.

type Ref 

type Ref struct {
	Module optional.Option[string]
	Name   string
}

A Ref is a reference to a configuration value.

func NewRef 

func NewRef(module, name string) Ref

NewRef creates a new Ref.

If [module] is empty, the Ref is considered to be a global configuration value.

func ParseRef 

func ParseRef(s string) (Ref, error)

func (Ref) String 

func (k Ref) String() string

func (*Ref) UnmarshalText 

func (k *Ref) UnmarshalText(text []byte) error

type Resolver 

type Resolver[R Role] interface {
	Role() R
	Get(ctx context.Context, ref Ref) (key *url.URL, err error)
	Set(ctx context.Context, ref Ref, key *url.URL) error
	Unset(ctx context.Context, ref Ref) error
	List(ctx context.Context) ([]Entry, error)
}

A Resolver resolves configuration names to keys that are then used to load values from a Provider.

This indirection allows for the storage of configuration values to be abstracted from the configuration itself. For example, the ftl-project.toml file contains per-module and global configuration maps, but the secrets themselves may be stored in a separate secret store such as a system keychain.

type Role added in v0.138.0 

type Role interface {
	Secrets | Configuration
}

Role of Manager, either Secrets or Configuration.

type Secrets added in v0.138.0 

type Secrets struct{}

func (Secrets) String added in v0.145.0 

func (Secrets) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.