docker

Documentation

Overview

Package docker implements the Docker Swarm provider (archetype A). It reconciles Service, Network, Volume, Secret and Config objects via the docker CLI, tagging every managed object with io.craneops.spec-hash so drift is detected by label comparison. Immutable resources (Secret, Config) are content-addressed (name-<hash8>).

Index

• func LoadDockerConfig(path string) (map[string]RegistryCred, error)
• func WithAuths(auths map[string]RegistryCred) func(*Provider)
• func WithDecrypter(d Decrypter) func(*Provider)
• func WithIngress(domain, network string) func(*Provider)
• func WithRequireSealed(v bool) func(*Provider)
• func WithSwarmAPI(api SwarmAPI) func(*Provider)
• type ConfigRef
• type ContainerSpec
• type Decrypter
• type EndpointSpec
• type EngineServiceSpec
• type FileRef
• type Healthcheck
• type Mount
• type NetworkAttach
• type Placement
• type PortConfig
• type Provider
  • func New(opts ...func(*Provider)) *Provider
  • func (p *Provider) Apply(ctx context.Context, a provider.Action) (map[string]any, error)
  • func (p *Provider) Delete(ctx context.Context, obj model.Object) (map[string]any, error)
  • func (p *Provider) Kinds() []string
  • func (p *Provider) Name() string
  • func (p *Provider) Observe(ctx context.Context, obj model.Object) (provider.Observed, error)
  • func (p *Provider) Plan(_ context.Context, obj model.Object, obs provider.Observed) ([]provider.Action, error)
  • func (p *Provider) Validate(obj model.Object) error
• type RegistryCred
• type Replicated
• type ResourceSpec
• type Resources
• type RestartPolicy
• type SecretRef
• type ServiceInfo
• type ServiceMode
• type SwarmAPI
• type TaskTemplate

Functions

func LoadDockerConfig

func LoadDockerConfig(path string) (map[string]RegistryCred, error)

LoadDockerConfig parses a docker config.json (the `auths` map) into host -> cred. Both the base64 `auth` form and explicit username/password are supported.

func WithAuths

func WithAuths(auths map[string]RegistryCred) func(*Provider)

WithAuths sets registry credentials (host -> cred) for pulling private images.

func WithDecrypter

func WithDecrypter(d Decrypter) func(*Provider)

WithDecrypter injects the sealer used to unseal secret values.

func WithIngress

func WithIngress(domain, network string) func(*Provider)

WithIngress sets the default ingress domain/network for Service ingress sugar.

func WithRequireSealed

func WithRequireSealed(v bool) func(*Provider)

WithRequireSealed enforces that secret values be sealed.

func WithSwarmAPI

func WithSwarmAPI(api SwarmAPI) func(*Provider)

WithSwarmAPI injects a SwarmAPI (used by tests).

Types

type ConfigRef

type ConfigRef struct {
	ConfigID   string  `json:"ConfigID"`
	ConfigName string  `json:"ConfigName"`
	File       FileRef `json:"File"`
}

type ContainerSpec

type ContainerSpec struct {
	Image       string       `json:"Image"`
	Command     []string     `json:"Command,omitempty"`
	Args        []string     `json:"Args,omitempty"`
	Env         []string     `json:"Env,omitempty"`
	Hosts       []string     `json:"Hosts,omitempty"` // extra /etc/hosts entries, "IP hostname" (Engine API order)
	Mounts      []Mount      `json:"Mounts,omitempty"`
	Secrets     []SecretRef  `json:"Secrets,omitempty"`
	Configs     []ConfigRef  `json:"Configs,omitempty"`
	Healthcheck *Healthcheck `json:"Healthcheck,omitempty"`
}

type Decrypter

type Decrypter interface {
	DecryptArmored(armored string) ([]byte, error)
}

Decrypter unseals armored ciphertext (implemented by *seal.Sealer).

type EndpointSpec

type EndpointSpec struct {
	Ports []PortConfig `json:"Ports,omitempty"`
}

type EngineServiceSpec

type EngineServiceSpec struct {
	Name         string            `json:"Name"`
	Labels       map[string]string `json:"Labels,omitempty"`
	TaskTemplate TaskTemplate      `json:"TaskTemplate"`
	Mode         ServiceMode       `json:"Mode"`
	EndpointSpec *EndpointSpec     `json:"EndpointSpec,omitempty"`
}

EngineServiceSpec mirrors the Docker Engine API ServiceSpec (the fields we support).

type FileRef

type FileRef struct {
	Name string `json:"Name"`
	UID  string `json:"UID"`
	GID  string `json:"GID"`
	Mode uint32 `json:"Mode"`
}

type Healthcheck

type Healthcheck struct {
	Test        []string `json:"Test,omitempty"`
	Interval    int64    `json:"Interval,omitempty"`
	Timeout     int64    `json:"Timeout,omitempty"`
	Retries     int      `json:"Retries,omitempty"`
	StartPeriod int64    `json:"StartPeriod,omitempty"`
}

Healthcheck mirrors the Engine API HealthConfig (durations are nanoseconds).

type Mount

