Help us shape the future of Go! Take the 2026 Go Developer Survey

cnab

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ActionInstall   = cnabclaims.ActionInstall
	ActionUpgrade   = cnabclaims.ActionUpgrade
	ActionUninstall = cnabclaims.ActionUninstall
	ActionUnknown   = cnabclaims.ActionUnknown
	// ActionValidate is the custom action of a nemo bundle that checks it
	// against the target, and changes nothing.
	ActionValidate = "validate"

	StatusSucceeded = cnabclaims.StatusSucceeded
	StatusCanceled  = cnabclaims.StatusCanceled
	StatusFailed    = cnabclaims.StatusFailed
	StatusRunning   = cnabclaims.StatusRunning
	StatusPending   = cnabclaims.StatusPending
	StatusUnknown   = cnabclaims.StatusUnknown

	OutputInvocationImageLogs = cnabclaims.OutputInvocationImageLogs
)
View Source 
const (
	// OfficialExtensionsPrefix is the prefix applied to extensions defined in the CNAB spec.
	OfficialExtensionsPrefix = "io.cnab."

	// NemoExtensionsPrefix is the prefix applied to nemo's own extensions.
	NemoExtensionsPrefix = "io.nemo."
)
View Source 
const (
	// ParameterOrchestrator is the orchestrator of the target: compose or
	// swarm. It is required: the installer never guesses it.
	ParameterOrchestrator = "nemo-orchestrator"
	// ParameterTimeout bounds the action, as a Go duration.
	ParameterTimeout = "nemo-timeout"
	// ParameterPurge also removes the volumes on uninstall.
	ParameterPurge = "nemo-purge"
	// ParameterVolumes holds the volume types of the target, as JSON.
	ParameterVolumes = "nemo-volumes"
	// ParameterRegistryAuth holds the credentials of the registries the
	// images are pulled from, by domain, as JSON. It is sensitive: the
	// runtime fills it from docker login and never stores it.
	ParameterRegistryAuth = "nemo-registry-auth"
)

Parameters a nemo bundle declares, so that a runtime, nemo's or Porter, delivers them to the installer like any CNAB parameter.

View Source 
const ComposeSchemaVersion = "1.0.0"

ComposeSchemaVersion is the version of the compose extension nemo writes.

View Source 
const RelocationMapFile = "/cnab/app/relocation-mapping.json"

RelocationMapFile is where a runtime mounts the relocation map in the invocation image (cnab-spec 103-bundle-runtime.md).

View Source 
const SupportedVersion = "1.0.0 || 1.1.0 || 1.2.0"

SupportedVersion is the range of bundle schema versions nemo reads.

Variables

View Source 
var (
	// RuntimeExtensions are the extensions the nemo runtime honours when a
	// bundle requires them.
	RuntimeExtensions = []ExtensionDefinition{
		DependenciesExtension,
		DockerExtension,
	}

	// InstallerExtensions are read by the installer, never by the runtime.
	// A bundle must not require them: a CNAB runtime refuses a bundle that
	// requires an extension it does not know, and Porter does.
	InstallerExtensions = []ExtensionDefinition{
		ComposeExtension,
	}
)
View Source 
var ComposeExtension = Extension[Compose]{
	Key:    NemoExtensionsPrefix + "compose",
	Schema: "io.nemo.compose.schema.json",
}

ComposeExtension holds a bundle's compose project. The installer applies it with Compose or Swarm, whichever the target runs: the bundle says what runs, never where. It is an installer extension, so a bundle never requires it (see InstallerExtensions).

View Source 
var DependenciesExtension = Extension[Dependencies]{
	Key:       OfficialExtensionsPrefix + "dependencies",
	Shorthand: "dependencies",
	Schema:    "io.cnab.dependencies.schema.json",
}

DependenciesExtension declares the other bundles a bundle needs, with semver ranges. The runtime orders a stack's installations with it. https://github.com/cnabio/cnab-spec/blob/main/500-CNAB-dependencies.md

View Source 
var DockerExtension = Extension[Docker]{
	Key:       OfficialExtensionsPrefix + "docker",
	Shorthand: "docker",
	Schema:    "io.cnab.docker.schema.json",
}

DockerExtension gives the invocation image access to the host's Docker daemon. Every nemo bundle requires it: a runtime that honours it mounts the Docker socket into the installer, and Porter asks for --allow-docker-host-access before it does.

View Source 
var ErrExtensionNotFound = errors.New("extension not found")

ErrExtensionNotFound is returned when reading an extension the bundle does not carry.

View Source 
var NewULID = cnabclaims.MustNewULID

Functions

func WriteParameterToString 

