zarfstate

package
v0.42.5 Latest Latest
Warning

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

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

Documentation

Overview

Package zarfstate reads the registry half of a Zarf deployment's state secret, so that a mirror can be pointed at a registry Zarf already stands up and authenticate against it with the credentials Zarf already generated.

It is in pkg/ rather than internal/ because `cargoship mirror` is not the only thing that has to find that registry: cluster-api-provider-cargoship discovers the packages mirrored into it -- see distro.ListMirrored -- from a controller running inside the same cluster, and a second hand-rolled decode of zarf's state JSON in another module is the copy that drifts.

Index

Constants

View Source
const (
	ModeNodePort = "nodeport"
	ModeProxy    = "proxy"
	ModeExternal = "external"
)

Registry modes, matching state.RegistryMode. Only an external registry records an address that is reachable from somewhere other than a cluster node.

Variables

This section is empty.

Functions

func APIEndpoint

func APIEndpoint(kubeconfig, kubeContext string) (string, error)

APIEndpoint is the address a tunnel to the API server should open onto, derived from the kubeconfig's own server URL: the loopback address, and the port that URL names.

The port is read rather than assumed because it is the one piece of this that varies -- k3s and RKE2 both serve 6443, but a cluster behind a load balancer on another port records that, and guessing would tunnel to a closed port on the node. The host is loopback because the API server listens there on every control-plane node, which is what makes any controller do.

func LoadCABundle

func LoadCABundle(ctx context.Context, opts Options) ([]byte, error)

LoadCABundle reads the CA that signed the registry's server certificate.

A zarf-managed-mTLS registry serves HTTPS with a certificate from a private CA, so a push to it validates against nothing the system roots hold. This is the one piece of that puzzle not in zarf state, and reading it out of the cluster is what lets a mirror verify the registry properly rather than being told to skip verification.

No client certificate is read, and that is deliberate rather than an omission. Zarf issues one -- the `zarf-registry-client-tls` secret, common name `zarf-registry-client` -- but it belongs to the per-node registry proxy, which is what presents it on a node's behalf. The registry itself does not require one from a direct client, so a push authenticates with the push credentials from state and nothing more.

func RESTConfig

func RESTConfig(kubeconfig, kubeContext string) (*rest.Config, error)

RESTConfig resolves a kubeconfig path and a context name into a connection.

This goes through the deferred loading rules rather than clientcmd.BuildConfigFromFlags because that helper has no way to name a context -- it always takes whichever one the file marks current, which is the wrong cluster as soon as an operator has more than one.

It is exported because a caller reaching the cluster for something other than a secret has to resolve the same kubeconfig and the same context this package did, rather than loading its own and quietly disagreeing about which cluster is meant.

Types

type Options

type Options struct {
	// RESTConfig is the connection to read over, instead of resolving a kubeconfig. Setting it
	// makes Kubeconfig and Context moot.
	//
	// It exists for the caller that already holds a connection and has no kubeconfig to name:
	// a controller running inside the cluster is configured from its service account, and
	// pointing it at the standard kubeconfig location finds nothing there.
	//
	// It is copied before Dial is applied to it, so a config shared with the rest of a
	// caller's process is left as it was found.
	RESTConfig *rest.Config
	// Kubeconfig is the file to read. Empty takes the ambient configuration -- KUBECONFIG, else
	// the standard location.
	Kubeconfig string
	// Context is the context within it. Empty takes whichever one it marks current.
	Context string
	// Dial, when set, carries the connection to the API server, which is how the state of a
	// cluster whose API this machine cannot route to is read -- see pkg/tunnel.
	//
	// The kubeconfig's server URL is deliberately left alone when this is set. TLS still
	// validates against the hostname it names, using the CA it names, so the credentials keep
	// working and no certificate SAN has to cover the address actually dialled. The kubeconfig
	// supplies the identity; Dial supplies the route.
	Dial func(ctx context.Context, network, address string) (net.Conn, error)
}

Options say which cluster to read, and how to reach it.

type Registry

type Registry struct {
	Address      string `json:"address"`
	Port         int    `json:"port"`
	NodePort     int    `json:"nodePort"`
	PushUsername string `json:"pushUsername"`
	PushPassword string `json:"pushPassword"`
	// PullUsername and PullPassword are the read-only half, and are all a consumer that only
	// reads the registry needs -- listing what has been mirrored into it, and pulling a
	// package back out. decode still insists on the push credentials rather than these,
	// because zarf writes both and the push half is what a mirror cannot proceed without.
	PullUsername string `json:"pullUsername"`
	PullPassword string `json:"pullPassword"`
	Mode         string `json:"registryMode"`
	MTLSStrategy string `json:"mtlsStrategy"`
}

Registry is the part of Zarf's state a mirror needs: where the registry is, and how to authenticate a push to it.

The fields are declared here rather than taken from zarf's state.RegistryInfo because that package pulls src/api/convert, src/api/v1beta1, src/pkg/pki and src/pkg/utils in behind it, none of which is otherwise linked -- the transitive-import trap docs/agent/choice-coci-fork.md records. The json tags are the contract, and they are what has to keep matching.

shortcut: hand-rolled struct instead of zarf's state.RegistryInfo; switch to the import if zarf's state JSON shape changes or that package becomes linked for another reason.

func Load

func Load(ctx context.Context, opts Options) (Registry, error)

Load reads the registry half of the zarf-state secret.

func (Registry) IsExternal

func (r Registry) IsExternal() bool

IsExternal reports whether the registry runs outside the cluster, which is the one case where the recorded address is reachable from a management node. An internal registry is reached through a NodePort or a per-node host port, and Zarf itself tunnels to it.

An empty mode is how Zarf wrote state before it recorded one; it meant external whenever an address was set, which is the same rule state.RegistryInfo.FillInEmptyValues applies.

func (Registry) UsesMTLS

func (r Registry) UsesMTLS() bool

UsesMTLS reports whether Zarf manages mTLS certificates for the registry, in which case a push needs a client certificate this package does not read.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL