Documentation ¶
Overview ¶
Package regclient is used to access OCI registries
Index ¶
- Constants
- Variables
- type ImageOpts
- type Opt
- func WithBlobSize(chunk, max int64) Opt
- func WithCertDir(path ...string) Opt
- func WithConfigHost(configHost config.Host) Opt
- func WithConfigHosts(configHosts []config.Host) Opt
- func WithDockerCerts() Opt
- func WithDockerCreds() Opt
- func WithFS(fs rwfs.RWFS) Opt
- func WithLog(log *logrus.Logger) Opt
- func WithRetryDelay(delayInit, delayMax time.Duration) Opt
- func WithRetryLimit(retryLimit int) Opt
- func WithUserAgent(ua string) Opt
- type RegClient
- func (rc *RegClient) BlobCopy(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, d digest.Digest) error
- func (rc *RegClient) BlobDelete(ctx context.Context, r ref.Ref, d digest.Digest) error
- func (rc *RegClient) BlobGet(ctx context.Context, r ref.Ref, d digest.Digest) (blob.Reader, error)
- func (rc *RegClient) BlobGetOCIConfig(ctx context.Context, ref ref.Ref, d digest.Digest) (blob.OCIConfig, error)
- func (rc *RegClient) BlobHead(ctx context.Context, r ref.Ref, d digest.Digest) (blob.Reader, error)
- func (rc *RegClient) BlobMount(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, d digest.Digest) error
- func (rc *RegClient) BlobPut(ctx context.Context, ref ref.Ref, d digest.Digest, rdr io.Reader, cl int64) (digest.Digest, int64, error)
- func (rc *RegClient) Close(ctx context.Context, r ref.Ref) error
- func (rc *RegClient) ImageCopy(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, opts ...ImageOpts) error
- func (rc *RegClient) ImageExport(ctx context.Context, ref ref.Ref, outStream io.Writer) error
- func (rc *RegClient) ImageImport(ctx context.Context, ref ref.Ref, rs io.ReadSeeker) error
- func (rc *RegClient) ManifestDelete(ctx context.Context, r ref.Ref) error
- func (rc *RegClient) ManifestGet(ctx context.Context, r ref.Ref) (manifest.Manifest, error)
- func (rc *RegClient) ManifestHead(ctx context.Context, r ref.Ref) (manifest.Manifest, error)
- func (rc *RegClient) ManifestPut(ctx context.Context, r ref.Ref, m manifest.Manifest, ...) error
- func (rc *RegClient) RepoList(ctx context.Context, hostname string, opts ...scheme.RepoOpts) (*repo.RepoList, error)
- func (rc *RegClient) TagDelete(ctx context.Context, r ref.Ref) error
- func (rc *RegClient) TagList(ctx context.Context, r ref.Ref, opts ...scheme.TagOpts) (*tag.List, error)
Constants ¶
const ( // DefaultUserAgent sets the header on http requests DefaultUserAgent = "regclient/regclient" // DockerCertDir default location for docker certs DockerCertDir = "/etc/docker/certs.d" // DockerRegistry is the well known name of Docker Hub, "docker.io" DockerRegistry = config.DockerRegistry // DockerRegistryAuth is the name of Docker Hub seen in docker's config.json DockerRegistryAuth = config.DockerRegistryAuth // DockerRegistryDNS is the actual registry DNS name for Docker Hub DockerRegistryDNS = config.DockerRegistryDNS )
Variables ¶
var ( // VCSRef is populated from an embed at build time to the git reference VCSRef = "" // VCSTag is populated from an embed at build time to the git tag if defined VCSTag = "" )
Functions ¶
This section is empty.
Types ¶
type ImageOpts ¶
type ImageOpts func(*imageOpt)
ImageOpts define options for the Image* commands
func ImageWithDigestTags ¶
func ImageWithDigestTags() ImageOpts
ImageWithDigestTags looks for "sha-<digest>.*" tags in the repo to copy with any manifest. These are used by some artifact systems like sigstore/cosign.
func ImageWithForceRecursive ¶
func ImageWithForceRecursive() ImageOpts
ImageWithForceRecursive attemtps to copy every manifest and blob even if parent manifests already exist.
func ImageWithPlatforms ¶
ImageWithPlatforms only copies specific platforms from a manifest list. This will result in a failure on many registries that validate manifests. Use the empty string to indicate images without a platform definition should be copied.
type Opt ¶
type Opt func(*RegClient)
Opt functions are used to configure NewRegClient
func WithBlobSize ¶
WithBlobSize overrides default blob sizes
func WithCertDir ¶
WithCertDir adds a path of certificates to trust similar to Docker's /etc/docker/certs.d
func WithConfigHost ¶
WithConfigHost adds config host settings
func WithConfigHosts ¶
WithConfigHosts adds a list of config host settings
func WithDockerCerts ¶
func WithDockerCerts() Opt
WithDockerCerts adds certificates trusted by docker in /etc/docker/certs.d
func WithDockerCreds ¶
func WithDockerCreds() Opt
WithDockerCreds adds configuration from users docker config with registry logins This changes the default value from the config file, and should be added after the config file is loaded
func WithRetryDelay ¶
WithRetryDelay specifies the time permitted for retry delays
func WithRetryLimit ¶
WithRetryLimit specifies the number of retries for non-fatal errors
func WithUserAgent ¶
WithUserAgent specifies the User-Agent http header
type RegClient ¶
type RegClient struct {
// contains filtered or unexported fields
}
RegClient is used to access OCI distribution-spec registries
func (*RegClient) BlobCopy ¶
func (rc *RegClient) BlobCopy(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, d digest.Digest) error
BlobCopy copies a blob between two locations If the blob already exists in the target, the copy is skipped A server side cross repository blob mount is attempted
func (*RegClient) BlobDelete ¶
BlobDelete removes a blob from the registry This method should only be used to repair a damaged registry Typically a server side garbage collection should be used to purge unused blobs
func (*RegClient) BlobGetOCIConfig ¶
func (rc *RegClient) BlobGetOCIConfig(ctx context.Context, ref ref.Ref, d digest.Digest) (blob.OCIConfig, error)
BlobGetOCIConfig retrieves an OCI config from a blob, automatically extracting the JSON
func (*RegClient) BlobMount ¶
func (rc *RegClient) BlobMount(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, d digest.Digest) error
BlobMount attempts to perform a server side copy/mount of the blob between repositories
func (*RegClient) BlobPut ¶
func (rc *RegClient) BlobPut(ctx context.Context, ref ref.Ref, d digest.Digest, rdr io.Reader, cl int64) (digest.Digest, int64, error)
BlobPut uploads a blob to a repository. This will attempt an anonymous blob mount first which some registries may support. It will then try doing a full put of the blob without chunking (most widely supported). If the full put fails, it will fall back to a chunked upload (useful for flaky networks).
func (*RegClient) Close ¶
Close is used to free resources associated with a reference With ocidir, this may trigger a garbage collection process
func (*RegClient) ImageCopy ¶
func (rc *RegClient) ImageCopy(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, opts ...ImageOpts) error
ImageCopy copies an image This will retag an image in the same repository, only pushing and pulling the top level manifest On the same registry, it will attempt to use cross-repository blob mounts to avoid pulling blobs Blobs are only pulled when they don't exist on the target and a blob mount fails
func (*RegClient) ImageExport ¶
ImageExport exports an image to an output stream. The format is compatible with "docker load" if a single image is selected and not a manifest list. The ref must include a tag for exporting to docker (defaults to latest), and may also include a digest. The export is also formatted according to OCI layout which supports multi-platform images. <https://github.com/opencontainers/image-spec/blob/master/image-layout.md> A tar file will be sent to outStream.
Resulting filesystem: oci-layout: created at top level, can be done at the start index.json: created at top level, single descriptor with org.opencontainers.image.ref.name annotation pointing to the tag manifest.json: created at top level, based on every layer added, only works for a single arch image blobs/$algo/$hash: each content addressable object (manifest, config, or layer), created recursively
func (*RegClient) ImageImport ¶
ImageImport pushes an image from a tar file to a registry
func (*RegClient) ManifestDelete ¶
ManifestDelete removes a manifest, including all tags pointing to that registry The reference must include the digest to delete (see TagDelete for deleting a tag) All tags pointing to the manifest will be deleted
func (*RegClient) ManifestGet ¶
ManifestGet retrieves a manifest
func (*RegClient) ManifestHead ¶
ManifestHead queries for the existence of a manifest and returns metadata (digest, media-type, size)
func (*RegClient) ManifestPut ¶
func (rc *RegClient) ManifestPut(ctx context.Context, r ref.Ref, m manifest.Manifest, opts ...scheme.ManifestOpts) error
ManifestPut pushes a manifest Any descriptors referenced by the manifest typically need to be pushed first
func (*RegClient) RepoList ¶
func (rc *RegClient) RepoList(ctx context.Context, hostname string, opts ...scheme.RepoOpts) (*repo.RepoList, error)
RepoList returns a list of repositories on a registry Note the underlying "_catalog" API is not supported on many cloud registries
func (*RegClient) TagDelete ¶
TagDelete deletes a tag from the registry. Since there's no API for this, you'd want to normally just delete the manifest. However multiple tags may point to the same manifest, so instead you must: 1. Make a manifest, for this we put a few labels and timestamps to be unique. 2. Push that manifest to the tag. 3. Delete the digest for that new manifest that is only used by that tag.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
regbot/internal/go2lua
Package go2lua converts between go and Lua data structures
|
Package go2lua converts between go and Lua data structures |
regbot/sandbox
Package sandbox defines the Lua sandbox used to run user scripts
|
Package sandbox defines the Lua sandbox used to run user scripts |
Package config is used for all regclient configuration settings
|
Package config is used for all regclient configuration settings |
internal
|
|
auth
Package auth is used for HTTP authentication
|
Package auth is used for HTTP authentication |
reghttp
Package reghttp is used for HTTP requests to a registry
|
Package reghttp is used for HTTP requests to a registry |
reqresp
Package reqresp is used to create mock web servers for testing
|
Package reqresp is used to create mock web servers for testing |
retryable
Package retryable is a legacy package, functionality has been moved to reghttp
|
Package retryable is a legacy package, functionality has been moved to reghttp |
rwfs
Package rwfs implements a read-write filesystem, extending fs.FS
|
Package rwfs implements a read-write filesystem, extending fs.FS |
units
Package units is copied from https://github.com/docker/go-units
|
Package units is copied from https://github.com/docker/go-units |
wraperr
Package wraperr packages an error with another wrapped error This allows errors.Is to work without directly injecting the string of the wrapped error
|
Package wraperr packages an error with another wrapped error This allows errors.Is to work without directly injecting the string of the wrapped error |
pkg
|
|
archive
Package archive is used to read and write tar files
|
Package archive is used to read and write tar files |
template
Package template wraps a common set of templates around text/template
|
Package template wraps a common set of templates around text/template |
Package regclient is a legacy package, this has been moved to the top level regclient package
|
Package regclient is a legacy package, this has been moved to the top level regclient package |
blob
Package blob is a legacy package, this has been moved to the types/blob package
|
Package blob is a legacy package, this has been moved to the types/blob package |
config
Package config is a legacy package, this has been moved to the config package
|
Package config is a legacy package, this has been moved to the config package |
manifest
Package manifest is a legacy package, this has been moved to the types/manifest package
|
Package manifest is a legacy package, this has been moved to the types/manifest package |
types
Package types is a legacy package, using the top level types package is recommended
|
Package types is a legacy package, using the top level types package is recommended |
Package scheme defines the interface for various reference schemes
|
Package scheme defines the interface for various reference schemes |
ocidir
Package ocidir implements the OCI Image Layout scheme with a directory (not packed in a tar)
|
Package ocidir implements the OCI Image Layout scheme with a directory (not packed in a tar) |
reg
Package reg implements the OCI registry scheme used by most images (host:port/repo:tag)
|
Package reg implements the OCI registry scheme used by most images (host:port/repo:tag) |
Package types defines various types that have no other internal imports This allows them to be used between other packages without creating import loops
|
Package types defines various types that have no other internal imports This allows them to be used between other packages without creating import loops |
blob
Package blob is the underlying type for pushing and pulling blobs
|
Package blob is the underlying type for pushing and pulling blobs |
docker
Package docker defines the common types for all docker schemas
|
Package docker defines the common types for all docker schemas |
docker/schema1
Package schema1 defines the manifest and json marshal/unmarshal for docker schema1
|
Package schema1 defines the manifest and json marshal/unmarshal for docker schema1 |
docker/schema2
Package schema2 contains structs for Docker schema v2 manifests.
|
Package schema2 contains structs for Docker schema v2 manifests. |
manifest
Package manifest abstracts the various types of supported manifests.
|
Package manifest abstracts the various types of supported manifests. |
oci
Package oci defiles OCI image-spec types Package oci defines common settings for all OCI types
|
Package oci defiles OCI image-spec types Package oci defines common settings for all OCI types |
oci/v1
Package v1 defiles version 1 of OCI image-spec types
|
Package v1 defiles version 1 of OCI image-spec types |
platform
Package platform handles the parsing and comparing of the image platform (e.g.
|
Package platform handles the parsing and comparing of the image platform (e.g. |
ref
Package ref is used to define references References default to remote registry references (registry:port/repo:tag) Schemes can be included in front of the reference for different reference types
|
Package ref is used to define references References default to remote registry references (registry:port/repo:tag) Schemes can be included in front of the reference for different reference types |
repo
Package repo handles a list of repositories from a registry
|
Package repo handles a list of repositories from a registry |
tag
Package tag is used for wrapping tag lists
|
Package tag is used for wrapping tag lists |