func WriteParameterToString(parameterName string, value any) (string, error)

WriteParameterToString changes a parameter's value from its type as defined by the bundle to its runtime string representation. The value should have already been converted to its bundle representation by calling ConvertParameterValue.

Types

type BundleReference 

type BundleReference struct {
	Reference  OCIReference
	Digest     digest.Digest
	Definition ExtendedBundle
	// RelocationMap is what cnab-to-oci returns when it pulls the bundle,
	// and what the runtime mounts as /cnab/app/relocation-mapping.json.
	RelocationMap relocation.ImageRelocationMap
}

BundleReference is a bundle as it was resolved from an OCI reference.

func (BundleReference) String 

func (reference BundleReference) String() string

type Claim 

type Claim = cnabclaims.Claim

type Compose 

type Compose struct {
	SchemaVersion string `json:"schemaVersion"`

	// Documents are merged in order into one project, like several -f flags.
	Documents []ComposeDocument `json:"compose"`
}

Compose is the content of the compose extension.

func (Compose) Load 

func (compose Compose) Load(ctx context.Context, name, workingDir string, environment types.Mapping) (*types.Project, error)

Load merges the documents into the compose project name, its relative paths resolved in workingDir. The documents are interpolated with environment; with none, as when a bundle is built, they are not, and keep their variables. The documents are left as they are: the loader normalizes what it is given, so it is given a copy.

type ComposeDocument 

type ComposeDocument struct {
	// Name is the file name shown in errors.
	Name   string         `json:"name,omitempty"`
	Config map[string]any `json:"config"`
}

ComposeDocument is one compose document, as parsed YAML.

type Dependencies 

type Dependencies struct {
	// Sequence is a list to order the dependencies
	Sequence []string `json:"sequence,omitempty"`

	// Requires is a list of bundles required by this bundle
	Requires map[string]Dependency `json:"requires,omitempty"`
}

Dependencies describes the set of custom extension metadata associated with the dependencies spec

func (Dependencies) ListBySequence 

func (dependencies Dependencies) ListBySequence() []Dependency

ListBySequence returns the dependencies by the defined sequence, if none is specified, they are sorted by name.

type Dependency 

type Dependency struct {
	// Name of the dependency
	// This is used internally but isn't persisted to bundle.json
	Name string `json:"-"`

	// Bundle is the location of the bundle in a registry, for example REGISTRY/NAME:TAG
	Bundle string `json:"bundle"`

	// Version is a set of allowed versions
	Version *DependencyVersion `json:"version,omitempty"`
}

Dependency describes a dependency on another bundle

func (Dependency) Allows 

func (dependency Dependency) Allows(version string) error

Allows checks a version against the dependency, as the specification reads it: within any of its ranges, and a prerelease only when allowed. The version may be written as a tag, v1.2.3.

func (Dependency) BundleName 

func (dependency Dependency) BundleName() (string, error)

BundleName is the name of the bundle the dependency is on: the last part of its repository, under which a bundle is pushed.

type DependencyLock 

type DependencyLock struct {
	Alias     string
	Reference string
}

DependencyLock is a dependency resolved to one bundle reference.

type DependencyVersion 

type DependencyVersion struct {
	// Ranges of semantic versions, with or without the leading v prefix, allowed by the dependency
	Ranges []string `json:"ranges,omitempty"`

	// AllowPrereleases specifies if prerelease versions can satisfy the dependency
	AllowPrereleases bool `json:"prereleases,omitempty"`
}

DependencyVersion is a set of allowed versions for a dependency

type Docker 

type Docker struct {
	// Privileged represents whether or not the Docker container should run as --privileged
	Privileged bool `json:"privileged,omitempty"`
}

Docker is the configuration of the Docker extension.

type ExtendedBundle 

type ExtendedBundle struct {
	bundle.Bundle

	// Each extension is nil when the bundle does not carry it.
	Docker       *Docker
	Dependencies *Dependencies
	Compose      *Compose
}

ExtendedBundle is a bundle that passed nemo's checks, with the extensions nemo knows decoded from its custom section. Build it with NewBundle, LoadBundle or UnmarshalBundle, never as a literal.

The decoded extensions are views of Custom: to change one, write it with its Extension and build the ExtendedBundle again.

func LoadBundle 

func LoadBundle(bundleFile string) (ExtendedBundle, error)

LoadBundle reads a bundle.json from the specified filepath.

func NewBundle 

func NewBundle(bundle bundle.Bundle) (ExtendedBundle, error)

NewBundle validates a bundle and decodes its extensions.

func UnmarshalBundle 

func UnmarshalBundle(data []byte) (ExtendedBundle, error)

