soci

package
v0.12.1 Latest Latest
Warning

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

Go to latest
Published: Dec 10, 2025 License: Apache-2.0 Imports: 30 Imported by: 6

Documentation

Index

Constants

View Source
const (
	// SociIndexArtifactType is the artifactType of index SOCI index
	SociIndexArtifactType = SociIndexArtifactTypeV1
	// SociIndexArtifactTypeV1 is the artifact type of a v1 SOCI index which
	// uses the subject field and the OCI referrers API
	SociIndexArtifactTypeV1 = "application/vnd.amazon.soci.index.v1+json"
	// SociIndexArtifactTypeV2 is the artifact type of a v2 SOCI index which
	// does not contain a subject and instead maintains a reference via an annotation on an image manifest
	SociIndexArtifactTypeV2 = "application/vnd.amazon.soci.index.v2+json"
	// SociLayerMediaType is the mediaType of ztoc
	SociLayerMediaType = "application/octet-stream"
	// IndexAnnotationImageLayerMediaType is the index annotation for image layer media type
	IndexAnnotationImageLayerMediaType = "com.amazon.soci.image-layer-mediaType"
	// IndexAnnotationImageLayerDigest is the index annotation for image layer digest
	IndexAnnotationImageLayerDigest = "com.amazon.soci.image-layer-digest"
	// IndexAnnotationSpanSize is the span size used to generate a soci artifact
	IndexAnnotationSociSpanSize = "com.amazon.soci.span-size"
	// IndexAnnotationBuildToolIdentifier is the index annotation for build tool identifier
	IndexAnnotationBuildToolIdentifier = "com.amazon.soci.build-tool-identifier"
	// IndexAnnotationDisableXAttrs is the index annotation if the layer has
	// extended attributes
	IndexAnnotationDisableXAttrs = "com.amazon.soci.disable-xattrs"
	// IndexAnnotationImageManifestDigest is the annotation to indicate the digest
	// of the associated image manifest. This is useful for v2 SOCI indexes which do not contain
	// a subject field. This annotation goes on a SOCI index descriptor in an OCI index,
	// not in the SOCI index itself.
	IndexAnnotationImageManifestDigest = "com.amazon.soci.image-manifest-digest"

	// ImageAnnotationSociIndexDigest is an annotation on image manifests to specify
	// a SOCI index digest for the image.
	ImageAnnotationSociIndexDigest = "com.amazon.soci.index-digest"
)

Variables

View Source
var (
	V1 = IndexVersion{
		// contains filtered or unexported fields
	}
	V2 = IndexVersion{
		// contains filtered or unexported fields
	}
)
View Source
var (
	ErrArtifactBucketNotFound = errors.New("soci_artifacts not found")
)
View Source
var (
	ErrEmptyIndex = errors.New("no ztocs created, all layers either skipped or produced errors")
)
View Source
var Optimizations = []Optimization{XAttrOptimization}

Optimizations contains the list of all known optimizations

Functions

func ArtifactsDbPath

func ArtifactsDbPath(root string) string

Get the default artifacts db path

func DecodeIndex

func DecodeIndex(r io.Reader, index *Index) error

DecodeIndex deserializes a JSON blob in an io.Reader into a SOCI index. The blob is an OCI 1.0 Manifest

func EnsureSnapshotterRootPath added in v0.10.0

func EnsureSnapshotterRootPath(root string) error

EnsureSnapshotterRootPath ensures that the snapshotter root path exists. It creates the directory with restricted permissions (0711) if it doesn't exist.

func GetImageManifestDescriptor

func GetImageManifestDescriptor(ctx context.Context, cs content.Store, imageTarget ocispec.Descriptor, platform platforms.MatchComparer) (*ocispec.Descriptor, error)

GetImageManifestDescriptor gets the descriptor of image manifest

func MarshalIndex

func MarshalIndex(i *Index) ([]byte, error)

MarshalIndex serializes a SOCI index into a JSON blob. The JSON blob is an OCI 1.0 Manifest

