api

package
v0.3.19 Latest Latest
Warning

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

 Go to latest Published: Aug 1, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Compression algorithms
	Uncompressed CompressionAlgorithm = "uncompressed"
	Gzip         CompressionAlgorithm = "gzip"
	Zstd         CompressionAlgorithm = "zstd"

	// Hash algorithms
	SHA256 HashAlgorithm = "sha256"

	// Layer formats
	TarLayer     = "application/vnd.oci.image.layer.v1.tar"
	TarGzipLayer = "application/vnd.oci.image.layer.v1.tar+gzip"
	TarZstdLayer = "application/vnd.oci.image.layer.v1.tar+zstd"

	// Config media types
	MediaTypeEmptyJSON = "application/vnd.oci.empty.v1+json"
)
View Source 
const (
	// AnnotationContainerdImageName is the annotation used by containerd to store the full
	// image reference (<registry>/<repository>:<tag>) in an OCI image index descriptor.
	// See https://github.com/containerd/containerd/blob/main/core/images/image.go
	AnnotationContainerdImageName = "io.containerd.image.name"

	// AnnotationAppleContainerizationImageName is the annotation used by Apple's Containerization
	// framework to store the full image reference (<registry>/<repository>:<tag>) in an OCI
	// image index descriptor.
	AnnotationAppleContainerizationImageName = "com.apple.containerization.image.name"

	// AnnotationOCIImageRefName is the annotation defined by the OCI image spec to store the
	// tag component of an image reference (e.g. "latest") in an OCI image index descriptor.
	// Note that this value may not be unique within the index.
	// See https://github.com/opencontainers/image-spec/blob/main/annotations.md
	AnnotationOCIImageRefName = "org.opencontainers.image.ref.name"

	// TocDigestAnnotation is the annotation key for the TOC digest in estargz layers
	TocDigestAnnotation = "containerd.io/snapshot/stargz/toc.digest"
	// UncompressedSizeAnnotation is the annotation key for the uncompressed size in estargz layers
	UncompressedSizeAnnotation = "io.containers.estargz.uncompressed-size"
)
View Source 
const (
	// SociIndexArtifactTypeV2 is the artifactType of a v2 SOCI index. It is also
	// the media type of the SOCI index's (empty "{}") config descriptor, which is
	// how the index's artifact type is conveyed on the manifest itself.
	SociIndexArtifactTypeV2 = "application/vnd.amazon.soci.index.v2+json"
	// SociLayerMediaType is the media type of a ztoc blob (a SOCI index "layer").
	SociLayerMediaType = "application/octet-stream"

	// SociImageLayerMediaTypeAnnotation records, on a ztoc descriptor, the media
	// type of the image layer the ztoc indexes.
	SociImageLayerMediaTypeAnnotation = "com.amazon.soci.image-layer-mediaType"
	// SociImageLayerDigestAnnotation records, on a ztoc descriptor, the digest of
	// the image layer the ztoc indexes.
	SociImageLayerDigestAnnotation = "com.amazon.soci.image-layer-digest"
	// SociSpanSizeAnnotation records, on a ztoc descriptor, the span size the ztoc
	// was generated with.
	SociSpanSizeAnnotation = "com.amazon.soci.span-size"
	// SociBuildToolIdentifierAnnotation records, on the SOCI index, the tool that
	// created it.
	SociBuildToolIdentifierAnnotation = "com.amazon.soci.build-tool-identifier"

	// SociIndexDigestAnnotation is set on an IMAGE manifest to point at its SOCI
	// index (v2 discovery). Setting it rewrites the image manifest, changing its
	// digest.
	SociIndexDigestAnnotation = "com.amazon.soci.index-digest"
	// SociImageManifestDigestAnnotation is set on a SOCI-index descriptor within an
	// OCI image index to point back at the image manifest it belongs to.
	SociImageManifestDigestAnnotation = "com.amazon.soci.image-manifest-digest"
)

SOCI Index Manifest v2 media/artifact types and annotation keys. These match github.com/awslabs/soci-snapshotter (soci/soci_index.go). SOCI v2 links a SOCI index to its image via annotations (not the referrers API / subject).