type Mount struct {
	Type     string `json:"Type"` // volume|bind
	Source   string `json:"Source,omitempty"`
	Target   string `json:"Target"`
	ReadOnly bool   `json:"ReadOnly,omitempty"`
}

type NetworkAttach

type NetworkAttach struct {
	Target  string   `json:"Target"`
	Aliases []string `json:"Aliases,omitempty"`
}

type Placement

type Placement struct {
	Constraints []string `json:"Constraints,omitempty"`
}

type PortConfig

type PortConfig struct {
	Protocol      string `json:"Protocol,omitempty"`
	TargetPort    uint32 `json:"TargetPort"`
	PublishedPort uint32 `json:"PublishedPort,omitempty"`
	PublishMode   string `json:"PublishMode,omitempty"` // ingress|host
}

type Provider

type Provider struct {
	Runner         run.Runner
	API            SwarmAPI
	Auths          map[string]RegistryCred // registry host -> creds (for private image pulls)
	IngressDomain  string
	IngressNetwork string
	Decrypter      Decrypter
	RequireSealed  bool // refuse plaintext secret values (server/Git mode)
}

Provider reconciles Docker Swarm resources. Services are managed directly via the Engine API (SwarmAPI); networks/volumes/secrets/configs use the docker CLI (Runner).

func New

func New(opts ...func(*Provider)) *Provider

New creates a Docker provider with sensible defaults.

func (*Provider) Apply

func (p *Provider) Apply(ctx context.Context, a provider.Action) (map[string]any, error)

Apply executes a create/update action.

func (*Provider) Delete

func (p *Provider) Delete(ctx context.Context, obj model.Object) (map[string]any, error)

Delete removes the live resource for an object.

func (*Provider) Kinds

func (p *Provider) Kinds() []string

Kinds returns the kinds this provider serves.

func (*Provider) Name

func (p *Provider) Name() string

Name returns the provider name.

func (*Provider) Observe

func (p *Provider) Observe(ctx context.Context, obj model.Object) (provider.Observed, error)

Observe reads the live spec-hash label for the object.

func (*Provider) Plan

func (p *Provider) Plan(_ context.Context, obj model.Object, obs provider.Observed) ([]provider.Action, error)

Plan compares the desired spec-hash with the observed one.

func (*Provider) Validate

func (p *Provider) Validate(obj model.Object) error

Validate enforces per-kind invariants at load time.

type RegistryCred

type RegistryCred struct {
	Username string
	Password string
}

RegistryCred is a username/password for one registry host.

type Replicated

type Replicated struct {
	Replicas uint64 `json:"Replicas"`
}

type ResourceSpec

type ResourceSpec struct {
	NanoCPUs    int64 `json:"NanoCPUs,omitempty"`
	MemoryBytes int64 `json:"MemoryBytes,omitempty"`
}

type Resources

type Resources struct {
	Limits       *ResourceSpec `json:"Limits,omitempty"`
	Reservations *ResourceSpec `json:"Reservations,omitempty"`
}

type RestartPolicy

type RestartPolicy struct {
	Condition string `json:"Condition,omitempty"`
}

type SecretRef

type SecretRef struct {
	SecretID   string  `json:"SecretID"`
	SecretName string  `json:"SecretName"`
	File       FileRef `json:"File"`
}

type ServiceInfo

type ServiceInfo struct {
	ID        string
	Version   uint64
	SpecHash  string
	SecretIDs []string // live secret IDs referenced by the service
	ConfigIDs []string // live config IDs referenced by the service
}

ServiceInfo is the observed state of a swarm service.

type ServiceMode

type ServiceMode struct {
	Replicated *Replicated `json:"Replicated,omitempty"`
	Global     *struct{}   `json:"Global,omitempty"`
}

type SwarmAPI

type SwarmAPI interface {
	ServiceByName(ctx context.Context, name string) (ServiceInfo, bool, error)
	CreateService(ctx context.Context, spec EngineServiceSpec, registryAuth string) (string, error)
	UpdateService(ctx context.Context, id string, version uint64, spec EngineServiceSpec, registryAuth string) error
	RemoveService(ctx context.Context, id string) error
	ResolveNetwork(ctx context.Context, name string) (string, error)
	// ResolveSecret/ResolveConfig map a base name to the live object's (id, actualName).
	// For crane-managed (content-addressed) objects the actual name is name-<hash>.
	ResolveSecret(ctx context.Context, name string) (id, actualName string, err error)
	ResolveConfig(ctx context.Context, name string) (id, actualName string, err error)
}

SwarmAPI is the subset of the Docker Engine API the Service provider needs. It is interface-bound so the provider's plan/apply logic is testable with a fake.

type TaskTemplate

type TaskTemplate struct {
	ContainerSpec ContainerSpec   `json:"ContainerSpec"`
	Resources     *Resources      `json:"Resources,omitempty"`
	RestartPolicy *RestartPolicy  `json:"RestartPolicy,omitempty"`
	Placement     *Placement      `json:"Placement,omitempty"`
	Networks      []NetworkAttach `json:"Networks,omitempty"`
}