Documentation
¶
Overview ¶
Package dockerlib is the activity-and-resource library over docker on a machine: install the engine, run containers. All bodies execute inside the per-(agent × run) container on the machine — with the machine's docker socket under their feet; the run workflow only orchestrates.
The durable half of dockerlib: containers, volumes, and networks are ENTITY RECORDS — owned in the tree, cascaded, transferable to a stand — whose lifecycle activities run on the machine's own (agent × run) executor. The executor lives while these records do.
Index ¶
- Constants
- func Build(spec BuildSpec) activity.Call[BuildReport]
- func Container(ctx pipeline.Context, agent pipeline.Agent, spec Spec, ...) pipeline.Resource[Info]
- func Install() activity.Call[InstallReport]
- func Job(spec JobSpec) activity.Call[JobReport]
- func Network(ctx pipeline.Context, agent pipeline.Agent, spec NetworkSpec, ...) pipeline.Resource[NetworkInfo]
- func Volume(ctx pipeline.Context, agent pipeline.Agent, spec volume.CreateOptions, ...) pipeline.Resource[VolumeInfo]
- type BuildReport
- type BuildSpec
- type Info
- type InstallReport
- type JobReport
- type JobSpec
- type NetworkInfo
- type NetworkSpec
- type Spec
- type VolumeInfo
Constants ¶
const ( ContainerKind entity.KindName = "docker" VolumeKind entity.KindName = "docker-volume" NetworkKind entity.KindName = "docker-network" )
Entity kinds.
Variables ¶
This section is empty.
Functions ¶
func Build ¶
func Build(spec BuildSpec) activity.Call[BuildReport]
Build assembles an image with the machine's own buildx — full BuildKit (cache export, multi-stage, secrets) with nothing wrapped: the CLI the machine already has (Install brings it) does the work, the digest comes back through --metadata-file, never log parsing.
func Container ¶
func Container(ctx pipeline.Context, agent pipeline.Agent, spec Spec, opts ...pipeline.ResourceOption) pipeline.Resource[Info]
Container declares a container on the agent's machine as an ORDINARY resource: an entity record in the tree — owned, cascaded, transferable to a stand. Its lifecycle runs on this agent's own executor, which lives while the record does.
func Install ¶
func Install() activity.Call[InstallReport]
Install brings the docker engine onto the machine — converging: an engine that is already there is reported, not reinstalled. A library verb is a Call: run it with pipelineactivity.Activity on one agent or pipelineactivity.ActivityAll on a selection.
func Job ¶ added in v0.3.0
Job runs a container to completion on the machine: pull, create, start, stream its output to the run's logs line by line, wait, remove. It is the one-shot counterpart of Container — a verb, not a resource: nothing is owned, nothing stays behind but the log file.
Whether a second execution is acceptable is the CALLER'S knowledge: a job that loads data or sends a message wants activity.WithGuarantee(activity.AtMostOnce).
func Network ¶
func Network(ctx pipeline.Context, agent pipeline.Agent, spec NetworkSpec, opts ...pipeline.ResourceOption) pipeline.Resource[NetworkInfo]
Network declares a docker network on the agent's machine as an ordinary resource — an owned entity record; it dies with its owner.
func Volume ¶
func Volume(ctx pipeline.Context, agent pipeline.Agent, spec volume.CreateOptions, opts ...pipeline.ResourceOption) pipeline.Resource[VolumeInfo]
Volume declares a docker volume on the agent's machine as an ordinary resource — an owned entity record; the data dies with its owner. The spec is docker's OWN type.
Types ¶
type BuildReport ¶
type BuildReport struct {
Digest string `json:"digest,omitempty"`
Tags []string `json:"tags,omitempty"`
}
BuildReport is the build's outcome: the immutable identity of what was built. The local image stays on the machine as cache — it is not a resource and owns nothing.
type BuildSpec ¶
type BuildSpec struct {
// Context is the build context directory.
Context string `json:"context"`
// File is the Dockerfile path; empty means <Context>/Dockerfile.
File string `json:"file,omitempty"`
// Tags to apply ("registry/name:tag").
Tags []string `json:"tags,omitempty"`
// Push pushes the tags after a successful build.
Push bool `json:"push,omitempty"`
// Target builds a specific stage.
Target string `json:"target,omitempty"`
// BuildArgs are --build-arg pairs.
BuildArgs map[string]string `json:"buildArgs,omitempty"`
// CacheFrom / CacheTo are buildx cache specs
// ("type=registry,ref=...").
CacheFrom []string `json:"cacheFrom,omitempty"`
CacheTo []string `json:"cacheTo,omitempty"`
}
BuildSpec describes one image build. Paths (Context, File) must be machine-valid — put the context under machine.Workspace() and this holds by construction (same absolute path in the container, on the machine, and for the daemon).
type Info ¶
type Info struct {
Id string `json:"id"`
}
Info is the output of a running container resource.
type InstallReport ¶
type InstallReport struct {
Version string `json:"version"`
// Installed is false when the engine was already there.
Installed bool `json:"installed"`
}
InstallReport is what Install returns.
type JobReport ¶ added in v0.3.0
type JobReport struct {
ExitCode int `json:"exitCode"`
// Stdout is the container's stdout, bounded to the first 256 KiB —
// enough for a machine-readable answer (a JSON line, a version).
Stdout string `json:"stdout,omitempty"`
// Tail is the end of the merged stdout+stderr, last 16 KiB: where a
// tool prints its summary or its error.
Tail string `json:"tail,omitempty"`
// LogPath is the full merged output on the machine — hand it to
// artifact.FromAgentFile to keep it.
LogPath string `json:"logPath,omitempty"`
}
JobReport is what came back from the container. A non-zero ExitCode is an OUTCOME, not an activity failure: the job ran, the caller decides what its exit status means. The activity fails only when the container could not be run at all.
type JobSpec ¶ added in v0.3.0
type JobSpec struct {
// Name is the container's name on the machine. A leftover container
// of the same name is replaced — the name is the job's identity.
Name string `json:"name"`
Config *container.Config `json:"config"`
Host *container.HostConfig `json:"host,omitempty"`
}
JobSpec describes one THROWAWAY container with docker's OWN types — the same pair Container takes. Everything docker already has a word for stays in that word: the command is Config.Cmd, the environment is Config.Env, files reach the container through Host.Mounts (bind the directory a file resource wrote to), the network is Host.NetworkMode.
type NetworkInfo ¶
NetworkInfo is the output of a network resource.
type NetworkSpec ¶
type NetworkSpec struct {
Name string `json:"name"`
Options network.CreateOptions `json:"options"`
}
NetworkSpec names a network with docker's own creation options.
type Spec ¶
type Spec struct {
Name string `json:"name"`
Config *container.Config `json:"config"`
Host *container.HostConfig `json:"host,omitempty"`
// Scrape is a prometheus metrics endpoint the container exposes
// (e.g. "http://localhost:9187/metrics"); the executor pulls it and
// ships the samples — histograms and summaries included — as this
// container's own metrics (Р-Н27).
Scrape string `json:"scrape,omitempty"`
// ScrapeEvery is the scrape step: 15s when zero, never under 1s. It
// is the scrape's own and does not move the stats beat.
ScrapeEvery time.Duration `json:"scrapeEvery,omitempty"`
}
Spec describes one container with docker's OWN types — structures their authors made, not ours.
type VolumeInfo ¶
type VolumeInfo struct {
Name string `json:"name"`
Mountpoint string `json:"mountpoint,omitempty"`
}
VolumeInfo is the output of a volume resource.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package dockertest models Docker resource declarations and capability publication for pipeline tests.
|
Package dockertest models Docker resource declarations and capability publication for pipeline tests. |
|
internal
|
|
|
contract
Package contract shares Docker resource wire types with adapters.
|
Package contract shares Docker resource wire types with adapters. |