oci

package
v0.11.1 Latest Latest
Warning

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

 Go to latest Published: Mar 21, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package oci provides functionality for packaging and pushing artifacts to OCI-compliant registries.

This package enables bundled artifacts to be pushed to any OCI-compliant registry (Docker Hub, GHCR, ECR, local registries, etc.) using the ORAS (OCI Registry As Storage) library. Artifacts are packaged as OCI Image Layout format and can be pushed to remote registries.

Overview

The package provides three main operations:

  • ParseOutputTarget: Parses output targets (file paths or OCI URIs) into Reference
  • Package: Creates a local OCI artifact in OCI Image Layout format
  • PushFromStore: Pushes a previously packaged artifact to a remote registry
  • PackageAndPush: High-level workflow combining Package and PushFromStore

The Reference type encapsulates parsed output target information, making it easy to determine if output is destined for the local filesystem or an OCI registry.

Core Types

  • Reference: Parsed output target (file path or OCI URI with registry/repository/tag)
  • OutputConfig: Configuration for PackageAndPush workflow
  • PackageAndPushResult: Combined result of package and push operations
  • PackageOptions: Configuration for local OCI packaging
  • PackageResult: Result of local packaging (digest, reference, store path)
  • PushOptions: Configuration for pushing to remote registries
  • PushResult: Result of a successful push (digest, reference)

URI Scheme

OCI output targets use the "oci://" URI scheme: 

oci://registry/repository:tag
oci://ghcr.io/nvidia/bundles:v1.0.0
oci://localhost:5000/test/bundle:latest

Local file paths are detected by absence of the oci:// scheme.

Usage

Parse output target and use high-level workflow: 

ref, err := oci.ParseOutputTarget("oci://ghcr.io/nvidia/bundle:v1.0.0")
if err != nil {
    return err
}

if ref.IsOCI {
    result, err := oci.PackageAndPush(ctx, oci.OutputConfig{
        Ref:       ref,
        SourceDir: "/path/to/bundle",
    })
}

Or use low-level Package and PushFromStore separately: 

pkgResult, err := oci.Package(ctx, oci.PackageOptions{
    SourceDir:  "/path/to/bundle",
    OutputDir:  "/path/to/output",
    Registry:   "ghcr.io",
    Repository: "nvidia/bundle",
    Tag:        "v1.0.0",
})
if err != nil {
    return err
}

pushResult, err := oci.PushFromStore(ctx, pkgResult.StorePath, oci.PushOptions{
    Registry:   "ghcr.io",
    Repository: "nvidia/bundle",
    Tag:        "v1.0.0",
})

Reference Type

