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
- func FromGoogleV1DescriptorToOCISpec(from ...v1.Descriptor) []ocispec.Descriptor
- func FromGoogleV1IndexImageToOCISpec(from v1.ImageIndex) (*ocispec.Index, error)
- func FromGoogleV1IndexManifestToOCISpec(from v1.IndexManifest) (*ocispec.Index, error)
- func FromGoogleV1PlatformToOCISpec(from *v1.Platform) *ocispec.Platform
- func IsOCIDescriptorKraftKitCompatible(descriptor *ocispec.Descriptor) (bool, error)
- func IsOCIIndexKraftKitCompatible(index *ocispec.Index) (bool, error)
- func IsOCIManifestKraftKitCompatible(manifest *ocispec.Manifest) (bool, error)
- func NewOCIManager(ctx context.Context, opts ...any) (packmanager.PackageManager, error)
- func NewPackageFromOCIManifestDigest(ctx context.Context, handle handler.Handler, ref string, ...) (pack.Package, error)
- func NewPackageFromTarget(ctx context.Context, targ target.Target, opts ...packmanager.PackOption) (pack.Package, error)
- func RegisterPackageManager() func(u *packmanager.UmbrellaManager) error
- type Blob
- type BlobOption
- type Index
- func (index *Index) AddManifest(_ context.Context, manifest *Manifest) error
- func (index *Index) Annotations() map[string]string
- func (index *Index) Descriptor() (*ocispec.Descriptor, error)
- func (index *Index) Save(ctx context.Context, fullref string, onProgress func(float64)) (ocispec.Descriptor, error)
- func (index *Index) SetAnnotation(_ context.Context, key, val string)
- type Layer
- type LayerOption
- type Manifest
- func NewManifest(ctx context.Context, handle handler.Handler) (*Manifest, error)
- func NewManifestFromDigest(ctx context.Context, handle handler.Handler, digest digest.Digest) (*Manifest, error)
- func NewManifestFromSpec(ctx context.Context, handle handler.Handler, spec ocispec.Manifest) (*Manifest, error)
- func (manifest *Manifest) AddBlob(ctx context.Context, blob *Blob) (ocispec.Descriptor, error)
- func (manifest *Manifest) AddLayer(ctx context.Context, layer *Layer) (ocispec.Descriptor, error)
- func (manifest *Manifest) Layers() []*Layer
- func (manifest *Manifest) Save(ctx context.Context, fullref string, onProgress func(float64)) (*ocispec.Descriptor, error)
- func (manifest *Manifest) SetAnnotation(_ context.Context, key, val string)
- func (manifest *Manifest) SetArchitecture(_ context.Context, architecture string)
- func (manifest *Manifest) SetCmd(_ context.Context, cmd []string)
- func (manifest *Manifest) SetLabel(_ context.Context, key, val string)
- func (manifest *Manifest) SetOS(_ context.Context, os string)
- func (manifest *Manifest) SetOSFeature(_ context.Context, feature ...string)
- func (manifest *Manifest) SetOSVersion(_ context.Context, osversion string)
- type OCIManagerOption
- func WithContainerd(ctx context.Context, addr, namespace string) OCIManagerOption
- func WithDefaultAuth() OCIManagerOption
- func WithDefaultRegistries() OCIManagerOption
- func WithDetectHandler() OCIManagerOption
- func WithDirectory(ctx context.Context, path string) OCIManagerOption
- func WithDockerConfig(auth regtypes.AuthConfig) OCIManagerOption
- func WithRegistries(registries ...string) OCIManagerOption
Constants ¶
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" )
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" )
const ( DefaultRegistry = "unikraft.org" DefaultNamespace = "default" DefaultTag = "latest" )
const ( WellKnownKernelPath = "/unikraft/bin/kernel" WellKnownKernelDbgPath = "/unikraft/bin/kernel.dbg" WellKnownInitrdPath = "/unikraft/bin/initrd" WellKnownConfigPath = "/unikraft/bin/config" WellKnownKernelSourceDir = "/unikraft/src" WellKnownAppSourceDir = "/unikraft/app" )
const ConfigFilename = "config.json"
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
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
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
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 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 ¶
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 NewIndexFromRef ¶ added in v0.7.0
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
AddManifest adds a manifest based an previously instantiated Manifest structure.
func (*Index) Annotations ¶ added in v0.7.0
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.
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 ¶
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
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 (*Manifest) AddBlob ¶ added in v0.7.0
AddBlob adds a blog to the manifest and returns the resulting descriptor.
func (*Manifest) AddLayer ¶ added in v0.7.0
AddLayer adds a layer directly to the image and returns the resulting descriptor.
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
SetAnnotation sets an anootation of the image with the provided key.
func (*Manifest) SetArchitecture ¶ added in v0.7.0
SetArchitecture sets the architecture of the image.
func (*Manifest) SetLabel ¶ added in v0.7.0
SetLabel sets a label of the image with the provided key.
func (*Manifest) SetOSFeature ¶ added in v0.7.0
SetOSFeature sets any OS features of the image.
type OCIManagerOption ¶ added in v0.6.0
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 ¶
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. |