oci

package
v0.8.7-12-g7bf661f5 Latest Latest
Warning

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

 Go to latest Published: May 31, 2024 License: BSD-3-Clause Imports: 57 Imported by: 3

README

Unikraft OCI Images

This package contains the implementation for handling both the packaging and distribution of Unikraft unikernels via the Open Container Image (OCI)'s Image Specification.

At a high-level, this is done in order to ease distribution of pre-built unikernel images using existing infrastructure. More precisely, the specification is adopted with several well-known annotations and practices to ensure consistency and compatibility with Unikraft unikernel images which are packed into an OCI image format.

Overview

The OCI Image Specification allows for the declaration of artifacts in a hierarchical fashion. The top-most element is an index which contains a list of manifests. Each manifest in KraftKit's case is a pre-built unikernel image along with accompanying root filesystem.

Supported backends

There are currently two supported backends for using and manipulating OCI images in KraftKit:

  • directory (default) handles the representation of the OCI Image in directory format;
  • containerd which requires configuration in the KraftKit config file and uses containerd's content storage system.
General usage
kraft pkg --name helloworld:latest --with-kconfig --plat qemu

In the directory implementation, the representation results in the following artifacts on the host system:

/root/.local/share/kraftkit/runtime/oci
├── configs
│   └── sha256
│       ├── 9530779d911fc36a50e156d36379d2e4d59eb259f28fba2311a80845a11988ec.json
│       └── fe5f6abe40068df5d5e98a08dc2f697faa5d22c064ac890e4f1a160d2999c6c4.json
├── indexes
│   └── helloworld
│       └── latest.json
├── layers
│   └── sha256
│       ├── 784e290aec5e97bf1e9ba17759fb0df3188a7285b08fccc84f882be4f2f65064
│       └── 989eddd15537fc00d20d560ae35c435b59b96c421412d75a85f22b7331a78aff
└── manifests
    └── sha256
        ├── 656072e6e2bb60be3bd439460058c3240e29aa83e718e42fd213789d2bbfa0f0.json
        └── 865cdfc985c9818b31b3b8094e405cd7e2d96fca4c19f07f38ef75a9077679d7.json

For containerd it results the following objects within the content store:

ctr content ls
DIGEST                                                                  SIZE    AGE             LABELS
sha256:089d3e4f1c08951c5bc7b0a41ab9fca5445ac06dea642679d243db00a1948f0d 2.627kB 1 second        containerd.io/distribution.source.index.docker.io=library/helloworld,containerd.io/gc.ref.content.l.0=sha256:989eddd15537fc00d20d560ae35c435b59b96c421412d75a85f22b7331a78aff,containerd.io/gc.ref.content.l.1=sha256:9530779d911fc36a50e156d36379d2e4d59eb259f28fba2311a80845a11988ec,containerd.io/gc.root=true,kraftkit.sh/oci.mediaType=application/vnd.oci.image.manifest.v1+json
sha256:784e290aec5e97bf1e9ba17759fb0df3188a7285b08fccc84f882be4f2f65064 217.1kB 1 second        containerd.io/gc.root=true,kraftkit.sh/oci.mediaType=application/vnd.oci.image.layer.v1.tar
sha256:9530779d911fc36a50e156d36379d2e4d59eb259f28fba2311a80845a11988ec 1.96kB  1 second        containerd.io/gc.root=true,kraftkit.sh/oci.mediaType=application/vnd.oci.image.config.v1+json
sha256:989eddd15537fc00d20d560ae35c435b59b96c421412d75a85f22b7331a78aff 241.7kB 1 second        containerd.io/gc.root=true,kraftkit.sh/oci.mediaType=application/vnd.oci.image.layer.v1.tar
sha256:ce3ff4f9a957ab52f8187d03d8e45db4cbb35101ea4e65ff0f3f08b0ebbda111 4.773kB 1 second        containerd.io/distribution.source.index.docker.io=library/helloworld,containerd.io/gc.ref.content.m.0=sha256:f63c483c81fd38dfc3c9088f7decaaec488cea3ff09648a5373ce6efb0c0234c,containerd.io/gc.ref.content.m.1=sha256:089d3e4f1c08951c5bc7b0a41ab9fca5445ac06dea642679d243db00a1948f0d,containerd.io/gc.root=true,kraftkit.sh/oci.mediaType=application/vnd.oci.image.index.v1+json
sha256:f63c483c81fd38dfc3c9088f7decaaec488cea3ff09648a5373ce6efb0c0234c 2.455kB 1 second        containerd.io/distribution.source.index.docker.io=library/helloworld,containerd.io/gc.ref.content.l.0=sha256:784e290aec5e97bf1e9ba17759fb0df3188a7285b08fccc84f882be4f2f65064,containerd.io/gc.ref.content.l.1=sha256:fe5f6abe40068df5d5e98a08dc2f697faa5d22c064ac890e4f1a160d2999c6c4,containerd.io/gc.root=true,kraftkit.sh/oci.mediaType=application/vnd.oci.image.manifest.v1+json
sha256:fe5f6abe40068df5d5e98a08dc2f697faa5d22c064ac890e4f1a160d2999c6c4 1.788kB 1 second        containerd.io/gc.root=true,kraftkit.sh/oci.mediaType=application/vnd.oci.image.config.v1+json

Documentation

Overview

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2024, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors. Licensed under the BSD-3-Clause License (the "License"). You may not use this file except in compliance with the License.

Index

Constants

View Source 
const (
	AnnotationMediaType            = "org.unikraft.mediaType"
	AnnotationName                 = "org.unikraft.image.name"
	AnnotationVersion              = "org.unikraft.image.version"
	AnnotationURL                  = "org.unikraft.image.url"
	AnnotationCreated              = "org.unikraft.image.created"
	AnnotaitonDescription          = "org.unikraft.image.description"
	AnnotationKernelPath           = "org.unikraft.kernel.image"
	AnnotationKernelVersion        = "org.unikraft.kernel.version"
	AnnotationKernelInitrdPath     = "org.unikraft.kernel.initrd"
	AnnotationKernelKConfig        = "org.unikraft.kernel.kconfig."
	AnnotationKernelArch           = "org.unikraft.kernel.arch"
	AnnotationKernelPlat           = "org.unikraft.kernel.plat"
	AnnotationFilesystemPath       = "org.unikraft.filesystem"
	AnnotationDiskIndexPathPattern = "org.unikraft.disk-%d"
	AnnotationKraftKitVersion      = "sh.kraftkit.version"
)
View Source 
const (
	MediaTypeLayer       = "application/vnd.unikraft.rootfs.diff"
	MediaTypeImageKernel = "application/vnd.unikraft.image.v1"
	MediaTypeInitrdCpio  = "application/vnd.unikraft.initrd.v1"
	MediaTypeConfig      = "application/vnd.unikraft.config.v1"

	MediaTypeLayerGzip       = MediaTypeLayer + "+gzip"
	MediaTypeImageKernelGzip = MediaTypeImageKernel + "+gzip"
	MediaTypeInitrdCpioGzip  = MediaTypeInitrdCpio + "+gzip"
	MediaTypeConfigGzip      = MediaTypeConfig + "+gzip"
)
View Source 
const (
	DefaultRegistry  = "unikraft.org"
	DefaultNamespace = "default"
	DefaultTag       = "latest"
)
View Source 
const (
	WellKnownKernelPath      = "/unikraft/bin/kernel"
	WellKnownKernelDbgPath   = "/unikraft/bin/kernel.dbg"
	WellKnownInitrdPath      = "/unikraft/bin/initrd"
	WellKnownConfigPath      = "/unikraft/bin/config"
	WellKnownKernelSourceDir = "/unikraft/src"
	WellKnownAppSourceDir    = "/unikraft/app"
)
View Source 
const ConfigFilename = "config.json"
View Source 
const OCIFormat pack.PackageFormat = "oci"