The Reference type represents a parsed output target:

  • IsOCI: True if target is an OCI registry (oci:// scheme)
  • Registry: OCI registry hostname (e.g., "ghcr.io")
  • Repository: Image repository path (e.g., "nvidia/bundle")
  • Tag: Image tag (e.g., "v1.0.0")
  • LocalPath: File system path for non-OCI targets

The Reference.WithTag() method returns a copy with the tag modified, useful for applying a default tag when none was specified.

PackageOptions

  • SourceDir: Directory containing artifacts to package
  • OutputDir: Where the OCI Image Layout will be created
  • Registry, Repository, Tag: Image reference components
  • SubDir: Optionally limit packaging to a subdirectory
  • ReproducibleTimestamp: Fixed timestamp for reproducible builds

PushOptions

  • PlainHTTP: Use HTTP instead of HTTPS (for local development registries)
  • InsecureTLS: Skip TLS certificate verification

Authentication

The package automatically uses Docker credential helpers for authentication. Credentials are loaded from the standard Docker configuration (~/.docker/config.json) using the ORAS credentials package.

Artifact Type

Artifacts are pushed with the media type "application/vnd.nvidia.aicr.artifact". This custom media type identifies AICR bundles and distinguishes them from runnable container images. Consumers that don't understand this type should treat the artifact as a non-executable blob.

Package oci provides utilities for packaging and pushing OCI artifacts.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type OutputConfig 

type OutputConfig struct {
	// SourceDir is the directory containing artifacts to package.
	SourceDir string
	// OutputDir is where temporary OCI artifacts will be created.
	OutputDir string
	// Reference contains the parsed OCI registry reference.
	Reference *Reference
	// Version is used for OCI annotations (org.opencontainers.image.version).
	Version string
	// PlainHTTP uses HTTP instead of HTTPS for the registry connection.
	PlainHTTP bool
	// InsecureTLS skips TLS certificate verification.
	InsecureTLS bool
	// Annotations are additional manifest annotations to include.
	// If nil, default AICR annotations will be used.
	Annotations map[string]string
}

OutputConfig configures the OCI package and push workflow.

type PackageAndPushResult 

type PackageAndPushResult struct {
	// Digest is the SHA256 digest of the pushed artifact.
	Digest string
	// Reference is the full image reference (registry/repository:tag).
	Reference string
	// StorePath is the path to the local OCI Image Layout directory.
	StorePath string
}

PackageAndPushResult contains the result of a successful package and push operation.

func PackageAndPush 

func PackageAndPush(ctx context.Context, cfg OutputConfig) (*PackageAndPushResult, error)

PackageAndPush packages a directory as an OCI artifact and pushes it to a registry. This is a convenience function that combines Package and PushFromStore operations.

type PackageOptions 

type PackageOptions struct {
	// SourceDir is the directory containing artifacts to package.
	SourceDir string
	// OutputDir is where the OCI Image Layout will be created.
	OutputDir string
	// Registry is the OCI registry host for the reference (e.g., "ghcr.io").
	Registry string
	// Repository is the image repository path (e.g., "nvidia/aicr").
	Repository string
	// Tag is the image tag (e.g., "v1.0.0", "latest").
	Tag string
	// SubDir optionally limits packaging to a subdirectory within SourceDir.
	SubDir string
	// Annotations are additional manifest annotations to include.
	// Standard OCI annotations (org.opencontainers.image.*) are recommended.
	Annotations map[string]string
}

PackageOptions configures local OCI packaging.

type PackageResult 

type PackageResult struct {
	// Digest is the SHA256 digest of the packaged artifact.
	Digest string
	// Reference is the full image reference (registry/repository:tag).
	Reference string
	// StorePath is the path to the OCI Image Layout directory.
	StorePath string
}

PackageResult contains the result of local OCI packaging.

func Package 

func Package(ctx context.Context, opts PackageOptions) (retResult *PackageResult, retErr error)

Package creates a local OCI artifact in OCI Image Layout format. This stores the artifact locally without pushing to a remote registry.

type PushOptions 

type PushOptions struct {
	// SourceDir is the directory containing artifacts to push.
	SourceDir string
	// Registry is the OCI registry host (e.g., "ghcr.io", "localhost:5000").
	Registry string
	// Repository is the image repository path (e.g., "nvidia/aicr").
	Repository string
	// Tag is the image tag (e.g., "v1.0.0", "latest").
	Tag string
	// PlainHTTP uses HTTP instead of HTTPS for the registry connection.
	PlainHTTP bool
	// InsecureTLS skips TLS certificate verification.
	InsecureTLS bool
}

PushOptions configures the OCI push operation.

type PushResult 

type PushResult struct {
	// Digest is the SHA256 digest of the pushed artifact.
	Digest string
	// Reference is the full image reference (registry/repository:tag).
	Reference string
}

PushResult contains the result of a successful OCI push.

func PushFromStore 

func PushFromStore(ctx context.Context, storePath string, opts PushOptions) (*PushResult, error)

PushFromStore pushes an already-packaged OCI artifact from a local OCI store to a remote registry.

type Reference 

type Reference struct {
	// IsOCI indicates whether this is an OCI registry reference (true) or local path (false).
	IsOCI bool
	// Registry is the OCI registry host (e.g., "ghcr.io", "localhost:5000").
	// Only populated when IsOCI is true.
	Registry string
	// Repository is the image repository path (e.g., "nvidia/bundle").
	// Only populated when IsOCI is true.
	Repository string
	// Tag is the image tag (e.g., "v1.0.0").
	// Empty string means no tag was specified; caller should apply a default.
	// Only populated when IsOCI is true.
	Tag string
	// LocalPath is the local directory path for non-OCI output.
	// Only populated when IsOCI is false.
	LocalPath string
}

Reference represents a parsed output target, which can be either an OCI registry reference or a local directory path.

func ParseOutputTarget 

func ParseOutputTarget(target string) (*Reference, error)

ParseOutputTarget parses an output target string to detect OCI URI or local directory. For OCI URIs (oci://registry/repository:tag), it extracts the components. For plain paths, it treats them as local directories.

If no tag is specified in an OCI URI, Tag will be empty; the caller is responsible for applying a default (e.g., CLI version).

func (*Reference) String 

func (r *Reference) String() string

String returns the full reference string. For OCI references: "oci://registry/repository:tag" (or without tag if empty). For local paths: the local path.

func (*Reference) WithTag 

func (r *Reference) WithTag(tag string) *Reference

WithTag returns a copy of the reference with the specified tag. For non-OCI references, returns the same reference unchanged.

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.