View Source 
const (
	PushCommand = "push"
	LoadCommand = "load"
)
View Source 
const (
	// SignSettingMediaType is the media type recorded for a sign_setting config
	// file descriptor. sign_setting files are small deterministic JSON blobs
	// produced by the `signing_config` Bazel rule that describe how to invoke a
	// signer plugin (they never carry key material).
	SignSettingMediaType = "application/vnd.rules-img.sign-config.v1+json"

	// Sign targets select which descriptors of a push operation are signed.
	// They are cumulative: "child_manifests" implies "roots", and "referrers"
	// implies both.
	SignTargetRoots          = "roots"
	SignTargetChildManifests = "child_manifests"
	SignTargetReferrers      = "referrers"
)

Signature artifact / sign_setting media types and target selectors.

Variables

View Source 
var (
	RegularFile = FileType{"f"}
	Directory   = FileType{"d"}
	Symlink     = FileType{"l"}
)

Functions

func NormalizeLoadReference added in v0.3.19 

func NormalizeLoadReference(ref string) (string, error)

NormalizeLoadReference validates a load image reference and returns the name that is handed to the daemon (or written to a docker-save tarball).

Unlike Docker's own reference normalization it never invents a registry and never inserts the "library/" namespace: a load target's image name is exactly what the user configured, so "my-app:latest" stays "my-app:latest" and a registry with a port keeps it ("docker.example.com:1234/foo:latest" is returned verbatim instead of being mistaken for the tag "1234/foo:latest"). The only rewrite is appending the default ":latest" tag to an untagged reference, which the daemons require (`docker load` rejects an untagged RepoTags entry). Digest references are returned unchanged.

An unparseable reference is an error rather than something we silently pass on: a name the daemon cannot resolve is never what the user meant.

func NormalizeLoadReferences added in v0.3.19 

func NormalizeLoadReferences(refs []string) ([]string, error)

NormalizeLoadReferences applies NormalizeLoadReference to every reference, returning a fresh slice. It fails on the first invalid reference.

func QualifyLoadTags added in v0.3.18 

func QualifyLoadTags(registry, repository string, tags []string) []string

QualifyLoadTags reconstructs full image names for a load operation. When both registry and repository are set, each tag is expanded to "<registry>/<repository>:<tag>". When either is empty (backwards-compatible mode) the tags are returned verbatim, because they are already full image references. The returned slice is always a fresh copy so callers may mutate it freely.

func ValidateLoadDestination added in v0.3.18 

func ValidateLoadDestination(registry, repository string) error

ValidateLoadDestination reports an error when exactly one of registry and repository is set. Both-set (split mode) and both-empty (verbatim, rules_oci-compatible mode) are valid; a lone registry or repository is a misconfiguration (for example a Go template that expanded to the empty string) that would otherwise silently fall back to verbatim mode. This mirrors the hard error the push path raises for a missing registry/repository, and must be checked against the post-template-expansion values (the Starlark-level guard only sees the raw, unexpanded strings).

Types

type Appender 

type Appender interface {
	io.Writer
	Finalize() (AppenderState, error)
}

type AppenderState 

type AppenderState struct {
	// Magic is an identifier for the format of the state.
	Magic string `json:"magic"`
	// OuterHashState is the inner state of the hash for the compressed data.
	// Used to resume the hash function for appending.
	OuterHashState []byte `json:"outer_hash_state"`
	// OuterHash is the final hash for the compressed data.
	// Cannot be used for resuming, but is the actual hash.
	OuterHash []byte `json:"outer_hash"`
	// ContentHashState is the state of the hash for the inner, uncompressed data.
	ContentHashState []byte `json:"content_hash_state"`
	// ContentHash is the final hash for the inner, uncompressed data.
	ContentHash []byte `json:"content_hash"`
	// CompressedSize is the compressed size of the blob.
	CompressedSize int64 `json:"compressed_size"`
	// UncompressedSize is the uncompressed size of the blob.
	UncompressedSize int64 `json:"uncompressed_size"`
	// LayerAnnotations are additional metadata for the layer.
	LayerAnnotations map[string]string `json:"layer_annotations,omitempty"`
}

func (*AppenderState) AppendBinary 

func (s *AppenderState) AppendBinary(b []byte) ([]byte, error)

func (*AppenderState) MarshalBinary 

func (s *AppenderState) MarshalBinary() ([]byte, error)

func (*AppenderState) UnmarshalBinary 

func (s *AppenderState) UnmarshalBinary(b []byte) error

type BaseCommandOperation 

