Documentation
¶
Index ¶
- Variables
- func ApplyRoleBindingTaints(ctx context.Context, store RBACStore, rb *corev1.RoleBinding) error
- func GetStoreBuilder[T ~string](name T) func(...any) (any, error)
- func IsAlreadyExists(err error) bool
- func IsConflict(err error) bool
- func IsDiscontinuity(err error) bool
- func IsNotFound(err error) bool
- func NewRBACProvider(store SubjectAccessCapableStore) rbac.Provider
- func NewWatchContext[T any](base context.Context, eventC <-chan WatchEvent[T]) context.Context
- func RegisterStoreBuilder[T ~string](name T, builder func(...any) (any, error))
- type AlertFilterOptions
- type Backend
- type ClusterMutator
- type ClusterStore
- type CompositeBackend
- type DeleteOpt
- type DeleteOptions
- type GetOpt
- type GetOptions
- type GrpcTtlCache
- type HistoryOpt
- type HistoryOptions
- type HttpTtlCache
- type IncludeValuesOpt
- type KeyRevision
- type KeyRevisionImpl
- type KeyValueStore
- type KeyValueStoreBroker
- type KeyValueStoreT
- type KeyValueStoreTBroker
- type KeyringStore
- type KeyringStoreBroker
- type LimitOpt
- type ListKeysOptions
- type ListOpt
- type Lock
- type LockManager
- type MutatorFunc
- func NewAddCapabilityMutator[O corev1.MetadataAccessor[T], T corev1.Capability[T]](capability T) MutatorFunc[O]
- func NewCompositeMutator[T any](mutators ...MutatorFunc[T]) MutatorFunc[T]
- func NewIncrementUsageCountMutator() MutatorFunc[*corev1.BootstrapToken]
- func NewRemoveCapabilityMutator[O corev1.MetadataAccessor[T], T corev1.Capability[T]](capability T) MutatorFunc[O]
- type PrefixOpt
- type PutOpt
- type PutOptions
- type RBACStore
- type RevisionOpt
- type RevisionOutOpt
- type RoleBindingMutator
- type RoleMutator
- type SelectorPredicate
- type SubjectAccessCapableStore
- type TokenCreateOption
- type TokenCreateOptions
- type TokenMutator
- type TokenStore
- type ValueStoreT
- type WatchEvent
- type WatchEventType
- type WatchOpt
- type WatchOptions
Constants ¶
This section is empty.
Variables ¶
var ( ErrEventChannelClosed = errors.New("event channel closed") ErrObjectDeleted = errors.New("object deleted") )
var ( ErrNotFound = status.Error(codes.NotFound, "not found") ErrAlreadyExists = status.Error(codes.AlreadyExists, "already exists") ErrConflict = lo.Must(status.New(codes.Aborted, "conflict").WithDetails(ErrDetailsConflict)).Err() )
var ( ErrDetailsConflict = &errdetails.ErrorInfo{Reason: "CONFLICT"} ErrDetailsDiscontinuity = &errdetails.ErrorInfo{Reason: "DISCONTINUITY"} )
Functions ¶
func ApplyRoleBindingTaints ¶
func GetStoreBuilder ¶ added in v0.9.2
func IsAlreadyExists ¶ added in v0.12.0
Use this instead of errors.Is(err, ErrAlreadyExists). The implementation of Is() for grpc status errors compares the error message, which can result in false negatives.
func IsConflict ¶ added in v0.12.0
Use this instead of errors.Is(err, ErrConflict). The status code is too generic to identify conflict errors, so there are additional details added to conflict errors to disambiguate them.
func IsDiscontinuity ¶ added in v0.12.0
func IsNotFound ¶ added in v0.12.0
Use this instead of errors.Is(err, ErrNotFound). The implementation of Is() for grpc status errors compares the error message, which can result in false negatives.
func NewRBACProvider ¶
func NewRBACProvider(store SubjectAccessCapableStore) rbac.Provider
func NewWatchContext ¶ added in v0.6.0
Returns a context that listens on a watch event channel and closes its Done channel when the object is deleted. This context should have exclusive read access to the event channel to avoid missing events.
Types ¶
type AlertFilterOptions ¶ added in v0.5.4
type Backend ¶
type Backend interface { TokenStore ClusterStore RBACStore KeyringStoreBroker KeyValueStoreBroker }
type ClusterMutator ¶
type ClusterMutator = MutatorFunc[*corev1.Cluster]
type ClusterStore ¶
type ClusterStore interface { CreateCluster(ctx context.Context, cluster *corev1.Cluster) error DeleteCluster(ctx context.Context, ref *corev1.Reference) error GetCluster(ctx context.Context, ref *corev1.Reference) (*corev1.Cluster, error) UpdateCluster(ctx context.Context, ref *corev1.Reference, mutator ClusterMutator) (*corev1.Cluster, error) WatchCluster(ctx context.Context, cluster *corev1.Cluster) (<-chan WatchEvent[*corev1.Cluster], error) WatchClusters(ctx context.Context, known []*corev1.Cluster) (<-chan WatchEvent[*corev1.Cluster], error) ListClusters(ctx context.Context, matchLabels *corev1.LabelSelector, matchOptions corev1.MatchOptions) (*corev1.ClusterList, error) }
type CompositeBackend ¶
type CompositeBackend struct { TokenStore ClusterStore RBACStore KeyringStoreBroker KeyValueStoreBroker }
func (*CompositeBackend) IsValid ¶
func (cb *CompositeBackend) IsValid() bool
func (*CompositeBackend) Use ¶
func (cb *CompositeBackend) Use(store any)
type DeleteOpt ¶ added in v0.12.0
type DeleteOpt interface{ ApplyDeleteOption(*DeleteOptions) }
type DeleteOptions ¶ added in v0.12.0
type DeleteOptions struct { // Delete only if the latest Revision matches Revision *int64 }
func (*DeleteOptions) Apply ¶ added in v0.12.0
func (o *DeleteOptions) Apply(opts ...DeleteOpt)
type GetOpt ¶ added in v0.12.0
type GetOpt interface{ ApplyGetOption(*GetOptions) }
type GetOptions ¶ added in v0.12.0
type GetOptions struct { // If set, will return the config at the specified revision instead of // the current config. Revision *int64 // If non-nil, will be set to the current revision of the key after the Get // operation completes successfully. If an error occurs, no changes // will be made to the value. RevisionOut *int64 }
func (*GetOptions) Apply ¶ added in v0.12.0
func (o *GetOptions) Apply(opts ...GetOpt)
type GrpcTtlCache ¶ added in v0.9.2
type HistoryOpt ¶ added in v0.12.0
type HistoryOpt interface{ ApplyHistoryOption(*HistoryOptions) }
type HistoryOptions ¶ added in v0.12.0
type HistoryOptions struct { // Specifies the latest modification revision to include in the returned // history. The history will contain all revisions of the key, starting at // the most recent creation revision, and ending at either the specified // revision, or the most recent modification revision of the key. If the // specified revision is before the latest creation revision, and the // key has multiple creation revisions (due to a delete and re-create), // then the history will instead start at the most recent creation // revision that is <= the specified revision. Revision *int64 // Include the values in the response, not just the metadata. This could // have performance implications, so use with caution. IncludeValues bool }
func (*HistoryOptions) Apply ¶ added in v0.12.0
func (o *HistoryOptions) Apply(opts ...HistoryOpt)
type HttpTtlCache ¶ added in v0.8.3
type IncludeValuesOpt ¶ added in v0.12.0
type IncludeValuesOpt bool
func IncludeValues ¶ added in v0.12.0
func IncludeValues(include bool) IncludeValuesOpt
IncludeValues can be used for HistoryOptions.
func (IncludeValuesOpt) ApplyHistoryOption ¶ added in v0.12.0
func (i IncludeValuesOpt) ApplyHistoryOption(opts *HistoryOptions)
type KeyRevision ¶ added in v0.12.0
type KeyRevision[T any] interface { Key() string SetKey(string) // If values were requested, returns the value at this revision. Otherwise, // returns the zero value for T. // Note that if the value has a revision field, it will *not* // be populated, and should be set manually if needed using the Revision() // method. Value() T // Returns the revision of this key. Larger values are newer, but the // revision number should otherwise be treated as an opaque value. Revision() int64 // Returns the timestamp of this revision. This may or may not always be // available, depending on if the underlying store supports it. Timestamp() time.Time }
type KeyRevisionImpl ¶ added in v0.12.0
func (*KeyRevisionImpl[T]) Key ¶ added in v0.12.0
func (k *KeyRevisionImpl[T]) Key() string
func (*KeyRevisionImpl[T]) Revision ¶ added in v0.12.0
func (k *KeyRevisionImpl[T]) Revision() int64
func (*KeyRevisionImpl[T]) SetKey ¶ added in v0.12.0
func (k *KeyRevisionImpl[T]) SetKey(key string)
func (*KeyRevisionImpl[T]) Timestamp ¶ added in v0.12.0
func (k *KeyRevisionImpl[T]) Timestamp() time.Time
func (*KeyRevisionImpl[T]) Value ¶ added in v0.12.0
func (k *KeyRevisionImpl[T]) Value() T
type KeyValueStore ¶
type KeyValueStore = KeyValueStoreT[[]byte]
type KeyValueStoreBroker ¶
type KeyValueStoreBroker interface {
KeyValueStore(namespace string) KeyValueStore
}
type KeyValueStoreT ¶ added in v0.6.0
type KeyValueStoreT[T any] interface { Put(ctx context.Context, key string, value T, opts ...PutOpt) error Get(ctx context.Context, key string, opts ...GetOpt) (T, error) // Starts a watch on the specified key. The returned channel will receive // events for the key until the context is canceled, after which the // channel will be closed. This function does not block. An error will only // be returned if the key is invalid or the watch fails to start. // // When the watch is started, the current value of the key will be sent // if and only if both of the following conditions are met: // 1. A revision is explicitly set in the watch options. If no revision is // specified, only future events will be sent. // 2. The key exists; or in prefix mode, there is at least one key matching // the prefix. // // In most cases a starting revision should be specified, as this will // ensure no events are missed. // // This function can be called multiple times for the same key, prefix, or // overlapping prefixes. Each call will initiate a separate watch, and events // are always replicated to all active watches. // // The channels are buffered to hold at least 64 events. Ensure that events // are read from the channel in a timely manner if a large volume of events // are expected; otherwise it will block and events may be delayed, or be // dropped by the backend. Watch(ctx context.Context, key string, opts ...WatchOpt) (<-chan WatchEvent[KeyRevision[T]], error) Delete(ctx context.Context, key string, opts ...DeleteOpt) error ListKeys(ctx context.Context, prefix string, opts ...ListOpt) ([]string, error) History(ctx context.Context, key string, opts ...HistoryOpt) ([]KeyRevision[T], error) }
type KeyValueStoreTBroker ¶ added in v0.12.0
type KeyValueStoreTBroker[T any] interface { KeyValueStore(namespace string) KeyValueStoreT[T] }
type KeyringStore ¶
type KeyringStoreBroker ¶
type KeyringStoreBroker interface {
KeyringStore(namespace string, ref *corev1.Reference) KeyringStore
}
type LimitOpt ¶ added in v0.12.0
type LimitOpt int64
func WithLimit ¶ added in v0.12.0
WithLimit can be used for ListKeysOptions or HistoryOptions.
func (LimitOpt) ApplyListOption ¶ added in v0.12.0
func (l LimitOpt) ApplyListOption(opts *ListKeysOptions)
type ListKeysOptions ¶ added in v0.12.0
type ListKeysOptions struct { // Maximum number of keys to return Limit *int64 }
func (*ListKeysOptions) Apply ¶ added in v0.12.0
func (o *ListKeysOptions) Apply(opts ...ListOpt)
type ListOpt ¶ added in v0.12.0
type ListOpt interface{ ApplyListOption(*ListKeysOptions) }
type Lock ¶ added in v0.11.2
type Lock interface { // Lock acquires a lock on the key. If the lock is already held, it will block until the lock is released.\ // // Lock returns an error when acquiring the lock fails. Lock() error // Unlock releases the lock on the key. If the lock was never held, it will return an error. Unlock() error }
Lock is a distributed lock that can be used to coordinate access to a resource.
Locks are single use, and return errors when used more than once. Retry mechanisms are built into\ the Lock and can be configured with LockOptions.
type LockManager ¶ added in v0.11.2
type LockManager interface { // Instantiates a new Lock instance for the given key, with the given options. // // Defaults to lock.DefaultOptions if no options are provided. Locker(key string, opts ...lock.LockOption) Lock }
LockManager replaces sync.Mutex when a distributed locking mechanism is required.
Usage ¶
## Transient lock (transactions, tasks, ...) ```
func distributedTransation(lm stores.LockManager, key string) error { keyMu := lm.Locker(key, lock.WithKeepalive(false), lock.WithExpireDuration(1 * time.Second)) if err := keyMu.Lock(); err != nil { return err } defer keyMu.Unlock() // do some work }
```
## Persistent lock (leader election)
```
func serve(lm stores.LockManager, key string, done chan struct{}) error { keyMu := lm.Locker(key, lock.WithKeepalive(true)) if err := keyMu.Lock(); err != nil { return err } go func() { <-done keyMu.Unlock() }() // serve a service... }
```
type MutatorFunc ¶
type MutatorFunc[T any] func(T)
func NewAddCapabilityMutator ¶
func NewAddCapabilityMutator[O corev1.MetadataAccessor[T], T corev1.Capability[T]](capability T) MutatorFunc[O]
func NewCompositeMutator ¶
func NewCompositeMutator[T any](mutators ...MutatorFunc[T]) MutatorFunc[T]
func NewIncrementUsageCountMutator ¶
func NewIncrementUsageCountMutator() MutatorFunc[*corev1.BootstrapToken]
func NewRemoveCapabilityMutator ¶
func NewRemoveCapabilityMutator[O corev1.MetadataAccessor[T], T corev1.Capability[T]](capability T) MutatorFunc[O]
type PrefixOpt ¶ added in v0.12.0
type PrefixOpt bool
func (PrefixOpt) ApplyWatchOption ¶ added in v0.12.0
func (p PrefixOpt) ApplyWatchOption(opts *WatchOptions)
type PutOpt ¶ added in v0.12.0
type PutOpt interface{ ApplyPutOption(*PutOptions) }
type PutOptions ¶ added in v0.12.0
type PutOptions struct { // Put only if the latest Revision matches Revision *int64 // If non-nil, will be set to the updated revision of the key after the Put // operation completes successfully. If an error occurs, no changes // will be made to the value. RevisionOut *int64 }
func (*PutOptions) Apply ¶ added in v0.12.0
func (o *PutOptions) Apply(opts ...PutOpt)
type RBACStore ¶
type RBACStore interface { CreateRole(context.Context, *corev1.Role) error UpdateRole(ctx context.Context, ref *corev1.Reference, mutator RoleMutator) (*corev1.Role, error) DeleteRole(context.Context, *corev1.Reference) error GetRole(context.Context, *corev1.Reference) (*corev1.Role, error) CreateRoleBinding(context.Context, *corev1.RoleBinding) error UpdateRoleBinding(ctx context.Context, ref *corev1.Reference, mutator RoleBindingMutator) (*corev1.RoleBinding, error) DeleteRoleBinding(context.Context, *corev1.Reference) error GetRoleBinding(context.Context, *corev1.Reference) (*corev1.RoleBinding, error) ListRoles(context.Context) (*corev1.RoleList, error) ListRoleBindings(context.Context) (*corev1.RoleBindingList, error) }
type RevisionOpt ¶ added in v0.12.0
type RevisionOpt int64
func WithRevision ¶ added in v0.12.0
func WithRevision(rev int64) RevisionOpt
WithRevision can be used for GetOptions, PutOptions, WatchOptions, or DeleteOptions
func (RevisionOpt) ApplyDeleteOption ¶ added in v0.12.0
func (r RevisionOpt) ApplyDeleteOption(opts *DeleteOptions)
func (RevisionOpt) ApplyGetOption ¶ added in v0.12.0
func (r RevisionOpt) ApplyGetOption(opts *GetOptions)
func (RevisionOpt) ApplyHistoryOption ¶ added in v0.12.0
func (r RevisionOpt) ApplyHistoryOption(opts *HistoryOptions)
func (RevisionOpt) ApplyPutOption ¶ added in v0.12.0
func (r RevisionOpt) ApplyPutOption(opts *PutOptions)
func (RevisionOpt) ApplyWatchOption ¶ added in v0.12.0
func (r RevisionOpt) ApplyWatchOption(opts *WatchOptions)
type RevisionOutOpt ¶ added in v0.12.0
type RevisionOutOpt struct {
// contains filtered or unexported fields
}
func WithRevisionOut ¶ added in v0.12.0
func WithRevisionOut(out *int64) RevisionOutOpt
WithRevisionOut can be used for GetOptions or PutOptions.
func (RevisionOutOpt) ApplyGetOption ¶ added in v0.12.0
func (r RevisionOutOpt) ApplyGetOption(opts *GetOptions)
func (RevisionOutOpt) ApplyPutOption ¶ added in v0.12.0
func (r RevisionOutOpt) ApplyPutOption(opts *PutOptions)
type RoleBindingMutator ¶ added in v0.11.0
type RoleBindingMutator = MutatorFunc[*corev1.RoleBinding]
type RoleMutator ¶ added in v0.11.0
type RoleMutator = MutatorFunc[*corev1.Role]
type SelectorPredicate ¶
type SelectorPredicate[T corev1.IdLabelReader] func(T) bool
func NewSelectorPredicate ¶ added in v0.6.1
func NewSelectorPredicate[T corev1.IdLabelReader](s *corev1.ClusterSelector) SelectorPredicate[T]
type SubjectAccessCapableStore ¶
type SubjectAccessCapableStore interface { ListClusters(ctx context.Context, matchLabels *corev1.LabelSelector, matchOptions corev1.MatchOptions) (*corev1.ClusterList, error) GetRole(ctx context.Context, ref *corev1.Reference) (*corev1.Role, error) ListRoleBindings(ctx context.Context) (*corev1.RoleBindingList, error) }
A store that can be used to compute subject access rules
type TokenCreateOption ¶
type TokenCreateOption func(*TokenCreateOptions)
func WithCapabilities ¶
func WithCapabilities(capabilities []*corev1.TokenCapability) TokenCreateOption
func WithLabels ¶
func WithLabels(labels map[string]string) TokenCreateOption
func WithMaxUsages ¶ added in v0.10.0
func WithMaxUsages(usages int64) TokenCreateOption
type TokenCreateOptions ¶
type TokenCreateOptions struct { Labels map[string]string Capabilities []*corev1.TokenCapability MaxUsages int64 }
func NewTokenCreateOptions ¶
func NewTokenCreateOptions() TokenCreateOptions
func (*TokenCreateOptions) Apply ¶
func (o *TokenCreateOptions) Apply(opts ...TokenCreateOption)
type TokenMutator ¶
type TokenMutator = MutatorFunc[*corev1.BootstrapToken]
type TokenStore ¶
type TokenStore interface { CreateToken(ctx context.Context, ttl time.Duration, opts ...TokenCreateOption) (*corev1.BootstrapToken, error) DeleteToken(ctx context.Context, ref *corev1.Reference) error GetToken(ctx context.Context, ref *corev1.Reference) (*corev1.BootstrapToken, error) UpdateToken(ctx context.Context, ref *corev1.Reference, mutator TokenMutator) (*corev1.BootstrapToken, error) ListTokens(ctx context.Context) ([]*corev1.BootstrapToken, error) }
type ValueStoreT ¶ added in v0.6.0
type ValueStoreT[T any] interface { Put(ctx context.Context, value T, opts ...PutOpt) error Get(ctx context.Context, opts ...GetOpt) (T, error) Watch(ctx context.Context, opts ...WatchOpt) (<-chan WatchEvent[KeyRevision[T]], error) Delete(ctx context.Context, opts ...DeleteOpt) error History(ctx context.Context, opts ...HistoryOpt) ([]KeyRevision[T], error) }
type WatchEvent ¶ added in v0.6.0
type WatchEvent[T any] struct { EventType WatchEventType Current T Previous T }
type WatchEventType ¶ added in v0.6.0
type WatchEventType string
const ( // An operation that creates a new key OR modifies an existing key. // // NB: The Watch API does not distinguish between create and modify events. // It is not practical (nor desired, in most cases) to provide this info // to the caller, because it cannot be guaranteed to be accurate in all cases. // Because of the inability to make this guarantee, any client code that // relies on this distinction would be highly likely to end up in an invalid // state after a sufficient amount of time, or after issuing a watch request // on a key that has a complex and/or truncated history. However, in certain // cases, clients may be able to correlate events with out-of-band information // to reliably disambiguate Put events. This is necessarily an implementation // detail and may not always be possible. WatchEventPut WatchEventType = "Put" // An operation that removes an existing key. // // Delete events make few guarantees, as different backends handle deletes // differently. Backends are not required to discard revision history, or // to stop sending events for a key after it has been deleted. Keys may // be recreated after a delete event, in which case a Put event will follow. // Such events may or may not contain a previous revision value, depending // on implementation details of the backend (they will always contain a // current revision value, though). WatchEventDelete WatchEventType = "Delete" )
type WatchOpt ¶ added in v0.12.0
type WatchOpt interface{ ApplyWatchOption(*WatchOptions) }
func WithPrefix ¶ added in v0.12.0
func WithPrefix() WatchOpt
type WatchOptions ¶ added in v0.12.0
type WatchOptions struct { // Starting revision for the watch. If not specified, will start at the // latest revision. Revision *int64 // If true, all keys under the same prefix will be watched. // When prefix mode is disabled (default), events will only be sent for // the single key specified in the request. // If used in combination with the revision option, will effectively // "replay" the history of all keys under the prefix starting at the // specified revision. // Care should be taken when using this option, especially in combination // with a past revision, as it could cause performance issues. Prefix bool }
func (*WatchOptions) Apply ¶ added in v0.12.0
func (o *WatchOptions) Apply(opts ...WatchOpt)