bundle

package
v0.2509.0 Latest Latest
Warning

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

 Go to latest Published: Nov 28, 2025 License: Apache-2.0 Imports: 32 Imported by: 7

Documentation

Overview

Package bundle implements support for unified runtime bundles.

Index

Constants

View Source 
const (
	// GPUNvidiaH100 is the NVIDIA H100 GPU.
	GPUNvidiaH100 = "nvidia-h100"
	// GPUNvidiaH200 is the NVIDIA H200 GPU.
	GPUNvidiaH200 = "nvidia-h200"
)
View Source 
const CfgDebugMockIDs = "runtime.debug.mock_ids"

CfgDebugMockIDs configures mock runtime IDs for the purpose of testing.

View Source 
const FileExtension = ".orc"

FileExtension is the file extension used for storing the bundle.

View Source 
const LabelOrigin = "net.oasis.origin"

LabelOrigin is the name of the special origin label assigned by the host which contains the origin of the bundle.

Variables

View Source 
var Flags = flag.NewFlagSet("", flag.ContinueOnError)

Flags has the configuration flags.

Functions

func ExplodedPath 

func ExplodedPath(dataDir string) string

ExplodedPath returns the path under the data directory that contains all of the exploded bundles.

func HashAllData added in v0.2403.0 

func HashAllData(d Data) (hash.Hash, error)

HashAllData hashes all of the underlying data and returns the hash.

func ReadAllData added in v0.2403.0 

func ReadAllData(d Data) ([]byte, error)

ReadAllData reads all of the underlying data into a buffer and returns it.

func TmpBundlePath added in v0.2502.0 

func TmpBundlePath(dataDir string) string

TmpBundlePath returns the path under the data directory that contains all of the temporary bundles.

Types

type AddOption added in v0.2502.0 

type AddOption func(o *AddOptions)

AddOption is an option used when adding a bundle.

func WithBundleLabels added in v0.2502.0 

func WithBundleLabels(labels map[string]string) AddOption

WithBundleLabels sets the bundle labels.

func WithBundleManifestHash added in v0.2502.0 

func WithBundleManifestHash(h hash.Hash) AddOption

WithBundleManifestHash sets the manifest hash to validate when adding a bundle.

func WithBundleValidator added in v0.2502.0 

func WithBundleValidator(f ValidatorFunc) AddOption

WithBundleValidator sets the bundle validator function.

func WithBundleVolumes added in v0.2502.0 

func WithBundleVolumes(volumes map[string]*volume.Volume) AddOption

WithBundleVolumes sets the bundle volumes to attach.

func WithManifestRewriter added in v0.2502.0 

func WithManifestRewriter(f ManifestRewriterFunc) AddOption

WithManifestRewriter sets the manifest rewriter function.

type AddOptions added in v0.2502.0 

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

AddOptions are options for adding bundles.

func NewAddOptions added in v0.2502.0 

func NewAddOptions(opts ...AddOption) *AddOptions

NewAddOptions creates options using default and given values.

type Bundle 

type Bundle struct {
	Manifest *Manifest
	Data     map[string]Data
	// contains filtered or unexported fields
}

Bundle is a runtime bundle instance.

func Open 

func Open(fn string, opts ...OpenOption) (_ *Bundle, err error)

Open opens and validates a runtime bundle instance.

func (*Bundle) Add 

func (bnd *Bundle) Add(fn string, data Data) error

Add adds/overwrites a file to/in the bundle.

func (*Bundle) Close 

func (bnd *Bundle) Close() error

Close closes the bundle, releasing resources.

func (*Bundle) EnclaveIdentities added in v0.2500.0 

func (bnd *Bundle) EnclaveIdentities(id component.ID) ([]sgx.EnclaveIdentity, error)

EnclaveIdentities returns the enclave identities of the given component.

func (*Bundle) EnclaveIdentity deprecated added in v0.2400.0 

func (bnd *Bundle) EnclaveIdentity(id component.ID) (*sgx.EnclaveIdentity, error)

