Documentation
¶
Overview ¶
Package resource contains helpers around managing groups of resources. A "resource" is any element created by a plugin. For example, an AWS deployment plugin may create load balancers, security groups, VPCs, etc. Each of these is a "resource".
This package simplifies resource lifecycle, state management, error handling, and more. Even if your plugin only has a single resource, this library is highly recommended.
Index ¶
- type Manager
- func (m *Manager) CreateAll(args ...interface{}) error
- func (m *Manager) DestroyAll(args ...interface{}) error
- func (m *Manager) LoadState(v *opaqueany.Any) error
- func (m *Manager) Resource(n string) *Resource
- func (m *Manager) State() *opaqueany.Any
- func (m *Manager) StatusAll(args ...interface{}) ([]*pb.StatusReport_Resource, error)
- func (m *Manager) StatusReport(args ...interface{}) (*pb.StatusReport, error)
- func (m *Manager) Validate() error
- type ManagerOption
- func WithDeclaredResourcesResp(dcr *component.DeclaredResourcesResp) ManagerOption
- func WithDestroyedResourcesResp(dtr *component.DestroyedResourcesResp) ManagerOption
- func WithLogger(l hclog.Logger) ManagerOption
- func WithResource(r *Resource) ManagerOption
- func WithValueProvider(f interface{}) ManagerOption
- type Resource
- func (r *Resource) Create(args ...interface{}) error
- func (r *Resource) DeclaredResource() (*pb.DeclaredResource, error)
- func (r *Resource) Destroy(args ...interface{}) error
- func (r *Resource) DestroyedResource() (*pb.DestroyedResource, error)
- func (r *Resource) SetState(v interface{}) error
- func (r *Resource) State() interface{}
- func (r *Resource) Status() *StatusResponse
- func (r *Resource) Validate() error
- type ResourceOption
- func WithCategoryDisplayHint(categoryDisplayHint pb.ResourceCategoryDisplayHint) ResourceOption
- func WithCreate(f interface{}) ResourceOption
- func WithDestroy(f interface{}) ResourceOption
- func WithName(n string) ResourceOption
- func WithPlatform(platform string) ResourceOption
- func WithState(v interface{}) ResourceOption
- func WithStatus(f interface{}) ResourceOption
- func WithType(t string) ResourceOption
- type StatusResponse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager manages the lifecycle and state of one or more resources.
A resource manager makes it easy to define the set of resources you want to create, create them, handle any errors, and persist the state of the resources you've created (such as IDs or other metadata) so that you can update or destroy the resources later.
Create a Manager with NewManager and a set of options.
func NewManager ¶
func NewManager(opts ...ManagerOption) *Manager
NewManager creates a new resource manager.
Callers should call Validate on the result to check for errors.
func (*Manager) CreateAll ¶
CreateAll creates all the resources for this manager.
The ordering will be determined based on the creation function dependencies for each resource.
Create will initialize brand new state. This will not reuse existing state. If there is any existing state loaded, this will return an error immediately because it risks that state being lost.
func (*Manager) DestroyAll ¶
DestroyAll destroys all the resources under management. This will call Destroy in the reverse order of Create. All the state that was created via Create will be available to the Destroy callbacks. Note that after a resource is destroyed, their state is also set to nil.
Only resources that have been created will be destroyed. This means that if Create partially failed, then only the resources that attempted creation will have Destroy called. Resources that were never called to Create will do nothing.
func (*Manager) Resource ¶
Resource returns the resource with the given name. This will return nil if the resource is not known.
func (*Manager) State ¶
State returns the serialized state for this manager and all the resources that are part of this manager. This is a `google.protobuf.Any` type and plugin authors are expected to serialize this type directly into their return values. This is an opaque type; plugin authors should make no attempt to deserialize this.
func (*Manager) StatusAll ¶
func (m *Manager) StatusAll(args ...interface{}) ([]*pb.StatusReport_Resource, error)
StatusAll invokes the statusFunc method of all the resources under management. The order in which the status of each resource is queried is non-deterministic, and does rely on any creation order or state of the resource. All the state that was created via Create will be available to the Status callbacks, if any. Resources are not required to have a state to have a status. Returns a slice of reports or an error.
func (*Manager) StatusReport ¶
func (m *Manager) StatusReport(args ...interface{}) (*pb.StatusReport, error)
StatusReport generates a report by invoking the statusFunc method of all resources under management, using those statuses to determine an overall composite health, and returns it within a status report. If all resources return the same health, the overall health will be that health. If resources return different healths, the overall health will be PARTIAL, and the health message will give more details. If your plugin wishes to use a different algorithm for determining overall health, you may modify this report before returning from your status function.
type ManagerOption ¶
type ManagerOption func(*Manager)
ManagerOption is used to configure NewManager.
func WithDeclaredResourcesResp ¶
func WithDeclaredResourcesResp(dcr *component.DeclaredResourcesResp) ManagerOption
WithDeclaredResourcesResp specifies a declared resource response that ResourceManager will automatically populate after creating resources. It will add one DeclaredResource per resource under management. For most plugins, this will be their only interaction with the DeclaredResourcesResponse.
func WithDestroyedResourcesResp ¶
func WithDestroyedResourcesResp(dtr *component.DestroyedResourcesResp) ManagerOption
WithDestroyedResourcesResp specifies a destroyed resource response that ResourceManager will automatically populate after creating resources. It will add one DestroyedResource per resource being destroyed. For most plugins, this will be their only interaction with the DeclaredResourcesResponse.
func WithLogger ¶
func WithLogger(l hclog.Logger) ManagerOption
WithLogger specifies the logger to use. If this is not set then this will use the default hclog logger.
func WithResource ¶
func WithResource(r *Resource) ManagerOption
WithResource specifies a resource for the manager. This can be called multiple times and the resources will be appended to the manager.
func WithValueProvider ¶
func WithValueProvider(f interface{}) ManagerOption
WithValueProvider specifies a function that can provide values for the arguments for resource lifecycle functions. This is useful for example to setup an API client. The value provider will be called AT MOST once for a set of resources (but may be called zero times if no resources depend on the value it returns).
The argument f should be a function. The function may accept arguments from any other value providers as well.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a single resource type with an associated lifecycle and state. A "resource" is any external thing a plugin creates such as a load balancer, networking primitives, files, etc. Representing these things as "resources" assists in lifecycle management, such as preventing dangling resources in the case of an error and properly cleaning them up.
func NewResource ¶
func NewResource(opts ...ResourceOption) *Resource
NewResource creates a new resource.
Callers should call Validate on the result to check for errors. If a resource is used in a resource manager, the resource manager Validate function will also validate all the resources part of it.
func (*Resource) Create ¶
Create creates this resource. args is a list of arguments to make available to the creation function via dependency injection (matching types in the arguments).
After Create is called, any state can be accessed via the State function. This may be populated even during failure with partial state.
func (*Resource) DeclaredResource ¶
func (r *Resource) DeclaredResource() (*pb.DeclaredResource, error)
DeclaredResource converts a resource to a DeclaredResource protobuf, which can be used in a component.DeclaredResourcesResp.
func (*Resource) Destroy ¶
Destroy destroys this resource. args is a list of arguments to make available to the destroy function via dependency injection. The state value will always be available as an argument (though it may be nil if this resource has no state).
After Destroy is called successfully (without an error result), the state will always be nil.
func (*Resource) DestroyedResource ¶
func (r *Resource) DestroyedResource() (*pb.DestroyedResource, error)
DestroyedResource converts a resource to a DestroyedResource protobuf, which can be used in a component.DestroyedResourcesResp
func (*Resource) SetState ¶
SetState manually sets the state for this resource. This is not recommended; typically state should only be modified through the lifecycle functions. However, this function is particularly useful to transition to using the resource manager from a previous version that didn't use the resource manager.
When calling Manager.DestroyAll after manually setting state using SetState, the Manager will destroy the resources in the opposite order SetState is called. To put it another way: try to call SetState on resources in the order they were created, since DestroyAll destroys in reverse creation order.
The value v must be the same type as the type given for WithState.
func (*Resource) State ¶
func (r *Resource) State() interface{}
State returns the current state for this resource. This will be nil if the resource hasn't been created yet or has been destroyed. If this value is non-nil, it is guaranteed to be the same type that was given to WithState. If WithState was never called, this is guaranteed to always be nil.
The returned value is also a direct pointer to the internally stored state so it should not be modified simultaneously to any resource operations.
func (*Resource) Status ¶
func (r *Resource) Status() *StatusResponse
Status returns a copy of this resources' internal status response, or nil if no status exists.
type ResourceOption ¶
type ResourceOption func(*Resource)
ResourceOption is used to configure NewResource.
func WithCategoryDisplayHint ¶
func WithCategoryDisplayHint(categoryDisplayHint pb.ResourceCategoryDisplayHint) ResourceOption
WithCategoryDisplayHint specifies the category this resource belongs to. Used for display purposes only.
Corresponds to the protobuf DeclaredResource.CategoryDisplayHint field
func WithCreate ¶
func WithCreate(f interface{}) ResourceOption
WithCreate sets the creation function for this resource.
The function may take as inputs any arguments it requires and can return any values it wants. The inputs will be automatically populated with available values that are configured on the resource manager. As a special case, the arguments may also accept the state type specified for WithState (if any) to get access to an allocated, empty state structure.
The return values are ignored, except for a final "error" value. A final "error" type value will be used to determine success or failure of the function call.
If a resource wants to access or share information with other resources, it must do so via the specified state type argument. This argument can be modified as the function runs and it will be made available to subsequent resources.
The creation function will be called for EACH deployment operation so if a resource is shared across deployments (such as a VPC), the creation function should be idempotent and look up that existing resource.
func WithDestroy ¶
func WithDestroy(f interface{}) ResourceOption
WithDestroy sets the function to destroy this resource.
Please see the docs for WithCreate since the semantics are very similar.
One important difference for the destruction function is that the state argument will be populated with the value of the state set during WithCreate.
func WithName ¶
func WithName(n string) ResourceOption
WithName sets the resource name. This name is used in output meant to be consumed by a user so it should be descriptive but short, such as "security group" or "app container". It must be unique among resources you create.
func WithPlatform ¶
func WithPlatform(platform string) ResourceOption
WithPlatform specifies the name of the platform this resource is being created on (i.e. kubernetes, docker, etc).
Corresponds to the protobuf DeclaredResource.Platform field
func WithState ¶
func WithState(v interface{}) ResourceOption
WithState specifies the state type for this resource. The state type must either by a proto.Message or implement the ProtoMarshaler interface.
An allocated zero value of this type will be made available during creation. The value given as v is NOT used directly; it is only used to determine the type. Therefore, the value v is ignored and shouldn't be used for initialization.
func WithStatus ¶
func WithStatus(f interface{}) ResourceOption
func WithType ¶
func WithType(t string) ResourceOption
WithType optionally sets the type of the resource according to the platform. E.g. "container", "instance", "autoscaling group", "pod", etc. If not specified, type will default to the resource's name. Multiple resources may share the same type, and generally one resource will have a type that matches the DeclaredResource corresponding to this resource.
type StatusResponse ¶
type StatusResponse struct {
Resources []*pb.StatusReport_Resource
}
StatusResponse is a container type that holds the resources status reports. A resource can have 1 status response containing zero to many individual status reports, depending on the resource. An example would be a K8s deployment resource returning a single status containing a StatusReport_Resource for each pod it currently tracks
Source Files