registry

package
v0.3.4 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

pkg/registry

The registry package implements the Orkestra pattern registry — an OCI-based store for operator patterns that can be pushed, pulled, and listed by the ork registry CLI commands.

A pattern is a directory containing a katalog.yaml and crd.yaml plus optional documentation and example files. The registry pushes each file as a named OCI layer, tags the manifest, and automatically maintains an index artifact so ork registry list works without any server-side catalog support.

What this package provides

What Where in code
Push/pull/info/list over OCI client.go — Client
Reference resolution (bare name → full OCI ref) resolve.go — Resolve, Ref
Pattern directory validation and metadata derivation pattern.go — ValidateDirectory, PatternMeta
Index management (auto-updated on push) client.go — updateIndex, fetchIndex, pushIndex
Local cache at ~/.orkestra/registry/ resolve.go — CachePath, IsCached

Artifact format

Each pattern is an OCI artifact with media type application/vnd.orkestra.pattern.v1+tar+gzip. Files are pushed as individually-typed layers:

katalog.yaml   application/vnd.orkestra.katalog.v1+yaml       (required)
crd.yaml       application/vnd.kubernetes.crd.v1+yaml         (required)
README.md      text/markdown                                   (optional)
cr.yaml        application/vnd.kubernetes.cr.v1+yaml          (optional)
pattern.yaml   application/vnd.orkestra.pattern-meta.v1+yaml  (optional)

Pattern metadata (name, version, description, tags, author) is stored as OCI manifest annotations and also derived from katalog.yaml at push time.

Push flow

ValidateDirectory(dir)           — check required files, derive PatternMeta
merger.New(katalog.yaml).Merge() — parse and validate katalog semantics   [CLI]
katalog.ValidateConfig(kfg)      — full field/GVK/dependency validation   [CLI]
validateCRDFile(crd.yaml)        — structural CRD YAML check               [CLI]
    ↓
client.Push(ctx, ref, dir)
    → read each file into memory store (nothing written to dir)
    → oras.Pack  — manifest with annotations
    → store.Tag  — register manifest under ref.Tag
    → oras.Copy  — push all blobs + manifest to remote
    → updateIndex — upsert pattern into index:latest (best-effort)

Index artifact

ork registry list reads a single index:latest artifact from the registry namespace root (ghcr.io/orkspace/orkestra-registry/patterns/index:latest). This artifact is a JSON blob containing a PatternIndex.

Push automatically updates the index after every successful push: it fetches the existing index, upserts the new pattern entry, and pushes the updated index back. There is no separate reindex step. If the index push fails it is logged as a warning — the pattern push is not rolled back.

Reference resolution

