Help us shape the future of Go! Take the 2026 Go Developer Survey

azurecontainerregistry

package
v1.9.0 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 36 Imported by: 0

README

Azure Container Registry

Parity grade: B · SDK azure-sdk-for-go/sdk/resourcemanager/containerregistry/armcontainerregistry@v1.2.0 · last audited 2026-10-22 (364908f83)

Coverage

Metric Value
PARITY entries audited 24 (24 ok)
Feature families 5 (5 ok)
Known gaps 10
Deferred items 0
Resource leaks partial
Known gaps
  • Access-token scopes are enforced on /v2 only; the /acr/v1 metadata API accepts any valid token.
  • The listener is plain HTTP unless --azure-acr-tls-cert/--azure-acr-tls-key are set, so az acr login and docker only trust it as an insecure or localhost registry.
  • Anonymous pull, repository-scoped tokens, scope maps and tokens, connected registries, cache rules, credential sets, agent pools and tasks are not modelled.
  • ARM importImage, listUsages, listPrivateLinkResources, private endpoint connections, customer-managed keys, network rules and policies other than their defaults are stored or defaulted but have no effect.
  • Webhooks: no retries, the quarantine action never fires, each webhook keeps its last 100 events, and ARM webhook PATCH is not implemented (PUT replaces).
  • Replications are metadata only: there is one copy of the data.
  • Blobs unreferenced by any manifest are never garbage collected, and registry size is not metered.
  • Content trust, quarantine and retention policies are not implemented; quarantineState is always Passed and signed is always false.
  • Each registry's embedded distribution library leaves one go-events broadcaster goroutine running until process exit.
  • No dashboard page.

More

Documentation

Overview

Package azurecontainerregistry emulates the Azure Container Registry data plane: a Docker Registry v2 API per registry, the OAuth2 refresh and access token endpoints az acr login uses, admin-user Basic authentication and the /acr/v1 repository, tag and manifest metadata API. Registries are created through the ARM Microsoft.ContainerRegistry provider, which shares their credentials. See PARITY.md.

Index

Constants

View Source
const DefaultPort = 10011

DefaultPort is the registry data plane's TCP port.

View Source
const NullUsername = "00000000-0000-0000-0000-000000000000"

NullUsername is the username registry clients send with a refresh token as the password.

Variables

View Source
var (
	ErrRegistryNotFound = errors.New("azurecontainerregistry: registry not found")
	ErrInvalidName      = errors.New("azurecontainerregistry: invalid registry name")
	ErrAdminDisabled    = errors.New("azurecontainerregistry: admin user is not enabled")
	ErrInvalidCred      = errors.New("azurecontainerregistry: credential name must be password or password2")
	ErrWebhookNotFound  = errors.New("azurecontainerregistry: webhook not found")
	ErrNilAppContext    = errors.New("azurecontainerregistry: nil app context")
	ErrNotFound         = errors.New("azurecontainerregistry: not found")
	ErrDenied           = errors.New("azurecontainerregistry: operation is disabled by the resource's attributes")
	ErrTLSKeyMissing    = errors.New("azurecontainerregistry: --azure-acr-tls-cert set without --azure-acr-tls-key")
	ErrTLSCertMissing   = errors.New("azurecontainerregistry: --azure-acr-tls-key set without --azure-acr-tls-cert")
)

Backend errors.

Functions

func SelfSignedConfig

func SelfSignedConfig() (*tls.Config, error)

SelfSignedConfig returns a TLS config with a generated certificate, for callers that want HTTPS in tests.

Types

type AttrPatch

type AttrPatch struct {
	Delete *bool
	Write  *bool
	Read   *bool
	List   *bool
}

AttrPatch carries the attributes a PATCH sets; nil leaves one unchanged.

type ConfigProvider

type ConfigProvider interface {
	GetAzureACRSettings() Settings
}

ConfigProvider extracts the Container Registry settings from the AppContext config.

type Credentials

type Credentials struct {
	Username  string
	Password1 string
	Password2 string
}

Credentials are a registry's admin-user credentials.

type DataDirConfig

type DataDirConfig interface {
	GetRegistryDataDir() string
}

DataDirConfig locates the directory registry blobs are kept in; empty keeps them in memory.

type EventContent

type EventContent struct {
	Target    *EventTarget  `json:"target,omitempty"`
	Request   *EventRequest `json:"request,omitempty"`
	ID        string        `json:"id"`
	Timestamp string        `json:"timestamp"`
	Action    string        `json:"action"`
}

EventContent is the JSON body posted to a webhook's service URI.

type EventRequest

type EventRequest struct {
	ID        string `json:"id"`
	Host      string `json:"host"`
	Method    string `json:"method"`
	Useragent string `json:"useragent"`
}

EventRequest is the registry request that caused an event.

type EventRequestMessage

type EventRequestMessage struct {
	Headers    map[string]string `json:"headers"`
	Content    EventContent      `json:"content"`
	Method     string            `json:"method"`
	RequestURI string            `json:"requestUri"`
	Version    string            `json:"version"`
}

EventRequestMessage is the HTTP request delivered to the service URI.

type EventResponseMessage

type EventResponseMessage struct {
	Headers      map[string]string `json:"headers"`
	Content      string            `json:"content"`
	ReasonPhrase string            `json:"reasonPhrase"`
	StatusCode   string            `json:"statusCode,omitempty"`
	Version      string            `json:"version"`
}

EventResponseMessage is the service URI's HTTP response.

type EventTarget

type EventTarget struct {
	MediaType  string `json:"mediaType,omitempty"`
	Digest     string `json:"digest,omitempty"`
	Repository string `json:"repository,omitempty"`
	Tag        string `json:"tag,omitempty"`
	Size       int64  `json:"size,omitempty"`
	Length     int64  `json:"length,omitempty"`
}

EventTarget is the artifact an event is about.

type Forgotten

type Forgotten struct {
	Digests []string
	Tags    []string
}

Forgotten lists what ForgetRepository removed.

type Handler

type Handler struct {
	Backend *InMemoryBackend

	Settings Settings
	Port     int
	// contains filtered or unexported fields
}

Handler owns the registry listener.

func NewHandler

func NewHandler(backend *InMemoryBackend, settings Settings) *Handler

NewHandler returns a Handler over backend.

func (*Handler) ExtractOperation

func (h *Handler) ExtractOperation(*echo.Context) string

ExtractOperation implements service.Service.

func (*Handler) ExtractResource

func (h *Handler) ExtractResource(*echo.Context) string

ExtractResource implements service.Service.

func (*Handler) GetSupportedOperations

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations implements service.Service.

func (*Handler) Handler

func (h *Handler) Handler() echo.HandlerFunc

Handler returns a 404 handler; the real API is on the dedicated port.

func (*Handler) MatchPriority

func (h *Handler) MatchPriority() int

MatchPriority implements service.Registerable.

func (*Handler) Name

func (h *Handler) Name() string

Name implements service.Service.

func (*Handler) Reset

func (h *Handler) Reset()

Reset implements service.Resettable.

func (*Handler) Restore

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher never matches: the registry listens on its own port.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP routes a request to the registry, token or metadata API.

func (*Handler) Shutdown

func (h *Handler) Shutdown(ctx context.Context)

Shutdown implements service.Shutdowner.

func (*Handler) Snapshot

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker binds the listener synchronously so a port conflict is returned to the caller.

type InMemoryBackend

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

InMemoryBackend holds every registry's control-plane state under one lock; blobs and manifests live in per-registry ociregistry handlers.

func NewInMemoryBackend

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend that keeps blobs in memory.

func (*InMemoryBackend) Allowed

func (b *InMemoryBackend) Allowed(reg, repo, ref, op string) bool

Allowed reports whether op (read, write or delete) may touch repo:ref.

func (*InMemoryBackend) Close

func (b *InMemoryBackend) Close()

Close stops webhook deliveries and releases every registry's storage handler without deleting stored images.

func (*InMemoryBackend) Credentials

func (b *InMemoryBackend) Credentials(name string) (Credentials, error)

Credentials returns the admin credentials; the admin user must be enabled.

func (*InMemoryBackend) DeleteRegistry

func (b *InMemoryBackend) DeleteRegistry(name string) error

DeleteRegistry removes the registry with its repositories, blobs and manifests.

func (*InMemoryBackend) DeleteWebhook

func (b *InMemoryBackend) DeleteWebhook(reg, name string) error

DeleteWebhook removes the webhook with its events; a missing one is not an error.

func (*InMemoryBackend) FireManifest

func (b *InMemoryBackend) FireManifest(reg string, c ManifestChange)

FireManifest delivers the change to every enabled webhook of reg whose actions and scope match.

func (*InMemoryBackend) ForgetRepository

func (b *InMemoryBackend) ForgetRepository(reg, repo string) (Forgotten, bool)

ForgetRepository drops a repository's metadata and returns the digests and tags it held.

func (*InMemoryBackend) HasWebhooks

func (b *InMemoryBackend) HasWebhooks(reg string) bool

HasWebhooks reports whether reg has any webhook.

func (*InMemoryBackend) IssueAccessToken

func (b *InMemoryBackend) IssueAccessToken(reg, audience string, scopes []string) (string, error)

IssueAccessToken mints a registry access token for the requested scopes.

func (*InMemoryBackend) IssueRefreshToken

func (b *InMemoryBackend) IssueRefreshToken(reg, audience string) (string, error)

IssueRefreshToken mints the refresh token az acr login exchanges an Entra ID token for.

func (*InMemoryBackend) Manifests

func (b *InMemoryBackend) Manifests(reg, repo string) ([]ManifestView, bool)

Manifests lists a repository's manifests in lexical digest order.

func (*InMemoryBackend) Names

func (b *InMemoryBackend) Names() []string

Names lists registry names, in lookup order of the single-registry fallback.

func (*InMemoryBackend) PatchManifest

func (b *InMemoryBackend) PatchManifest(reg, repo, digest string, p AttrPatch) error

PatchManifest updates a manifest's attributes.

func (*InMemoryBackend) PatchRepository

func (b *InMemoryBackend) PatchRepository(reg, repo string, p AttrPatch) error

PatchRepository updates a repository's attributes.

func (*InMemoryBackend) PatchTag

func (b *InMemoryBackend) PatchTag(reg, repo, tag string, p AttrPatch) error

PatchTag updates a tag's attributes.

func (*InMemoryBackend) PingWebhook

func (b *InMemoryBackend) PingWebhook(reg, name string) (string, error)

PingWebhook delivers a ping event to the webhook and returns the event id.

func (*InMemoryBackend) PutRegistry

func (b *InMemoryBackend) PutRegistry(name string, adminEnabled bool) (RegistryInfo, error)

PutRegistry creates the registry or updates its admin-user flag.

func (*InMemoryBackend) RecordManifestDelete

func (b *InMemoryBackend) RecordManifestDelete(reg, repo, ref string)

RecordManifestDelete forgets a deleted manifest with its tags, or just the tag when ref is one.

func (*InMemoryBackend) RecordManifestPut

func (b *InMemoryBackend) RecordManifestPut(reg, repo, ref, digest string)

RecordManifestPut notes a stored manifest, and the tag when ref is one.

func (*InMemoryBackend) RegenerateCredential

func (b *InMemoryBackend) RegenerateCredential(name, which string) (Credentials, error)

RegenerateCredential replaces the "password" or "password2" credential and returns both.

func (*InMemoryBackend) Registry

func (b *InMemoryBackend) Registry(name string) (RegistryInfo, bool)

Registry returns the registry named name.

func (*InMemoryBackend) Repositories

func (b *InMemoryBackend) Repositories(reg string) []RepoView

Repositories lists the repositories holding at least one manifest, in lexical order.

func (*InMemoryBackend) Repository

func (b *InMemoryBackend) Repository(reg, repo string) (RepoView, bool)

Repository returns one repository's entry.

func (*InMemoryBackend) Reset

func (b *InMemoryBackend) Reset()

Reset removes every registry and its stored images.

func (*InMemoryBackend) Restore

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads a snapshot, replacing every registry.

func (*InMemoryBackend) SetContext

func (b *InMemoryBackend) SetContext(ctx context.Context)

SetContext bounds the lifetime of the registries the backend builds.

func (*InMemoryBackend) SetDataDir

func (b *InMemoryBackend) SetDataDir(dir string)

SetDataDir keeps registry blobs under dir (one subdirectory per registry); empty keeps them in memory.

func (*InMemoryBackend) SetWebhook