type BaseCommandOperation struct {
	Command   string               `json:"command"`   // "push" or "load"
	RootKind  string               `json:"root_kind"` // "manifest" or "index"
	Root      Descriptor           `json:"root"`      // the descriptor of the index / single manifest to push
	Manifests []ManifestDeployInfo `json:"manifests"` // for index push, the list of manifests to push. For single manifest push, this contains just one element.

	CrossMountHint *CrossMountSource `json:"cross_mount_hint,omitempty"` // repository from which layers can be cross-mounted

	PullInfo
}

type CAS 

type CAS interface {
	Import(CASStateSupplier) error
	Export(CASStateExporter) error
	Store(r io.Reader, intendedPath string) (linkPath string, blobHash []byte, blobSize int64, err error)
	StoreKnownHashAndSize(r io.Reader, blobHash []byte, size int64, intendedPath string) (linkPath string, err error)
	StoreNode(r io.Reader, hdr *tar.Header) (linkPath string, blobHash []byte, size int64, err error)
	StoreNodeKnownHash(r io.Reader, hdr *tar.Header, blobHash []byte) (linkPath string, err error)
	StoreTree(fsys fs.FS, intendedPath string) (linkPath string, err error)
	StoreTreeKnownHash(fsys fs.FS, intendedPath string, treeHash []byte) (linkPath string, err error)
}

type CASStateExporter 

type CASStateExporter interface {
	Export(CASStateSupplier) error
}

type CASStateSupplier 

type CASStateSupplier interface {
	// Blobs are files without any metadata.
	// The hash is the hash of the file contents.
	BlobHashes() iter.Seq2[[]byte, error]
	// Nodes are inodes with metadata.
	// The hash includes any metadata,
	// as well as the file contents.
	NodeHashes() iter.Seq2[[]byte, error]
	// Trees are made up of blobs
	// with paths in the tree.
	TreeHashes() iter.Seq2[[]byte, error]
}

type CompressionAlgorithm 

type CompressionAlgorithm string

type CrossMountSource added in v0.3.8 

type CrossMountSource struct {
	Registry   string `json:"registry,omitempty"`
	Repository string `json:"repository"`
}

type DeployManifest 

type DeployManifest struct {
	Operations []json.RawMessage `json:"operations"`
	Settings   DeploySettings    `json:"settings"`
}

func (*DeployManifest) BaseOperations 

func (dm *DeployManifest) BaseOperations() ([]BaseCommandOperation, error)

func (*DeployManifest) LoadOperations 

func (dm *DeployManifest) LoadOperations() ([]IndexedLoadDeployOperation, error)

func (*DeployManifest) PushOperations 

func (dm *DeployManifest) PushOperations() ([]IndexedPushDeployOperation, error)

func (*DeployManifest) RegistryTagOperations added in v0.3.9 

func (dm *DeployManifest) RegistryTagOperations() ([]IndexedRegistryTagDeployOperation, error)

type DeploySettings 

type DeploySettings struct {
	PushStrategy string `json:"push_strategy,omitempty"`
	LoadStrategy string `json:"load_strategy,omitempty"`
	// DefaultSignSetting is the content descriptor of the sign_setting config
	// file used for push operations that request signing but do not carry their
	// own Sign.Setting. It is resolved at runtime against the discovered
	// sign_settings and may be overridden by `img deploy --default_sign_setting`.
	DefaultSignSetting *Descriptor `json:"default_sign_setting,omitempty"`
	// BlobRepository, when non-empty, overrides the repository that layer blobs
	// are pushed to. Blobs are uploaded to this repository (within the push
	// operation's registry) and the manifest push cross-mounts them from here
	// into the operation's real repository. Empty means blobs go to the
	// operation's own repository (the default behavior).
	BlobRepository string `json:"blob_repository,omitempty"`
	// ForbidLayerPush, when true, forbids uploading layer blob bytes during a
	// push. Layers may still be cross-mounted or skipped when already present,
	// but any attempt to actually upload a layer's bytes fails. This guards
	// deployments where layer blobs are expected to have been pushed at build
	// time (and mounted server-side): if the deploy is ever asked to upload a
	// layer, it fails loudly instead of silently re-uploading.
	ForbidLayerPush bool `json:"forbid_layer_push,omitempty"`
}

type Descriptor 