Bare references are resolved in this order:

  1. Full OCI reference (oci://host/repo:tag) — used as-is after stripping oci://
  2. ORKESTRA_REGISTRY environment variable + /name:tag
  3. Default: ghcr.io/orkspace/orkestra-registry/patterns/name:tag
ref, err := registry.Resolve("postgres:v14")
// → ghcr.io/orkspace/orkestra-registry/patterns/postgres:v14

Authentication

Reads ~/.docker/config.json via credentials.NewStoreFromDocker. Run docker login ghcr.io before pushing. No separate ork registry login command.

Developer documentation

I want to… Go to
Understand push and pull end-to-end docs/01-push-pull.md
Understand the index and how list works docs/02-index.md
Understand reference resolution and the cache docs/03-resolve-cache.md
Add a new pattern or extend the artifact format docs/04-patterns.md

Documentation

Overview

pkg/registry/client.go

ORAS-based OCI client for pushing and pulling Orkestra patterns.

Authentication uses ~/.docker/config.json via oras.land/oras-go/v2. No separate login step — docker login ghcr.io is sufficient.

Push: validates the directory, reads each file, pushes as OCI layers. Pull: fetches the manifest, extracts layers to the cache directory. Info: fetches the manifest only, reads annotations. List: fetches the index artifact from the registry root.

pkg/registry/pattern.go

Pattern is the atomic unit of the Orkestra Registry. A pattern directory contains: 

katalog.yaml  — operator declaration (required)
crd.yaml      — CRD schema (required)
README.md     — human documentation (optional)
cr.yaml       — example CR (optional)

Pattern metadata is derived entirely from katalog.yaml:

  • name, version, description, author, tags from metadata
  • required providers from spec.providers

No separate pattern.yaml is required or allowed.

pkg/registry/resolve.go

Reference resolution for ork registry commands.

A bare reference like "postgres:v14" is resolved to a full OCI reference using the following priority:

  1. Full OCI reference (starts with "oci://") — used as-is
  2. ORKESTRA_REGISTRY env var + "/name:version"
  3. Default: ghcr.io/orkspace/orkestra-registry/name:version

The "oci://" prefix is stripped before passing to ORAS — it is a user-facing convention to signal "this is an OCI reference", not part of the actual URL.

Index

Constants

View Source 
const (
	// MediaType is the OCI artifact media type for Orkestra patterns.
	MediaType = "application/vnd.orkestra.pattern.v1+tar+gzip"

	// FileKatalog is the required operator declaration file.
	FileKatalog = "katalog.yaml"

	// FileCRD is the required CRD schema file.
	FileCRD = "crd.yaml"

	// FileReadme is the human documentation file.
	FileReadme = "README.md"

	// FileCR is the example CR file.
	FileCR = "cr.yaml"
)
View Source 
const (
	// DefaultRegistry is the official Orkestra pattern registry.
	DefaultRegistry = "ghcr.io/orkspace/orkestra-registry/patterns"

	// EnvRegistry is the environment variable for overriding the registry.
	EnvRegistry = "ORKESTRA_REGISTRY"

	// CacheDir is the local cache directory for pulled patterns.
	// Resolved relative to the user's home directory.
	CacheDir = ".orkestra/registry"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ChangelogEntry 

type ChangelogEntry struct {
	Version string `yaml:"version"`
	Notes   string `yaml:"notes"`
}

ChangelogEntry represents one version entry in the changelog.

type Client 

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

Client wraps ORAS for Orkestra pattern operations.

func NewClient 

func NewClient() (*Client, error)

NewClient returns a Client with credentials loaded from the Docker config.

func (*Client) Info 

func (c *Client) Info(ctx context.Context, ref *Ref) (*PatternInfo, error)

Info fetches manifest metadata without downloading the pattern files.

func (*Client) List 

func (c *Client) List(ctx context.Context, registryURL string) (*PatternIndex, error)

List fetches the pattern index from the registry index artifact. Returns an empty index (not an error) when no patterns have been pushed yet.

func (*Client) Pull 

func (c *Client) Pull(ctx context.Context, ref *Ref, refresh bool) (string, error)

Pull fetches a pattern from the registry into the local cache. Returns the cache directory path.

func (*Client) Push 

func (c *Client) Push(ctx context.Context, ref *Ref, dir string, progress func(file string, size int64)) (string, error)

Push validates the directory and pushes all pattern files to the registry. Returns the manifest digest on success.

type PatternEntry 

type PatternEntry struct {
	Name          string   `json:"name"`
	LatestVersion string   `json:"latestVersion"`
	Description   string   `json:"description"`
	Tags          []string `json:"tags"`
	Author        string   `json:"author,omitempty"`
}

PatternEntry is one row in the pattern index.

type PatternIndex 

type PatternIndex struct {
	UpdatedAt string         `json:"updatedAt"`
	Patterns  []PatternEntry `json:"patterns"`
}

PatternIndex is the top-level index stored at registry/index:latest.

type PatternInfo 

type PatternInfo struct {
	Ref      *Ref
	Digest   string
	Size     int64
	PushedAt time.Time
	Meta     *PatternMeta
}

PatternInfo holds the metadata returned by Info.

type PatternMeta 

type PatternMeta struct {
	Name        string           `yaml:"name"`
	Version     string           `yaml:"version"`
	Description string           `yaml:"description"`
	Author      string           `yaml:"author,omitempty"`
	License     string           `yaml:"license,omitempty"`
	Tags        []string         `yaml:"tags,omitempty"`
	Requires    PatternRequires  `yaml:"requires,omitempty"`
	Changelog   []ChangelogEntry `yaml:"changelog,omitempty"` // reserved for future use
}

PatternMeta holds metadata derived from the Katalog.

func LoadPatternMeta 

func LoadPatternMeta(dir string) (*PatternMeta, error)

LoadPatternMeta returns pattern metadata for a directory (convenience wrapper).

func ValidateDirectory 

func ValidateDirectory(dir string) (*PatternMeta, []string, error)

ValidateDirectory checks that dir contains a valid pattern. Returns metadata (from katalog.yaml) and the list of files to include.

type PatternRequires 

type PatternRequires struct {
	Providers []string `yaml:"providers,omitempty"`
}

PatternRequires declares external dependencies.

type Ref 

type Ref struct {
	// Registry is the hostname (e.g. "ghcr.io").
	Registry string

	// Repository is the full repository path without the registry
	// (e.g. "orkspace/orkestra-registry/postgres").
	Repository string

	// Tag is the version tag (e.g. "v14").
	Tag string

	// Full is the complete reference without the oci:// prefix.
	// Suitable for passing directly to ORAS.
	Full string
}

Ref holds a resolved OCI reference.

func Resolve 

func Resolve(input string) (*Ref, error)

Resolve converts a user-supplied reference to a fully qualified OCI Ref. 

"postgres:v14"                          → ghcr.io/orkspace/orkestra-registry/postgres:v14
"oci://ghcr.io/myorg/patterns/redis:v7" → ghcr.io/myorg/patterns/redis:v7
"myorg/redis:v7" (with ORKESTRA_REGISTRY set) → resolved against env

func (*Ref) CachePath 

func (r *Ref) CachePath() (string, error)

CachePath returns the local filesystem path for this ref. Structure: ~/.orkestra/registry/<registry>/<repository>/<tag>/

func (*Ref) IsCached 

func (r *Ref) IsCached() bool

IsCached returns true when the pattern is already in the local cache.

func (*Ref) ShortName 

func (r *Ref) ShortName() string

ShortName returns the name:tag portion for display.

func (*Ref) String 

func (r *Ref) String() string

String returns the full reference with oci:// prefix for display.

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.