EnclaveIdentity returns the enclave identity of the given component.

Deprecated: Use EnclaveIdentities instead.

func (*Bundle) ExplodedPath 

func (bnd *Bundle) ExplodedPath(dataDir string) string

ExplodedPath returns the path under the data directory that contains the exploded bundle assets.

func (*Bundle) GenerateFilename added in v0.2500.0 

func (bnd *Bundle) GenerateFilename() string

GenerateFilename returns the recommended filename for storing the bundle.

func (*Bundle) MrEnclave 

func (bnd *Bundle) MrEnclave(id component.ID) (*sgx.MrEnclave, error)

MrEnclave returns the MRENCLAVE of the SGX excutable.

func (*Bundle) MrSigner added in v0.2400.0 

func (bnd *Bundle) MrSigner(id component.ID) (*sgx.MrSigner, error)

MrSigner returns the MRSIGNER that signed the SGX executable.

func (*Bundle) ResetManifest added in v0.2201.9 

func (bnd *Bundle) ResetManifest()

ResetManifest removes the serialized manifest from the bundle so that it can be regenerated on the next call to Write.

This needs to be used after doing modifications to bundles.

func (*Bundle) Rewrite added in v0.2502.0 

func (bnd *Bundle) Rewrite(manifestRewriter ManifestRewriterFunc)

Rewrite invokes the passed manifest rewriter function to rewrite the manifest then reserializes it and recomputes its hash.

Passing a nil rewriter will result in no changes to the manifest.

Note that this can result in generating a malformed manifest.

func (*Bundle) Validate 

func (bnd *Bundle) Validate() error

Validate validates the runtime bundle for well-formedness.

func (*Bundle) Write 

func (bnd *Bundle) Write(fn string) error

Write serializes a runtime bundle to the on-disk representation.

func (*Bundle) WriteExploded 

func (bnd *Bundle) WriteExploded(dir string) error

WriteExploded extracts the runtime bundle to the given directory.

type Component added in v0.2400.0 

type Component struct {
	// Kind is the component kind.
	Kind component.Kind `json:"kind"`

	// Name is the name of the component that can be used to filter components when multiple are
	// provided by a runtime.
	Name string `json:"name,omitempty"`

	// Version is the component version.
	Version version.Version `json:"version,omitempty"`

	// Executable is the name of the runtime ELF executable file if any.
	// NOTE: This may go away in the future, use `ELF` instead.
	Executable string `json:"executable,omitempty"`

	// ELF is the ELF specific manifest metadata if any.
	ELF *ELFMetadata `json:"elf,omitempty"`

	// SGX is the SGX specific manifest metadata if any.
	SGX *SGXMetadata `json:"sgx,omitempty"`

	// TDX is the TDX specific manifest metadata if any.
	TDX *TDXMetadata `json:"tdx,omitempty"`

	// Identities are the (optional) expected enclave identities. When not provided, it must be
	// computed at runtime. In the future, this field will become required.
	//
	// Multiple identities may be provided because they can differ across different deployment
	// systems (e.g. hypervisors).
	Identities []Identity `json:"identity,omitempty"`

	// Disabled specifies whether the component is disabled by default and needs to be explicitly
	// enabled via node configuration to be used.
	Disabled bool `json:"disabled,omitempty"`
}

Component is a runtime component.

func (*Component) ID added in v0.2400.0 

func (c *Component) ID() component.ID

ID returns this component's identifier.

func (*Component) IsNetworkAllowed added in v0.2400.0 

func (c *Component) IsNetworkAllowed() bool

IsNetworkAllowed returns true if network access should be allowed for the component.

func (*Component) Matches added in v0.2400.0 

func (c *Component) Matches(id component.ID) bool

Matches returns true iff the component matches the given component ID.

func (*Component) RequiredVolumeNames added in v0.2502.0 

func (c *Component) RequiredVolumeNames() []string

RequiredVolumeNames returns a list of required volume names for this component.