UnmarshalBundle reads a bundle.json.

func (ExtendedBundle) CheckRequiredExtensions 

func (bundle ExtendedBundle) CheckRequiredExtensions() error

CheckRequiredExtensions checks that the nemo runtime honours every extension the bundle requires.

func (ExtendedBundle) ConvertParameterValue 

func (bundle ExtendedBundle) ConvertParameterValue(key string, value any) (any, error)

ConvertParameterValue converts a parameter's value from an unknown type, it could be a string from stdin or another Go type, into the type of the parameter as defined in the bundle.

func (ExtendedBundle) GetParameterType 

func (bundle ExtendedBundle) GetParameterType(definition *definition.Schema) string

GetParameterType determines the type of parameter, accounting for files.

func (ExtendedBundle) GetReferencedRegistries 

func (bundle ExtendedBundle) GetReferencedRegistries() ([]string, error)

GetReferencedRegistries identifies all OCI registries used by the bundle from both the bundle image and the referenced images.

func (ExtendedBundle) IsFileType 

func (bundle ExtendedBundle) IsFileType(definition *definition.Schema) bool

IsFileType determines if the parameter/credential is of type "file": a base64-encoded string, delivered to the installer as a file.

func (ExtendedBundle) IsSensitiveParameter 

func (bundle ExtendedBundle) IsSensitiveParameter(name string) bool

IsSensitiveParameter determines if the parameter contains a sensitive value.

func (ExtendedBundle) WriteParameterToString 

func (bundle ExtendedBundle) WriteParameterToString(parameterName string, value any) (string, error)

type Extension 

type Extension[T any] struct {
	// Key is the key of the extension in custom.
	Key string
	// Shorthand is the short name some bundles require the extension by.
	// https://github.com/cnabio/cnab-spec/issues/403
	Shorthand string
	// Schema is the file of the extension's schema in schemas/.
	Schema string
}

Extension is a custom extension of a bundle: a key in custom, a JSON schema embedded in schemas/, and the Go type its value decodes to.

Whether a bundle may list it in requiredExtensions is not a property of the extension: see RuntimeExtensions.

func (Extension[T]) Matches 

func (extension Extension[T]) Matches(name string) bool

Matches reports whether a name in requiredExtensions designates the extension.

func (Extension[T]) Name 

func (extension Extension[T]) Name() string

Name returns the key of the extension.

func (Extension[T]) Read 

func (extension Extension[T]) Read(bundle bundle.Bundle) (T, error)

Read decodes the extension from the bundle's custom section, after checking it against its schema. It returns ErrExtensionNotFound when the bundle does not carry it.

func (Extension[T]) RequiredBy 

func (extension Extension[T]) RequiredBy(bundle bundle.Bundle) bool

RequiredBy reports whether the bundle lists the extension in requiredExtensions.

func (Extension[T]) Write 

func (extension Extension[T]) Write(bundle *bundle.Bundle, value T) error

Write stores the extension in the bundle's custom section, after checking it against its schema.

type ExtensionDefinition 

type ExtensionDefinition interface {
	Name() string
	Matches(name string) bool
}

ExtensionDefinition is an Extension, whatever the type of its value.

type Installation 

type Installation = cnabclaims.Installation

type OCIReference 

type OCIReference struct {
	// Name is the wrapped reference that we are providing helper methods on top of
	Named reference.Named
}

OCIReference is a wrapper around a docker reference with convenience methods for decomposing and manipulating bundle references.

It is designed to be safe to call even when uninitialized, returning empty strings when parts are requested that do not exist, such as calling Digest() when no digest is set on the reference.

func MustParseOCIReference 

func MustParseOCIReference(value string) OCIReference

MustParseOCIReference parses the specified value as an OCIReference, panicking on any errors. Only use this for unit tests where you know the value is a reference.

func ParseOCIReference 

func ParseOCIReference(value string) (OCIReference, error)

ParseOCIReference parses the specified value as an OCIReference. If the reference includes a digest, the digest is validated.

func (OCIReference) Canonical 

func (ociReference OCIReference) Canonical() string

Canonical is the full reference, its registry included: docker.io/library/nginx:1.27, as registry clients want it.

func (OCIReference) Digest 

func (ociReference OCIReference) Digest() digest.Digest

Digest portion of the reference. Example: ghcr.io/getporter/mybuns@sha256:abc123 returns sha256:abc123

func (OCIReference) HasDigest 

func (ociReference OCIReference) HasDigest() bool

HasDigest determines if the reference has a digest portion. Example: ghcr.io/getporter/mybuns@sha256:abc123 returns true

func (OCIReference) HasTag 

