store

Documentation

Overview

Package store provides a generic way to store credentials to connect to virtually any kind of remote system. The term `context` comes from the similar feature in Kubernetes kubectl config files.

Conceptually, a context is a set of metadata and TLS data, that can be used to connect to various endpoints of a remote system. TLS data and metadata are stored separately, so that in the future, we will be able to store sensitive information in a more secure way, depending on the os we are running on (e.g.: on Windows we could use the user Certificate Store, on macOS the user Keychain...).

Current implementation is purely file based with the following structure:

${CONTEXT_ROOT}
  meta/
    <context id>/meta.json: contains context medata (key/value pairs) as
                            well as a list of endpoints (themselves containing
                            key/value pair metadata).
  tls/
    <context id>/endpoint1/: directory containing TLS data for the endpoint1
                             in the corresponding context.

The context store itself has absolutely no knowledge about what a docker endpoint should contain in term of metadata or TLS config. Client code is responsible for generating and parsing endpoint metadata and TLS files. The multi-endpoints approach of this package allows to combine many different endpoints in the same "context".

Context IDs are actually SHA256 hashes of the context name, and are there only to avoid dealing with special characters in context names.

Index

• func Export(name string, s Reader) io.ReadCloser
• func Import(name string, s Writer, reader io.Reader) error
• func IsErrContextDoesNotExist(err error) bool
• func IsErrTLSDataDoesNotExist(err error) bool
• func Names(s Lister) ([]string, error)
• func ValidateContextName(name string) error
• type Config
  • func NewConfig(contextType TypeGetter, endpoints ...NamedTypeGetter) Config
  • func (c Config) ForeachEndpointType(cb func(string, TypeGetter) error) error
  • func (c Config) SetEndpoint(name string, getter TypeGetter)
• type ContextStore
  • func New(dir string, cfg Config) *ContextStore
  • func (s *ContextStore) CreateOrUpdate(meta Metadata) error
  • func (s *ContextStore) GetMetadata(name string) (Metadata, error)
  • func (s *ContextStore) GetStorageInfo(contextName string) StorageInfo
  • func (s *ContextStore) GetTLSData(contextName, endpointName, fileName string) ([]byte, error)
  • func (s *ContextStore) List() ([]Metadata, error)
  • func (s *ContextStore) ListTLSFiles(name string) (map[string]EndpointFiles, error)
  • func (s *ContextStore) Remove(name string) error
  • func (s *ContextStore) ResetEndpointTLSMaterial(contextName string, endpointName string, data *EndpointTLSData) error
  • func (s *ContextStore) ResetTLSMaterial(name string, data *ContextTLSData) error
• type ContextTLSData
• type EndpointFiles
• type EndpointTLSData
• type LimitedReader
  • func (l *LimitedReader) Read(p []byte) (n int, err error)
• type Lister
• type Metadata
• type NamedTypeGetter
  • func EndpointTypeGetter(name string, getter TypeGetter) NamedTypeGetter
• type Reader
• type ReaderLister
• type ReaderWriter
• type StorageInfo
• type StorageInfoProvider
• type Store
• type TypeGetter
• type Writer

Functions

func Export

func Export(name string, s Reader) io.ReadCloser

