Documentation
¶
Index ¶
- Constants
- Variables
- func ArtifactsDbPath(root string) string
- func DecodeIndex(r io.Reader, index *Index) error
- func EnsureSnapshotterRootPath(root string) error
- func GetImageManifestDescriptor(ctx context.Context, cs content.Store, imageTarget ocispec.Descriptor, ...) (*ocispec.Descriptor, error)
- func MarshalIndex(i *Index) ([]byte, error)
- func UnmarshalIndex(b []byte, index *Index) error
- type ArtifactEntry
- type ArtifactEntryType
- type ArtifactsDb
- func (db *ArtifactsDb) GetArtifactEntriesByImageDigest(digest string) ([][]byte, error)
- func (db *ArtifactsDb) GetArtifactEntry(digest string) (*ArtifactEntry, error)
- func (db *ArtifactsDb) GetArtifactType(digest string) (ArtifactEntryType, error)
- func (db *ArtifactsDb) RemoveArtifactEntryByIndexDigest(digest []byte) error
- func (db *ArtifactsDb) RemoveOldArtifacts(ctx context.Context, blobStore store.Store) error
- func (db *ArtifactsDb) SyncWithLocalStore(ctx context.Context, blobStore store.Store, blobStorePath string, ...) error
- func (db *ArtifactsDb) Walk(f func(*ArtifactEntry) error) error
- func (db *ArtifactsDb) WriteArtifactEntry(entry *ArtifactEntry) error
- type BuildOption
- type BuilderOption
- func WithArtifactsDb(db *ArtifactsDb) BuilderOption
- func WithBuildToolIdentifier(tool string) BuilderOption
- func WithForceRecreateZtocs(forceRecreateZtocs bool) BuilderOption
- func WithMinLayerSize(minLayerSize int64) BuilderOption
- func WithOptimizations(optimizations []Optimization) BuilderOption
- func WithSpanSize(spanSize int64) BuilderOption
- type ConvertOption
- type Index
- type IndexBuilder
- type IndexDescriptorInfo
- type IndexVersion
- type IndexWithMetadata
- type Optimization
Constants ¶
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 ¶
var ( V1 = IndexVersion{ // contains filtered or unexported fields } V2 = IndexVersion{ // contains filtered or unexported fields } )
var (
ErrArtifactBucketNotFound = errors.New("soci_artifacts not found")
)
var (
ErrEmptyIndex = errors.New("no ztocs created, all layers either skipped or produced errors")
)
var Optimizations = []Optimization{XAttrOptimization}
Optimizations contains the list of all known optimizations
Functions ¶
func DecodeIndex ¶
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
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 ¶
MarshalIndex serializes a SOCI index into a JSON blob. The JSON blob is an OCI 1.0 Manifest
func UnmarshalIndex ¶
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
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.
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.