imageexec

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 28, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package imageexec admits immutable container images and binds their use to typed Docker and Compose execution sinks. Admission resolves a runnable leaf, validates its metadata, and verifies its independent local image-store record before returning an Image. Images and prepared projects cannot be reconstructed from IDs or labels. Their zero values are inert. Runtime construction probes and negotiates the descriptor-capable Docker API before exposing admission or execution capabilities.

Admission is read-only. A missing selected leaf returns MaterializationRequired; callers must perform bounded image ingestion before retrying its immutable ID. Execution stays inside the caller's existing storage mutation capabilities; an Image proves what content was admitted, not permission to mutate tenant substrate.

Index

Constants

View Source 
const (
	LabelImageReference = "fred.image_reference"
	LabelImageID        = "fred.image_id"
)
View Source 
const (
	MaxImageVolumes         = 16
	MaxImageVolumePathBytes = 4096
	MaxImageVolumeBytes     = 16 << 10
	MaxImageLabels          = 128
	MaxImageLabelBytes      = 64 << 10
	MaxInspectResponseBytes = 2 << 20
)

Image metadata is outside the tenant manifest's HTTP body budget. These limits apply before an Image can authorize helpers or workload creation.

Variables

View Source 
var (
	ErrUnavailable    = errors.New("image execution capability is unavailable")
	ErrInvalidImage   = errors.New("image was not admitted")
	ErrForeignImage   = errors.New("image belongs to another admitter")
	ErrInvalidProject = errors.New("compose project was not prepared")
	ErrForeignProject = errors.New("compose project belongs to another admitter")
)

Functions

func DirectCreationLabels 

func DirectCreationLabels() map[string]string

DirectCreationLabels returns the detached neutral projection installed by DockerCreator. Helper receipt construction and recovery use this same policy. Empty values must be written explicitly: omission would inherit image labels.

func NewDockerRuntime 

func NewDockerRuntime(ctx context.Context, source DockerSource, profiles TenantSeccompSource) (*Admitter, *DockerCreator, error)

NewDockerRuntime binds admission and direct creation to the same SDK client and to the tenant seccomp profile every creation must carry. There is no way to build a creator without a profile source. An unusable profile does not fail construction: each creation asks the source again and refuses while it stays unusable. NewDockerRuntime probes the daemon and requires descriptor-capable API negotiation before minting either capability. The context is used only during construction; ownership of the supplied client remains with the caller, including on error. Callers retain the typed capabilities instead of the raw creation operation.

Types

type Admitter 

type Admitter struct {
	// contains filtered or unexported fields
}

Admitter owns the source from which images are admitted. Creators bound to this admitter accept only the images and projects it minted.

func (*Admitter) Admit 

func (a *Admitter) Admit(ctx context.Context, imageReference string) (Image, error)

Admit resolves and validates only local image content. An index whose selected leaf lacks an independently addressable local record returns MaterializationRequired without an Image. Mutable references are never resolved again after the initial inspection.

func (*Admitter) Compile 

func (a *Admitter) Compile(project *composetypes.Project, images map[string]Image) (PreparedProject, error)

Compile binds every active service to its admitted image and to the tenant seccomp profile, and freezes the resulting project. Each service's security options name exactly one profile, the sealed file of the current one, and keep every other option. It neither inspects nor pulls images.

func (*Admitter) NewComposeExecutor 

func (a *Admitter) NewComposeExecutor(up ComposeUpFunc) (*ComposeExecutor, error)

func (*Admitter) ReAdmit 

func (a *Admitter) ReAdmit(ctx context.Context, id string, platform ocispec.Platform, originalReference string) (Image, error)

ReAdmit restores a persisted execution identity against this runtime. The original reference is display metadata only: it is validated but never resolved or pulled. Creation still consumes the newly admitted immutable ID.

type ComposeExecutor 

type ComposeExecutor struct {
	// contains filtered or unexported fields
}

ComposeExecutor accepts only complete projects compiled by its own Admitter.

func (*ComposeExecutor) Up 

func (e *ComposeExecutor) Up(ctx context.Context, prepared PreparedProject, forceRecreate bool) error

Up executes a private copy: Compose may mutate its input without changing the sealed plan or a concurrent execution. Options cannot inject another project.

type ComposeUpFunc 

type ComposeUpFunc func(context.Context, *composetypes.Project, composeapi.UpOptions) error

ComposeUpFunc is captured once when wiring the Compose execution sink.

type DockerCreator 

type DockerCreator struct {
	// contains filtered or unexported fields
}

DockerCreator is a creation sink which accepts only images admitted by its own Admitter. The raw Docker operation never escapes this type.

func (*DockerCreator) Create 

func (c *DockerCreator) Create(ctx context.Context, image Image, config *container.Config, host *container.HostConfig, networks *network.NetworkingConfig, name string) (container.CreateResponse, error)

Create assigns execution identity itself; config.Image and image-binding labels supplied by the caller cannot override the admitted content.

func (*DockerCreator) CreateProjectContainer 

func (c *DockerCreator) CreateProjectContainer(ctx context.Context, binding ProjectContainer, config *container.Config, host *container.HostConfig, networks *network.NetworkingConfig, name string) (container.CreateResponse, error)

CreateProjectContainer consumes the image and grouping authority selected from one compiled service. Raw config labels cannot choose a project or substitute another image; ordinary direct creation remains outside Compose discovery.