func (*Component) TEEKind added in v0.2403.0 

func (c *Component) TEEKind() component.TEEKind

TEEKind returns the kind of TEE supported by the component.

func (*Component) Validate added in v0.2400.0 

func (c *Component) Validate() error

Validate validates the component structure for well-formedness.

type ComponentNotification added in v0.2502.0 

type ComponentNotification struct {
	// Added is set when the given component has been added.
	Added *ExplodedComponent
	// Removed is set when the given component has been removed.
	Removed *component.ID
}

ComponentNotification is a component notification.

type Data added in v0.2403.0 

type Data interface {
	// Open returns an io.ReadCloser that can be used to access the underlying data.
	Open() (io.ReadCloser, error)
}

Data is a data item in the bundle.

func NewBytesData added in v0.2403.0 

func NewBytesData(b []byte) Data

NewBytesData creates a new Data instance from the given byte slice. The slice is not copied.

func NewFileData added in v0.2403.0 

func NewFileData(fn string) Data

NewFileData creates a new Data instance that opens and reads the given file path.

type ELFMetadata added in v0.2500.0 

type ELFMetadata struct {
	// Executable is the name of the ELF executable file.
	Executable string `json:"executable"`
}

ELFMetadata is the ELF specific manifest metadata.

func (*ELFMetadata) Validate added in v0.2500.0 

func (e *ELFMetadata) Validate() error

Validate validates the ELF metadata structure for well-formedness.

type ExplodedComponent added in v0.2500.0 

type ExplodedComponent struct {
	*Component

	// TEEKind specifies the kind of Trusted Execution Environment (TEE)
	// in which the component should run.
	TEEKind component.TEEKind

	// Detached is true iff the bundle containing the component does not
	// include a RONL component.
	Detached bool

	// ExplodedDataDir is the path to the data directory where the bundle
	// containing the component has been extracted.
	ExplodedDataDir string

	// Labels are labels attached to this exploded component.
	Labels map[string]string

	// Volumes are the volumes attached to this exploded component.
	Volumes map[string]*volume.Volume
}

ExplodedComponent is an exploded runtime component ready for execution.

func (*ExplodedComponent) ExplodedPath added in v0.2500.0 

func (c *ExplodedComponent) ExplodedPath(fn string) string

ExplodedPath returns the path that the corresponding asset will be written to via WriteExploded.

type ExplodedManifest added in v0.2500.0 

type ExplodedManifest struct {
	*Manifest

	// ExplodedDataDir is the path to the data directory where the bundle
	// represented by manifest has been extracted.
	ExplodedDataDir string

	// Labels are labels attached to the manifest by the registry.
	Labels map[string]string

	// Volumes are the volumes attached to this exploded manifest.
	Volumes map[string]*volume.Volume
}

ExplodedManifest is manifest with corresponding exploded bundle dir.

func (*ExplodedManifest) HasLabels added in v0.2502.0 

func (m *ExplodedManifest) HasLabels(labels map[string]string) bool

HasLabels returns true iff the exploded manifest has all of the given labels set.

func (*ExplodedManifest) ValidateVolumes added in v0.2502.0 

func (m *ExplodedManifest) ValidateVolumes() error

ValidateVolumes validates that the exploded manifest has all of the required volumes present.

type GPUResource added in v0.2500.0 

type GPUResource struct {
	// Model is the GPU model. It may be omitted to specify that the model is not important.
	Model string `json:"model,omitempty"`
	// Count is the number of GPUs requested.
	Count uint8 `json:"count"`
}

GPUResource is the GPU resource descriptor.

func (*GPUResource) Validate added in v0.2500.0 

func (g *GPUResource) Validate() error

Validate validates the GPU resource.

type Identity added in v0.2500.0 

type Identity struct {
	// Hypervisor is the optional hypervisor this identity is for.
	Hypervisor string `json:"hypervisor,omitempty"`

	// Enclave is the enclave identity.
	Enclave sgx.EnclaveIdentity `json:"enclave"`
}

