Documentation ¶
Overview ¶
Package regclient is used to access OCI registries.
Index ¶
- Constants
- type BlobOpts
- type ImageOpts
- func ImageWithCallback(...) ImageOpts
- func ImageWithCheckBaseDigest(d string) ImageOpts
- func ImageWithCheckBaseRef(r string) ImageOpts
- func ImageWithCheckSkipConfig() ImageOpts
- func ImageWithChild() ImageOpts
- func ImageWithDigestTags() ImageOpts
- func ImageWithExportCompress() ImageOpts
- func ImageWithExportRef(r ref.Ref) ImageOpts
- func ImageWithFastCheck() ImageOpts
- func ImageWithForceRecursive() ImageOpts
- func ImageWithImportName(name string) ImageOpts
- func ImageWithIncludeExternal() ImageOpts
- func ImageWithPlatform(p string) ImageOpts
- func ImageWithPlatforms(p []string) ImageOpts
- func ImageWithReferrers(rOpts ...scheme.ReferrerOpts) ImageOpts
- type ManifestOpts
- type Opt
- func WithBlobLimit(limit int64) Optdeprecated
- func WithBlobSize(chunk, max int64) Optdeprecated
- func WithCertDir(path ...string) Optdeprecated
- func WithConfigHost(configHost ...config.Host) Opt
- func WithConfigHosts(configHosts []config.Host) Optdeprecated
- func WithDockerCerts() Opt
- func WithDockerCreds() Opt
- func WithFS(fs rwfs.RWFS) Opt
- func WithLog(log *logrus.Logger) Opt
- func WithRegOpts(opts ...reg.Opts) Opt
- func WithRetryDelay(delayInit, delayMax time.Duration) Optdeprecated
- func WithRetryLimit(retryLimit int) Optdeprecated
- func WithUserAgent(ua string) Opt
- type RegClient
- func (rc *RegClient) BlobCopy(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, d types.Descriptor, ...) error
- func (rc *RegClient) BlobDelete(ctx context.Context, r ref.Ref, d types.Descriptor) error
- func (rc *RegClient) BlobGet(ctx context.Context, r ref.Ref, d types.Descriptor) (blob.Reader, error)
- func (rc *RegClient) BlobGetOCIConfig(ctx context.Context, r ref.Ref, d types.Descriptor) (blob.OCIConfig, error)
- func (rc *RegClient) BlobHead(ctx context.Context, r ref.Ref, d types.Descriptor) (blob.Reader, error)
- func (rc *RegClient) BlobMount(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, d types.Descriptor) error
- func (rc *RegClient) BlobPut(ctx context.Context, r ref.Ref, d types.Descriptor, rdr io.Reader) (types.Descriptor, error)
- func (rc *RegClient) Close(ctx context.Context, r ref.Ref) error
- func (rc *RegClient) ImageCheckBase(ctx context.Context, r ref.Ref, opts ...ImageOpts) error
- func (rc *RegClient) ImageCopy(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, opts ...ImageOpts) error
- func (rc *RegClient) ImageExport(ctx context.Context, r ref.Ref, outStream io.Writer, opts ...ImageOpts) error
- func (rc *RegClient) ImageImport(ctx context.Context, r ref.Ref, rs io.ReadSeeker, opts ...ImageOpts) error
- func (rc *RegClient) ManifestDelete(ctx context.Context, r ref.Ref, opts ...ManifestOpts) error
- func (rc *RegClient) ManifestGet(ctx context.Context, r ref.Ref, opts ...ManifestOpts) (manifest.Manifest, error)
- func (rc *RegClient) ManifestHead(ctx context.Context, r ref.Ref, opts ...ManifestOpts) (manifest.Manifest, error)
- func (rc *RegClient) ManifestPut(ctx context.Context, r ref.Ref, m manifest.Manifest, opts ...ManifestOpts) error
- func (rc *RegClient) Ping(ctx context.Context, r ref.Ref) (ping.Result, error)
- func (rc *RegClient) ReferrerList(ctx context.Context, r ref.Ref, opts ...scheme.ReferrerOpts) (referrer.ReferrerList, 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 ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BlobOpts ¶ added in v0.5.0
type BlobOpts func(*blobOpt)
BlobOpts define options for the Image* commands.
func BlobWithCallback ¶ added in v0.5.0
func BlobWithCallback(callback func(kind types.CallbackKind, instance string, state types.CallbackState, cur, total int64)) BlobOpts
BlobWithCallback provides progress data to a callback function.
type ImageOpts ¶
type ImageOpts func(*imageOpt)
ImageOpts define options for the Image* commands.
func ImageWithCallback ¶ added in v0.5.0
func ImageWithCallback(callback func(kind types.CallbackKind, instance string, state types.CallbackState, cur, total int64)) ImageOpts
ImageWithCallback provides progress data to a callback function.
func ImageWithCheckBaseDigest ¶ added in v0.4.5
ImageWithCheckBaseDigest provides a base digest to compare in ImageCheckBase.
func ImageWithCheckBaseRef ¶ added in v0.4.5
ImageWithCheckBaseRef provides a base reference to compare in ImageCheckBase.
func ImageWithCheckSkipConfig ¶ added in v0.4.5
func ImageWithCheckSkipConfig() ImageOpts
ImageWithCheckSkipConfig skips the configuration check in ImageCheckBase.
func ImageWithChild ¶ added in v0.4.4
func ImageWithChild() ImageOpts
ImageWithChild attempts to copy every manifest and blob even if parent manifests already exist in ImageCopy.
func ImageWithDigestTags ¶
func ImageWithDigestTags() ImageOpts
ImageWithDigestTags looks for "sha-<digest>.*" tags in the repo to copy with any manifest in ImageCopy. These are used by some artifact systems like sigstore/cosign.
func ImageWithExportCompress ¶ added in v0.5.2
func ImageWithExportCompress() ImageOpts
ImageWithExportCompress adds gzip compression to tar export output in ImageExport.
func ImageWithExportRef ¶ added in v0.4.8
ImageWithExportRef overrides the image name embedded in the export file in ImageExport.
func ImageWithFastCheck ¶ added in v0.5.0
func ImageWithFastCheck() ImageOpts
ImageWithFastCheck skips check for referrers when manifest has already been copied in ImageCopy.
func ImageWithForceRecursive ¶
func ImageWithForceRecursive() ImageOpts
ImageWithForceRecursive attempts to copy every manifest and blob even if parent manifests already exist in ImageCopy.
func ImageWithImportName ¶ added in v0.5.0
ImageWithImportName selects the name of the image to import when multiple images are included in ImageImport.
func ImageWithIncludeExternal ¶ added in v0.4.3
func ImageWithIncludeExternal() ImageOpts
ImageWithIncludeExternal attempts to copy every manifest and blob even if parent manifests already exist in ImageCopy.
func ImageWithPlatform ¶ added in v0.4.5
ImageWithPlatform requests specific platforms from a manifest list in ImageCheckBase.
func ImageWithPlatforms ¶
ImageWithPlatforms only copies specific platforms from a manifest list in ImageCopy. 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.
func ImageWithReferrers ¶ added in v0.4.3
func ImageWithReferrers(rOpts ...scheme.ReferrerOpts) ImageOpts
ImageWithReferrers recursively recursively includes referrer images in ImageCopy.
type ManifestOpts ¶ added in v0.4.1
type ManifestOpts func(*manifestOpt)
ManifestOpts define options for the Manifest* commands.
func WithManifest ¶ added in v0.4.5
func WithManifest(m manifest.Manifest) ManifestOpts
WithManifest passes a manifest to ManifestDelete.
func WithManifestCheckReferrers ¶ added in v0.4.5
func WithManifestCheckReferrers() ManifestOpts
WithManifestCheckReferrers checks for referrers field on ManifestDelete. This will update the client managed referrer listing.
func WithManifestChild ¶ added in v0.4.5
func WithManifestChild() ManifestOpts
WithManifestChild for ManifestPut indicates the manifest is not the top level manifest being copied. This is used by the ocidir scheme to determine what entries to include in the index.json.
func WithManifestDesc ¶ added in v0.4.5
func WithManifestDesc(d types.Descriptor) ManifestOpts
WithManifestDesc includes the descriptor for ManifestGet. This is used to automatically extract a Data field if available.
func WithManifestRequireDigest ¶ added in v0.4.6
func WithManifestRequireDigest() ManifestOpts
WithManifestRequireDigest falls back from a HEAD to a GET request when digest headers aren't received.
type Opt ¶
type Opt func(*RegClient)
Opt functions are used by New to create a *RegClient.
func WithBlobLimit
deprecated
added in
v0.4.8
WithBlobLimit sets the max size for chunked blob uploads which get stored in memory.
Deprecated: replace with WithRegOpts(reg.WithBlobLimit(limit)), see WithRegOpts and reg.WithBlobLimit.
func WithBlobSize
deprecated
WithBlobSize overrides default blob sizes.
Deprecated: replace with WithRegOpts(reg.WithBlobSize(chunk, max)), see WithRegOpts and reg.WithBlobSize.
func WithCertDir
deprecated
WithCertDir adds a path of certificates to trust similar to Docker's /etc/docker/certs.d.
Deprecated: replace with WithRegOpts(reg.WithCertDirs(path)), see WithRegOpts and reg.WithCertDirs.
func WithConfigHost ¶
WithConfigHost adds a list of config host settings.
func WithConfigHosts
deprecated
WithConfigHosts adds a list of config host settings.
Deprecated: replace with WithConfigHost.
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 WithRegOpts ¶ added in v0.4.8
WithRegOpts passes through opts to the reg scheme.
func WithRetryDelay
deprecated
WithRetryDelay specifies the time permitted for retry delays.
Deprecated: replace with WithRegOpts(reg.WithDelay(delayInit, delayMax)), see WithRegOpts and reg.WithDelay.
func WithRetryLimit
deprecated
WithRetryLimit specifies the number of retries for non-fatal errors.
Deprecated: replace with WithRegOpts(reg.WithRetryLimit(retryLimit)), see WithRegOpts and reg.WithRetryLimit.
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 types.Descriptor, opts ...BlobOpts) 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) BlobGet ¶
func (rc *RegClient) BlobGet(ctx context.Context, r ref.Ref, d types.Descriptor) (blob.Reader, error)
BlobGet retrieves a blob, returning a reader. This reader must be closed to free up resources that limit concurrent pulls.
func (*RegClient) BlobGetOCIConfig ¶
func (rc *RegClient) BlobGetOCIConfig(ctx context.Context, r ref.Ref, d types.Descriptor) (blob.OCIConfig, error)
BlobGetOCIConfig retrieves an OCI config from a blob, automatically extracting the JSON.
func (*RegClient) BlobHead ¶
func (rc *RegClient) BlobHead(ctx context.Context, r ref.Ref, d types.Descriptor) (blob.Reader, error)
BlobHead is used to verify if a blob exists and is accessible.
func (*RegClient) BlobMount ¶
func (rc *RegClient) BlobMount(ctx context.Context, refSrc ref.Ref, refTgt ref.Ref, d types.Descriptor) 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, r ref.Ref, d types.Descriptor, rdr io.Reader) (types.Descriptor, error)
BlobPut uploads a blob to a repository. Descriptor is optional, leave size and digest to zero value if unknown. Reader must also be an io.Seeker to support chunked upload fallback.
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) ImageCheckBase ¶ added in v0.4.5
ImageCheckBase returns nil if the base image is unchanged. A base image mismatch returns an error that wraps types.ErrMismatch.
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. Referrers are optionally copied recursively.
func (*RegClient) ImageExport ¶
func (rc *RegClient) ImageExport(ctx context.Context, r ref.Ref, outStream io.Writer, opts ...ImageOpts) error
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. 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 ¶
func (rc *RegClient) ImageImport(ctx context.Context, r ref.Ref, rs io.ReadSeeker, opts ...ImageOpts) error
ImageImport pushes an image from a tar file (ImageExport) 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 ¶
func (rc *RegClient) ManifestGet(ctx context.Context, r ref.Ref, opts ...ManifestOpts) (manifest.Manifest, error)
ManifestGet retrieves a manifest.
func (*RegClient) ManifestHead ¶
func (rc *RegClient) ManifestHead(ctx context.Context, r ref.Ref, opts ...ManifestOpts) (manifest.Manifest, error)
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 ...ManifestOpts) error
ManifestPut pushes a manifest. Any descriptors referenced by the manifest typically need to be pushed first.
func (*RegClient) ReferrerList ¶ added in v0.4.3
func (rc *RegClient) ReferrerList(ctx context.Context, r ref.Ref, opts ...scheme.ReferrerOpts) (referrer.ReferrerList, error)
ReferrerList retrieves a list of referrers to a manifest. The descriptor list should contain manifests that each have a subject field matching the requested ref.
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
|
|
ascii
Package ascii is used to output asci content to a terminal
|
Package ascii is used to output asci content to a terminal |
auth
Package auth is used for HTTP authentication
|
Package auth is used for HTTP authentication |
cache
Package cache is used to store values with limits.
|
Package cache is used to store values with limits. |
conffile
Package conffile wraps the read and write of configuration files
|
Package conffile wraps the read and write of configuration files |
diff
Package diff computes the efficient set of changes (insert/delete) between two arrays of strings
|
Package diff computes the efficient set of changes (insert/delete) between two arrays of strings |
godbg
Package godbg provides tooling for debugging Go
|
Package godbg provides tooling for debugging Go |
httplink
Package httplink parses the Link header from HTTP responses according to RFC5988
|
Package httplink parses the Link header from HTTP responses according to RFC5988 |
limitread
Package limitread provides a reader that will error if the limit is ever exceeded
|
Package limitread provides a reader that will error if the limit is ever exceeded |
muset
Package muset is used to acquire a group of mutex locks
|
Package muset is used to acquire a group of mutex locks |
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 |
strparse
Package strparse is used to parse strings
|
Package strparse is used to parse strings |
throttle
Package throttle is used to limit concurrent activities
|
Package throttle is used to limit concurrent activities |
timejson
Package timejson extends time methods with marshal/unmarshal for json
|
Package timejson extends time methods with marshal/unmarshal for json |
units
Package units is taken from https://github.com/docker/go-units
|
Package units is taken from https://github.com/docker/go-units |
version
Package version returns details on the Go and Git repo used in the build
|
Package version returns details on the Go and Git repo used in the build |
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 |
Package mod changes an image according to the requested modifications.
|
Package mod changes an image according to the requested modifications. |
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 defiles OCI image-spec types |
oci/v1
Package v1 defiles version 1 of OCI image-spec types
|
Package v1 defiles version 1 of OCI image-spec types |
ping
Package ping is used for data types with the Ping methods.
|
Package ping is used for data types with the Ping methods. |
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.
|
Package ref is used to define references. |
referrer
Package referrer is used for responses to the referrers to a manifest
|
Package referrer is used for responses to the referrers to a manifest |
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 |
warning
Package warning is used to handle HTTP warning headers
|
Package warning is used to handle HTTP warning headers |