func (*DockerCreator) ForInspection 

func (c *DockerCreator) ForInspection() *InspectionCreator

ForInspection projects the general image-bound creator into a constructor whose entire configuration is owned by this package.

func (*DockerCreator) ValidateImage 

func (c *DockerCreator) ValidateImage(image Image) error

ValidateImage checks issuer ownership without entering a mutation. Durable helper admission uses this before reserving a recovery identity, so a foreign image cannot consume a permanent ambiguous-Create receipt. Create repeats the same check at its own side-effect boundary.

type DockerSource 

type DockerSource interface {
	Source
	ClientVersion() string
	ServerVersion(context.Context) (types.Version, error)
	ContainerCreate(context.Context, *container.Config, *container.HostConfig, *network.NetworkingConfig, *ocispec.Platform, string) (container.CreateResponse, error)
}

DockerSource binds inspection and creation to one SDK client at the composition boundary. The runtime retains all raw capabilities privately.

type Image 

type Image struct {
	// contains filtered or unexported fields
}

Image is an admitted, independently addressable immutable image. Only Admit can mint a usable Image; its zero value grants no execution capability.

func (Image) ID 

func (i Image) ID() string

ID returns the immutable execution ID, or an empty string for a zero Image.

func (Image) Platform 

func (i Image) Platform() ocispec.Platform

Platform returns a copy of the admitted image's runnable platform.

func (Image) Reference 

func (i Image) Reference() string

Reference returns the original reference supplied to Admit.

func (Image) User 

func (i Image) User() string

User returns the image's USER directive.

func (Image) Volumes 

func (i Image) Volumes() []string

Volumes returns a sorted copy of the image's VOLUME declarations.

type InspectionCreator 

type InspectionCreator struct {
	// contains filtered or unexported fields
}

InspectionCreator creates only inert image views. It accepts no container or mount configuration: every image VOLUME is covered before Create, preventing anonymous host-volume population. It exposes no Start operation. The caller still owns unpack allocation and the durable helper receipt through its storage mutation protocol.

func (*InspectionCreator) Create 

func (c *InspectionCreator) Create(ctx context.Context, image Image, labels map[string]string, name string) (container.CreateResponse, error)

Create constructs a never-started view of the admitted image. Docker's archive API reads beneath inert tmpfs declarations, while Create recognizes them as volume overrides and performs no volume copy. WorkingDir is neutral so image configuration cannot trigger directory creation or copy-up.

type MaterializationRequired 

type MaterializationRequired struct {
	// contains filtered or unexported fields
}

MaterializationRequired identifies a selected immutable platform manifest without granting execution authority. Its content must pass the caller's bounded ingestion before ReAdmit can independently inspect the local image.

func (*MaterializationRequired) Error 

func (m *MaterializationRequired) Error() string

func (*MaterializationRequired) ID 

func (m *MaterializationRequired) ID() string

ID is the exact selected manifest identity required for subsequent admission.

func (*MaterializationRequired) Reference 

func (m *MaterializationRequired) Reference() string

Reference is the immutable repository reference for bounded ingestion.

type Metadata 

type Metadata struct {
	// contains filtered or unexported fields
}

Metadata is image configuration admitted by the same policy used by the execution boundary. Its zero value carries no admission evidence.

func AdmitMetadata 

func AdmitMetadata(labels map[string]string, volumes map[string]struct{}) (Metadata, error)

AdmitMetadata validates registry configuration before it can reach Docker, and is also used when inspecting a local execution identity.

func (Metadata) Valid 

func (m Metadata) Valid() bool

Valid reports whether this metadata passed admission.

func (Metadata) Volumes 

func (m Metadata) Volumes() []string

Volumes returns independent storage for the canonical admitted volume paths.

type PreparedProject 

type PreparedProject struct {
	// contains filtered or unexported fields
}

PreparedProject is a complete Compose project bound to admitted images. Its contents cannot be changed or recovered as a mutable project by callers.

func (PreparedProject) Container 

func (p PreparedProject) Container(service string) (ProjectContainer, error)

Container selects an exact service from this immutable compiled project. It does not accept replacement image or label values from the caller.

func (PreparedProject) Name 

func (p PreparedProject) Name() string

Name returns the project's name, or an empty string for a zero project.

type ProjectContainer 

type ProjectContainer struct {
	// contains filtered or unexported fields
}

ProjectContainer owns the admitted image and generated grouping stamps of one compiled service. Its zero value cannot authorize direct creation.

func (ProjectContainer) Image 

func (p ProjectContainer) Image() Image

Image returns the same admitted image owned by this service binding. Volume preparation may inspect it without acquiring independent creation authority.

type Source 

type Source interface {
	ImageInspect(context.Context, string, ...client.ImageInspectOption) (dockerimage.InspectResponse, error)
}

Source is the read-only image-store capability captured by an Admitter. It cannot fetch images or create or start containers.

type TenantSeccompSource 

type TenantSeccompSource interface {
	TenantSeccompProfile() (tenantseccomp.Profile, error)
}

TenantSeccompSource yields the process's verified tenant seccomp profile. tenantseccomp.Process is the production source; it builds the profile and its sealed file on demand and attempts either again after a failure. Every error it returns wraps tenantseccomp.ErrRefused.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.