Identity is the cryptographic identity of a component.

type Manager added in v0.2500.0 

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

Manager is responsible for managing bundles.

func NewManager added in v0.2500.0 

func NewManager(dataDir string, runtimeIDs []common.Namespace, store ManifestStore, volumeManager VolumeManager) (*Manager, error)

NewManager creates a new bundle manager.

func (*Manager) Add added in v0.2500.0 

func (m *Manager) Add(path string, opts ...AddOption) error

Add adds a bundle from the given path.

func (*Manager) AddTemporary added in v0.2502.0 

func (m *Manager) AddTemporary(tmpPath string, opts ...AddOption) error

AddTemporary adds a bundle from the given temporary bundle file.

func (*Manager) Cleanup added in v0.2500.0 

func (m *Manager) Cleanup(runtimeID common.Namespace, version version.Version)

Cleanup updates the runtime's maximum bundle version for pending clean-up.

If the specified runtime already exists in the cleanup queue, its version is updated only if the provided versions is greater.

Warning: If clean-up fails it's not retried.

func (*Manager) Download added in v0.2500.0 

func (m *Manager) Download(runtimeID common.Namespace, manifestHashes []hash.Hash)

Download updates the checksums of bundles pending download for the given runtime.

Any existing checksums in the download queue for the given runtime are removed and replaced with the given ones.

func (*Manager) Remove added in v0.2502.0 

func (m *Manager) Remove(labels map[string]string)

Remove removes bundles matching the given labels.

func (*Manager) RemoveTemporary added in v0.2502.0 

func (m *Manager) RemoveTemporary(tmpPath string) error

RemoveTemporary removes the given temporary bundle file.

func (*Manager) Start added in v0.2500.0 

func (m *Manager) Start()

Start starts the bundle manager.

func (*Manager) Stop added in v0.2500.0 

func (m *Manager) Stop()

Stop halts the bundle manager.

func (*Manager) WriteTemporary added in v0.2502.0 

func (m *Manager) WriteTemporary(tmpPath string, create bool, data []byte) error

WriteTemporary writes the given data to a temporary file that can later be referenced as a bundle.

type Manifest 

type Manifest struct {
	// Name is the optional human readable runtime name.
	Name string `json:"name,omitempty"`

	// ID is the runtime identifier.
	ID common.Namespace `json:"id"`

	// Version is the runtime version.
	// NOTE: This may go away in the future, use `Component.Version` instead.
	Version version.Version `json:"version,omitempty"`

	// Executable is the name of the runtime ELF executable file.
	// NOTE: This may go away in the future, use `Components` instead.
	Executable string `json:"executable,omitempty"`

	// SGX is the SGX specific manifest metadata if any.
	// NOTE: This may go away in the future, use `Components` instead.
	SGX *SGXMetadata `json:"sgx,omitempty"`

	// Components are the additional runtime components.
	Components []*Component `json:"components,omitempty"`

	// Digests is the cryptographic digests of the bundle contents,
	// excluding the manifest.
	Digests map[string]hash.Hash `json:"digests"`
}

Manifest is a deserialized runtime bundle manifest.

func (*Manifest) GetAvailableComponents added in v0.2400.0 

func (m *Manifest) GetAvailableComponents() map[component.ID]*Component

GetAvailableComponents collects all of the available components into a map.

func (*Manifest) GetComponentByID added in v0.2400.0 

func (m *Manifest) GetComponentByID(id component.ID) (*Component, bool)

GetComponentByID returns the first component with the given kind.

func (*Manifest) Hash added in v0.2401.0 

func (m *Manifest) Hash() hash.Hash

Hash returns a cryptographic hash of the CBOR-serialized manifest.

func (*Manifest) IsDetached added in v0.2401.0 

func (m *Manifest) IsDetached() bool

IsDetached returns true iff the manifest does not include a RONL component. Such bundles require that the RONL component is provided out-of-band (e.g. in a separate bundle).