func (b *InMemoryBackend) SetWebhook(reg string, w Webhook) error

SetWebhook creates or replaces the webhook, keeping the events it already recorded.

func (*InMemoryBackend) Snapshot

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises registries, credentials and image metadata. Blobs and manifests are not part of it: they live under the data directory when one is configured.

func (*InMemoryBackend) Tags

func (b *InMemoryBackend) Tags(reg, repo string) ([]TagView, bool)

Tags lists a repository's tags in lexical order.

func (*InMemoryBackend) VerifyAccess

func (b *InMemoryBackend) VerifyAccess(tok, reg string) bool

VerifyAccess reports whether tok is an unexpired access token of reg.

func (*InMemoryBackend) VerifyAdmin

func (b *InMemoryBackend) VerifyAdmin(reg, user, password string) bool

VerifyAdmin reports whether user and password are the registry's enabled admin credentials.

func (*InMemoryBackend) VerifyRefresh

func (b *InMemoryBackend) VerifyRefresh(tok, reg string) bool

VerifyRefresh reports whether tok is an unexpired refresh token of reg.

func (*InMemoryBackend) WebhookEvents

func (b *InMemoryBackend) WebhookEvents(reg, name string) ([]WebhookEvent, error)

WebhookEvents returns the webhook's recorded deliveries, oldest first.

type ManifestChange

type ManifestChange struct {
	Req        RequestInfo
	Repository string
	Tag        string
	Digest     string
	MediaType  string
	ConfigType string
	Size       int64
	Delete     bool
}

ManifestChange is a manifest push or delete the registry observed.

type ManifestView

type ManifestView struct {
	Created time.Time
	Updated time.Time
	Digest  string
	Tags    []string
	Attrs   attrs
}

ManifestView is a manifest's listing entry.

type Provider

type Provider struct{}

Provider implements service.Provider for Azure Container Registry.

func (*Provider) Init

Init builds the backend and handler; the port is bound by Handler.StartWorker.

func (*Provider) Name

func (p *Provider) Name() string

Name returns the service provider name.

type RegistryInfo

type RegistryInfo struct {
	CreatedAt    time.Time
	Name         string
	AdminEnabled bool
}

RegistryInfo is the control-plane view of a registry.

type RepoView

type RepoView struct {
	Created       time.Time
	Updated       time.Time
	Name          string
	Attrs         attrs
	ManifestCount int
	TagCount      int
}

RepoView is a repository's listing entry.

type RequestInfo

type RequestInfo struct {
	ID        string
	Host      string
	Method    string
	Useragent string
}

RequestInfo describes the registry request behind a manifest event.

type Settings

type Settings struct {
	TLSCertFile string `` //nolint:lll // config struct tags are intentionally verbose
	/* 222-byte string literal not displayed */
	TLSKeyFile string `json:"tlsKeyFile"  env:"AZURE_ACR_TLS_KEY"  name:"tls-key"  help:"Path to the PEM key matching --azure-acr-tls-cert."` //nolint:lll // config struct tags are intentionally verbose
	Port       int    ``                                                                                                                      //nolint:lll // config struct tags are intentionally verbose
	/* 238-byte string literal not displayed */
}

Settings is the Kong-embedded configuration of the Azure Container Registry emulator.

func DefaultSettings

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider exists.

type TagView

type TagView struct {
	Created time.Time
	Updated time.Time
	Name    string
	Digest  string
	Attrs   attrs
}

TagView is a tag's listing entry.

type Webhook

type Webhook struct {
	Headers    map[string]string `json:"headers,omitempty"`
	Name       string            `json:"name"`
	ServiceURI string            `json:"serviceUri"`
	Scope      string            `json:"scope,omitempty"`
	Status     string            `json:"status"`
	Actions    []string          `json:"actions"`
}

Webhook is a registry webhook fired on image and chart pushes and deletes.

type WebhookEvent

type WebhookEvent struct {
	EventResponseMessage *EventResponseMessage `json:"eventResponseMessage,omitempty"`
	ID                   string                `json:"id"`
	EventRequestMessage  EventRequestMessage   `json:"eventRequestMessage"`
}

WebhookEvent is one recorded delivery attempt.

Jump to

Keyboard shortcuts

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