Variables

This section is empty.

Functions

func FromGoogleV1DescriptorToOCISpec added in v0.7.0 

func FromGoogleV1DescriptorToOCISpec(from ...v1.Descriptor) []ocispec.Descriptor

Convert github.com/google/go-containerregistry/pkg/v1.Descriptor to github.com/opencontainers/image-spec/specs-go/v1.Descriptor

func FromGoogleV1IndexImageToOCISpec added in v0.7.0 

func FromGoogleV1IndexImageToOCISpec(from v1.ImageIndex) (*ocispec.Index, error)

Convert github.com/google/go-containerregistry/pkg/v1.IndexImage to github.com/opencontainers/image-spec/specs-go/v1.Index

func FromGoogleV1IndexManifestToOCISpec added in v0.7.0 

func FromGoogleV1IndexManifestToOCISpec(from v1.IndexManifest) (*ocispec.Index, error)

Convert github.com/google/go-containerregistry/pkg/v1.IndexManifest to github.com/opencontainers/image-spec/specs-go/v1.Index

func FromGoogleV1PlatformToOCISpec added in v0.7.0 

func FromGoogleV1PlatformToOCISpec(from *v1.Platform) *ocispec.Platform

Convert github.com/google/go-containerregistry/pkg/v1.Platform to github.com/opencontainers/image-spec/specs-go/v1.Platform

func IsOCIDescriptorKraftKitCompatible added in v0.7.0 

func IsOCIDescriptorKraftKitCompatible(descriptor *ocispec.Descriptor) (bool, error)

IsOCIDescriptorKraftKitCompatible is a utility method that is used to determine whether the provided OCI Specification Descriptor structure is compatible with KraftKit. Ultimately, this is achieved by testing whether the annotation "sh.kraftkit.version" has been set. The value of this annotation is discarded.

func IsOCIIndexKraftKitCompatible added in v0.7.0 

func IsOCIIndexKraftKitCompatible(index *ocispec.Index) (bool, error)

IsOCIIndexKraftKitCompatible is a utility method that is used to determine whether the provided OCI Specification Index structure is compatible with KraftKit. Ultimately, this is achieved by testing whether the annotation "sh.kraftkit.version" has been set. The value of this annotation is discarded.

func IsOCIManifestKraftKitCompatible added in v0.7.0 

func IsOCIManifestKraftKitCompatible(manifest *ocispec.Manifest) (bool, error)

IsOCIManifestKraftKitCompatible is a utility method that is used to determine whether the provided OCI Specification Manifest structure is compatible with KraftKit. Ultimately, this is achieved by testing whether the annotation "sh.kraftkit.version" has been set. The value of this annotation is discarded.

func NewOCIManager 

func NewOCIManager(ctx context.Context, opts ...any) (packmanager.PackageManager, error)

NewOCIManager instantiates a new package manager based on OCI archives.

func NewPackageFromOCIManifestDigest added in v0.7.0 

func NewPackageFromOCIManifestDigest(ctx context.Context, handle handler.Handler, ref string, auths map[string]config.AuthConfig, dgst digest.Digest) (pack.Package, error)

NewPackageFromOCIManifestDigest is a constructor method which instantiates a package based on the OCI format based on a provided OCI Image manifest digest.

func NewPackageFromTarget 

func NewPackageFromTarget(ctx context.Context, targ target.Target, opts ...packmanager.PackOption) (pack.Package, error)

NewPackageFromTarget generates an OCI implementation of the pack.Package construct based on an input Application and options.

func RegisterPackageManager added in v0.6.7 

func RegisterPackageManager() func(u *packmanager.UmbrellaManager) error

Types

type Blob 

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

func NewBlob 

func NewBlob(_ context.Context, mediaType string, data []byte, opts ...BlobOption) (*Blob, error)

