Documentation
¶
Overview ¶
Package repo builds and reads package repository indexes.
A repository is one index file listing every version of every package it offers. Each version is a complete PackageSource spec, so whatever reads the index can install an entry without translating it. The index is served over HTTP like a Helm repository index, or pushed to an OCI registry.
Index ¶
- Constants
- Variables
- func GenerateKey() (private, public []byte, err error)
- func KeyID(publicPEM string) (string, error)
- func LoadIndexWithRoot(ctx context.Context, fetchers Fetchers, url string, trust Trust, now time.Time) (*Index, []byte, Trust, error)
- func LoadRepository(ctx context.Context, fetchers Fetchers, spec v1.RepositorySpec, ...) (*Index, []byte, Trust, error)
- func Newer(a, b Version) bool
- func ParsePublicKeys(pems []string) ([]ed25519.PublicKey, error)
- func Sign(index, privatePEM []byte) ([]byte, error)
- func SignIndex(index, sigFile, privatePEM []byte) ([]byte, error)
- func SignRoot(sr *SignedRoot, privatePEM []byte) error
- func SignSources(file, privatePEM []byte) ([]byte, []string, error)
- func SpecDigest(spec v1.PackageSourceSpec) (string, error)
- func Verify(index, signature []byte, keys []ed25519.PublicKey) error
- type AllowAll
- type BuildOptions
- type ChartFetcher
- type Delegation
- type Fetchers
- type HTTPFetcher
- type Index
- type IndexFetcher
- type Package
- type Policy
- type Role
- type Root
- type Selection
- type Signature
- type Signatures
- type SignedRoot
- type Store
- func (s *Store) Attempted(name string) bool
- func (s *Store) Catalog(ctx context.Context, variant string, policy Policy) resolve.Catalog
- func (s *Store) Delete(name string)
- func (s *Store) Describe(pkg string) (description, home string)
- func (s *Store) Failed(name string)
- func (s *Store) Offered(pkg, only string) (string, []Version, bool)
- func (s *Store) Packages() []string
- func (s *Store) Select(ctx context.Context, pkg, constraint, only string, policy Policy) (Selection, error)
- func (s *Store) Set(name string, priority int32, idx *Index)
- type Trust
- type TrustedRoot
- type Version
Constants ¶
const ( AnnotationDescription = "kubepkg.dev/description" AnnotationHome = "kubepkg.dev/home" )
Annotations on a PackageSource that describe the package in the index.
const ( RoleRoot = "root" RoleIndex = "index" )
Roles a root delegates.
const AnnotationSignatures = "kubepkg.dev/signatures"
AnnotationSignatures on a PackageSource carries the signatures of a delegated team over that version, as a JSON list; the index copies them into the version. Annotations are outside the spec digest, so signing changes nothing that is signed.
const IndexAPIVersion = "kubepkg.dev/v1alpha1"
IndexAPIVersion is the version of the index file format. It is not the version of the cluster API and stays as indexes were first published.
const IndexKind = "RepositoryIndex"
IndexKind is the kind of an index document.
const RootFile = "root.yaml"
RootFile is where a repository publishes its current root, next to its index; every version also lives at root/<version>.yaml.
const SignatureSuffix = ".sig"
SignatureSuffix is appended to an index URL to find its signature.
Variables ¶
var ( ErrFetchFailed = errors.New("index cannot be fetched") ErrInvalidIndex = errors.New("index is not valid") )
Errors of LoadIndex besides ErrBadSignature.
var ErrBadSignature = errors.New("index is not signed by a trusted key")
ErrBadSignature is returned when no trusted key signed an index.
var ErrExpired = errors.New("expired")
ErrExpired is returned for a root or an index past its expiry.
var ErrNewerFormat = errors.New("made for a newer kubepkg")
ErrNewerFormat is returned for repository files made for a newer kubepkg.
var ErrNoVersion = errors.New("no repository offers an acceptable version")
ErrNoVersion is returned when no repository offers an acceptable version.
Functions ¶
func GenerateKey ¶
GenerateKey makes an ed25519 key pair, PEM encoded: the private key as PKCS #8, the public key as PKIX.
func LoadIndexWithRoot ¶
func LoadIndexWithRoot(ctx context.Context, fetchers Fetchers, url string, trust Trust, now time.Time) (*Index, []byte, Trust, error)
LoadIndexWithRoot fetches the root chain and the index next to url, follows the root from version 1 to the current one, checks the index against its index role and both expiries, and returns the index and the root reached, to be passed back as Trust next time.
func LoadRepository ¶
func LoadRepository(ctx context.Context, fetchers Fetchers, spec v1.RepositorySpec, status v1.RepositoryStatus, now time.Time) (*Index, []byte, Trust, error)
LoadRepository loads a Repository's index the way its spec asks: through its pinned root, with plain public keys, or unchecked. It refuses an index older than the one in status and returns the root reached, for status, when the repository has a root.
func ParsePublicKeys ¶
ParsePublicKeys reads PEM encoded ed25519 public keys.
func Sign ¶
Sign signs the index bytes exactly as published. The signature is base64 text, served next to the index under SignatureSuffix. Because the index pins every chart by digest, it covers the whole repository.
func SignIndex ¶
SignIndex adds the key's signature over the index bytes to a signature file, which may be empty or hold signatures by other keys.
func SignRoot ¶
func SignRoot(sr *SignedRoot, privatePEM []byte) error
SignRoot adds the key's signature to a root. Signers can sign one after another, on different machines.
func SignSources ¶
SignSources adds the key's signature to every PackageSource in a YAML file, in its signatures annotation, and returns the file and what was signed. Charts must be pinned by digest already, as the index will publish them, or the signature would not match.
func SpecDigest ¶
SpecDigest is the sha256 of a spec in canonical JSON.
Types ¶
type AllowAll ¶
type AllowAll struct{}
AllowAll is the default policy.
func (AllowAll) AdmitIndex ¶
AdmitIndex implements Policy.
type BuildOptions ¶
type BuildOptions struct {
// Verify downloads charts that are already pinned and checks their
// digests too. Charts without a digest are always downloaded and
// pinned.
Verify bool
// Base is the index already published. Its versions are kept, and a
// version rebuilt with the same number must not change: published
// versions are immutable, a changed recipe needs a new build.
Base *Index
// Relocate moves the charts and package trees of published versions
// from one registry path to another, oci://old=oci://new by prefix,
// when a repository moves registries. Only the location changes: each
// relocated chart is fetched from its new place and must have the
// digest it was published with, so what a version installs stays the
// same; its spec digest changes with the location.
Relocate map[string]string
}
BuildOptions control Build.
type ChartFetcher ¶
type ChartFetcher interface {
FetchChart(ctx context.Context, c source.Chart) (dir, digest string, err error)
}
ChartFetcher resolves chart digests; source.Fetcher implements it.
type Delegation ¶
type Delegation struct {
Name string `json:"name"`
// Packages are name patterns, as path.Match takes them: "cdi", "kubevirt-*".
Packages []string `json:"packages"`
KeyIDs []string `json:"keyids"`
Threshold int `json:"threshold"`
}
Delegation hands the packages whose names match its patterns to other keys: versions of those packages are trusted only with enough of these keys' signatures, whoever signs the index. A team then publishes through the repository's CI without the CI's key being able to forge its packages.
type Fetchers ¶
type Fetchers map[string]IndexFetcher
Fetchers pick an IndexFetcher by URL scheme. A distribution adds its own schemes, e.g. for an internal artifact store.
type HTTPFetcher ¶
type HTTPFetcher struct{}
HTTPFetcher fetches indexes over HTTP(S).
func (HTTPFetcher) FetchIndex ¶
FetchIndex implements IndexFetcher.
type Index ¶
type Index struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
// Generated is when the index was built. Clusters refuse an index
// older than one they accepted, so an old signed index cannot be
// replayed to roll them back to versions since withdrawn.
Generated *metav1.Time `json:"generated,omitempty"`
// Expires bounds how long clients accept the index: a mirror that
// keeps serving an old one is refused once it expires. Repositories
// with a root must set it.
Expires *metav1.Time `json:"expires,omitempty"`
Packages map[string]Package `json:"packages"`
// Unknown lists versions this kubepkg left out because their specs
// have fields it does not know: built for a newer kubepkg.
Unknown []string `json:"-"`
// Untrusted lists versions left out because their delegation did not
// sign them.
Untrusted []string `json:"-"`
}
Index is a repository index.
func Build ¶
func Build(ctx context.Context, dir string, charts ChartFetcher, opts BuildOptions) (*Index, error)
Build reads every PackageSource in the YAML files under dir and returns the index. Charts without a digest are downloaded and pinned in the index, so a published version always installs the same bytes; the source files are left as they are.
func LoadIndex ¶
func LoadIndex(ctx context.Context, fetchers Fetchers, url string, publicKeys []string) (*Index, []byte, error)
LoadIndex fetches the index at url, checks its signature when public keys are given, and parses it. Errors are ErrFetchFailed, ErrBadSignature or ErrInvalidIndex.
type IndexFetcher ¶
IndexFetcher downloads a repository index.
type Package ¶
type Package struct {
Description string `json:"description,omitempty"`
Home string `json:"home,omitempty"`
// Versions are sorted newest first, by version and then build.
Versions []Version `json:"versions"`
}
Package is every published version of one package.
type Policy ¶
type Policy interface {
// AdmitIndex runs on every fetched index before it is used; raw is the
// index as fetched.
AdmitIndex(ctx context.Context, repository string, raw []byte, idx *Index) error
// AdmitVersion runs on a version before it is selected for install.
AdmitVersion(ctx context.Context, repository, pkg string, v Version) error
}
Policy decides which indexes and versions the operator accepts. It is where a distribution checks signatures, allowed registries and the like.
type Root ¶
type Root struct {
Version int `json:"version"`
Expires time.Time `json:"expires"`
// Keys are PEM encoded ed25519 public keys by key ID.
Keys map[string]string `json:"keys"`
Roles map[string]Role `json:"roles"`
// Delegations hand packages to other keys. A kubepkg that does not
// know them cannot reproduce what was signed and refuses the root,
// rather than install delegated packages unchecked.
Delegations []Delegation `json:"delegations,omitempty"`
}
Root says which keys may sign for which role, and how many must. It is the repository's trust anchor, after TUF: clients pin the first root's keys and follow later versions, each signed by enough keys of the root before it and of itself.
type Signatures ¶
type Signatures struct {
Signatures []Signature `json:"signatures"`
}
Signatures is the signature file of an index: several keys may sign.
type SignedRoot ¶
SignedRoot is a root with the signatures over its canonical form.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds the accepted index of each repository.
func (*Store) Catalog ¶
Catalog lists, for every package, the releases of the given variant from the repository it is taken from and that policy admits, so the resolver sees exactly the versions the operator will select from. Of several builds of one version only the newest admitted one is listed.
func (*Store) Describe ¶
Describe returns the description and home of a package from the repository it is taken from.
func (*Store) Offered ¶
Offered returns the repository a package is taken from and its versions, newest first. The highest priority repository that has the package at all shadows the others (ties by name): a package a vendor repository carries never silently comes from a community one. only restricts the choice to one repository.
type Trust ¶
type Trust struct {
RootKeys []string
RootThreshold int
// RootVersion and RootDigest are the root accepted before; 0 starts
// from version 1. A different root under an accepted version number is
// a forked chain, as made with stolen old keys, and is refused.
RootVersion int
RootDigest string
}
Trust is what a client pins: the first root's keys and threshold, and the root version it accepted last, so a root cannot be rolled back.
type TrustedRoot ¶
type TrustedRoot struct {
Root Root
}
TrustedRoot is where a client stands: the root it last accepted.
func Bootstrap ¶
func Bootstrap(sr *SignedRoot, pinned []string, threshold int) (*TrustedRoot, error)
Bootstrap verifies version 1 of a root against keys the client pinned out of band and the threshold it expects.
func (*TrustedRoot) Update ¶
func (t *TrustedRoot) Update(next *SignedRoot) error
Update accepts the next root version: it must be exactly one version on, signed by enough root keys of the current root and of itself.
func (*TrustedRoot) VerifyIndex ¶
VerifyIndex checks an index against the index role of the root and the expiry of both, and leaves out versions of delegated packages their delegation did not sign.
type Version ¶
type Version struct {
Version string `json:"version"`
Build int32 `json:"build,omitempty"`
// Digest is the sha256 of the spec in canonical JSON. It identifies
// exactly what this version installs, charts included, because every
// chart in the spec is pinned by digest.
Digest string `json:"digest"`
Spec v1.PackageSourceSpec `json:"spec"`
// Signatures are by keys a root delegates the package to.
Signatures []Signature `json:"signatures,omitempty"`
}
Version is one published build of a version.