Documentation
¶
Overview ¶
Package runenv manages the Docker env where agent runs execute.
Index ¶
- func FreePort() (uint16, error)
- func PullImage(ctx context.Context, cli *client.Client, imageRef string, ...) error
- type Container
- func (d *Container) CopyFileFromHost(ctx context.Context, content []byte, containerPath string, mode os.FileMode) error
- func (d *Container) CopyFromHost(ctx context.Context, containerID, hostPath, containerDir string) error
- func (d *Container) CreateAgentStartFile(ctx context.Context) error
- func (c *Container) ExecBash(ctx context.Context, script string) (stdout, stderr string, err error)
- func (c *Container) ID() string
- func (c *Container) Stop(ctx context.Context, timeout time.Duration, remove bool) error
- type ContainerBuildStep
- type ContainerBuilder
- type ContainerConfig
- type ContainerEndpoint
- type ContainerPreBuildStep
- func WithEnv(envString string) ContainerPreBuildStep
- func WithExposeContainerPort(containerPort int) ContainerPreBuildStep
- func WithExposePort(port network.Port) ContainerPreBuildStep
- func WithHostBind(from string, to string) ContainerPreBuildStep
- func WithHostMounts(cfg *agentconfig.DockerConfig) ContainerPreBuildStep
- func WithImage(imgName string) ContainerPreBuildStep
- func WithLabel(label, value string) ContainerPreBuildStep
- type DockerClient
- func (d *DockerClient) AbyssContainers(ctx context.Context) ([]container.Summary, error)
- func (d *DockerClient) Close() error
- func (d *DockerClient) GetContainer(containerID string) *Container
- func (d *DockerClient) StartContainer(ctx context.Context, config *container.Config, ...) (*Container, ContainerEndpoint, error)
- type ErrInvalidContainerMetadata
- type LabelMetadata
- type ParallelStep
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FreePort ¶
FreePort finds a random, unused TCP port on the host by asking the OS to bind to port 0 and reading back the assigned port. The listener is closed before returning, so the port is free for the caller to use.
func PullImage ¶ added in v0.0.2
func PullImage(ctx context.Context, cli *client.Client, imageRef string, policy agentconfig.ImagePullPolicy) error
PullImage pulls imageRef according to policy using the Docker API client. An empty policy is treated as ImagePullPolicyIfNotPresent.
Types ¶
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
Container is an abstraction around Docker's container objects. It primarily adds logging and utility functions specific to abyss.
func NewContainer ¶
func NewContainer(docker *DockerClient, containerID string) *Container
NewContainer initializes a new container.
func (*Container) CopyFileFromHost ¶
func (d *Container) CopyFileFromHost( ctx context.Context, content []byte, containerPath string, mode os.FileMode, ) error
CopyFileFromHost copies a single file's content into the container identified by containerID. Parent directories of containerPath are created as needed.
func (*Container) CopyFromHost ¶
func (d *Container) CopyFromHost(ctx context.Context, containerID, hostPath, containerDir string) error
CopyFromHost copies the file or directory at hostPath into the container identified by containerID, placing it under containerDir. Parent directories of containerDir that do not already exist inside the container are created. The basename of hostPath is preserved, so a host path of "/tmp/foo.txt" copied into "/opt/app" lands at "/opt/app/foo.txt".
func (*Container) CreateAgentStartFile ¶ added in v0.0.2
CreateAgentStartFile creates an empty start file inside the container at the default start file path, signaling that the agent should begin its work.
func (*Container) ExecBash ¶
ExecBash runs script inside the container identified by containerID using "bash -c". It returns the script's stdout and stderr. If the script exits with a non-zero status, the returned error reports the exit code and the output is still returned so callers can inspect it.
type ContainerBuildStep ¶ added in v0.0.2
ContainerBuildStep runs after the Docker container has been started. They have access to the container's filesystem, shell, etc, but can't change the container's configuration like networking.
func NewParallelStep ¶ added in v0.0.3
func NewParallelStep(inner ...ContainerBuildStep) ContainerBuildStep
NewParallelStep returns a new ParallelStep with the given inner steps.
func WithCopyFiles ¶ added in v0.0.2
func WithCopyFiles(files []agentconfig.FileCopyConfig) ContainerBuildStep
WithCopyFiles returns a build step that copies each file declared in the agent config into the container. Files with Type "inline" use Source as the file contents; files with Type "path" read the contents from the host path in Source. Each file is written to its Target path inside the container, creating parent directories as needed. When a "path" entry points to a directory, the directory is copied recursively into the container at Target.
func WithSetupScripts ¶ added in v0.0.2
func WithSetupScripts(scripts []agentconfig.SetupScriptsConfig) ContainerBuildStep
WithSetupScripts returns a build step that copies each setup script into the container and executes it with bash. Scripts with Type "inline" use Source as the script contents; scripts with Type "file" read the contents from the host path in Source. Each script is written to a temporary path inside the container, made executable, and run before the agent starts.
type ContainerBuilder ¶ added in v0.0.2
type ContainerBuilder struct {
ConfigPath string
// contains filtered or unexported fields
}
ContainerBuilder accumulates build steps and starts a container. TODO this should be two separate "config-builder" and "container-builder" parts.
func NewContainerBuilder ¶ added in v0.0.2
func NewContainerBuilder( configPath string, config *ContainerConfig, steps ...ContainerPreBuildStep, ) (*ContainerBuilder, error)
NewContainerBuilder creates a builder, applying any pre-build steps to the config.
func (*ContainerBuilder) AddStep ¶ added in v0.0.2
func (b *ContainerBuilder) AddStep(step ContainerBuildStep)
AddStep appends a single build step to the builder.
func (*ContainerBuilder) AddSteps ¶ added in v0.0.2
func (b *ContainerBuilder) AddSteps(newSteps ...ContainerBuildStep)
AddSteps appends multiple build steps to the builder.
func (*ContainerBuilder) Build ¶ added in v0.0.2
func (b *ContainerBuilder) Build(ctx context.Context, cli *DockerClient) (*Container, ContainerEndpoint, error)
Build starts the container and runs each build step against it.
type ContainerConfig ¶ added in v0.0.2
type ContainerConfig struct {
Host *container.HostConfig
Config *container.Config
Endpoint *ContainerEndpoint
// Name is the name to assign to the container. An empty name lets Docker
// generate one.
Name string
// ContainerPort is the port the container exposes to the host.
ContainerPort uint16
// HostPort is the host port bound to ContainerPort. 0 lets Docker assign a
// free port.
HostPort uint16
}
ContainerConfig holds the Docker host and container configuration used to build a container.
func (*ContainerConfig) Validate ¶ added in v0.0.2
func (c *ContainerConfig) Validate() *types.ValidationError
Validate ensures the required host and container configs are present.
type ContainerEndpoint ¶
type ContainerEndpoint struct {
// ContainerID is the ID of the started container.
ContainerID string
// IP is the address the host should connect to.
IP string
// Port is the host port bound to the container's exposed port.
Port uint16
}
ContainerEndpoint describes how the host can reach a started container.
func (ContainerEndpoint) String ¶
func (e ContainerEndpoint) String() string
String returns the endpoint as an "ip:port" address.
type ContainerPreBuildStep ¶ added in v0.0.2
type ContainerPreBuildStep func(*ContainerConfig) error
ContainerPreBuildStep is a step that runs before the container is started. They can modify the Docker configuration, but can't run bash scripts in the container or things like that.
func WithEnv ¶ added in v0.0.2
func WithEnv(envString string) ContainerPreBuildStep
WithEnv returns a pre-build step that appends an environment variable.
func WithExposeContainerPort ¶ added in v0.0.2
func WithExposeContainerPort(containerPort int) ContainerPreBuildStep
WithExposeContainerPort exposes the given port on the built container.
func WithExposePort ¶ added in v0.0.2
func WithExposePort(port network.Port) ContainerPreBuildStep
WithExposePort returns a pre-build step that marks a port as exposed.
func WithHostBind ¶ added in v0.0.2
func WithHostBind(from string, to string) ContainerPreBuildStep
WithHostBind returns a pre-build step that binds a host path into the container. Returns errors when it is unable to get a clean, absolute path to either of the provided paths.
func WithHostMounts ¶ added in v0.0.2
func WithHostMounts(cfg *agentconfig.DockerConfig) ContainerPreBuildStep
WithHostMounts creates a ContainerPreBuildStep that configures the container to mount any host mounts in the config.
Paths are normalized as part of this step, so relative paths are fine and will be resolved to absolute paths.
func WithImage ¶ added in v0.0.2
func WithImage(imgName string) ContainerPreBuildStep
WithImage returns a pre-build step that sets the container image.
func WithLabel ¶ added in v0.0.2
func WithLabel(label, value string) ContainerPreBuildStep
WithLabel returns a pre-build step that sets a container label.
type DockerClient ¶
DockerClient wraps the Docker SDK client and provides helpers for managing containers in a run environment.
func NewDockerClient ¶
func NewDockerClient() (*DockerClient, error)
NewDockerClient creates a DockerClient configured from the environment (DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY).
func (*DockerClient) AbyssContainers ¶
AbyssContainers lists containers that have the `abyss` label set.
func (*DockerClient) Close ¶
func (d *DockerClient) Close() error
Close releases resources held by the underlying Docker client.
func (*DockerClient) GetContainer ¶ added in v0.0.2
func (d *DockerClient) GetContainer(containerID string) *Container
GetContainer returns a *Container. It does not validate that the provided containerID actually exists.
func (*DockerClient) StartContainer ¶
func (d *DockerClient) StartContainer( ctx context.Context, config *container.Config, hostConfig *container.HostConfig, labels map[string]string, name string, containerPort uint16, hostPort uint16, ) (*Container, ContainerEndpoint, error)
StartContainer creates and starts a Docker container with the provided configuration, labels, name, and port mappings.
type ErrInvalidContainerMetadata ¶ added in v0.0.3
type ErrInvalidContainerMetadata struct {
// contains filtered or unexported fields
}
ErrInvalidContainerMetadata is returned when a container's abyss labels are malformed or absent.
func NewErrInvalidContainerMetadata ¶ added in v0.0.3
func NewErrInvalidContainerMetadata(msg string) *ErrInvalidContainerMetadata
NewErrInvalidContainerMetadata builds an error for invalid or missing container labels.
func (*ErrInvalidContainerMetadata) Error ¶ added in v0.0.3
func (e *ErrInvalidContainerMetadata) Error() string
Error formats the invalid metadata error.
type LabelMetadata ¶ added in v0.0.3
LabelMetadata holds the abyss metadata stored in container labels.
func GetLabelMetadata ¶ added in v0.0.3
func GetLabelMetadata(summary *container.Summary) (*LabelMetadata, error)
GetLabelMetadata extracts abyss metadata from a container's labels. Returns an error for missing labels
func (*LabelMetadata) AddToMap ¶ added in v0.0.3
func (l *LabelMetadata) AddToMap(underlying map[string]string)
AddToMap writes the metadata labels into the given map.
func (*LabelMetadata) ToMap ¶ added in v0.0.3
func (l *LabelMetadata) ToMap() map[string]string
ToMap returns the metadata as a map of container labels.
type ParallelStep ¶ added in v0.0.3
type ParallelStep struct {
// contains filtered or unexported fields
}
ParallelStep runs multiple ContainerBuildSteps in parallel to improve startup performance.