func (*Manifest) IsLegacy added in v0.2403.0 

func (m *Manifest) IsLegacy() bool

IsLegacy returns true iff this is a legacy manifest that defines executables at the top level.

func (*Manifest) UnmarshalJSON added in v0.2500.0 

func (m *Manifest) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON customizes the unmarshalling of the manifest.

func (*Manifest) Validate added in v0.2400.0 

func (m *Manifest) Validate() error

Validate validates the manifest structure for well-formedness.

type ManifestRewriterFunc added in v0.2502.0 

type ManifestRewriterFunc func(*Manifest)

ManifestRewriterFunc is a function which is passed the manifest for modification.

type ManifestStore added in v0.2500.0 

type ManifestStore interface {
	// HasManifest returns true iff the store already contains an exploded manifest
	// with the given hash.
	HasManifest(hash hash.Hash) bool

	// AddManifest adds the provided exploded manifest to the store.
	AddManifest(manifest *ExplodedManifest) error

	// RemoveManifest removes an exploded manifest with provided hash.
	RemoveManifest(hash hash.Hash) bool

	// RemoveManifestsWithLabels removes all manifests matching the provided labels.
	//
	// Returns the number of removed manifests.
	RemoveManifestsWithLabels(labels map[string]string) int

	// Manifests returns all known exploded manifests.
	Manifests() []*ExplodedManifest
}

ManifestStore is an interface that defines methods for storing exploded manifests.

type OpenOption added in v0.2500.0 

type OpenOption func(o *OpenOptions)

OpenOption is an option used when opening a bundle file.

func WithManifestHash added in v0.2500.0 

func WithManifestHash(manifestHash hash.Hash) OpenOption

WithManifestHash sets the manifest hash for verification.

type OpenOptions added in v0.2500.0 

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

OpenOptions are options for opening bundle files.

func NewOpenOptions added in v0.2500.0 

func NewOpenOptions(opts ...OpenOption) *OpenOptions

NewOpenOptions creates options using default and given values.

type Registry added in v0.2500.0 

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

Registry is a registry of manifests and components.

func NewRegistry added in v0.2500.0 

func NewRegistry() *Registry

NewRegistry creates a new registry of manifests and components.

func (*Registry) AddManifest added in v0.2500.0 

func (r *Registry) AddManifest(manifest *ExplodedManifest) error

AddManifest adds the provided exploded manifest to the store.

func (*Registry) Components added in v0.2500.0 

func (r *Registry) Components(runtimeID common.Namespace) []*ExplodedComponent

Components returns all components for the given runtime.

func (*Registry) GetVersions added in v0.2500.0 

func (r *Registry) GetVersions(runtimeID common.Namespace) []version.Version

GetVersions returns versions for the given runtime, sorted in ascending order.

func (*Registry) HasManifest added in v0.2500.0 

func (r *Registry) HasManifest(hash hash.Hash) bool

HasManifest returns true iff the store already contains a manifest with the given hash.

func (*Registry) Manifests added in v0.2500.0 

func (r *Registry) Manifests() []*ExplodedManifest

Manifests returns all known manifests.

func (*Registry) ManifestsWithLabels added in v0.2502.0 

func (r *Registry) ManifestsWithLabels(labels map[string]string) []*ExplodedManifest

ManifestsWithLabels returns all manifests that have the specified labels set.

func (*Registry) RemoveManifest added in v0.2500.0 

func (r *Registry) RemoveManifest(hash hash.Hash) bool

RemoveManifest removes a manifest with provided hash.

func (*Registry) RemoveManifestsWithLabels added in v0.2502.0 

func (r *Registry) RemoveManifestsWithLabels(labels map[string]string) int

RemoveManifestsWithLabels removes all manifests matching the provided labels.

Returns the number of removed manifests.

func (*Registry) WatchComponents added in v0.2500.0 

func (r *Registry) WatchComponents(runtimeID common.Namespace) (<-chan *ComponentNotification, *pubsub.Subscription)