func UnmarshalIndex

func UnmarshalIndex(b []byte, index *Index) error

UnmarshalIndex deserializes a JSON blob in a byte array into a SOCI index. The blob is an OCI 1.0 Manifest

Types

type ArtifactEntry

type ArtifactEntry struct {
	// Size is the SOCI artifact's size in bytes.
	Size int64
	// Digest is the SOCI artifact's digest.
	Digest string
	// OriginalDigest is the digest of the content for which the SOCI artifact was created.
	OriginalDigest string
	// ImageDigest is the digest of the container image that was used to generate the artifact
	// ImageDigest refers to the image, OriginalDigest refers to the specific content within that
	// image that was used to generate the Artifact.
	ImageDigest string
	// Platform is the platform for which the artifact was generated.
	Platform string
	// Location is the file path for the SOCI artifact.
	Location string
	// Type is the type of SOCI artifact.
	Type ArtifactEntryType
	// Media Type of the stored artifact.
	MediaType string
	// ArtifactType is the type of artifact stored (e.g. index manifest v1 vs index manifest v2)
	ArtifactType string
	// Creation time of SOCI artifact.
	CreatedAt time.Time
	// Span Size used to generate the SOCI artifact.
	SpanSize int64
}

ArtifactEntry is a metadata object for a SOCI artifact.

type ArtifactEntryType

type ArtifactEntryType string

ArtifactEntryType is the type of SOCI artifact represented by the ArtifactEntry

var (

	// ArtifactEntryTypeIndex indicates that an ArtifactEntry is a SOCI index artifact
	ArtifactEntryTypeIndex ArtifactEntryType = "soci_index"
	// ArtifactEntryTypeLayer indicates that an ArtifactEntry is a SOCI layer artifact
	ArtifactEntryTypeLayer ArtifactEntryType = "soci_layer"
)

type ArtifactsDb

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

ArtifactsDB is a store for SOCI artifact metadata

func NewDB

func NewDB(path string) (*ArtifactsDb, error)

NewDB returns an instance of an ArtifactsDB

func (*ArtifactsDb) GetArtifactEntriesByImageDigest added in v0.4.0

func (db *ArtifactsDb) GetArtifactEntriesByImageDigest(digest string) ([][]byte, error)

GetArtifactEntriesByImageDigest returns all index digests greated from a given image digest

func (*ArtifactsDb) GetArtifactEntry

func (db *ArtifactsDb) GetArtifactEntry(digest string) (*ArtifactEntry, error)

GetArtifactEntry loads a single ArtifactEntry from the ArtifactsDB by digest

func (*ArtifactsDb) GetArtifactType

func (db *ArtifactsDb) GetArtifactType(digest string) (ArtifactEntryType, error)

GetArtifactType gets Type of an ArtifactEntry from the ArtifactsDB by digest

func (*ArtifactsDb) RemoveArtifactEntryByIndexDigest

func (db *ArtifactsDb) RemoveArtifactEntryByIndexDigest(digest []byte) error

RemoveArtifactEntryByIndexDigest removes an index's artifact entry using its digest

func (*ArtifactsDb) RemoveOldArtifacts added in v0.4.0

func (db *ArtifactsDb) RemoveOldArtifacts(ctx context.Context, blobStore store.Store) error

