Documentation

Overview

    Package component has the interfaces for all the components that can be implemented. A component is the broad term used to describe all builders, platforms, registries, etc.

    Many component interfaces have functions named `XFunc` where "X" is some operation and the return value is "interface{}". These functions should return a method handle to the function implementing that operation. This pattern is done so that we can support custom typed operations that take and return full rich types for an operation. We use a minimal dependency-injection framework (see internal/mapper) to call these functions.

    Package component exposes the component types supported and helpers around those types.

    Index

    Constants

    This section is empty.

    Variables

      TypeMap is a mapping of Type to the nil pointer to the interface of that type. This can be used with libraries such as mapper.

      Functions

      func Configure

      func Configure(c interface{}, body hcl.Body, ctx *hcl.EvalContext) hcl.Diagnostics

        Configure configures c with the provided configuration.

        If c does not implement Configurable AND body is non-empty, then it is an error. If body is empty in that case, it is not an error.

        func Documentation

        func Documentation(c interface{}) (*docs.Documentation, error)

          Documentation returns the documentation for the given component.

          If c does not implement Documented, nil is returned.

          func Id

          func Id() (string, error)

            Id returns a unique Id that can be used for new values. This generates a ulid value but the ID itself should be an internal detail. An error will be returned if the ID could be generated.

            func ProtoAny

            func ProtoAny(m interface{}) (*any.Any, error)

              ProtoAny returns an *any.Any for the given ProtoMarshaler object.

              func ProtoAnySlice

              func ProtoAnySlice(m interface{}) ([]*any.Any, error)

                ProtoAny returns []*any.Any for the given input slice by encoding each result into a proto value.

                func ProtoAnyUnmarshal

                func ProtoAnyUnmarshal(m interface{}, out proto.Message) error

                  ProtoAnyUnmarshal attempts to unmarshal a ProtoMarshler implementation to another type. This can be used to get more concrete data out of a generic component.

                  Types

                  type Artifact

                  type Artifact interface {
                  	// Labels are the labels to set. These will overwrite any conflicting
                  	// labels on the value. Please namespace the labels you set. The recommended
                  	// namespacing is using a URL structure, followed by a slash, and a key.
                  	// For example: "plugin.example.com/key" as the key. The value can be
                  	// any string.
                  	Labels() map[string]string
                  }

                  type AuthResult

                  type AuthResult struct {
                  	// Authenticated when true means that the plugin should now be authenticated
                  	// (given the other fields in this struct). If ValidateAuth is called,
                  	// it should succeed. If this is false, the auth method may have printed
                  	// help text or some other information, but it didn't authenticate. However,
                  	// this is not an error.
                  	Authenticated bool
                  }

                    AuthResult is the return value expected from Authenticator.AuthFunc.

                    type Authenticator

                    type Authenticator interface {
                    	// AuthFunc should return the method for getting credentials for a
                    	// plugin. This should return AuthResult.
                    	AuthFunc() interface{}
                    
                    	// ValidateAuthFunc should return the method for validating authentication
                    	// credentials for the plugin
                    	ValidateAuthFunc() interface{}
                    }

                      Authenticator is responsible for authenticating different types of plugins.

                      type Builder

                      type Builder interface {
                      	// BuildFunc should return the method handle for the "build" operation.
                      	// The build function has access to a *Source and should return an Artifact.
                      	BuildFunc() interface{}
                      }

                        Builder is responsible for building an artifact from source.

                        type ConfigRequest

                        type ConfigRequest struct {
                        	Name   string
                        	Config map[string]string
                        }

                          ConfigRequest is sent to ReadFunc for ConfigSourcer to represent a single configuration variable that was requested. The ReadFunc parameters should have a `[]*ConfigRequest` parameter for these.

                          type ConfigSourcer

                          type ConfigSourcer interface {
                          	// ReadFunc returns the function for reading configuration.
                          	//
                          	// The returned function can start a background goroutine to more efficiently
                          	// watch for changes. The entrypoint will periodically call Read to check for
                          	// updates.
                          	//
                          	// If the configuration changes for any dynamic configuration variable,
                          	// the entrypoint will call Stop followed by Read, so plugins DO NOT need
                          	// to implement config diffing. Plugins may safely assume if Read is called
                          	// after a Stop that the config is new, and that subsequent calls have the
                          	// same config.
                          	//
                          	// Read is called for ALL defined configuration variables for this source.
                          	// If ANY change, Stop is called followed by Read again. Only one sourcer
                          	// is active for a set of configs.
                          	ReadFunc() interface{}
                          
                          	// StopFunc returns a function for stopping configuration sourcing.
                          	// You can return nil if stopping is not necessary or supported for
                          	// this sourcer.
                          	//
                          	// The stop function should stop any background processes started with Read.
                          	StopFunc() interface{}
                          }

                            ConfigSourcer can be implemented by plugins that support sourcing dynamic configuration for running applications.

                            This plugin type runs alongside the application. The initial config loading will block the application start so authors should attempt to source configuration as quickly as possible.

                            type Configurable

                            type Configurable interface {
                            	// Config should return a pointer to an allocated configuration
                            	// structure. This structure will be written to directly with the
                            	// decoded configuration. If this returns nil, then it is as if
                            	// Configurable was not implemented.
                            	Config() (interface{}, error)
                            }

                              Configurable can be optionally implemented by any compontent to accept user configuration.

                              type ConfigurableNotify

                              type ConfigurableNotify interface {
                              	Configurable
                              
                              	// ConfigSet is called with the value of the configuration after
                              	// decoding is complete successfully.
                              	ConfigSet(interface{}) error
                              }

                                ConfigurableNotify is an optional interface that can be implemented by any component to receive a notification that the configuration was decoded.

                                type Deployment

                                type Deployment interface{}

                                type DeploymentConfig

                                type DeploymentConfig struct {
                                	Id                    string
                                	ServerAddr            string
                                	ServerTls             bool
                                	ServerTlsSkipVerify   bool
                                	EntrypointInviteToken string
                                }

                                  DeploymentConfig is the configuration for the behavior of a deployment. Platforms should take this argument and use the value to set the appropriate settings for the deployment

                                  func (*DeploymentConfig) Env

                                  func (c *DeploymentConfig) Env() map[string]string

                                    Env returns the environment variables that should be set for the entrypoint binary to have the proper configuration.

                                    type DeploymentInfo

                                    type DeploymentInfo struct {
                                    	// ComponentName is the name of the plugin that launched this deployment.
                                    	ComponentName string
                                    
                                    	// Labels of the deployment
                                    	Labels map[string]string
                                    }

                                      DeploymentInfo is available to some plugins to get information about the deployment.

                                      This is currently only available to ConfigSourcer and provides information about the running deployment.

                                      type Destroyer

                                      type Destroyer interface {
                                      	// DestroyFunc should return the method handle for the destroy operation.
                                      	DestroyFunc() interface{}
                                      }

                                        Destroyer is responsible for destroying resources associated with this implementation. This can be implemented by all of the component types and will be called to perform cleanup on any created resources.

                                        type Documented

                                        type Documented interface {
                                        	// Documentation() returns a completed docs.Documentation struct
                                        	// describing the components configuration.
                                        	Documentation() (*docs.Documentation, error)
                                        }

                                          Documented can be optionally implemented by any component to return documentation about the component.

                                          type ExecResult

                                          type ExecResult struct {
                                          	// ExitCode is the exit code for the process that was run.
                                          	ExitCode int
                                          }

                                            ExecResult is returned by an Exec function to indicate the status of the run command.

                                            type ExecSessionInfo

                                            type ExecSessionInfo struct {
                                            	Input  io.Reader // effectively the stdin from the user (stdin)
                                            	Output io.Writer // the output from the session (stdout)
                                            	Error  io.Writer // an error output from the session (stderr)
                                            
                                            	IsTTY bool // indicates if the input/output is a terminal
                                            
                                            	// If this is a TTY, this is the terminal type (ie, the value of the TERM
                                            	// environment variable)
                                            	Term string
                                            
                                            	// If this is a TTY, this is the initial window size.
                                            	InitialWindowSize WindowSize
                                            
                                            	// a channel that is sent the size of the users window. A new value
                                            	// is sent on start and on each detection of window change.
                                            	WindowSizeUpdates <-chan WindowSize
                                            
                                            	// arguments to pass to the session. Normally interpreted as the first value
                                            	// being the command to run and the rest arguments to that command.
                                            	Arguments []string
                                            
                                            	// environment variables to set within the context of the session.
                                            	// This will contain configuration variables from the server
                                            	// as well as any variable derived from external systems like vault
                                            	// or kubernetes.
                                            	Environment []string
                                            }

                                              ExecSessionInfo contains the information required by the exec plugin to setup a new exec and send the data back to a client. A ExecSessionInfo value is passed to a plugins ExecFunc() to allow the function to properly create the exec session.

                                              type Execer

                                              type Execer interface {
                                              	// ExecFunc should return the method handle for a exec session operation.
                                              	// This function has the following types available:
                                              	//  - hclog.Logger
                                              	//  - context.Context
                                              	//  - The Deployment type implemented by the plugin
                                              	//  - *component.ExecSessionInfo
                                              	//  - UI
                                              	//
                                              	// The ExecSessionInfo value contains all the things required launch the
                                              	// exec session.
                                              	ExecFunc() interface{}
                                              }

                                                Exec is responsible for starting the exec plugin to allow a deployment plugin to provide it's own exec functionality. By default, the waypoint exec functionality is achieved by creating a session on a long running instance of a deployment. But if a platform plugin type does not creat any long running instances, they can implement this interface and provide the exec functionality in their own bespoke way.

                                                type JobInfo

                                                type JobInfo struct {
                                                	// Id is the ID of the job that is executing this plugin operation.
                                                	// If this is empty then it means that the execution is happening
                                                	// outside of a job.
                                                	Id string
                                                
                                                	// Local is true if the operation is running locally on a machine
                                                	// alongside the invocation. This can be used to determine if you can
                                                	// do things such as open browser windows, read user files, etc.
                                                	Local bool
                                                
                                                	// Workspace is the workspace that this job is executing in. This should
                                                	// be used by plugins to properly isolate resources from each other.
                                                	Workspace string
                                                }

                                                  JobInfo is available to plugins to get information about the context in which a job is executing.

                                                  type LabelSet

                                                  type LabelSet struct {
                                                  	Labels map[string]string
                                                  }

                                                  type LinesChunkWriter

                                                  type LinesChunkWriter interface {
                                                  	OutputLines([]string) error
                                                  }

                                                    LinesChunkWriter is used by a logs plugin to output a chunk of lines. A concrete implementation is provided to the plugin inside the LogsSessionInfo value.

                                                    type LogEvent

                                                    type LogEvent struct {
                                                    	Partition string
                                                    	Timestamp time.Time
                                                    	Message   string
                                                    }

                                                      LogEvent represents a single log entry.

                                                      type LogPlatform

                                                      type LogPlatform interface {
                                                      	// LogsFunc should return the method handle for a logs operation.
                                                      	// This function has the following types available:
                                                      	//  - hclog.Logger
                                                      	//  - context.Context
                                                      	//  - The Deployment type implemented by the plugin
                                                      	//  - *component.LogViewer
                                                      	//  - UI
                                                      	LogsFunc() interface{}
                                                      }

                                                        LogPlatform is responsible for starting the logs plugin that allows a plugin to read logs for a deployment in its own way. This function has the following types available:

                                                        type LogViewer

                                                        type LogViewer struct {
                                                        	// This is the time horizon log entries must be beyond to be emitted.
                                                        	StartingAt time.Time
                                                        
                                                        	// The maximum number of log entries to emit.
                                                        	Limit int
                                                        
                                                        	// New LogEvents should be sent to this channel.
                                                        	Output chan LogEvent
                                                        }

                                                          LogViewer returns batches of log lines. This is expected to be returned by a LogPlatform implementation.

                                                          type LogsSessionInfo

                                                          type LogsSessionInfo struct {
                                                          	Output LinesChunkWriter
                                                          
                                                          	// The time horizon to begin showing logs from. Only show logs newer
                                                          	// than this time stamp.
                                                          	StartingFrom time.Time
                                                          
                                                          	// The maximum number of lines to output.
                                                          	Limit int
                                                          }

                                                            ExecSessionInfo contains the information required by the exec plugin to setup a new exec and send the data back to a client. A ExecSessionInfo value is passed to a plugins ExecFunc() to allow the function to properly create the exec session.

                                                            type Platform

                                                            type Platform interface {
                                                            	// DeployFunc should return the method handle for the "deploy" operation.
                                                            	// The deploy function has access to the following and should use this
                                                            	// as necessary to perform a deploy.
                                                            	//
                                                            	//   artifact, artifact registry
                                                            	//
                                                            	DeployFunc() interface{}
                                                            }

                                                              Platform is responsible for deploying artifacts.

                                                              type PlatformReleaser

                                                              type PlatformReleaser interface {
                                                              	// DefaultReleaserFunc() should return a function that returns
                                                              	// a ReleaseManger implementation. This ReleaseManager will NOT have
                                                              	// any config so it must work by default.
                                                              	DefaultReleaserFunc() interface{}
                                                              }

                                                                PlatformReleaser is an optional interface that a Platform can implement to provide default Release functionality. This only takes effect if no release is configured.

                                                                type ProtoMarshaler

                                                                type ProtoMarshaler interface {
                                                                	// Proto returns a proto.Message of this structure. This may also return
                                                                	// a proto Any value and it will not be re-wrapped with Any.
                                                                	Proto() proto.Message
                                                                }

                                                                  ProtoMarshaler is the interface required by objects that must support protobuf marshaling. This expects the object to go to a proto.Message which is converted to a proto Any value[1]. The plugin is expected to register a proto type that can decode this Any value.

                                                                  This enables the project to encode intermediate objects (such as artifacts) and store them in a database.

                                                                  [1]: https://developers.google.com/protocol-buffers/docs/proto3#any

                                                                  type Registry

                                                                  type Registry interface {
                                                                  	// PushFunc should return the method handle to the function for the "push"
                                                                  	// operation. The push function should take an artifact type and push it
                                                                  	// to the registry.
                                                                  	PushFunc() interface{}
                                                                  }

                                                                    Registry is responsible for managing artifacts.

                                                                    type Release

                                                                    type Release interface {
                                                                    	// URL is the URL to access this release.
                                                                    	URL() string
                                                                    }

                                                                    type ReleaseManager

                                                                    type ReleaseManager interface {
                                                                    	// ReleaseFunc should return the method handle for the "release" operation.
                                                                    	ReleaseFunc() interface{}
                                                                    }

                                                                      ReleaseManager is responsible for taking a deployment and making it "released" which means that traffic can now route to it.

                                                                      type Source

                                                                      type Source struct {
                                                                      	App  string
                                                                      	Path string
                                                                      }

                                                                        See Args.Source in the protobuf protocol.

                                                                        type Template

                                                                        type Template interface {
                                                                        	// TemplateData returns the template information to make available.
                                                                        	//
                                                                        	// This should return empty values for available keys even if the
                                                                        	// struct it is attached to is nil. This enables the automated documentation
                                                                        	// generator to work properly. Do not return "nil" when there is no data!
                                                                        	// And expect that this will be called on nil or empty values.
                                                                        	TemplateData() map[string]interface{}
                                                                        }

                                                                          Template can be implemented by Artifact, Deployment, and Release. This will expose this information as available variables in the HCL configuration as well as functions in the `template`-prefixed family, such as `templatefile`.

                                                                          If Template is NOT implemented, we will automatically infer template data based on exported variables of the result value. This may not be desirable in which case you should implement Template and return nil.

                                                                          type Type

                                                                          type Type uint

                                                                            Type is an enum of all the types of components supported. This isn't used directly in this package but is used by other packages to reference the component types.

                                                                            const (
                                                                            	InvalidType        Type = iota // Invalid
                                                                            	BuilderType                    // Builder
                                                                            	RegistryType                   // Registry
                                                                            	PlatformType                   // Platform
                                                                            	ReleaseManagerType             // ReleaseManager
                                                                            	LogPlatformType                // LogPlatform
                                                                            	AuthenticatorType              // Authenticator
                                                                            	MapperType                     // Mapper
                                                                            	ConfigSourcerType              // ConfigSourcer
                                                                            
                                                                            )

                                                                            func (Type) String

                                                                            func (i Type) String() string

                                                                            type WindowSize

                                                                            type WindowSize struct {
                                                                            	Height int // the height (in lines) of the terminal
                                                                            	Width  int // the width (in lines) of the terminal
                                                                            }

                                                                              WindowSize provides information about the size of the terminal window.

                                                                              type WorkspaceDestroyer

                                                                              type WorkspaceDestroyer interface {
                                                                              	// DestroyWorkspaceFunc is called when a workspace destroy operation is performed.
                                                                              	//
                                                                              	// This will only be called if that plugin had performed some operation
                                                                              	// previously on the workspace. This may be called multiple times so it should
                                                                              	// be idempotent. This will be called after all individual DestroyFuncs are
                                                                              	// complete.
                                                                              	DestroyWorkspaceFunc() interface{}
                                                                              }

                                                                                WorkspaceDestroyer is called when a workspace destroy operation is performed (typically via the "waypoint destroy" CLI). This can be implemented by any plugin.

                                                                                Directories

                                                                                Path Synopsis