NewBlob generates an OCI blob based on input byte array for a given media type.

func NewBlobFromFile 

func NewBlobFromFile(_ context.Context, mediaType string, filePath string, opts ...BlobOption) (*Blob, error)

NewBlobFromFile generates an OCI blob based on an input file for a given media type

type BlobOption 

type BlobOption func(*Blob) error

func WithBlobPlatform 

func WithBlobPlatform(platform *ocispec.Platform) BlobOption

WithBlobPlatform specifies platform attribution such that the later queries to the blob store which include platform specification only return those with the set parameters.

func WithBlobRemoveAfterSave 

func WithBlobRemoveAfterSave(removeAfterSave bool) BlobOption

WithBlobRemoveAfterSave atomizes each operation on the blob.

type Index added in v0.7.0 

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

func NewIndex added in v0.7.0 

func NewIndex(_ context.Context, handle handler.Handler) (*Index, error)

NewIndex instantiates a new index using the provided handler.

func NewIndexFromRef added in v0.7.0 

func NewIndexFromRef(ctx context.Context, handle handler.Handler, ref string) (*Index, error)

NewIndexFromRef instantiates a new index using the provided reference which is used by the handle to look up any local existing indexes.

func NewIndexFromSpec added in v0.7.0 

func NewIndexFromSpec(ctx context.Context, handle handler.Handler, spec *ocispec.Index) (*Index, error)

NewIndexFromSpec instantiates a new index using the provided handler as well as a reference

func (*Index) AddManifest added in v0.7.0 

func (index *Index) AddManifest(_ context.Context, manifest *Manifest) error

AddManifest adds a manifest based an previously instantiated Manifest structure.

func (*Index) Annotations added in v0.7.0 

func (index *Index) Annotations() map[string]string

Annotations returns the map of annotations for the index.

func (*Index) Descriptor added in v0.7.0 

func (index *Index) Descriptor() (*ocispec.Descriptor, error)

IndexDesc returns the descriptor of the index.

func (*Index) Save added in v0.7.0 

func (index *Index) Save(ctx context.Context, fullref string, onProgress func(float64)) (ocispec.Descriptor, error)

Save the index.

func (*Index) SetAnnotation added in v0.7.0 

func (index *Index) SetAnnotation(_ context.Context, key, val string)

SetAnnotation sets an anootation of the image with the provided key.

type Layer 

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

func NewLayerFromFile 

func NewLayerFromFile(ctx context.Context, mediaType, src, dst string, opts ...LayerOption) (*Layer, error)

NewLayerFromFile creates a new layer from a given blob

type LayerOption 

type LayerOption func(*Layer) error

func WithLayerAnnotation 

func WithLayerAnnotation(key, val string) LayerOption

WithLayerAnnotation sets an annotation for a particular layer

type Manifest added in v0.7.0 

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

func NewManifest added in v0.7.0 

func NewManifest(ctx context.Context, handle handler.Handler) (*Manifest, error)

NewManifest instantiates a new image based in a handler and any provided options.

func NewManifestFromDigest added in v0.7.0 

func NewManifestFromDigest(ctx context.Context, handle handler.Handler, digest digest.Digest) (*Manifest, error)

NewManifestFromDigest instantiates a new Manifest structure from a given digest.

func NewManifestFromSpec added in v0.7.0 

func NewManifestFromSpec(ctx context.Context, handle handler.Handler, spec ocispec.Manifest) (*Manifest, error)

func (*Manifest) AddBlob added in v0.7.0 

func (manifest *Manifest) AddBlob(ctx context.Context, blob *Blob) (ocispec.Descriptor, error)

AddBlob adds a blog to the manifest and returns the resulting descriptor.

func (*Manifest) AddLayer added in v0.7.0 

func (manifest *Manifest) AddLayer(ctx context.Context, layer *Layer) (ocispec.Descriptor, error)

AddLayer adds a layer directly to the image and returns the resulting descriptor.