RemoveOldArtifacts will remove any artifacts from the artifacts database that no longer exist in SOCIs local content store. NOTE: Removing buckets while iterating (bucket.ForEach) causes unexpected behavior (see: https://github.com/boltdb/bolt/issues/426). This implementation works around this issue by appending buckets to a slice when iterating and removing them after.

func (*ArtifactsDb) SyncWithLocalStore added in v0.3.0

func (db *ArtifactsDb) SyncWithLocalStore(ctx context.Context, blobStore store.Store, blobStorePath string, cs content.Store) error

SyncWithLocalStore will sync the artifacts databse with SOCIs local content store, either adding new or removing old artifacts.

func (*ArtifactsDb) Walk

func (db *ArtifactsDb) Walk(f func(*ArtifactEntry) error) error

Walk applys a function to all ArtifactEntries in the ArtifactsDB

func (*ArtifactsDb) WriteArtifactEntry

func (db *ArtifactsDb) WriteArtifactEntry(entry *ArtifactEntry) error

WriteArtifactEntry stores a single ArtifactEntry into the ArtifactsDB. If there is already an artifact in the ArtifactsDB with the same Digest, the old data is overwritten.

type BuildOption

type BuildOption func(*buildConfig) error

BuildOption is a functional argument that affects a single SOCI Index build.

func WithNoGarbageCollectionLabel added in v0.10.0

func WithNoGarbageCollectionLabel() BuildOption

WithNoGarbageCollectionLabel prevents the index builder from putting a root GC label on the soci index. The builder will set content GC labels to prevent the ztocs from being garbage collected.

The caller is responsible for putting appropriate GC labels to prevent the index from being garbage collected. The caller is also responsible for ensuring that the SOCI index does not get garbage collected after the build finishes, but before the GC label is applied. This can be done by calling `contentStore.BatchOpen` before calling `Build`.

func WithPlatform

func WithPlatform(platform ocispec.Platform) BuildOption

WithPlatform sets the platform for a single build operation.

type BuilderOption added in v0.10.0

type BuilderOption func(c *builderConfig) error

BuilderOption is a functional argument that affects a SOCI index builder and all indexes built with that builder.

func WithArtifactsDb

func WithArtifactsDb(db *ArtifactsDb) BuilderOption

WithArtifactsDb specifies the artifacts database

func WithBuildToolIdentifier

func WithBuildToolIdentifier(tool string) BuilderOption

WithBuildToolIdentifier specifies the build tool annotation value.

func WithForceRecreateZtocs added in v0.12.0

func WithForceRecreateZtocs(forceRecreateZtocs bool) BuilderOption

func WithMinLayerSize

func WithMinLayerSize(minLayerSize int64) BuilderOption

WithMinLayerSize specifies min layer size to build a ztoc for a layer.

func WithOptimizations added in v0.7.0

func WithOptimizations(optimizations []Optimization) BuilderOption

WithOptimizations enables optional optimizations when building the SOCI Index (experimental)

func WithSpanSize

func WithSpanSize(spanSize int64) BuilderOption

WithSpanSize specifies span size.

type ConvertOption added in v0.10.0

type ConvertOption func(*convertConfig) error

func ConvertWithNoGarbageCollectionLabels added in v0.10.0

func ConvertWithNoGarbageCollectionLabels() ConvertOption

ConvertWithNoGarbageCollectionLabels disables adding a containerd root gc label to the converted image and SOCI indexes. The caller is responsible for ensuring the OCI Index doesn't get garbage collected.

func ConvertWithPlatforms added in v0.10.0

func ConvertWithPlatforms(platforms ...ocispec.Platform) ConvertOption

ConvertWithPlatforms sets the platforms that will be indexed during conversion

type Index

type Index struct {
	// MediaType represents the type of document into which the SOCI index manifest will be serialized
	MediaType string `json:"mediaType"`

	// Artifact type is the media type of the SOCI index itself.
	ArtifactType string `json:"artifactType"`

	// Blobs are descriptors for the zTOCs in the index.
	Blobs []ocispec.Descriptor `json:"blobs,omitempty"`

	// Subject is the descriptor for the resource to which the index applies.
	Subject *ocispec.Descriptor `json:"subject,omitempty"`

	// Annotations are optional additional metadata for the index.
	Annotations map[string]string `json:"annotations,omitempty"`

	Config ocispec.Descriptor `json:"-"`
}

Index represents a SOCI index manifest.

func NewIndex

func NewIndex(version IndexVersion, blobs []ocispec.Descriptor, subject *ocispec.Descriptor, annotations map[string]string) *Index

NewIndex returns a new index.

func NewIndexFromReader

func NewIndexFromReader(reader io.Reader) (*Index, error)

NewIndexFromReader returns a new index from a Reader.

type IndexBuilder

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

IndexBuilder creates soci indices.

func NewIndexBuilder

func NewIndexBuilder(contentStore content.Store, blobStore store.Store, opts ...BuilderOption) (*IndexBuilder, error)

NewIndexBuilder returns an `IndexBuilder` that is used to create soci indices.

func (*IndexBuilder) Build

func (b *IndexBuilder) Build(ctx context.Context, img images.Image, opts ...BuildOption) (*IndexWithMetadata, error)

Build builds a soci index for `img` and pushes it with its corresponding zTOCs to the blob store. Returns the SOCI index and its metadata.

func (*IndexBuilder) Convert added in v0.10.0

func (b *IndexBuilder) Convert(ctx context.Context, img images.Image, opts ...ConvertOption) (*ocispec.Descriptor, error)

Convert converts an image into a SOCI enabled image.

At a high level, this process: 1. Creates a SOCI index for each platform (unless overridden by ConvertWithPlatforms) 2. Adds an annotation to each image with the SOCI index digest 3. Appends the SOCI indexes to the list of manifests in the OCI index

Notes: Adding an annotation to an image changes the image digest. This is equivalent to creating a new image. This function will serialize and push the new image manifest to the content store and replaces the original image in the OCI index. The layers will be shared, not duplicated.

If the image is a single platform image, this function will create an OCI index so that it can bundle the image and SOCI index into a single artifact.

type IndexDescriptorInfo

type IndexDescriptorInfo struct {
	ocispec.Descriptor
	CreatedAt time.Time
}

IndexDescriptorInfo has a soci index descriptor and additional metadata.

func GetIndexDescriptorCollection

func GetIndexDescriptorCollection(ctx context.Context, cs content.Store, artifactsDb *ArtifactsDb, img images.Image, ps []ocispec.Platform) ([]IndexDescriptorInfo, *ocispec.Descriptor, error)

GetIndexDescriptorCollection returns all `IndexDescriptorInfo` of the given image and platforms.

type IndexVersion added in v0.10.0

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

IndexVersion represents the version of an index created by the index builder

type IndexWithMetadata

type IndexWithMetadata struct {
	// Index is the SOCI index itself
	Index *Index
	// Desc is the descriptor for the serialized SOCI index
	Desc ocispec.Descriptor
	// Platform is the platform for the SOCI index
	Platform *ocispec.Platform
	// ImageDesc is the descriptor of the original image used
	// to create the SOCI index. This could either be a reference to an image
	// manifest in the case of single-platorm images or an OCI Index/Docker Manifest List
	// in the case of multi-platform images. This descriptor is intended for mapping
	// the SOCI index to a particular image ref, but not necessarily a specific platform.
	ImageDesc ocispec.Descriptor
	// ManifestDesc is the descriptor of the original image manifest used
	// to create the SOCI index. This is the same as the ImageDesc for single-platform images,
	// but not for multiplatform images. This descriptor always maps to the platform-specific image
	// manifest that was used when creating the SOCI index. For SOCI v1 indexes, this is the same
	// as the Subject. For SOCI v2 indexes, this is used in place of the subject.
	ManifestDesc ocispec.Descriptor
	CreatedAt    time.Time
}

IndexWithMetadata has a soci `Index` and its metadata.

type Optimization added in v0.7.0

type Optimization string

Optimization represents an optional optimization to be applied when building the SOCI index

const (
	// XAttrOptimization optimizes xattrs by disabling them for layers where there are no xattrs or opaque directories
	XAttrOptimization Optimization = "xattr"
)

func ParseOptimization added in v0.7.0

func ParseOptimization(s string) (Optimization, error)

ParseOptimization parses a string into a known optimization. If the string does not match a known optimization, an error is returned.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL