registry

package
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Sep 16, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package registry manages the Stackr-hosted Docker registry (registry:2 with htpasswd auth) and external registry records.

Index

Constants

View Source
const (
	Issuer  = "stackr"
	Service = "stackr-registry"
	// TokenTTL is short on purpose: the credential is re-presented per pull and
	// push, so nothing needs a long-lived token, and a leaked one expires
	// before it is useful.
	TokenTTL = 5 * time.Minute
	// TokenPath is the route stackrd serves the exchange on, appended to the
	// panel's base URL to make the realm the registry advertises.
	TokenPath = "/v2/token"
)

Issuer and Service name this stackr in the tokens it mints. They must match the registry's REGISTRY_AUTH_TOKEN_ISSUER and _SERVICE or every token is refused with no useful message.

View Source
const (
	AgentUser = "stkr-agent"
	AgentRepo = "stkr-agent"
)

AgentUser and AgentRepo are the pull-only identity the node agent's service spec carries. The agent image lives outside every org's namespace, so it used to travel with the registry's root pair: a credential good for every org's images, on every node, permanently, because the agent is a global service.

View Source
const ServiceName = "stkr-registry"

ServiceName is the registry's swarm service, which is also the name it answers to on the stkr overlay.

View Source
const SystemCredentialName = "stackr"

SystemCredentialName is the credential stackr's own deploys push with. One per org, created on demand, not deletable: without it the org's next build has nothing to push with.

Variables

This section is empty.

Functions

func AgentSecret

func AgentSecret(registryPassword string) string

AgentSecret derives the agent's pull secret from the registry password, the same shape as systemSecret and for the same reason: nothing to store, and rotating the registry password rotates it.

func Auth

func Auth(orgSlug, secret, host string) string

Auth builds the base64 blob the Docker API takes in X-Registry-Auth, and swarm passes on to every node so a worker can pull the image itself. Without it a task placed on a worker pulls anonymously and the registry refuses it.

host is the address the caller dials: a push uses the manager's own localhost, a pull uses the address every node can reach.

func EncodeAuth

func EncodeAuth(reg *repo.Registry, host string) string

EncodeAuth builds the base64 credential blob swarm passes to every node so it can pull the image itself (the API's --with-registry-auth). Without it a task placed on a worker pulls anonymously and a private registry refuses it, on the manager only because the daemon there is already logged in.

host is the pull address, not the push one: it is what the node dials.

func EnsureManaged

func EnsureManaged(ctx context.Context, store repo.Store, rt *runtime.Runtime, signer *Signer, dataDir, port, baseURL string) (*repo.Registry, error)

EnsureManaged creates (if needed) and starts the managed registry service. It is reachable at localhost:<port>, inside Docker's default insecure-local allowance, so no TLS is needed for same-host pushes. A TLS domain through traefik (proxy.WriteRegistry) is what lets a worker pull without an insecure-registry entry. realm is where a docker client is sent to exchange a credential for a token. It has to be an address the *client* can reach, which for a build on the manager is stackrd's own listen address.

func EnsureSystemCredential

func EnsureSystemCredential(ctx context.Context, store repo.Store, reg *repo.Registry, org *repo.Org) (string, error)

EnsureSystemCredential returns the org's stackr-owned push secret, creating or repairing its row as needed.

func GarbageCollect

func GarbageCollect(ctx context.Context, rt *runtime.Runtime) (string, error)

GarbageCollect reclaims blobs no manifest references any more. Runs in the registry's own container: the storage driver is local to it.

func HashSecret

func HashSecret(raw string) string

HashSecret is how a credential's plaintext is stored and looked up. Same shape as an API key hash, deliberately: one rule for "a bearer string in this database is a hash".

func Namespace

func Namespace(orgSlug string) string

Namespace is the repository prefix one org owns: everything under it is theirs, and nothing outside it is reachable with their token.

Repositories are flat and underscore-joined: envnet.Scope.ImageRepo is stkr/<org>_<stack>_<tile> and deploy strips the stkr/ push prefix, so what the registry stores is <org>_<stack>_<tile>. Slugs are [a-z0-9-] only, so the trailing underscore is an unambiguous boundary: acme_ cannot match acme-evil_.

func OrgCredential

func OrgCredential(ctx context.Context, store repo.Store, t *repo.Tile) (*repo.Registry, *repo.Org, string, error)

OrgCredential resolves the org that owns a tile and its stackr-owned push secret, with the managed registry row. One place rather than per caller: a caller that reaches for the registry's root pair instead hands that node a credential good for every org's images.

func OrgHasImages

func OrgHasImages(ctx context.Context, store repo.Store, orgID string) (bool, error)

OrgHasImages reports whether anything has ever been pushed under the org's registry namespace.

Read from the deployments table rather than the registry's catalog API: the namespace is the org slug and the registry has no rename, so a rename would have to re-tag every image (a blob mount plus a manifest push per tag) or orphan them. Refusing the rename is the smaller thing to be right about, and refusing it needs an answer even while the registry is down.

walks the org's stacks and tiles. Tens of rows; add a store query if an org ever grows big enough to notice.

func OrgPullAuth

func OrgPullAuth(ctx context.Context, store repo.Store, rt *runtime.Runtime, t *repo.Tile) (string, string, error)

OrgPullAuth is the pull address and the org-scoped auth blob for a tile's image, which is what swarm hands the node that has to pull it.

func PanelAddr

func PanelAddr(reg *repo.Registry) string

PullAddr is the registry address every node can reach, which is not the same as the one the manager pushes to.

The managed registry's URL is localhost:<port>, and that is right for a push: it happens on the manager, and docker allows plain HTTP to localhost without an insecure-registries entry. It is wrong for anything a service spec references, "localhost" on a worker means the worker, which has no registry, and the task is rejected with "failed to resolve reference".

So: the TLS domain when the registry has one (traefik routes it and every node just works), otherwise the manager's own advertise address with the same port, which is exactly what the join script writes into the node's daemon.json insecure-registries. PanelAddr is how the panel's own process reaches the registry: the service name on the stkr overlay, resolved by docker's DNS.

Not reg.URL. That is localhost:<port>, which is exact on the manager's host, because the registry publishes its port in host mode, and wrong inside the panel's own container, where localhost is the panel. The panel is a swarm service like everything else stackr runs, so its catalog and manifest reads have to go over the overlay.

func PullAddr

func PullAddr(ctx context.Context, rt *runtime.Runtime, reg *repo.Registry) (string, error)

func ValidRepoName

func ValidRepoName(name string) bool

ValidRepoName is checkRepo for callers that want to refuse a name with their own status code rather than surfacing a registry error. The rail below stays, as the thing no caller can forget.

func ValidTag

func ValidTag(tag string) bool

ValidTag is ValidRepoName for a tag.

Types

type Access

type Access struct {
	Type    string   `json:"type"`
	Name    string   `json:"name"`
	Actions []string `json:"actions"`
}

Access is one repository the token grants, in the registry's own shape.

func GrantAgentPull

func GrantAgentPull(scopes []string) []Access

GrantAgentPull narrows what the agent identity may have to pulling its own image. Asking for anything else, including a push of it, gets nothing.

func GrantAll

func GrantAll(scopes []string) []Access

GrantAll hands back every scope the client asked for. Only the admin root credential gets this: the agent image and the garbage collector live outside any org's namespace, so a token scoped to one org cannot reach them.

func GrantFor

func GrantFor(orgSlug string, scopes []string) []Access

GrantFor narrows a requested scope to what the org may actually have. The registry sends what the client asked for; answering with a token that contains it unchanged is exactly the hole this replaces.

scopes are the raw `scope` query values, each "repository:<name>:<action>[,<action>]". Anything outside the org's namespace is dropped rather than refused: the registry turns a missing grant into its own 401, which is the message a docker client knows how to render.

type Client

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

Client reads the registry's v2 API as the admin root credential. Only the panel uses it: a tenant's view is filtered by namespace before it is rendered, never by asking the registry nicely.

func NewClient

func NewClient(reg *repo.Registry, signer *Signer) *Client

NewClient talks to the registry over the stkr overlay (PanelAddr), so no TLS and no proxy hop. Not the push address: that is localhost:<port>, which is the manager's host and not the inside of the panel's own container. The signer is what mints the tokens it authenticates with: the registry runs REGISTRY_AUTH=token and no longer answers basic auth at all. A nil signer makes every call fail with that said, rather than 401ing with nothing to explain it.

func (*Client) DeleteTag

func (c *Client) DeleteTag(ctx context.Context, name, tag string) error

DeleteTag removes a tag's manifest. The blobs stay until the next garbage collection, which rides the admin maintenance cleanup toggle.

func (*Client) Images

func (c *Client) Images(ctx context.Context, orgSlug string) ([]string, error)

Images lists the repositories inside one org's namespace, shortest first.

func (*Client) Tag

func (c *Client) Tag(ctx context.Context, name, tag string) (TagInfo, error)

Tag reads one tag's manifest: the digest a delete needs, and the size of the layers it accounts for.

func (*Client) Tags

func (c *Client) Tags(ctx context.Context, name string) ([]string, error)

Tags lists one repository's tags. name is the full repository path, which the caller must already have checked belongs to the org it is rendering.

type Signer

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

Signer mints registry tokens. One per process, loaded from (or created in) the data directory so a restart does not invalidate the registry's root bundle.

func LoadSigner

func LoadSigner(dir string) (*Signer, error)

LoadSigner reads the token keypair from dir, creating a self-signed one on first run. The certificate is what the registry container mounts as its rootcertbundle, so the two halves have to come from the same place.

func (*Signer) Sign

func (s *Signer) Sign(subject string, access []Access) (string, time.Time, error)

Sign mints a token for subject with the given access set. An empty access set is still a valid token: that is how the registry's own /v2/ ping succeeds for a caller who has authenticated but asked for nothing.

type TagInfo

type TagInfo struct {
	Tag    string    `json:"tag"`
	Digest string    `json:"digest"`
	Size   int64     `json:"size"`
	Pushed time.Time `json:"pushed,omitempty"`
}

TagInfo is what the panel shows per tag.

Jump to

Keyboard shortcuts

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