WatchComponents provides a channel that streams runtime components as they are added to the registry.

type SGXMetadata 

type SGXMetadata struct {
	// Executable is the name of the SGX enclave executable file.
	Executable string `json:"executable"`

	// Signature is the name of the SGX enclave signature file.
	Signature string `json:"signature"`
}

SGXMetadata is the SGX specific manifest metadata.

func (*SGXMetadata) Validate added in v0.2400.0 

func (s *SGXMetadata) Validate() error

Validate validates the SGX metadata structure for well-formedness.

type TDXMetadata added in v0.2403.0 

type TDXMetadata struct {
	// Firmware is the name of the virtual firmware file. It should rarely change and multiple
	// components may use the same firmware.
	Firmware string `json:"firmware"`
	// Kernel is the name of the kernel image file. It should rarely change and multiple components
	// may use the same kernel.
	Kernel string `json:"kernel,omitempty"`
	// InitRD is the name of the initial RAM disk image file. It should rarely change and multiple
	// components may use the same initrd.
	InitRD string `json:"initrd,omitempty"`
	// ExtraKernelOptions are the extra kernel options to pass to the kernel after any of the
	// default options. Note that kernel options affect TD measurements.
	ExtraKernelOptions []string `json:"extra_kernel_options,omitempty"`

	// Stage2Image is the name of the stage 2 VM image file.
	Stage2Image string `json:"stage2_image,omitempty"`
	// Stage2Format is the format of the stage 2 VM image file. Empty means raw.
	Stage2Format string `json:"stage2_format,omitempty"`
	// Stage2Persist is the flag specifying whether the modifications to stage 2 image file should
	// be (locally) persisted across TD restarts.
	Stage2Persist bool `json:"stage2_persist,omitempty"`

	// Resources are the requested VM resources.
	Resources TDXResources `json:"resources"`
}

TDXMetadata is the TDX specific manifest metadata.

Note that changes to these fields may change the TD measurements.

func (*TDXMetadata) HasInitRD added in v0.2403.0 

func (t *TDXMetadata) HasInitRD() bool

HasInitRD returns true iff the TDX metadata indicates there is an initial RAM disk image present.

func (*TDXMetadata) HasKernel added in v0.2403.0 

func (t *TDXMetadata) HasKernel() bool

HasKernel returns true iff the TDX metadata indicates there is a kernel present.

func (*TDXMetadata) HasStage2 added in v0.2403.0 

func (t *TDXMetadata) HasStage2() bool

HasStage2 returns true iff the TDX metadata indicates there is a stage 2 image present.

func (*TDXMetadata) Validate added in v0.2403.0 

func (t *TDXMetadata) Validate() error

Validate validates the TDX metadata structure for well-formedness.

type TDXResources added in v0.2403.0 

type TDXResources struct {
	// Memory is the requested VM memory amount in megabytes.
	Memory uint64 `json:"memory"`
	// CPUCount is the requested number of vCPUs.
	CPUCount uint8 `json:"cpus"`
	// GPU is the optional GPU resource configuration.
	GPU *GPUResource `json:"gpu,omitempty"`
}

TDXResources are the requested VM resources for TDX VMs.

Note that changes to these fields may change the TD measurements.

func (*TDXResources) Validate added in v0.2403.0 

func (r *TDXResources) Validate() error

Validate validates the VM resources.

type ValidatorFunc added in v0.2502.0 

type ValidatorFunc func(*Bundle) error

ValidatorFunc is a function that validates a bundle.

type VolumeManager added in v0.2502.0 

type VolumeManager interface {
	// GetOrCreate retrieves the first volume matching given labels or creates a new one.
	GetOrCreate(labels map[string]string) (*volume.Volume, error)
}

VolumeManager is an interface that defines methods for managing volumes.

Source Files

View all Source files

Directories

Path Synopsis
Package component contains types for runtime components.
 Package component contains types for runtime components.

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.