func (ociReference OCIReference) HasTag() bool

HasTag determines if the reference has a tag portion. Example: ghcr.io/getporter/mybuns:latest returns true

func (OCIReference) HasVersion 

func (ociReference OCIReference) HasVersion() bool

HasVersion detects if the reference tag is a bundle version (semver).

func (OCIReference) IsRepositoryOnly 

func (ociReference OCIReference) IsRepositoryOnly() bool

IsRepositoryOnly determines if the reference is fully qualified with a tag/digest or if it only contains a repository. Example: ghcr.io/getporter/mybuns returns true

func (OCIReference) MarshalJSON 

func (ociReference OCIReference) MarshalJSON() ([]byte, error)

func (OCIReference) Registry 

func (ociReference OCIReference) Registry() string

Registry portion of the reference. Example: ghcr.io/getporter/mybuns:v0.1.1 returns ghcr.io

func (OCIReference) Repository 

func (ociReference OCIReference) Repository() string

Repository portion of the reference. Example: docker.io/getporter/mybuns:v0.1.1 returns getporter/mybuns

func (OCIReference) String 

func (ociReference OCIReference) String() string

Always print the original name provided, not the one with docker.io prefixed.

func (OCIReference) Tag 

func (ociReference OCIReference) Tag() string

Tag portion of the reference. Example: ghcr.io/getporter/mybuns:latest returns latest

func (*OCIReference) UnmarshalJSON 

func (ociReference *OCIReference) UnmarshalJSON(bytes []byte) error

func (OCIReference) Version 

func (ociReference OCIReference) Version() string

Version parses the reference tag as a bundle version (semver).

func (OCIReference) WithDigest 

func (ociReference OCIReference) WithDigest(digest digest.Digest) (OCIReference, error)

WithDigest creates a new reference using the repository and the specified digest.

func (OCIReference) WithTag 

func (ociReference OCIReference) WithTag(tag string) (OCIReference, error)

WithTag creates a new reference using the repository and the specified tag.

func (OCIReference) WithVersion 

func (ociReference OCIReference) WithVersion(version string) (OCIReference, error)

WithVersion creates a new reference using the repository and the specified bundle version. If build metadata is present, "+" is converted to "_".

func (OCIReference) WithoutVersion 

func (ociReference OCIReference) WithoutVersion() OCIReference

WithoutVersion returns the repository alone, without tag nor digest.

type Output 

type Output = cnabclaims.Output

type OutputMetadata 

type OutputMetadata = cnabclaims.OutputMetadata

type Outputs 

type Outputs = cnabclaims.Outputs

type Resolver 

type Resolver struct {
	Tags     TagLister
	Strategy VersionStrategy
}

Resolver resolves the dependencies of a bundle to bundle references.

func (Resolver) ResolveDependencies 

func (resolver Resolver) ResolveDependencies(ctx context.Context, bundle ExtendedBundle) ([]DependencyLock, error)

ResolveDependencies resolves every dependency of the bundle, in its sequence.

func (Resolver) ResolveVersion 

func (resolver Resolver) ResolveVersion(ctx context.Context, name string, dependency Dependency) (OCIReference, error)

ResolveVersion returns the reference of the bundle the dependency resolves to.

type Result 

type Result = cnabclaims.Result

type SchemaVersion 

type SchemaVersion = schema.Version

func BundleSchemaVersion 

func BundleSchemaVersion() SchemaVersion

BundleSchemaVersion is the schemaVersion value for CNAB bundle documents.

func ClaimSchemaVersion 

func ClaimSchemaVersion() SchemaVersion

ClaimSchemaVersion is the schemaVersion value for CNAB claim documents.

type TagLister 

type TagLister interface {
	ListTags(ctx context.Context, repository OCIReference) ([]string, error)
}

TagLister lists the tags of a repository. The registry client implements it.

type VersionStrategy 

type VersionStrategy string

VersionStrategy says which version satisfying a dependency's ranges is picked. 

const (
	// VersionMax picks the highest version satisfying the ranges. It is the default.
	VersionMax VersionStrategy = ""
	// VersionMaxMinor picks the highest version with the same major as the
	// reference's tag.
	VersionMaxMinor VersionStrategy = "max-minor"
	// VersionMaxPatch picks the highest version with the same major and minor
	// as the reference's tag.
	VersionMaxPatch VersionStrategy = "max-patch"
	// VersionMin picks the lowest version satisfying the ranges.
	VersionMin VersionStrategy = "min"
	// VersionExact keeps the reference's tag or digest, and fails without one.
	VersionExact VersionStrategy = "exact"
)

Source Files

View all Source files

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.