type Descriptor struct {
	DiffID      string            `json:"diff_id,omitempty"`
	MediaType   string            `json:"mediaType"`
	Digest      string            `json:"digest"`
	Size        int64             `json:"size"`
	Annotations map[string]string `json:"annotations,omitempty"`
	History     []History         `json:"history,omitempty"`
}

type FileType 

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

func (FileType) String 

func (f FileType) String() string

type HashAlgorithm 

type HashAlgorithm string

func (HashAlgorithm) Len 

func (h HashAlgorithm) Len() int

type History added in v0.3.14 

type History struct {
	// Created is the combined date and time at which the layer was created, formatted as defined by RFC 3339, section 5.6.
	Created *time.Time `json:"created,omitempty"`

	// CreatedBy is the command which created the layer.
	CreatedBy string `json:"created_by,omitempty"`

	// Author is the author of the build point.
	Author string `json:"author,omitempty"`

	// Comment is a custom message set when creating the layer.
	Comment string `json:"comment,omitempty"`

	// EmptyLayer is used to mark if the history item created a filesystem diff.
	EmptyLayer bool `json:"empty_layer,omitempty"`
}

History describes the history of a layer. This is a re-export of the oci spec v1 History structure to avoid taking a dep on it

func LayerHistory added in v0.3.16 

func LayerHistory(createdBy string) []History

LayerHistory returns the history for a layer whose creating command is createdBy (e.g. "bazel build //pkg:target", assembled by the caller). When createdBy is empty (no --history was provided), it records a "history missing" marker so every layer carries at least a created_by entry.

type IndexedLoadDeployOperation 

type IndexedLoadDeployOperation struct {
	I        int
	Strategy string
	LoadDeployOperation
}

type IndexedPushDeployOperation 

type IndexedPushDeployOperation struct {
	I        int
	Strategy string
	PushDeployOperation
}

type IndexedRegistryTagDeployOperation added in v0.3.9 

type IndexedRegistryTagDeployOperation struct {
	I        int
	Strategy string
	RegistryTagDeployOperation
}

type LayerBlob added in v0.3.16 

type LayerBlob struct {
	Descriptor
	Sources []LayerSource `json:"sources,omitempty"`
	// CompactStream, when set, marks this layer as a compact-stream layer whose
	// compressed blob was never materialized. It holds the CAS digest and size of
	// the .cstream index, from which the layer is reconstructed (the .cstream
	// header carries the compression parameters and the expected output digest).
	// The input blobs referenced by the .cstream are resolved from the CAS by the
	// digests recorded in its reference table.
	CompactStream *Descriptor `json:"compact_stream,omitempty"`
}

LayerBlob is the descriptor of a single layer together with the upstream sources it can be fetched from. It embeds Descriptor so the layer's mediaType/digest/size fields marshal inline; the extra "sources" field lists the registry/repository combinations the blob is available from (e.g. the shallow base image it was pulled from). Sources is empty for layers built locally that have no upstream origin.

type LayerFormat 

type LayerFormat string

func (LayerFormat) CompressionAlgorithm 

func (c LayerFormat) CompressionAlgorithm() CompressionAlgorithm

type LayerSource added in v0.3.16 

type LayerSource struct {
	Registry   string `json:"registry"`
	Repository string `json:"repository"`
}

LayerSource identifies one place a layer blob can be fetched from. The blob is content-addressed, so only the registry and repository are needed; the digest is the layer's own descriptor digest. A layer may list multiple sources (for example the same repository mirrored across several registries, or the same blob shared by base images from different repositories).

type LoadDeployOperation 

type LoadDeployOperation struct {
	BaseCommandOperation
	Registry   string   `json:"registry,omitempty"`
	Repository string   `json:"repository,omitempty"`
	Tags       []string `json:"tags,omitempty"`
	Daemon     string   `json:"daemon,omitempty"`
}

LoadDeployOperation describes loading an image into a local daemon. It mirrors PushTarget's Registry/Repository/Tags shape, but keeps every destination field optional: when only Tags are set (the rules_oci-compatible mode) the tags are already full image references and Registry/Repository are omitted entirely. When Registry and Repository are both set, Tags are bare tags and the full image names are reconstructed as "<registry>/<repository>:<tag>" (see ImageNames).

func (LoadDeployOperation) ImageNames added in v0.3.18 

func (o LoadDeployOperation) ImageNames() []string

