provenance

Documentation

Overview

Package provenance answers where a target's GitOps files live: the owning GitHub repository, branch and directory. The answer comes from a cluster's Flux objects (a Kustomization and the GitRepository it builds from) or from an explicit location the caller names. Input is data the caller has read; the package talks to no cluster.

Index

• Constants
• Variables
• type Flux
  • func (f *Flux) Add(obj map[string]any) error
  • func (f Flux) FindKustomization(namespace, name string) (Kustomization, bool)
  • func (f Flux) Resolve(namespace, name string) (Location, error)
• type GitRepository
• type Keys
• type Kustomization
• type Location
  • func Explicit(repository, branch, directory string) (Location, error)
  • func (l Location) Path(name string) (string, error)
• type Repository
  • func ParseRepositoryURL(raw string) (Repository, error)
  • func (r Repository) String() string
• type SourceRef

Constants

const (

	// KindGitRepository is the only Flux source kind a commit can target.
	KindGitRepository = "GitRepository"
)

Variables

var (
	// ErrNotFound is returned when the named Kustomization or the GitRepository
	// it references is not among the Flux objects.
	ErrNotFound = errors.New("flux object not found")
	// ErrNotGit is returned when a Kustomization builds from a source that is
	// not a GitRepository; there is no repository to commit to.
	ErrNotGit = errors.New("kustomization source is not a GitRepository")
	// ErrNoBranch is returned when a GitRepository does not follow a branch;
	// a tag, semver range or commit cannot receive a commit.
	ErrNoBranch = errors.New("git repository follows no branch")
	// ErrNotGitHub is returned for a repository URL that is not a GitHub
	// owner/name repository.
	ErrNotGitHub = errors.New("not a GitHub repository URL")
	// ErrInvalidPath is returned for a directory or file name that is absolute
	// or leaves the location's directory.
	ErrInvalidPath = errors.New("path leaves the repository directory")
)

var ErrUnknownObject = errors.New("not a flux kustomization or git repository")

ErrUnknownObject is returned by Add for an object that is neither a Flux Kustomization nor a Flux GitRepository.

Types

type Flux

type Flux struct {
	Kustomizations  []Kustomization
	GitRepositories []GitRepository
}

Flux is a cluster's Flux objects as the caller read them.

func (*Flux) Add

func (f *Flux) Add(obj map[string]any) error

Add records one decoded Kubernetes object (the shape of `kubectl get -o json`, or an unstructured object's content) as a Kustomization or GitRepository. Any other apiVersion/kind is an error: the caller hands over the Flux objects it read, nothing else.

func (Flux) FindKustomization

func (f Flux) FindKustomization(namespace, name string) (Kustomization, bool)

FindKustomization returns the Kustomization namespace/name, and whether the Flux objects hold it.

func (Flux) Resolve

func (f Flux) Resolve(namespace, name string) (Location, error)

Resolve returns the location the Kustomization namespace/name builds from: the GitHub repository and branch of its GitRepository and its spec.path as the directory.

type GitRepository

type GitRepository struct {
	Name      string
	Namespace string
	URL       string
	// Branch is spec.ref.branch; empty when the source follows something else.
	Branch string
}

GitRepository is the part of a Flux GitRepository the resolution reads.

type Keys

type Keys struct {
	Provider  string
	SecretRef string
}

Keys is a Kustomization's spec.decryption: the provider ("sops") and the Secret next to the Kustomization that holds the keys.

type Kustomization

type Kustomization struct {
	Name      string
	Namespace string
	SourceRef SourceRef
	// Path is spec.path as Flux carries it ("./management-clusters/x").
	Path string
	// ServiceAccountName, Interval and Timeout are spec.serviceAccountName,
	// spec.interval and spec.timeout as Flux carries them ("1m"); empty when
	// unset.
	ServiceAccountName string
	Interval           string
	Timeout            string
	// Prune is spec.prune: whether Flux removes what leaves the directory.
	Prune bool
	// Keys is spec.decryption, nil when the Kustomization applies no
	// encrypted files.
	Keys *Keys
}

Kustomization is the part of a Flux Kustomization the resolution reads.

type Location

type Location struct {
	Repository Repository
	Branch     string
	// Directory is repository-relative without a leading "./" or trailing "/";
	// the empty string is the repository root.
	Directory string
}

Location is where a target's files live: a directory on a branch of a repository.

func Explicit

func Explicit(repository, branch, directory string) (Location, error)

Explicit returns the location the caller names: repository as owner/name, the branch, and a repository-relative directory ("" or "." for the root).

func (Location) Path

func (l Location) Path(name string) (string, error)

Path returns the repository-relative path of a file in the location. A name that is absolute or climbs out of the directory is refused.

type Repository

type Repository struct {
	Owner string
	Name  string
}

Repository is a GitHub repository.

func ParseRepositoryURL

func ParseRepositoryURL(raw string) (Repository, error)

ParseRepositoryURL returns the GitHub repository a Flux GitRepository URL names, in its https, ssh:// or scp-like git@ form, with or without ".git", on github.com or on GitHub's SSH endpoint on port 443, ssh.github.com.

func (Repository) String

func (r Repository) String() string

String returns owner/name.

type SourceRef

type SourceRef struct {
	Kind string
	Name string
	// Namespace is empty when the source lives next to the Kustomization.
	Namespace string
}

SourceRef names the Flux source a Kustomization builds from.