Export exports an existing namespace into an opaque data stream This stream is actually a tarball containing context metadata and TLS materials, but it does not map 1:1 the layout of the context store (don't try to restore it manually without calling store.Import)

func Import

func Import(name string, s Writer, reader io.Reader) error

Import imports an exported context into a store

func IsErrContextDoesNotExist

func IsErrContextDoesNotExist(err error) bool

IsErrContextDoesNotExist checks if the given error is a "context does not exist" condition.

Deprecated: use github.com/docker/docker/errdefs.IsNotFound()

func IsErrTLSDataDoesNotExist

func IsErrTLSDataDoesNotExist(err error) bool

IsErrTLSDataDoesNotExist checks if the given error is a "context does not exist" condition

Deprecated: use github.com/docker/docker/errdefs.IsNotFound()

func Names

func Names(s Lister) ([]string, error)

Names return Metadata names for a Lister

func ValidateContextName

func ValidateContextName(name string) error

ValidateContextName checks a context name is valid.

Types

type Config

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

Config is used to configure the metadata marshaler of the context ContextStore

func NewConfig

func NewConfig(contextType TypeGetter, endpoints ...NamedTypeGetter) Config

NewConfig creates a config object

func (Config) ForeachEndpointType

func (c Config) ForeachEndpointType(cb func(string, TypeGetter) error) error

ForeachEndpointType calls cb on every endpoint type registered with the Config

func (Config) SetEndpoint

func (c Config) SetEndpoint(name string, getter TypeGetter)

SetEndpoint set an endpoint typing information

type ContextStore

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

ContextStore implements Store.

func New

func New(dir string, cfg Config) *ContextStore

New creates a store from a given directory. If the directory does not exist or is empty, initialize it

func (*ContextStore) CreateOrUpdate

func (s *ContextStore) CreateOrUpdate(meta Metadata) error

CreateOrUpdate creates or updates metadata for the context.

func (*ContextStore) GetMetadata

func (s *ContextStore) GetMetadata(name string) (Metadata, error)

GetMetadata returns the metadata for the context with the given name. It returns an errdefs.ErrNotFound if the context was not found.

func (*ContextStore) GetStorageInfo

func (s *ContextStore) GetStorageInfo(contextName string) StorageInfo

GetStorageInfo returns the paths where the Metadata and TLS data are stored for the context.

func (*ContextStore) GetTLSData

func (s *ContextStore) GetTLSData(contextName, endpointName, fileName string) ([]byte, error)

GetTLSData reads, and returns the content of the given fileName for an endpoint. It returns an errdefs.ErrNotFound if the file was not found.

func (*ContextStore) List

func (s *ContextStore) List() ([]Metadata, error)

List return all contexts.

func (*ContextStore) ListTLSFiles

func (s *ContextStore) ListTLSFiles(name string) (map[string]EndpointFiles, error)

ListTLSFiles returns the list of TLS files present for each endpoint in the context.

func (*ContextStore) Remove

func (s *ContextStore) Remove(name string) error

Remove deletes the context with the given name, if found.

func (*ContextStore) ResetEndpointTLSMaterial

func (s *ContextStore) ResetEndpointTLSMaterial(contextName string, endpointName string, data *EndpointTLSData) error

ResetEndpointTLSMaterial removes TLS data for the given context and endpoint, and replaces it with the new data.

func (*ContextStore) ResetTLSMaterial

func (s *ContextStore) ResetTLSMaterial(name string, data *ContextTLSData) error

ResetTLSMaterial removes TLS data for all endpoints in the context and replaces it with the new data.

type ContextTLSData

type ContextTLSData struct {
	Endpoints map[string]EndpointTLSData
}

ContextTLSData represents tls data for a whole context

type EndpointFiles

type EndpointFiles []string

EndpointFiles is a slice of strings representing file names

type EndpointTLSData

type EndpointTLSData struct {
	Files map[string][]byte
}

EndpointTLSData represents tls data for a given endpoint

type LimitedReader

type LimitedReader struct {
	R io.Reader
	N int64 // max bytes remaining
}

LimitedReader is a fork of io.LimitedReader to override Read.

func (*LimitedReader) Read

func (l *LimitedReader) Read(p []byte) (n int, err error)

Read is a fork of io.LimitedReader.Read that returns an error when limit exceeded.

type Lister

type Lister interface {
	List() ([]Metadata, error)
}

Lister provides listing of contexts

type Metadata

type Metadata struct {
	Name      string                 `json:",omitempty"`
	Metadata  interface{}            `json:",omitempty"`
	Endpoints map[string]interface{} `json:",omitempty"`
}

Metadata contains metadata about a context and its endpoints

type NamedTypeGetter

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

NamedTypeGetter is a TypeGetter associated with a name

func EndpointTypeGetter

func EndpointTypeGetter(name string, getter TypeGetter) NamedTypeGetter

EndpointTypeGetter returns a NamedTypeGetter with the spcecified name and getter

type Reader

type Reader interface {
	GetMetadata(name string) (Metadata, error)
	ListTLSFiles(name string) (map[string]EndpointFiles, error)
	GetTLSData(contextName, endpointName, fileName string) ([]byte, error)
}

Reader provides read-only (without list) access to context data

type ReaderLister

type ReaderLister interface {
	Reader
	Lister
}

ReaderLister combines Reader and Lister interfaces

type ReaderWriter

type ReaderWriter interface {
	Reader
	Writer
}

ReaderWriter combines Reader and Writer interfaces

type StorageInfo

type StorageInfo struct {
	MetadataPath string
	TLSPath      string
}

StorageInfo contains data about where a given context is stored

type StorageInfoProvider

type StorageInfoProvider interface {
	GetStorageInfo(contextName string) StorageInfo
}

StorageInfoProvider provides more information about storage details of contexts

type Store

type Store interface {
	Reader
	Lister
	Writer
	StorageInfoProvider
}

Store provides a context store for easily remembering endpoints configuration

type TypeGetter

type TypeGetter func() interface{}

TypeGetter is a func used to determine the concrete type of a context or endpoint metadata by returning a pointer to an instance of the object eg: for a context of type DockerContext, the corresponding TypeGetter should return new(DockerContext)

type Writer

type Writer interface {
	CreateOrUpdate(meta Metadata) error
	Remove(name string) error
	ResetTLSMaterial(name string, data *ContextTLSData) error
	ResetEndpointTLSMaterial(contextName string, endpointName string, data *EndpointTLSData) error
}

Writer provides write access to context data