Documentation ¶
Overview ¶
Example (CopyArtifactManifestRemoteToLocal) ¶
Example_copyArtifactManifestRemoteToLocal gives an example of copying an artifact manifest from a remote repository to local.
src, err := remote.NewRepository(fmt.Sprintf("%s/source", remoteHost)) if err != nil { panic(err) } dst := memory.New() ctx := context.Background() exampleDigest := "sha256:70c29a81e235dda5c2cebb8ec06eafd3cca346cbd91f15ac74cefd98681c5b3d" descriptor, err := src.Resolve(ctx, exampleDigest) if err != nil { panic(err) } err = oras.CopyGraph(ctx, src, dst, descriptor, oras.DefaultCopyGraphOptions) if err != nil { panic(err) } // verify that the artifact manifest described by the descriptor exists in dst contentExists, err := dst.Exists(ctx, descriptor) if err != nil { panic(err) } fmt.Println(contentExists)
Output: true
Example (ExtendedCopyArtifactAndReferrersRemoteToLocal) ¶
Example_extendedCopyArtifactAndReferrersRemoteToLocal gives an example of copying an artifact along with its referrers from a remote repository to local.
src, err := remote.NewRepository(fmt.Sprintf("%s/source", remoteHost)) if err != nil { panic(err) } dst := memory.New() ctx := context.Background() tagName := "latest" // ExtendedCopy will copy the artifact tagged by "latest" along with all of its // referrers from src to dst. desc, err := oras.ExtendedCopy(ctx, src, tagName, dst, tagName, oras.DefaultExtendedCopyOptions) if err != nil { panic(err) } fmt.Println(desc.Digest)
Output: sha256:f396bc4d300934a39ca28ab0d5ac8a3573336d7d63c654d783a68cd1e2057662
Index ¶
- Constants
- Variables
- func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, ...) (ocispec.Descriptor, error)
- func CopyGraph(ctx context.Context, src content.ReadOnlyStorage, dst content.Storage, ...) error
- func ExtendedCopy(ctx context.Context, src ReadOnlyGraphTarget, srcRef string, dst Target, ...) (ocispec.Descriptor, error)
- func ExtendedCopyGraph(ctx context.Context, src content.ReadOnlyGraphStorage, dst content.Storage, ...) error
- func Fetch(ctx context.Context, target ReadOnlyTarget, reference string, ...) (ocispec.Descriptor, io.ReadCloser, error)
- func FetchBytes(ctx context.Context, target ReadOnlyTarget, reference string, ...) (ocispec.Descriptor, []byte, error)
- func Pack(ctx context.Context, pusher content.Pusher, artifactType string, ...) (ocispec.Descriptor, error)
- func PushBytes(ctx context.Context, pusher content.Pusher, mediaType string, ...) (ocispec.Descriptor, error)
- func Resolve(ctx context.Context, target ReadOnlyTarget, reference string, ...) (ocispec.Descriptor, error)
- func Tag(ctx context.Context, target Target, src, dst string) (ocispec.Descriptor, error)
- func TagBytes(ctx context.Context, target Target, mediaType string, contentBytes []byte, ...) (ocispec.Descriptor, error)
- func TagBytesN(ctx context.Context, target Target, mediaType string, contentBytes []byte, ...) (ocispec.Descriptor, error)
- func TagN(ctx context.Context, target Target, srcReference string, ...) (ocispec.Descriptor, error)
- type CopyGraphOptions
- type CopyOptions
- type ExtendedCopyGraphOptions
- type ExtendedCopyOptions
- type FetchBytesOptions
- type FetchOptions
- type GraphTarget
- type PackOptions
- type ReadOnlyGraphTarget
- type ReadOnlyTarget
- type ResolveOptions
- type TagBytesNOptions
- type TagNOptions
- type Target
Examples ¶
Constants ¶
const ( // MediaTypeUnknownConfig is the default mediaType used when no // config media type is specified. MediaTypeUnknownConfig = "application/vnd.unknown.config.v1+json" // MediaTypeUnknownArtifact is the default artifactType used when no // artifact type is specified. MediaTypeUnknownArtifact = "application/vnd.unknown.artifact.v1" )
Variables ¶
var ErrInvalidDateTimeFormat = errors.New("invalid date and time format")
ErrInvalidDateTimeFormat is returned by Pack() when AnnotationArtifactCreated or AnnotationCreated is provided, but its value is not in RFC 3339 format. Reference: https://www.rfc-editor.org/rfc/rfc3339#section-5.6
Functions ¶
func Copy ¶
func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, dstRef string, opts CopyOptions) (ocispec.Descriptor, error)
Copy copies a rooted directed acyclic graph (DAG) with the tagged root node in the source Target to the destination Target. The destination reference will be the same as the source reference if the destination reference is left blank. Returns the descriptor of the root node on successful copy.
Example (LocalToLocal) ¶
src := exampleMemoryStore dst := memory.New() tagName := "latest" ctx := context.Background() desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions) if err != nil { panic(err) // Handle error } fmt.Println(desc.Digest)
Output: sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
Example (LocalToOciFile) ¶
src := exampleMemoryStore tempDir, err := os.MkdirTemp("", "oras_oci_example_*") if err != nil { panic(err) // Handle error } defer os.RemoveAll(tempDir) dst, err := oci.New(tempDir) if err != nil { panic(err) // Handle error } tagName := "latest" ctx := context.Background() desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions) if err != nil { panic(err) // Handle error } fmt.Println(desc.Digest)
Output: sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
Example (LocalToRemote) ¶
src := exampleMemoryStore reg, err := remote.NewRegistry(remoteHost) if err != nil { panic(err) // Handle error } ctx := context.Background() dst, err := reg.Repository(ctx, "target") if err != nil { panic(err) // Handle error } tagName := "latest" desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions) if err != nil { panic(err) // Handle error } fmt.Println(desc.Digest)
Output: sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
Example (RemoteToLocal) ¶
reg, err := remote.NewRegistry(remoteHost) if err != nil { panic(err) // Handle error } ctx := context.Background() src, err := reg.Repository(ctx, "source") if err != nil { panic(err) // Handle error } dst := memory.New() tagName := "latest" desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions) if err != nil { panic(err) // Handle error } fmt.Println(desc.Digest)
Output: sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
Example (RemoteToRemote) ¶
reg, err := remote.NewRegistry(remoteHost) if err != nil { panic(err) // Handle error } ctx := context.Background() src, err := reg.Repository(ctx, "source") if err != nil { panic(err) // Handle error } dst, err := reg.Repository(ctx, "target") if err != nil { panic(err) // Handle error } tagName := "latest" desc, err := oras.Copy(ctx, src, tagName, dst, tagName, oras.DefaultCopyOptions) if err != nil { panic(err) // Handle error } fmt.Println(desc.Digest)
Output: sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
func CopyGraph ¶
func CopyGraph(ctx context.Context, src content.ReadOnlyStorage, dst content.Storage, root ocispec.Descriptor, opts CopyGraphOptions) error
CopyGraph copies a rooted directed acyclic graph (DAG) from the source CAS to the destination CAS.
func ExtendedCopy ¶
func ExtendedCopy(ctx context.Context, src ReadOnlyGraphTarget, srcRef string, dst Target, dstRef string, opts ExtendedCopyOptions) (ocispec.Descriptor, error)
ExtendedCopy copies the directed acyclic graph (DAG) that are reachable from the given tagged node from the source GraphTarget to the destination Target. The destination reference will be the same as the source reference if the destination reference is left blank. Returns the descriptor of the tagged node on successful copy.
func ExtendedCopyGraph ¶
func ExtendedCopyGraph(ctx context.Context, src content.ReadOnlyGraphStorage, dst content.Storage, node ocispec.Descriptor, opts ExtendedCopyGraphOptions) error
ExtendedCopyGraph copies the directed acyclic graph (DAG) that are reachable from the given node from the source GraphStorage to the destination Storage.
func Fetch ¶
func Fetch(ctx context.Context, target ReadOnlyTarget, reference string, opts FetchOptions) (ocispec.Descriptor, io.ReadCloser, error)
Fetch fetches the content identified by the reference.
func FetchBytes ¶
func FetchBytes(ctx context.Context, target ReadOnlyTarget, reference string, opts FetchBytesOptions) (ocispec.Descriptor, []byte, error)
FetchBytes fetches the content bytes identified by the reference.
func Pack ¶
func Pack(ctx context.Context, pusher content.Pusher, artifactType string, blobs []ocispec.Descriptor, opts PackOptions) (ocispec.Descriptor, error)
Pack packs the given blobs, generates a manifest for the pack, and pushes it to a content storage. When opts.PackImageManifest is true, artifactType will be used as the the config descriptor mediaType of the image manifest. If succeeded, returns a descriptor of the manifest.
func PushBytes ¶
func PushBytes(ctx context.Context, pusher content.Pusher, mediaType string, contentBytes []byte) (ocispec.Descriptor, error)
PushBytes describes the contentBytes using the given mediaType and pushes it. If mediaType is not specified, "application/octet-stream" is used.
func Resolve ¶
func Resolve(ctx context.Context, target ReadOnlyTarget, reference string, opts ResolveOptions) (ocispec.Descriptor, error)
Resolve resolves a descriptor with provided reference from the target.
func TagBytes ¶
func TagBytes(ctx context.Context, target Target, mediaType string, contentBytes []byte, reference string) (ocispec.Descriptor, error)
TagBytes describes the contentBytes using the given mediaType, pushes it, and tag it with the given reference. If mediaType is not specified, "application/octet-stream" is used.
func TagBytesN ¶
func TagBytesN(ctx context.Context, target Target, mediaType string, contentBytes []byte, references []string, opts TagBytesNOptions) (ocispec.Descriptor, error)
TagBytesN describes the contentBytes using the given mediaType, pushes it, and tag it with the given references. If mediaType is not specified, "application/octet-stream" is used.
Types ¶
type CopyGraphOptions ¶
type CopyGraphOptions struct { // Concurrency limits the maximum number of concurrent copy tasks. // If less than or equal to 0, a default (currently 3) is used. Concurrency int // MaxMetadataBytes limits the maximum size of the metadata that can be // cached in the memory. // If less than or equal to 0, a default (currently 4 MiB) is used. MaxMetadataBytes int64 // PreCopy handles the current descriptor before copying it. PreCopy func(ctx context.Context, desc ocispec.Descriptor) error // PostCopy handles the current descriptor after copying it. PostCopy func(ctx context.Context, desc ocispec.Descriptor) error // OnCopySkipped will be called when the sub-DAG rooted by the current node // is skipped. OnCopySkipped func(ctx context.Context, desc ocispec.Descriptor) error // FindSuccessors finds the successors of the current node. // fetcher provides cached access to the source storage, and is suitable // for fetching non-leaf nodes like manifests. Since anything fetched from // fetcher will be cached in the memory, it is recommended to use original // source storage to fetch large blobs. // If FindSuccessors is nil, content.Successors will be used. FindSuccessors func(ctx context.Context, fetcher content.Fetcher, desc ocispec.Descriptor) ([]ocispec.Descriptor, error) }
CopyGraphOptions contains parameters for oras.CopyGraph.
var DefaultCopyGraphOptions CopyGraphOptions
DefaultCopyGraphOptions provides the default CopyGraphOptions.
type CopyOptions ¶
type CopyOptions struct { CopyGraphOptions // MapRoot maps the resolved root node to a desired root node for copy. // When MapRoot is provided, the descriptor resolved from the source // reference will be passed to MapRoot, and the mapped descriptor will be // used as the root node for copy. MapRoot func(ctx context.Context, src content.ReadOnlyStorage, root ocispec.Descriptor) (ocispec.Descriptor, error) }
CopyOptions contains parameters for oras.Copy.
var DefaultCopyOptions CopyOptions = CopyOptions{ CopyGraphOptions: DefaultCopyGraphOptions, }
DefaultCopyOptions provides the default CopyOptions.
func (*CopyOptions) WithTargetPlatform ¶
func (opts *CopyOptions) WithTargetPlatform(p *ocispec.Platform)
WithTargetPlatform configures opts.MapRoot to select the manifest whose platform matches the given platform. When MapRoot is provided, the platform selection will be applied on the mapped root node. - If the given platform is nil, no platform selection will be applied. - If the root node is a manifest, it will remain the same if platform matches, otherwise ErrNotFound will be returned. - If the root node is a manifest list, it will be mapped to the first matching manifest if exists, otherwise ErrNotFound will be returned. - Otherwise ErrUnsupported will be returned.
type ExtendedCopyGraphOptions ¶
type ExtendedCopyGraphOptions struct { CopyGraphOptions // Depth limits the maximum depth of the directed acyclic graph (DAG) that // will be extended-copied. // If Depth is no specified, or the specified value is less than or // equal to 0, the depth limit will be considered as infinity. Depth int // FindPredecessors finds the predecessors of the current node. // If FindPredecessors is nil, src.Predecessors will be adapted and used. FindPredecessors func(ctx context.Context, src content.ReadOnlyGraphStorage, desc ocispec.Descriptor) ([]ocispec.Descriptor, error) }
ExtendedCopyGraphOptions contains parameters for oras.ExtendedCopyGraph.
var DefaultExtendedCopyGraphOptions ExtendedCopyGraphOptions = ExtendedCopyGraphOptions{ CopyGraphOptions: DefaultCopyGraphOptions, }
DefaultExtendedCopyGraphOptions provides the default ExtendedCopyGraphOptions.
func (*ExtendedCopyGraphOptions) FilterAnnotation ¶
func (opts *ExtendedCopyGraphOptions) FilterAnnotation(key string, regex *regexp.Regexp)
FilterAnnotation configures opts.FindPredecessors to filter the predecessors whose annotation matches a given regex pattern. A predecessor is kept if key is in its annotations and the annotation value matches regex. If regex is nil, predecessors whose annotations contain key will be kept, no matter of the annotation value. For performance consideration, when using both FilterArtifactType and FilterAnnotation, it's recommended to call FilterArtifactType first.
func (*ExtendedCopyGraphOptions) FilterArtifactType ¶
func (opts *ExtendedCopyGraphOptions) FilterArtifactType(regex *regexp.Regexp)
FilterArtifactType configures opts.FindPredecessors to filter the predecessors whose artifact type matches a given regex pattern. A predecessor is kept if its artifact type matches regex. If regex is nil, all predecessors will be kept. For performance consideration, when using both FilterArtifactType and FilterAnnotation, it's recommended to call FilterArtifactType first.
type ExtendedCopyOptions ¶
type ExtendedCopyOptions struct {
ExtendedCopyGraphOptions
}
ExtendedCopyOptions contains parameters for oras.ExtendedCopy.
var DefaultExtendedCopyOptions ExtendedCopyOptions = ExtendedCopyOptions{ ExtendedCopyGraphOptions: DefaultExtendedCopyGraphOptions, }
DefaultExtendedCopyOptions provides the default ExtendedCopyOptions.
type FetchBytesOptions ¶
type FetchBytesOptions struct { // FetchOptions contains parameters for fetching content. FetchOptions // MaxBytes limits the maximum size of the fetched content bytes. // If less than or equal to 0, a default (currently 4 MiB) is used. MaxBytes int64 }
FetchBytesOptions contains parameters for oras.FetchBytes.
var DefaultFetchBytesOptions FetchBytesOptions
DefaultFetchBytesOptions provides the default FetchBytesOptions.
type FetchOptions ¶
type FetchOptions struct { // ResolveOptions contains parameters for resolving reference. ResolveOptions }
FetchOptions contains parameters for oras.Fetch.
var DefaultFetchOptions FetchOptions
DefaultFetchOptions provides the default FetchOptions.
type GraphTarget ¶
type GraphTarget interface { content.GraphStorage content.TagResolver }
GraphTarget is a CAS with generic tags that supports direct predecessor node finding.
type PackOptions ¶
type PackOptions struct { // Subject is the subject of the manifest. Subject *ocispec.Descriptor // ManifestAnnotations is the annotation map of the manifest. ManifestAnnotations map[string]string // PackImageManifest controls whether to pack an image manifest or not. // - If true, pack an image manifest; artifactType will be used as the // the config descriptor mediaType of the image manifest. // - If false, pack an artifact manifest. // Default: false. PackImageManifest bool // ConfigDescriptor is a pointer to the descriptor of the config blob. // If not nil, artifactType will be implied by the mediaType of the // specified ConfigDescriptor, and ConfigAnnotations will be ignored. // This option is valid only when PackImageManifest is true. ConfigDescriptor *ocispec.Descriptor // ConfigAnnotations is the annotation map of the config descriptor. // This option is valid only when PackImageManifest is true // and ConfigDescriptor is nil. ConfigAnnotations map[string]string }
PackOptions contains parameters for oras.Pack.
type ReadOnlyGraphTarget ¶
type ReadOnlyGraphTarget interface { content.ReadOnlyGraphStorage content.Resolver }
ReadOnlyGraphTarget represents a read-only GraphTarget.
type ReadOnlyTarget ¶
type ReadOnlyTarget interface { content.ReadOnlyStorage content.Resolver }
ReadOnlyTarget represents a read-only Target.
type ResolveOptions ¶
type ResolveOptions struct { // TargetPlatform ensures the resolved content matches the target platform // if the node is a manifest, or selects the first resolved content that // matches the target platform if the node is a manifest list. TargetPlatform *ocispec.Platform // MaxMetadataBytes limits the maximum size of metadata that can be cached // in the memory. // If less than or equal to 0, a default (currently 4 MiB) is used. MaxMetadataBytes int64 }
ResolveOptions contains parameters for oras.Resolve.
var DefaultResolveOptions ResolveOptions
DefaultResolveOptions provides the default ResolveOptions.
type TagBytesNOptions ¶
type TagBytesNOptions struct { // Concurrency limits the maximum number of concurrent tag tasks. // If less than or equal to 0, a default (currently 5) is used. Concurrency int }
TagBytesNOptions contains parameters for oras.TagBytesN.
var DefaultTagBytesNOptions TagBytesNOptions
DefaultTagBytesNOptions provides the default TagBytesNOptions.
type TagNOptions ¶
type TagNOptions struct { // Concurrency limits the maximum number of concurrent tag tasks. // If less than or equal to 0, a default (currently 5) is used. Concurrency int // MaxMetadataBytes limits the maximum size of metadata that can be cached // in the memory. // If less than or equal to 0, a default (currently 4 MiB) is used. MaxMetadataBytes int64 }
TagNOptions contains parameters for oras.TagN.
var DefaultTagNOptions TagNOptions
DefaultTagNOptions provides the default TagNOptions.
Directories ¶
Path | Synopsis |
---|---|
Package content provides implementations to access content stores.
|
Package content provides implementations to access content stores. |
file
Package file provides implementation of a content store based on file system.
|
Package file provides implementation of a content store based on file system. |
memory
Package memory provides implementation of a memory backed content store.
|
Package memory provides implementation of a memory backed content store. |
oci
Package oci provides access to an OCI content store.
|
Package oci provides access to an OCI content store. |
internal
|
|
Package registry provides high-level operations to manage registries.
|
Package registry provides high-level operations to manage registries. |
internal/doc
Package doc provides the constant can be used in example test files.
|
Package doc provides the constant can be used in example test files. |
remote
Package remote provides a client to the remote registry.
|
Package remote provides a client to the remote registry. |
remote/auth
Package auth provides authentication for a client to a remote registry.
|
Package auth provides authentication for a client to a remote registry. |