ImageNames returns the fully-qualified image reference(s) this load operation applies. See QualifyLoadTags for the reconstruction rules.

type ManifestDeployInfo 

type ManifestDeployInfo struct {
	// Descriptor of the manifest to push
	Descriptor Descriptor `json:"descriptor"`
	// Descriptor of the config to push
	Config Descriptor `json:"config"`
	// Descriptor of the layers to push, each carrying its own upstream sources.
	LayerBlobs []LayerBlob `json:"layer_blobs"`
}

type OCIArtifactSigner added in v0.3.18 

type OCIArtifactSigner interface {
	// Sign generates a cryptographic signature for the given target artifact.
	// The 'subject' descriptor contains the digest, size, and mediaType of the
	// target. It returns a v1.Image representing the OCI signature artifact
	// itself, properly linked via the OCI 1.1 subject field, ready to be pushed
	// to a registry.
	Sign(ctx context.Context, subject v1.Descriptor) (v1.Image, error)
}

OCIArtifactSigner abstracts the creation of OCI-native signature artifacts.

It is the single seam between `img deploy` and any signing implementation. `img deploy` itself carries exactly one implementation, which delegates to an external signer plugin over a subprocess RPC (see img_tool/pkg/signer). Plugin authors implement this same interface in-process and wrap it with the shared runner in img_tool/signer-plugins/pkg/plugin.

type PullInfo 

type PullInfo struct {
	OriginalBaseImageRegistries []string `json:"original_registries,omitempty"`
	OriginalBaseImageRepository string   `json:"original_repository,omitempty"`
	OriginalBaseImageTag        string   `json:"original_tag,omitempty"`
	OriginalBaseImageDigest     string   `json:"original_digest,omitempty"`
}

type PushDeployOperation 

type PushDeployOperation struct {
	BaseCommandOperation
	PushTarget
	// Sign, when set, requests that the pushed artifact be signed after a
	// successful push (signatures are attached as OCI referrers). It is only
	// meaningful for push operations.
	Sign *SignConfig `json:"sign,omitempty"`
	// Referrer marks this push operation as a referrer artifact of a preceding
	// push (e.g. an SBOM). It lets the deploy tool decide whether the
	// "referrers" sign target applies to this operation.
	Referrer bool `json:"referrer,omitempty"`
}

type PushTarget 

type PushTarget struct {
	Registry   string   `json:"registry"`
	Repository string   `json:"repository"`
	Tags       []string `json:"tags,omitempty"`
}

type RegistryTagDeployOperation added in v0.3.9 

type RegistryTagDeployOperation struct {
	BaseCommandOperation
	PushTarget
}

RegistryTagDeployOperation attaches extra tags to a manifest already pushed by a preceding push operation. Tags are pre-expanded at build time.

type SignConfig added in v0.3.18 

type SignConfig struct {
	// Setting is the content descriptor of the sign_setting config file to use.
	// When nil, the operation falls back to DeploySettings.DefaultSignSetting
	// (or the runtime --default_sign_setting override).
	Setting *Descriptor `json:"setting,omitempty"`
	// BestEffort, when true, downgrades signing failures for this operation to a
	// warning instead of aborting the deploy.
	BestEffort bool `json:"best_effort,omitempty"`
	// Targets selects which descriptors of the operation to sign (see the
	// SignTarget* constants). Empty means the default (roots only). The runtime
	// --sign_targets flag overrides this value.
	Targets []string `json:"targets,omitempty"`
}

SignConfig captures, per push operation, whether and how the pushed artifact is signed. It carries no key material: Setting references (by content descriptor) a sign_setting config file shipped in the deploy binary's runfiles, which the deploy tool resolves and hands to a signer plugin.

type TarAppender 

type TarAppender interface {
	AppendTar(r io.Reader) error
	Finalize() (AppenderState, error)
}

type TarCAS 

type TarCAS interface {
	CAS
	TarWriter
}

type TarWriter 

type TarWriter interface {
	Close() error
	WriteHeader(hdr *tar.Header) error
	WriteRegular(hdr *tar.Header, r io.Reader) error
	WriteRegularDeduplicated(hdr *tar.Header, r io.Reader) error
	WriteRegularFromPath(hdr *tar.Header, filePath string) error
	WriteRegularFromPathDeduplicated(hdr *tar.Header, filePath string) error
}

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.