Documentation
¶
Overview ¶
Package oci provides Zarf's ORAS registry client and OCI descriptor helpers.
Use NewOrasRemote to configure registry access. WithRetryPolicy enables resumable blob reads.
Index ¶
- Constants
- func FetchJSONFile[T any](ctx context.Context, fetcher content.Fetcher, manifest *Manifest, path string) (result T, err error)
- func FetchUnmarshal[T any](ctx context.Context, fetcher content.Fetcher, ...) (result T, err error)
- func IsEmptyDescriptor(descriptor ocispec.Descriptor) bool
- func PlatformForArch(arch string) ocispec.Platform
- func RemoveDuplicateDescriptors(descriptors []ocispec.Descriptor) []ocispec.Descriptor
- func SumDescsSize(descriptors []ocispec.Descriptor) int64
- func UpdateIndexWithDescriptor(ctx context.Context, repo *registryremote.Repository, tag string, ...) (ocispec.Descriptor, error)
- type Manifest
- type Modifier
- func WithCache(cache content.Storage) Modifier
- func WithCredentialFunc(fn auth.CredentialFunc) Modifier
- func WithInsecureSkipVerify(insecure bool) Modifier
- func WithLogger(logger *slog.Logger) Modifier
- func WithPlainHTTP(plainHTTP bool) Modifier
- func WithRetryPolicy(policy retry.Policy) Modifier
- func WithTransport(transport *http.Transport) Modifier
- func WithUserAgent(userAgent string) Modifier
- type OrasRemote
- func (o *OrasRemote) CopyToTarget(ctx context.Context, layers []ocispec.Descriptor, target oras.Target, ...) error
- func (o *OrasRemote) Fetch(ctx context.Context, desc ocispec.Descriptor) (io.ReadCloser, error)
- func (o *OrasRemote) FetchLayer(ctx context.Context, desc ocispec.Descriptor) (bytes []byte, err error)
- func (o *OrasRemote) FetchLayerReader(ctx context.Context, desc ocispec.Descriptor) (*content.VerifyReader, error)
- func (o *OrasRemote) FetchManifest(ctx context.Context, desc ocispec.Descriptor) (manifest *Manifest, err error)
- func (o *OrasRemote) FetchRoot(ctx context.Context) (*Manifest, error)
- func (o *OrasRemote) GetDefaultCopyOpts() oras.CopyOptions
- func (o *OrasRemote) Log() *slog.Logger
- func (o *OrasRemote) Repo() *remote.Repository
- func (o *OrasRemote) ResolveRoot(ctx context.Context) (ocispec.Descriptor, error)
- func (o *OrasRemote) UpdateIndex(ctx context.Context, tag string, publishedDesc ocispec.Descriptor) error
Examples ¶
Constants ¶
const (
// MultiOS is the OS used for multi-platform packages
MultiOS = "multi"
)
Variables ¶
This section is empty.
Functions ¶
func FetchJSONFile ¶
func FetchJSONFile[T any](ctx context.Context, fetcher content.Fetcher, manifest *Manifest, path string) (result T, err error)
FetchJSONFile fetches and unmarshals the JSON file at path, located via the manifest.
func FetchUnmarshal ¶
func FetchUnmarshal[T any](ctx context.Context, fetcher content.Fetcher, unmarshaler func(data []byte, v any) error, descriptor ocispec.Descriptor) (result T, err error)
FetchUnmarshal fetches (and digest-verifies, via content.FetchAll) the descriptor and unmarshals it.
func IsEmptyDescriptor ¶
func IsEmptyDescriptor(descriptor ocispec.Descriptor) bool
IsEmptyDescriptor returns true if the given descriptor is empty.
func PlatformForArch ¶
PlatformForArch sets the target architecture for the remote
func RemoveDuplicateDescriptors ¶
func RemoveDuplicateDescriptors(descriptors []ocispec.Descriptor) []ocispec.Descriptor
RemoveDuplicateDescriptors removes duplicate descriptors from the given list.
func SumDescsSize ¶
func SumDescsSize(descriptors []ocispec.Descriptor) int64
SumDescsSize returns the size of all the descriptors added together
func UpdateIndexWithDescriptor ¶
func UpdateIndexWithDescriptor(ctx context.Context, repo *registryremote.Repository, tag string, platform ocispec.Platform, manifest ocispec.Descriptor) (ocispec.Descriptor, error)
UpdateIndexWithDescriptor updates the index referenced by tag for platform and pushes the resulting immutable descriptor without changing the tag.
Types ¶
type Manifest ¶
Manifest wraps an OCI image manifest.
func (*Manifest) Locate ¶
func (manifest *Manifest) Locate(pathOrDigest string) v1.Descriptor
Locate returns the layer whose title annotation or digest matches pathOrDigest.
func (*Manifest) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
type Modifier ¶
type Modifier func(*OrasRemote)
Modifier is a function that modifies an OrasRemote
func WithCredentialFunc ¶ added in v0.89.0
func WithCredentialFunc(fn auth.CredentialFunc) Modifier
WithCredentialFunc sets fn as the source of registry credentials. If fn is nil, the Docker credential store is used instead.
func WithInsecureSkipVerify ¶
WithInsecureSkipVerify sets the insecure TLS flag for the remote. An explicit value takes precedence over WithTransport regardless of modifier order.
func WithLogger ¶
WithLogger sets the logger for the remote
func WithPlainHTTP ¶
WithPlainHTTP sets the plain HTTP flag for the remote
func WithRetryPolicy ¶ added in v1.0.0
WithRetryPolicy configures HTTP retries and resumable blob reads. Nil keeps default HTTP retries and disables read recovery.
On policy-approved read failures, the returned reader automatically continues after the bytes already returned to the caller. If recovery fails or retries are exhausted, Read returns an error.
Read recovery requires range-capable blobs and lasts only for one reader. Manifest bodies, destination uploads, and later processes are not resumed.
The policy may be called concurrently. For read failures, the response is nil.
Example ¶
package main
import (
"errors"
"io"
"net/http"
"time"
"github.com/zarf-dev/zarf/src/pkg/oci"
"oras.land/oras-go/v2/registry/remote/retry"
)
func main() {
policy := &retry.GenericPolicy{
MaxRetry: 8,
MinWait: 250 * time.Millisecond,
MaxWait: 3 * time.Second,
Backoff: retry.DefaultBackoff,
Retryable: func(response *http.Response, err error) (bool, error) {
// Retry truncated responses, which ORAS's default predicate does not retry.
if errors.Is(err, io.ErrUnexpectedEOF) {
return true, nil
}
return retry.DefaultPredicate(response, err)
},
}
_, err := oci.NewOrasRemote("registry.example.com/packages/demo", oci.PlatformForArch("amd64"),
oci.WithRetryPolicy(policy))
if err != nil {
panic(err)
}
}
Output:
func WithTransport ¶
WithTransport sets the HTTP transport for the remote.
func WithUserAgent ¶
WithUserAgent sets the user agent for the remote
type OrasRemote ¶
type OrasRemote struct {
// contains filtered or unexported fields
}
OrasRemote is a wrapper around the Oras remote repository.
func NewOrasRemote ¶
func NewOrasRemote(url string, platform ocispec.Platform, modifiers ...Modifier) (*OrasRemote, error)
NewOrasRemote returns an oras remote repository client and context for the given url.
Registry credentials come from the Docker credential store by default. Use WithCredentialFunc to provide a different credential source.
func (*OrasRemote) CopyToTarget ¶
func (o *OrasRemote) CopyToTarget(ctx context.Context, layers []ocispec.Descriptor, target oras.Target, copyOpts oras.CopyOptions) error
CopyToTarget copies the given layers from the remote repository to the given target
func (*OrasRemote) Fetch ¶
func (o *OrasRemote) Fetch(ctx context.Context, desc ocispec.Descriptor) (io.ReadCloser, error)
Fetch fetches the content for the given descriptor, honoring the layer cache when configured. This satisfies oras content.Fetcher, so an OrasRemote can be passed directly to oras helpers such as content.FetchAll and FetchJSONFile.
func (*OrasRemote) FetchLayer ¶
func (o *OrasRemote) FetchLayer(ctx context.Context, desc ocispec.Descriptor) (bytes []byte, err error)
FetchLayer fetches (and digest-verifies) the layer with the given descriptor.
func (*OrasRemote) FetchLayerReader ¶
func (o *OrasRemote) FetchLayerReader(ctx context.Context, desc ocispec.Descriptor) (*content.VerifyReader, error)
FetchLayerReader fetches the layer with the given descriptor from the remote repository.
func (*OrasRemote) FetchManifest ¶
func (o *OrasRemote) FetchManifest(ctx context.Context, desc ocispec.Descriptor) (manifest *Manifest, err error)
FetchManifest fetches the manifest with the given descriptor from the remote repository.
func (*OrasRemote) FetchRoot ¶
func (o *OrasRemote) FetchRoot(ctx context.Context) (*Manifest, error)
FetchRoot fetches the root manifest from the remote repository.
func (*OrasRemote) GetDefaultCopyOpts ¶
func (o *OrasRemote) GetDefaultCopyOpts() oras.CopyOptions
GetDefaultCopyOpts returns the default copy options
func (*OrasRemote) Log ¶
func (o *OrasRemote) Log() *slog.Logger
Log gives you access to the OrasRemote logger
func (*OrasRemote) Repo ¶
func (o *OrasRemote) Repo() *remote.Repository
Repo gives you access to the underlying remote repository
func (*OrasRemote) ResolveRoot ¶
func (o *OrasRemote) ResolveRoot(ctx context.Context) (ocispec.Descriptor, error)
ResolveRoot returns the root descriptor for the remote repository
func (*OrasRemote) UpdateIndex ¶
func (o *OrasRemote) UpdateIndex(ctx context.Context, tag string, publishedDesc ocispec.Descriptor) error
UpdateIndex updates the index for the given package.