func (*Manifest) Layers added in v0.7.0 

func (manifest *Manifest) Layers() []*Layer

Layers returns the layers of this OCI image.

func (*Manifest) Save added in v0.7.0 

func (manifest *Manifest) Save(ctx context.Context, fullref string, onProgress func(float64)) (*ocispec.Descriptor, error)

Save the image.

func (*Manifest) SetAnnotation added in v0.7.0 

func (manifest *Manifest) SetAnnotation(_ context.Context, key, val string)

SetAnnotation sets an anootation of the image with the provided key.

func (*Manifest) SetArchitecture added in v0.7.0 

func (manifest *Manifest) SetArchitecture(_ context.Context, architecture string)

SetArchitecture sets the architecture of the image.

func (*Manifest) SetCmd added in v0.7.0 

func (manifest *Manifest) SetCmd(_ context.Context, cmd []string)

Set the command of the image.

func (*Manifest) SetEnv added in v0.8.3 

func (manifest *Manifest) SetEnv(_ context.Context, env []string)

Set the environment variables of the image.

func (*Manifest) SetLabel added in v0.7.0 

func (manifest *Manifest) SetLabel(_ context.Context, key, val string)

SetLabel sets a label of the image with the provided key.

func (*Manifest) SetOS added in v0.7.0 

func (manifest *Manifest) SetOS(_ context.Context, os string)

SetOS sets the OS of the image.

func (*Manifest) SetOSFeature added in v0.7.0 

func (manifest *Manifest) SetOSFeature(_ context.Context, feature ...string)

SetOSFeature sets any OS features of the image.

func (*Manifest) SetOSVersion added in v0.7.0 

func (manifest *Manifest) SetOSVersion(_ context.Context, osversion string)

SetOSVersion sets the version of the OS of the image.

type OCIManagerOption added in v0.6.0 

type OCIManagerOption func(context.Context, *ociManager) error

func WithContainerd added in v0.6.0 

func WithContainerd(ctx context.Context, addr, namespace string) OCIManagerOption

WithContainerd forces the use of a containerd handler by providing an address to the containerd daemon (whether UNIX socket or TCP socket) as well as the default namespace to operate within.

func WithDefaultAuth added in v0.6.0 

func WithDefaultAuth() OCIManagerOption

WithDefaultAuth uses the KraftKit-set configuration for authentication against remote registries.

func WithDefaultRegistries added in v0.6.0 

func WithDefaultRegistries() OCIManagerOption

WithDefaultRegistries sets the list of KraftKit-set registries which is defined through its configuration.

func WithDetectHandler added in v0.6.0 

func WithDetectHandler() OCIManagerOption

WithDetectHandler uses internal KraftKit configuration to determine which underlying OCI handler implementation should be used. Ultimately, this is done by checking whether set configuration can ultimately invoke a relative client to enable the handler.

func WithDirectory added in v0.7.0 

func WithDirectory(ctx context.Context, path string) OCIManagerOption

WithDirectory forces the use of a directory handler by providing a path to the directory to use as the OCI root.

func WithDockerConfig added in v0.6.0 

func WithDockerConfig(auth regtypes.AuthConfig) OCIManagerOption

WithDockerConfig sets the authentication configuration to use when making calls to authenticated registries.

func WithRegistries added in v0.6.0 

func WithRegistries(registries ...string) OCIManagerOption

WithRegistries sets the list of registries to use when making calls to non-canonically named OCI references.

Source Files

View all Source files

Directories

Path Synopsis
SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2024, Unikraft GmbH and The KraftKit Authors.
 SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2024, Unikraft GmbH and The KraftKit Authors.
SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors.
 SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022, Unikraft GmbH and The KraftKit Authors.
Package simpleauth implements a basic pass-by-reference of credentials for the authn.Authenticator interface.
 Package simpleauth implements a basic pass-by-reference of credentials for the authn.Authenticator interface.

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.