diff --git a/docs/client_libraries/_category_.json b/docs/client_libraries/_category_.json deleted file mode 100644 index b75c9bb7..00000000 --- a/docs/client_libraries/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Client Libraries", - "position": 40, - "link": { - "type": "generated-index", - "description": "The following languages are currently supported:" - } -} \ No newline at end of file diff --git a/docs/client_libraries/go.mdx b/docs/client_libraries/go.mdx deleted file mode 100644 index cb03fc9f..00000000 --- a/docs/client_libraries/go.mdx +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Go -sidebar_position: 1 ---- - -# Go - -Source code: [github.com/oras-project/oras-go](https://github.com/oras-project/oras-go) - -## Introduction - -The ORAS Go client library provides the ability to replicate artifacts between different [Targets](./overview.mdx#target). -Furthermore, the version `v2` is a registry client conforming [image-spec v1.1.0-rc6](https://github.com/opencontainers/image-spec/releases/tag/v1.1.0-rc6) and [distribution-spec v1.1.0-rc4](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0-rc4). - -Using the ORAS Go client library, you can develop your own registry client: - -```sh -myclient push artifacts.example.com/myartifact:1.0 ./mything.thang -``` - -## Usage - -The package `oras.land/oras-go/v2` can quickly be imported in other Go-based tools that -wish to benefit from the ability to store arbitrary content in container registries. - -1. Get the `oras.land/oras-go/v2` package -```sh -go get oras.land/oras-go/v2 -``` - -2. Import and use the `v2` package -```go -import "oras.land/oras-go/v2" -``` - -3. Run -```sh -go mod tidy -``` - -**The API documentation and examples are available at [pkg.go.dev](https://pkg.go.dev/oras.land/oras-go/v2).** - -## Quick Start - -### Push files to a remote repository -See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PushFilesToRemoteRepository). - -### Pull files from a remote repository -See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullFilesFromRemoteRepository). - -### Pull a docker or OCI image from a remote repository -See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullImageFromRemoteRepository). - -### Pull an Image using the Docker credential store -See [this example](https://pkg.go.dev/oras.land/oras-go/v2#example-package-PullImageUsingDockerCredentials). diff --git a/docs/client_libraries/img/polytree.svg b/docs/client_libraries/img/polytree.svg deleted file mode 100644 index 14c2c6e6..00000000 --- a/docs/client_libraries/img/polytree.svg +++ /dev/null @@ -1,119 +0,0 @@ - - - - - - -polytree - - - -A - -A - - - -F - -F - - - - -C - -C - - - -A->C - - - - - -D - -D - - - -A->D - - - - - -B - -B - - - -E - -E - - - -B->E - - - - - -G - -G - - - - -B->D - - - - - -I - -I - - - - -G->I - - - - - - -D->F - - - - - -D->G - - - - - -H - -H - - - -H->I - - - - - diff --git a/docs/client_libraries/overview.mdx b/docs/client_libraries/overview.mdx deleted file mode 100644 index 866d4ac6..00000000 --- a/docs/client_libraries/overview.mdx +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Overview -sidebar_position: 0 ---- - -# Overview - -## Languages - -The following languages are currently supported: - -- [Go](./go.mdx) -- [Python](https://oras-project.github.io/oras-py/getting_started/user-guide.html) -- [Rust](./rust.mdx) (in progress) -- [C#](https://oras-project.github.io/oras-dotnet/api) - -## Unified Experience - -The objective of ORAS is simple as transferring artifacts from one place to another. - -In the conventional [client-server model](https://en.wikipedia.org/wiki/Client%E2%80%93server_model), the operation of downloading artifacts from the remote registries is referred to as **pull**, and the operation of uploading artifacts to the remote registry is referred to as **push**. - -This model can be generalized by abstracting the client and the server as **targets** so that pull and push can be viewed as **copying** from one target to another (see [**Copy API** oras-project/oras-go#8](https://github.com/oras-project/oras-go/pull/8)). -For instances, - -- Copy from memory to a remote registry. -- Copy from a remote registry to a local file folder. -- Copy from a remote registry to another remote registry. -- Copy from memory to a local file folder. - -### Targets - -Generally, a target is a [content-addressable storage (CAS)](https://en.wikipedia.org/wiki/Content-addressable_storage) with tags. -All blobs in a CAS are addressed by their [descriptors](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/descriptor.md). - -To retrieve a blob, - -1. Get a descriptor. Optionally, it can be resolved by a tag. -2. Query the blob with a descriptor. - -To store a blob, - -1. Store the blob directly in the CAS. A descriptor will be returned. -2. Optionally, associate the returned descriptor with a tag. - -It is worth noting that a target is not equal to a registry. - -- Blobs can be tagged in a target but not in a registry. -- Tag list is available in a registry but not always available in a target. - -### Graphs - -Besides plain blobs, it is natural to store [directed acyclic graphs (DAGs)](https://en.wikipedia.org/wiki/Directed_acyclic_graph) in a CAS. -Precisely, all blobs are leaf nodes and most manifests are non-leaf nodes. - -An artifact is a rooted DAG where its root node is an [OCI manifest](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/manifest.md) or an [OCI Artifact Manifest](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md). -Additionally, artifacts can be grouped by an [OCI index](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-index.md), which is also a rooted DAG. - -Given a node of a DAG in a CAS, it is efficient to find out all its children. -Since CASs are usually not enumerable or indexed, it is not possible to find the parent nodes of an arbitrary node. -Nevertheless, some CASs choose to implement or partially implement the functionality of parent node finding. -For instances, registries with [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers) support are CASs with partially implementation where parent node finding is only available for manifest nodes. - -### Extended Copy - -With the concepts above, we can formally define that - -- **Copy** is a function to replicate a rooted DAG from one CAS to another. -- **Extended Copy** is a function to replicate a DAG from one CAS to another. - -It is worth noting that extended copy is possible only if the source CAS supports parent node finding. -Based on the scenarios, extended copy can have many options such as opting to copy a sub-DAG rooted by a certain node and all its parent nodes of a certain depth with / without their children. - -Optionally, node filters or even node modifiers can be attached to a copy process for advanced scenarios. - -Related issues: - -- [**Support copy of images and associated references** oras-project/oras-go#29](https://github.com/oras-project/oras-go/issues/29) -- [**Copy Artifact Reference Graph** oras-project/oras#307](https://github.com/oras-project/oras/issues/307) - -Hint: A [polytree](https://en.wikipedia.org/wiki/Polytree) is a DAG. - -![polytree](./img/polytree.svg) - -## Paradigms - -🚧 *Note: this section is contingent on -[oras-project/oras-go#8](https://github.com/oras-project/oras-go/pull/8) and -does not reprersent the current state of the ORAS Go client library.* - -At a high-level, each client library provides the concept of a `Target` interface -and a `Copy` method. `Copy` transfers content from one `Target` to another. - -### `Target` - -A `Target` represents a place to which one can send/push or retrieve/pull artifacts. -Anything that implements this interface can be used as a place to send -or retrieve artifacts. - -Some examples of a `Target` may include the following: - -- An OCI Registry -- An [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md) -- A local collection of files - -### `Copy` - -`Copy` copies a rooted DAG identified by a reference from one `Target` to another `Target`. - -#### Method signature - -The following is a rough method signature based on the Go version: - -```go -func Copy(from Target, fromRef string, to Target, toRef string) Descriptor -``` - -### `ExtendedCopy` - -`Copy` copies a DAG reachable from a node identified by a reference from one `Target` to another `Target`. - -#### Method signature - -The following is a rough method signature based on the Go version: - -```go -func ExtendedCopy(from Target, fromRef string, to Target, toRef string) Descriptor -``` diff --git a/docs/client_libraries/python.mdx b/docs/client_libraries/python.mdx deleted file mode 100644 index 3b196616..00000000 --- a/docs/client_libraries/python.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Python -sidebar_position: 2 ---- - - -# Python - -See [Oras Python](https://oras-project.github.io/oras-py/getting_started/user-guide.html). \ No newline at end of file diff --git a/docs/client_libraries/rust.mdx b/docs/client_libraries/rust.mdx deleted file mode 100644 index e0afdcc5..00000000 --- a/docs/client_libraries/rust.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Rust -sidebar_position: 3 ---- - -# Rust - -:::note - -🚧 Rust client library currently in progress! Contributions welcome! - -::: - -Source code: [github.com/oras-project/oras-rs](https://github.com/oras-project/oras-rs) diff --git a/docs/commands/_category_.json b/docs/commands/_category_.json deleted file mode 100644 index 03c6914a..00000000 --- a/docs/commands/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "ORAS Commands", - "position": 30, - "link": { - "type": "generated-index", - "description": "A guide to ORAS Commands" - } -} \ No newline at end of file diff --git a/docs/commands/oras_attach.mdx b/docs/commands/oras_attach.mdx deleted file mode 100644 index d77e0b88..00000000 --- a/docs/commands/oras_attach.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: oras attach -sidebar_position: 10 -warning: Do NOT modify this generated file ---- - -# oras attach - -[Preview] Attach files to an existing artifact -** This command is in preview and under development. ** - -```bash -oras attach [flags] --artifact-type= {:|@} [:] [...] -``` - -## Examples - -Attach file 'hi.txt' with type 'doc/example' to manifest 'hello:v1' in registry 'localhost:5000': - -```bash -oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt -``` - -Attach file "hi.txt" using a specific method for the Referrers API: - -```bash -oras attach --artifact-type doc/example --distribution-spec v1.1-referrers-api localhost:5000/hello:v1 hi.txt # via API -oras attach --artifact-type doc/example --distribution-spec v1.1-referrers-tag localhost:5000/hello:v1 hi.txt # via tag scheme -``` - -Attach file 'hi.txt' and add annotations from file 'annotation.json': - -```bash -oras attach --artifact-type doc/example --annotation-file annotation.json localhost:5000/hello:v1 hi.txt -``` - -Attach an artifact with manifest annotations: - -```bash -oras attach --artifact-type doc/example --annotation "key1=val1" --annotation "key2=val2" localhost:5000/hello:v1 -``` - -Attach file 'hi.txt' and add manifest annotations: - -```bash -oras attach --artifact-type doc/example --annotation "key=val" localhost:5000/hello:v1 hi.txt -``` - -Attach file 'hi.txt' and export the pushed manifest to 'manifest.json': - -```bash -oras attach --artifact-type doc/example --export-manifest manifest.json localhost:5000/hello:v1 hi.txt -``` - -Attach file to the manifest tagged 'v1' in an OCI image layout folder 'layout-dir': - -```bash -oras attach --oci-layout --artifact-type doc/example layout-dir:v1 hi.txt -``` - -## Options - -``` - -a, --annotation stringArray manifest annotations - --annotation-file string path of the annotation file - --artifact-type string artifact type - --ca-file string server certificate authority file for the remote registry - --concurrency int concurrency level (default 5) - -d, --debug debug mode - --disable-path-validation skip path validation - --distribution-spec string [Preview] set OCI distribution spec version and API option for target. options: v1.1-referrers-api, v1.1-referrers-tag - --export-manifest path path of the pushed manifest - -H, --header stringArray add custom headers to requests - -h, --help help for attach - --insecure allow connections to SSL registry without certs - --oci-layout set target as an OCI image layout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_blob_delete.mdx b/docs/commands/oras_blob_delete.mdx deleted file mode 100644 index 61b90666..00000000 --- a/docs/commands/oras_blob_delete.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: oras blob delete -sidebar_position: 20 -warning: Do NOT modify this generated file ---- - -# oras blob delete - -Delete a blob from a remote registry - -```bash -oras blob delete [flags] @ -``` - -## Examples - -Delete a blob: - -```bash -oras blob delete localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -Delete a blob without prompting confirmation: - -```bash -oras blob delete --force localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -Delete a blob and print its descriptor: - -```bash -oras blob delete --descriptor --force localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - --descriptor output the descriptor - -f, --force ignore nonexistent references, never prompt - -H, --header stringArray add custom headers to requests - -h, --help help for delete - --insecure allow connections to SSL registry without certs - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --pretty prettify JSON objects printed to stdout - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_blob_fetch.mdx b/docs/commands/oras_blob_fetch.mdx deleted file mode 100644 index 84797475..00000000 --- a/docs/commands/oras_blob_fetch.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: oras blob fetch -sidebar_position: 30 -warning: Do NOT modify this generated file ---- - -# oras blob fetch - -Fetch a blob from a registry or an OCI image layout - -```bash -oras blob fetch [flags] {--output | --descriptor} @ -``` - -## Examples - -Fetch a blob from registry and save it to a local file: - -```bash -oras blob fetch --output blob.tar.gz localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -Fetch a blob from registry and print the raw blob content: - -```bash -oras blob fetch --output - localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -Fetch and print the descriptor of a blob: - -```bash -oras blob fetch --descriptor localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -Fetch a blob, save it to a local file and print the descriptor: - -```bash -oras blob fetch --output blob.tar.gz --descriptor localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -Fetch and print a blob from OCI image layout folder 'layout-dir': - -```bash -oras blob fetch --oci-layout --output - layout-dir@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -Fetch and print a blob from OCI image layout archive file 'layout.tar': - -```bash -oras blob fetch --oci-layout --output - layout.tar@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - --descriptor output the descriptor - -H, --header stringArray add custom headers to requests - -h, --help help for fetch - --insecure allow connections to SSL registry without certs - --oci-layout set target as an OCI image layout - -o, --output path output file path, use - for stdout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --pretty prettify JSON objects printed to stdout - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_blob_push.mdx b/docs/commands/oras_blob_push.mdx deleted file mode 100644 index f22fa961..00000000 --- a/docs/commands/oras_blob_push.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: oras blob push -sidebar_position: 40 -warning: Do NOT modify this generated file ---- - -# oras blob push - -Push a blob to a registry or an OCI image layout - -```bash -oras blob push [flags] [@digest] -``` - -## Examples - -Push blob 'hi.txt' to a registry: - -```bash -oras blob push localhost:5000/hello hi.txt -``` - -Push blob 'hi.txt' with the specific digest: - -```bash -oras blob push localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 hi.txt -``` - -Push blob from stdin with blob size and digest: - -```bash -oras blob push --size 12 localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 - -``` - -Push blob 'hi.txt' and output the descriptor: - -```bash -oras blob push --descriptor localhost:5000/hello hi.txt -``` - -Push blob 'hi.txt' with the specific returned media type in the descriptor: - -```bash -oras blob push --media-type application/vnd.oci.image.config.v1+json --descriptor localhost:5000/hello hi.txt -``` - -Push blob 'hi.txt' and output the prettified descriptor: - -```bash -oras blob push --descriptor --pretty localhost:5000/hello hi.txt -``` - -Push blob without TLS: - -```bash -oras blob push --insecure localhost:5000/hello hi.txt -``` - -Push blob 'hi.txt' into an OCI image layout folder 'layout-dir': - -```bash -oras blob push --oci-layout layout-dir hi.txt -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - --descriptor output the descriptor - -H, --header stringArray add custom headers to requests - -h, --help help for push - --insecure allow connections to SSL registry without certs - --media-type string specify the returned media type in the descriptor if --descriptor is used (default "application/vnd.oci.image.layer.v1.tar") - --oci-layout set target as an OCI image layout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --pretty prettify JSON objects printed to stdout - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - --size int provide the blob size (default -1) - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_completion_bash.mdx b/docs/commands/oras_completion_bash.mdx deleted file mode 100644 index df773508..00000000 --- a/docs/commands/oras_completion_bash.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: oras completion bash -sidebar_position: 50 ---- - -# oras completion bash - -Generate the autocompletion script for the bash shell. -This script depends on the 'bash-completion' package. -If it is not installed already, you can install it via your operationg system package manager. -To load completions in your current shell session: -```bash - source <(oras completion bash) -``` - -To load completions for every new session, execute once: -## Linux: -```bash - oras completion bash > /etc/bash_completion.d/oras -``` - -## macOS: -```bash - oras completion bash > $(brew --prefix)/etc/bash_completion.d/oras -``` - -You will need to start a new shell for this setup to take effect. - -## Options - -``` - -h, --help help for bash - --no-descriptions disable completion descriptions -``` diff --git a/docs/commands/oras_completion_fish.mdx b/docs/commands/oras_completion_fish.mdx deleted file mode 100644 index 8971c852..00000000 --- a/docs/commands/oras_completion_fish.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: oras completion fish -sidebar_position: 60 ---- - -# oras completion fish - -Generate the autocompletion script for the fish shell. -To load completions in your current shell session: -```bash - oras completion fish | source -``` - -To load completions for every new session, execute once: -```bash - oras completion fish > ~/.config/fish/completions/oras.fish -``` - -You will need to start a new shell for this setup to take effect. - -## Options - -``` - -h, --help help for fish - --no-descriptions disable completion descriptions -``` diff --git a/docs/commands/oras_completion_powershell.mdx b/docs/commands/oras_completion_powershell.mdx deleted file mode 100644 index ec89280f..00000000 --- a/docs/commands/oras_completion_powershell.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: oras completion powershell -sidebar_position: 70 ---- - -# oras completion powershell - -Generate the autocompletion script for powershell. -To load completions in your current shell session: -```bash - oras completion powershell | Out-String | Invoke-Expression -``` - -To load completions for every new session, add the output of the above command -to your powershell profile. - -## Options - -``` - -h, --help help for powershell - --no-descriptions disable completion descriptions -``` diff --git a/docs/commands/oras_completion_zsh.mdx b/docs/commands/oras_completion_zsh.mdx deleted file mode 100644 index 89ea6bc6..00000000 --- a/docs/commands/oras_completion_zsh.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: oras completion zsh -sidebar_position: 80 ---- - -# oras completion zsh - -Generate the autocompletion script for the zsh shell. -If shell completion is not already enabled in your environment you will need -to enable it. You can execute the following once: -```bash - echo "autoload -U compinit; compinit" >> ~/.zshrc -``` - -To load completions in your current shell session: -```bash - source <(oras completion zsh) -``` - -To load completions for every new session, execute once: -## Linux: -```bash -oras completion zsh > "${fpath[1]}/_oras" -``` - -## macOS: -```bash -oras completion zsh > $(brew --prefix)/share/zsh/site-functions/_oras -``` - -You will need to start a new shell for this setup to take effect. - -## Options - -``` - -h, --help help for zsh - --no-descriptions disable completion descriptions -``` diff --git a/docs/commands/oras_cp.mdx b/docs/commands/oras_cp.mdx deleted file mode 100644 index 4503c5d6..00000000 --- a/docs/commands/oras_cp.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: oras cp -sidebar_position: 50 -warning: Do NOT modify this generated file ---- - -# oras cp - -Copy artifacts from one target to another - -```bash -oras cp [flags] {:|@} [:[,][...]] -``` - -## Examples - -Copy an artifact between registries: - -```bash -oras cp localhost:5000/net-monitor:v1 localhost:6000/net-monitor-copy:v1 -``` - -Download an artifact into an OCI image layout folder: - -```bash -oras cp --to-oci-layout localhost:5000/net-monitor:v1 ./downloaded:v1 -``` - -Upload an artifact from an OCI image layout folder: - -```bash -oras cp --from-oci-layout ./to-upload:v1 localhost:5000/net-monitor:v1 -``` - -Upload an artifact from an OCI layout tar archive: - -```bash -oras cp --from-oci-layout ./to-upload.tar:v1 localhost:5000/net-monitor:v1 -``` - -Copy an artifact and its referrers: - -```bash -oras cp -r localhost:5000/net-monitor:v1 localhost:6000/net-monitor-copy:v1 -``` - -Copy an artifact and referrers using specific methods for the Referrers API: - -```bash -oras cp -r --from-distribution-spec v1.1-referrers-api --to-distribution-spec v1.1-referrers-tag localhost:5000/net-monitor:v1 localhost:6000/net-monitor-copy:v1 -``` - -Copy certain platform of an artifact: - -```bash -oras cp --platform linux/arm/v5 localhost:5000/net-monitor:v1 localhost:6000/net-monitor-copy:v1 -``` - -Copy an artifact with multiple tags: - -```bash -oras cp localhost:5000/net-monitor:v1 localhost:6000/net-monitor-copy:tag1,tag2,tag3 -``` - -Copy an artifact with multiple tags with concurrency tuned: - -```bash -oras cp --concurrency 10 localhost:5000/net-monitor:v1 localhost:5000/net-monitor-copy:tag1,tag2,tag3 -``` - -## Options - -``` - --concurrency int concurrency level (default 3) - -d, --debug debug mode - --from-ca-file string server certificate authority file for the remote source registry - --from-distribution-spec string [Preview] set OCI distribution spec version and API option for source target. options: v1.1-referrers-api, v1.1-referrers-tag - --from-header stringArray add custom headers to source requests - --from-insecure allow connections to source SSL registry without certs - --from-oci-layout set source target as an OCI image layout - --from-password string source registry password or identity token - --from-plain-http allow insecure connections to source registry without SSL check - --from-registry-config path path of the authentication file for source registry - --from-resolve host:port:address[:address_port] customized DNS for source registry, formatted in host:port:address[:address_port] - --from-username string source registry username - -h, --help help for cp - --platform os[/arch][/variant][:os_version] request platform in the form of os[/arch][/variant][:os_version] - -r, --recursive [Preview] recursively copy the artifact and its referrer artifacts - --resolve host:port:address[:address_port] base DNS rules formatted in host:port:address[:address_port] for --from-resolve and --to-resolve - --to-ca-file string server certificate authority file for the remote destination registry - --to-distribution-spec string [Preview] set OCI distribution spec version and API option for destination target. options: v1.1-referrers-api, v1.1-referrers-tag - --to-header stringArray add custom headers to destination requests - --to-insecure allow connections to destination SSL registry without certs - --to-oci-layout set destination target as an OCI image layout - --to-password string destination registry password or identity token - --to-plain-http allow insecure connections to destination registry without SSL check - --to-registry-config path path of the authentication file for destination registry - --to-resolve host:port:address[:address_port] customized DNS for destination registry, formatted in host:port:address[:address_port] - --to-username string destination registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_discover.mdx b/docs/commands/oras_discover.mdx deleted file mode 100644 index b35feb90..00000000 --- a/docs/commands/oras_discover.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: oras discover -sidebar_position: 60 -warning: Do NOT modify this generated file ---- - -# oras discover - -[Preview] Discover referrers of a manifest in a registry or an OCI image layout -** This command is in preview and under development. ** - -```bash -oras discover [flags] {:|@} -``` - -## Examples - -Discover direct referrers of manifest 'hello:v1' in registry 'localhost:5000': - -```bash -oras discover localhost:5000/hello:v1 -``` - -Discover direct referrers via referrers API: - -```bash -oras discover --distribution-spec v1.1-referrers-api localhost:5000/hello:v1 -``` - -Discover direct referrers via tag scheme: - -```bash -oras discover --distribution-spec v1.1-referrers-tag localhost:5000/hello:v1 -``` - -Discover all the referrers of manifest 'hello:v1' in registry 'localhost:5000', displayed in a tree view: - -```bash -oras discover -o tree localhost:5000/hello:v1 -``` - -Discover all the referrers of manifest with annotations, displayed in a tree view: - -```bash -oras discover -v -o tree localhost:5000/hello:v1 -``` - -Discover referrers with type 'test-artifact' of manifest 'hello:v1' in registry 'localhost:5000': - -```bash -oras discover --artifact-type test-artifact localhost:5000/hello:v1 -``` - -Discover referrers of the manifest tagged 'v1' in an OCI image layout folder 'layout-dir': - -```bash -oras discover --oci-layout layout-dir:v1 -oras discover --oci-layout -v -o tree layout-dir:v1 -``` - -## Options - -``` - --artifact-type string artifact type - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - --distribution-spec string [Preview] set OCI distribution spec version and API option for target. options: v1.1-referrers-api, v1.1-referrers-tag - -H, --header stringArray add custom headers to requests - -h, --help help for discover - --insecure allow connections to SSL registry without certs - --oci-layout set target as an OCI image layout - -o, --output string format in which to display referrers (table, json, or tree). tree format will also show indirect referrers (default "table") - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --platform os[/arch][/variant][:os_version] request platform in the form of os[/arch][/variant][:os_version] - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_help.mdx b/docs/commands/oras_help.mdx deleted file mode 100644 index dfee4c95..00000000 --- a/docs/commands/oras_help.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: oras help -sidebar_position: 70 -warning: Do NOT modify this generated file ---- - -# oras help - -Help provides help for any command in the application. -Simply type oras help [path to command] for full details. - -```bash -oras help [command] [flags] -``` - -## Options - -``` - -h, --help help for help -``` diff --git a/docs/commands/oras_login.mdx b/docs/commands/oras_login.mdx deleted file mode 100644 index 62612000..00000000 --- a/docs/commands/oras_login.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: oras login -sidebar_position: 80 -warning: Do NOT modify this generated file ---- - -# oras login - -Log in to a remote registry - -```bash -oras login [flags] -``` - -## Examples - -Log in with username and password from command line flags: - -```bash -oras login -u username -p password localhost:5000 -``` - -Log in with username and password from stdin: - -```bash -oras login -u username --password-stdin localhost:5000 -``` - -Log in with identity token from command line flags: - -```bash -oras login -p token localhost:5000 -``` - -Log in with identity token from stdin: - -```bash -oras login --password-stdin localhost:5000 -``` - -Log in with username and password in an interactive terminal: - -```bash -oras login localhost:5000 -``` - -Log in with username and password in an interactive terminal and no TLS check: - -```bash -oras login --insecure localhost:5000 -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - -H, --header stringArray add custom headers to requests - -h, --help help for login - --insecure allow connections to SSL registry without certs - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_logout.mdx b/docs/commands/oras_logout.mdx deleted file mode 100644 index ca0e75e6..00000000 --- a/docs/commands/oras_logout.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: oras logout -sidebar_position: 90 -warning: Do NOT modify this generated file ---- - -# oras logout - -Log out from a remote registry - -```bash -oras logout [flags] -``` - -## Examples - -Logout: - -```bash -oras logout localhost:5000 -``` - -## Options - -``` - -d, --debug debug mode - -h, --help help for logout - --registry-config stringArray auth config path -``` diff --git a/docs/commands/oras_manifest_delete.mdx b/docs/commands/oras_manifest_delete.mdx deleted file mode 100644 index 6ea48d25..00000000 --- a/docs/commands/oras_manifest_delete.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: oras manifest delete -sidebar_position: 100 -warning: Do NOT modify this generated file ---- - -# oras manifest delete - -Delete a manifest from remote registry - -```bash -oras manifest delete [flags] {:|@} -``` - -## Examples - -Delete a manifest tagged with 'v1' from repository 'localhost:5000/hello': - -```bash -oras manifest delete localhost:5000/hello:v1 -``` - -Delete a manifest without prompting confirmation: - -```bash -oras manifest delete --force localhost:5000/hello:v1 -``` - -Delete a manifest and print its descriptor: - -```bash -oras manifest delete --descriptor localhost:5000/hello:v1 -``` - -Delete a manifest by digest 'sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9' from repository 'localhost:5000/hello': - -```bash -oras manifest delete localhost:5000/hello@sha:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9 -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - --descriptor output the descriptor - --distribution-spec string [Preview] set OCI distribution spec version and API option for target. options: v1.1-referrers-api, v1.1-referrers-tag - -f, --force ignore nonexistent references, never prompt - -H, --header stringArray add custom headers to requests - -h, --help help for delete - --insecure allow connections to SSL registry without certs - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --pretty prettify JSON objects printed to stdout - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_manifest_fetch-config.mdx b/docs/commands/oras_manifest_fetch-config.mdx deleted file mode 100644 index 61438e3e..00000000 --- a/docs/commands/oras_manifest_fetch-config.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: oras manifest fetch-config -sidebar_position: 120 -warning: Do NOT modify this generated file ---- - -# oras manifest fetch-config - -Fetch the config of a manifest from a registry or an OCI image layout - -```bash -oras manifest fetch-config [flags] {:|@} -``` - -## Examples - -Fetch the config: - -```bash -oras manifest fetch-config localhost:5000/hello:v1 -``` - -Fetch the config of certain platform: - -```bash -oras manifest fetch-config --platform 'linux/arm/v5' localhost:5000/hello:v1 -``` - -Fetch and print the prettified config: - -```bash -oras manifest fetch-config --pretty localhost:5000/hello:v1 -``` - -Fetch the config and save it to a local file: - -```bash -oras manifest fetch-config --output config.json localhost:5000/hello:v1 -``` - -Fetch the descriptor of the config: - -```bash -oras manifest fetch-config --descriptor localhost:5000/hello:v1 -``` - -Fetch and print the prettified descriptor of the config: - -```bash -oras manifest fetch-config --descriptor --pretty localhost:5000/hello:v1 -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - --descriptor output the descriptor - -H, --header stringArray add custom headers to requests - -h, --help help for fetch-config - --insecure allow connections to SSL registry without certs - --oci-layout set target as an OCI image layout - -o, --output path file path to write the fetched config to, use - for stdout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --platform os[/arch][/variant][:os_version] request platform in the form of os[/arch][/variant][:os_version] - --pretty prettify JSON objects printed to stdout - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_manifest_fetch.mdx b/docs/commands/oras_manifest_fetch.mdx deleted file mode 100644 index b55888cd..00000000 --- a/docs/commands/oras_manifest_fetch.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: oras manifest fetch -sidebar_position: 110 -warning: Do NOT modify this generated file ---- - -# oras manifest fetch - -Fetch manifest of the target artifact - -```bash -oras manifest fetch [flags] {:|@} -``` - -## Examples - -Fetch raw manifest from a registry: - -```bash -oras manifest fetch localhost:5000/hello:v1 -``` - -Fetch the descriptor of a manifest from a registry: - -```bash -oras manifest fetch --descriptor localhost:5000/hello:v1 -``` - -Fetch manifest from a registry with specified media type: - -```bash -oras manifest fetch --media-type 'application/vnd.oci.image.manifest.v1+json' localhost:5000/hello:v1 -``` - -Fetch manifest from a registry with certain platform: - -```bash -oras manifest fetch --platform 'linux/arm/v5' localhost:5000/hello:v1 -``` - -Fetch manifest from a registry with prettified json result: - -```bash -oras manifest fetch --pretty localhost:5000/hello:v1 -``` - -Fetch raw manifest from an OCI image layout folder 'layout-dir': - -```bash -oras manifest fetch --oci-layout layout-dir:v1 -``` - -Fetch raw manifest from an OCI layout archive file 'layout.tar': - -```bash -oras manifest fetch --oci-layout layout.tar:v1 -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - --descriptor output the descriptor - -H, --header stringArray add custom headers to requests - -h, --help help for fetch - --insecure allow connections to SSL registry without certs - --media-type strings accepted media types - --oci-layout set target as an OCI image layout - -o, --output path file path to write the fetched manifest to, use - for stdout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --platform os[/arch][/variant][:os_version] request platform in the form of os[/arch][/variant][:os_version] - --pretty prettify JSON objects printed to stdout - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_manifest_push.mdx b/docs/commands/oras_manifest_push.mdx deleted file mode 100644 index 69e01441..00000000 --- a/docs/commands/oras_manifest_push.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: oras manifest push -sidebar_position: 130 -warning: Do NOT modify this generated file ---- - -# oras manifest push - -Push a manifest to a registry or an OCI image layout - -```bash -oras manifest push [flags] [:[,][...]|@] -``` - -## Examples - -Push a manifest to repository 'localhost:5000/hello' and tag with 'v1': - -```bash -oras manifest push localhost:5000/hello:v1 manifest.json -``` - -Push a manifest using a specific method for the Referrers API: - -```bash -oras manifest push --distribution-spec v1.1-referrers-api localhost:5000/hello:v1 manifest.json -oras manifest push --distribution-spec v1.1-referrers-tag localhost:5000/hello:v1 manifest.json -``` - -Push a manifest with content read from stdin: - -```bash -oras manifest push localhost:5000/hello:v1 - -``` - -Push a manifest and output its descriptor: - -```bash -oras manifest push --descriptor localhost:5000/hello:v1 manifest.json -``` - -Push a manifest to repository 'localhost:5000/hello' and output the prettified descriptor: - -```bash -oras manifest push --descriptor --pretty localhost:5000/hello manifest.json -``` - -Push a manifest with specified media type to repository 'localhost:5000/hello' and tag with 'v1': - -```bash -oras manifest push --media-type application/vnd.cncf.oras.artifact.manifest.v1+json localhost:5000/hello:v1 oras_manifest.json -``` - -Push a manifest to repository 'localhost:5000/hello' and tag with 'tag1', 'tag2', 'tag3': - -```bash -oras manifest push localhost:5000/hello:tag1,tag2,tag3 manifest.json -``` - -Push a manifest to repository 'localhost:5000/hello' and tag with 'tag1', 'tag2', 'tag3' and concurrency level tuned: - -```bash -oras manifest push --concurrency 6 localhost:5000/hello:tag1,tag2,tag3 manifest.json -``` - -Push a manifest to an OCI image layout folder 'layout-dir' and tag with 'v1': - -```bash -oras manifest push --oci-layout layout-dir:v1 manifest.json -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - --concurrency int concurrency level (default 5) - -d, --debug debug mode - --descriptor output the descriptor - --distribution-spec string [Preview] set OCI distribution spec version and API option for target. options: v1.1-referrers-api, v1.1-referrers-tag - -H, --header stringArray add custom headers to requests - -h, --help help for push - --insecure allow connections to SSL registry without certs - --media-type string media type of manifest - --oci-layout set target as an OCI image layout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --pretty prettify JSON objects printed to stdout - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_pull.mdx b/docs/commands/oras_pull.mdx deleted file mode 100644 index 925d81b6..00000000 --- a/docs/commands/oras_pull.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: oras pull -sidebar_position: 140 -warning: Do NOT modify this generated file ---- - -# oras pull - -Pull files from a registry or an OCI image layout - -```bash -oras pull [flags] {:|@} -``` - -## Examples - -Pull artifact files from a registry: - -```bash -oras pull localhost:5000/hello:v1 -``` - -Recursively pulling all files from a registry, including subjects of hello:v1: - -```bash -oras pull --include-subject localhost:5000/hello:v1 -``` - -Pull files from an insecure registry: - -```bash -oras pull --insecure localhost:5000/hello:v1 -``` - -Pull files from the HTTP registry: - -```bash -oras pull --plain-http localhost:5000/hello:v1 -``` - -Pull files from a registry with local cache: - -```bash -export ORAS_CACHE=~/.oras/cache -oras pull localhost:5000/hello:v1 -``` - -Pull files from a registry with certain platform: - -```bash -oras pull --platform linux/arm/v5 localhost:5000/hello:v1 -``` - -Pull all files with concurrency level tuned: - -```bash -oras pull --concurrency 6 localhost:5000/hello:v1 -``` - -Pull artifact files from an OCI image layout folder 'layout-dir': - -```bash -oras pull --oci-layout layout-dir:v1 -``` - -Pull artifact files from an OCI layout archive 'layout.tar': - -```bash -oras pull --oci-layout layout.tar:v1 -``` - -## Options - -``` - -T, --allow-path-traversal allow storing files out of the output directory - --ca-file string server certificate authority file for the remote registry - --concurrency int concurrency level (default 3) - --config string output manifest config file - -d, --debug debug mode - -H, --header stringArray add custom headers to requests - -h, --help help for pull - --include-subject [Preview] recursively pull the subject of artifacts - --insecure allow connections to SSL registry without certs - -k, --keep-old-files do not replace existing files when pulling, treat them as errors - --oci-layout set target as an OCI image layout - -o, --output string output directory (default ".") - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --platform os[/arch][/variant][:os_version] request platform in the form of os[/arch][/variant][:os_version] - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_push.mdx b/docs/commands/oras_push.mdx deleted file mode 100644 index a54c8082..00000000 --- a/docs/commands/oras_push.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: oras push -sidebar_position: 150 -warning: Do NOT modify this generated file ---- - -# oras push - -Push files to a registry or an OCI image layout - -```bash -oras push [flags] [:[,][...]] [:] [...] -``` - -## Examples - -Push file "hi.txt" with media type "application/vnd.oci.image.layer.v1.tar" (default): - -```bash -oras push localhost:5000/hello:v1 hi.txt -``` - -Push file "hi.txt" and export the pushed manifest to a specified path: - -```bash -oras push --export-manifest manifest.json localhost:5000/hello:v1 hi.txt -``` - -Push file "hi.txt" with the custom media type "application/vnd.me.hi": - -```bash -oras push localhost:5000/hello:v1 hi.txt:application/vnd.me.hi -``` - -Push multiple files with different media types: - -```bash -oras push localhost:5000/hello:v1 hi.txt:application/vnd.me.hi bye.txt:application/vnd.me.bye -``` - -Push file "hi.txt" with artifact type "application/vnd.example+type": - -```bash -oras push --artifact-type application/vnd.example+type localhost:5000/hello:v1 hi.txt -``` - -Push file "hi.txt" with config type "application/vnd.me.config": - -```bash -oras push --image-spec v1.0 --artifact-type application/vnd.me.config localhost:5000/hello:v1 hi.txt -``` - -Push file "hi.txt" with the custom manifest config "config.json" of the custom media type "application/vnd.me.config": - -```bash -oras push --config config.json:application/vnd.me.config localhost:5000/hello:v1 hi.txt -``` - -Push file to the insecure registry: - -```bash -oras push --insecure localhost:5000/hello:v1 hi.txt -``` - -Push file to the HTTP registry: - -```bash -oras push --plain-http localhost:5000/hello:v1 hi.txt -``` - -Push repository with manifest annotations: - -```bash -oras push --annotation "key=val" localhost:5000/hello:v1 -``` - -Push repository with manifest annotation file: - -```bash -oras push --annotation-file annotation.json localhost:5000/hello:v1 -``` - -Push file "hi.txt" with multiple tags: - -```bash -oras push localhost:5000/hello:tag1,tag2,tag3 hi.txt -``` - -Push file "hi.txt" with multiple tags and concurrency level tuned: - -```bash -oras push --concurrency 6 localhost:5000/hello:tag1,tag2,tag3 hi.txt -``` - -Push file "hi.txt" into an OCI image layout folder 'layout-dir' with tag 'test': - -```bash -oras push --oci-layout layout-dir:test hi.txt -``` - -## Options - -``` - -a, --annotation stringArray manifest annotations - --annotation-file string path of the annotation file - --artifact-type string artifact type - --ca-file string server certificate authority file for the remote registry - --concurrency int concurrency level (default 5) - --config path path of image config file - -d, --debug debug mode - --disable-path-validation skip path validation - --export-manifest path path of the pushed manifest - -H, --header stringArray add custom headers to requests - -h, --help help for push - --image-spec string [Experimental] specify manifest type for building artifact. options: v1.1, v1.0 (default "v1.1") - --insecure allow connections to SSL registry without certs - --oci-layout set target as an OCI image layout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_repo_ls.mdx b/docs/commands/oras_repo_ls.mdx deleted file mode 100644 index 0552c0c1..00000000 --- a/docs/commands/oras_repo_ls.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: oras repo ls -sidebar_position: 160 -warning: Do NOT modify this generated file ---- - -# oras repo ls - -List the repositories under the registry - -```bash -oras repo ls [flags] -``` - -## Examples - -List the repositories under the registry: - -```bash -oras repo ls localhost:5000 -``` - -List the repositories under a namespace in the registry: - -```bash -oras repo ls localhost:5000/example-namespace -``` - -List the repositories under the registry that include values lexically after last: - -```bash -oras repo ls --last "last_repo" localhost:5000 -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - -H, --header stringArray add custom headers to requests - -h, --help help for ls - --insecure allow connections to SSL registry without certs - --last last start after the repository specified by last - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_repo_tags.mdx b/docs/commands/oras_repo_tags.mdx deleted file mode 100644 index 9398e90d..00000000 --- a/docs/commands/oras_repo_tags.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: oras repo tags -sidebar_position: 170 -warning: Do NOT modify this generated file ---- - -# oras repo tags - -Show tags of the target repository - -```bash -oras repo tags [flags] -``` - -## Examples - -Show tags of the target repository: - -```bash -oras repo tags localhost:5000/hello -``` - -Show tags in the target repository with digest-like tags hidden: - -```bash -oras repo tags --exclude-digest-tag localhost:5000/hello -``` - -Show tags of the target repository that include values lexically after last: - -```bash -oras repo tags --last "last_tag" localhost:5000/hello -``` - -Show tags of the target OCI image layout folder 'layout-dir': - -```bash -oras repo tags --oci-layout layout-dir -``` - -Show tags of the target OCI layout archive 'layout.tar': - -```bash -oras repo tags --oci-layout layout.tar -``` - -[Experimental] Show tags associated with a particular tagged resource: - -```bash -oras repo tags localhost:5000/hello:latest -``` - -[Experimental] Show tags associated with a digest: - -```bash -oras repo tags localhost:5000/hello@sha256:c551125a624189cece9135981621f3f3144564ddabe14b523507bf74c2281d9b -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - -d, --debug debug mode - --exclude-digest-tags [Preview] exclude all digest-like tags such as 'sha256-aaaa...' - -H, --header stringArray add custom headers to requests - -h, --help help for tags - --insecure allow connections to SSL registry without certs - --last last start after the tag specified by last - --oci-layout set target as an OCI image layout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_tag.mdx b/docs/commands/oras_tag.mdx deleted file mode 100644 index 46bb3343..00000000 --- a/docs/commands/oras_tag.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: oras tag -sidebar_position: 180 -warning: Do NOT modify this generated file ---- - -# oras tag - -Tag a manifest in a registry or an OCI image layout - -```bash -oras tag [flags] {:|@} [...] -``` - -## Examples - -Tag the manifest 'v1.0.1' in 'localhost:5000/hello' to 'v1.0.2': - -```bash -oras tag localhost:5000/hello:v1.0.1 v1.0.2 -``` - -Tag the manifest with digest sha256:9463e0d192846bc994279417b50114606712d516aab45f4d8b31cbc6e46aad71 to 'v1.0.2' - -```bash -oras tag localhost:5000/hello@sha256:9463e0d192846bc994279417b50114606712d516aab45f4d8b31cbc6e46aad71 v1.0.2 -``` - -Tag the manifest 'v1.0.1' in 'localhost:5000/hello' to 'v1.0.2', 'latest' - -```bash -oras tag localhost:5000/hello:v1.0.1 v1.0.2 latest -``` - -Tag the manifest 'v1.0.1' in 'localhost:5000/hello' to 'v1.0.1', 'v1.0.2', 'latest' with concurrency level tuned: - -```bash -oras tag --concurrency 1 localhost:5000/hello:v1.0.1 v1.0.2 latest -``` - -Tag the manifest 'v1.0.1' to 'v1.0.2' in an OCI image layout folder 'layout-dir': - -```bash -oras tag layout-dir:v1.0.1 v1.0.2 -``` - -## Options - -``` - --ca-file string server certificate authority file for the remote registry - --concurrency int concurrency level (default 5) - -d, --debug debug mode - -H, --header stringArray add custom headers to requests - -h, --help help for tag - --insecure allow connections to SSL registry without certs - --oci-layout set target as an OCI image layout - -p, --password string registry password or identity token - --password-stdin read password or identity token from stdin - --plain-http allow insecure connections to registry without SSL check - --registry-config path path of the authentication file for registry - --resolve host:port:address[:address_port] customized DNS for registry, formatted in host:port:address[:address_port] - -u, --username string registry username - -v, --verbose verbose output -``` diff --git a/docs/commands/oras_version.mdx b/docs/commands/oras_version.mdx deleted file mode 100644 index efd519e1..00000000 --- a/docs/commands/oras_version.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: oras version -sidebar_position: 190 -warning: Do NOT modify this generated file ---- - -# oras version - -Show the oras version information - -```bash -oras version [flags] -``` - -## Examples - -print version: - -```bash -oras version -``` - -## Options - -``` - -h, --help help for version -``` diff --git a/docs/commands/use_oras_cli.mdx b/docs/commands/use_oras_cli.mdx deleted file mode 100644 index 460d9b3a..00000000 --- a/docs/commands/use_oras_cli.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Use the ORAS command line -sidebar_position: 0 ---- - -# Use the ORAS command line - -To list available commands, either run `oras` with no parameters or execute `oras help`: - -``` -$ oras -Usage: - oras [command] - -Available Commands: - attach Attach files to an existing artifact - blob Blob operations - completion Generate the autocompletion script for the specified shell - cp Copy artifacts from one target to another - discover Discover referrers of a manifest in the remote registry - help Help about any command - login Log in to a remote registry - logout Log out from a remote registry - manifest Manifest operations - pull Pull files from remote registry - push Push files to remote registry - repo Repository operations - tag Tag a manifest in the remote registry - version Show the oras version information - -Flags: - -h, --help help for oras - -Use "oras [command] --help" for more information about a command. -``` - diff --git a/docs/compatible_oci_registries.mdx b/docs/compatible_oci_registries.mdx deleted file mode 100644 index 0f230fe5..00000000 --- a/docs/compatible_oci_registries.mdx +++ /dev/null @@ -1,329 +0,0 @@ ---- -title: Compatible OCI Registries -sidebar_position: 70 ---- - -# Compatible OCI Registries - -This page contains a list of projects leveraging ORAS, as well as -registries that are known to support [OCI Artifacts][artifacts]. - -*Would like your registry and/or project listed here? -Please [submit an issue](https://github.com/oras-project/oras-www/issues/new?assignees=&labels=adopter&template=submit_adopter.yml&title=%5BAdd+adopter%5D%3A). -We're happy to promote all usage, as well as provide feedback.* - -## Registries supporting OCI Artifacts - -- [CNCF Distribution](#cncf-distribution) - local/offline verification -- [Amazon Elastic Container Registry](#amazon-elastic-container-registry-ecr) -- [Azure Container Registry](#azure-container-registry-acr) -- [Google Artifact Registry](#google-artifact-registry-gar) -- [GitHub Packages container registry](#github-packages-container-registry-ghcr) -- [Docker Hub](#docker-hub) -- [Zot Registry](#zot-registry) - -### CNCF Distribution - -[https://github.com/distribution/distribution](https://github.com/distribution/distribution) version 2.7+ - -[CNCF Distribution](https://github.com/distribution/distribution) is a reference implementation of the [OCI distribution-spec][distribution-spec]. Running distribution locally, as a container, provides local/offline verification of ORAS and [OCI Artifacts][artifacts]. - -#### Using a local, unauthenticated container registry - -Run the [docker registry image](https://hub.docker.com/_/registry) locally: - -``` -docker run -it --rm -p 5000:5000 registry -``` - -This will start a distribution server at `localhost:5000` -*(with wide-open access and no persistence outside of the container)*. - -#### Using Docker Registry with authentication - -- Create a valid htpasswd file (must use `-B` for bcrypt): - - ``` - htpasswd -cB -b auth.htpasswd myuser mypass - ``` - -- Start a registry using the password file for authentication: - - ``` - docker run -it --rm -p 5000:5000 \ - -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \ - -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \ - registry - ``` - -- In a new window, login with `oras`: - - ``` - oras login -u myuser -p mypass localhost:5000 - ``` - -You will notice a new entry for `localhost:5000` appear in `~/.docker/config.json`. - -To remove the entry from the credentials file, use `oras logout`: - -``` -oras logout localhost:5000 -``` - -#### Using an insecure Docker registry - -To login to the registry without a certificate, a self-signed certificate, or an unencrypted HTTP connection Docker registry, `oras` supports the `--insecure` flag. - -- Create a valid htpasswd file (must use `-B` for bcrypt): - - ``` - htpasswd -cB -b auth.htpasswd myuser mypass - ``` - -- Generate your self-signed certificates: - - ``` - $ mkdir -p certs - $ openssl req \ - -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \ - -x509 -days 365 -out certs/domain.crt - ``` - -- Start a registry using that file for auth and listen the `0.0.0.0` address: - - ``` - docker run -it --rm -p 5000:5000 \ - -v `pwd`/certs:/certs \ - -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \ - -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \ - -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 \ - -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ - -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ - registry - ``` - -- In a new window, login with `oras` using the ip address not localhost: - - ``` - oras login -u myuser -p mypass --insecure :5000 - ``` - -You will notice a new entry for `:5000` appear in `~/.docker/config.json`. - -Then you can pull files from the registry or push files to the registry. - -- To push single file to this registry: - - ``` - oras push :5000/library/hello:latest hi.txt --insecure - ``` - -- To pull files from this registry: - - ``` - oras pull :5000/library/hello:latest --insecure - ``` - -- To remove the entry from the credentials file, use `oras logout`: - - ``` - oras logout :5000 - ``` - -##### Using a plain HTTP Docker registry - -To pull or push the HTTP Docker registry. `oras` support `--plain-http` flag to pull or push. - -The `--plain-http` flag mean that you want to use http instead of https to connect the Docker registry. - -- Create a valid htpasswd file (must use `-B` for bcrypt): - - ``` - htpasswd -cB -b auth.htpasswd myuser mypass - ``` - -- Start a registry using that file for auth and listen the `0.0.0.0` address: - - ``` - docker run -it --rm -p 5000:5000 \ - -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \ - -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \ - -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 \ - registry - ``` - -- In a new window, login with `oras` using the ip address not localhost: - - ``` - oras login -u myuser -p mypass --insecure :5000 - ``` - -You will notice a new entry for `:5000` appear in `~/.docker/config.json`. - -Then you can pull files from the registry or push files to the registry. - -- To push single file to this registry: - - ``` - oras push :5000/library/hello:latest hi.txt --plain-http - ``` - -- To pull files from this registry: - - ``` - oras pull :5000/library/hello:latest --plain-http - ``` - -- To remove the entry from the credentials file, use `oras logout`: - - ``` - oras logout :5000 - ``` - -### [Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/) - -ECR Artifact Blog Post: [OCI Arfifact Support in Amazon ECR](https://aws.amazon.com/blogs/containers/oci-artifact-support-in-amazon-ecr/) - -- Authenticating with ECR using the AWS CLI - ``` - aws ecr get-login-password --region $AWS_REGION --profile $PROFILE | oras login \ - --password-stdin \ - --username AWS \ - "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com" - ``` - -- Pushing Artifacts to ECR - - ``` - oras push $REPO_URI:1.0 \ - --artifact-type application/vnd.unknown.config.v1+json \ - ./artifact.txt:application/vnd.unknown.layer.v1+txt - ``` - -- Pulling Artifacts from ECR - - ``` - oras pull $REPO_URI:1.0 - ``` - -### [Azure Container Registry (ACR)](https://aka.ms/acr) - -ACR Artifact Documentation: [aka.ms/acr/artifacts](https://aka.ms/acr/artifacts) - -- Authenticating with ACR using [Service Principals](https://docs.microsoft.com/azure/container-registry/container-registry-auth-service-principal) - - ``` - oras login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD - ``` - -- Authenticating with ACR [using AAD credentials](https://docs.microsoft.com/azure/container-registry/container-registry-authentication) and the [`az cli`](https://docs.microsoft.com/cli/azure/install-azure-cli?view=azure-cli-latest) - - ``` - az login - az acr login --name myregistry - ``` - -- Pushing Artifacts to ACR - - ``` - oras push myregistry.azurecr.io/samples/artifact:1.0 \ - --artifact-type application/vnd.unknown.config.v1+json \ - ./artifact.txt:application/vnd.unknown.layer.v1+txt - ``` - -- Pulling Artifacts from ACR - - ``` - oras pull myregistry.azurecr.io/samples/artifact:1.0 - ``` - -### [Google Artifact Registry (GAR)](https://cloud.google.com/artifact-registry) - -- Authenticating with GAR using the gcloud command-line tool - - ``` - gcloud auth configure-docker ${REGION}-docker.pkg.dev - ``` - -- Pushing Artifacts to GAR - - ``` - oras push ${REGION}-docker.pkg.dev/${GCP_PROJECT}/samples/artifact:1.0 \ - ./artifact.txt:application/vnd.unknown.layer.v1+txt - ``` - -- Pulling Artifacts from GAR - - ``` - oras pull ${REGION}-docker.pkg.dev/${GCP_PROJECT}/samples/artifact:1.0 - ``` - -### [GitHub Packages container registry (GHCR)](https://docs.github.com/en/packages/guides/about-github-container-registry) - -- [Authenticating with GHCR](https://docs.github.com/en/packages/guides/pushing-and-pulling-docker-images#authenticating-to-github-container-registry) - - ``` - echo $GITHUB_PAT | oras login ghcr.io -u GITHUB_USERNAME --password-stdin - ``` - -- Pushing Artifacts to GHCR - - ``` - oras push ghcr.io/${GITHUB_OWNER}/samples/artifact:1.0 \ - ./artifact.txt:application/vnd.unknown.layer.v1+txt - ``` - -- Pulling Artifacts from GHCR - - ``` - oras pull ghcr.io/${GITHUB_OWNER}/samples/artifact:1.0 - ``` - -### [Docker Hub](https://hub.docker.com/) - -- [Authenticating with Docker Hub](https://docs.docker.com/docker-hub/access-tokens/) - - ``` - echo $ACCESS_TOKEN | docker login -u $DH_USER --password-stdin - ``` - -- Pushing Artifacts to Docker Hub - - ``` - oras push docker.io/${DH_USER}/artifact:1.0 \ - ./artifact.txt:application/vnd.unknown.layer.v1+txt - ``` - -- Pulling Artifacts from Docker Hub - - ``` - oras pull docker.io/${DH_USER}/artifact:1.0 - ``` - -[artifacts]: https://github.com/opencontainers/artifacts -[distribution-spec]: https://github.com/opencontainers/distribution-spec/ - -### [Zot Registry](https://zotregistry.dev) - -- [Authenticating with Zot Registry](https://zotregistry.dev/user-guides/user-guide-datapath/#authentication_2) - - ``` - echo $ZR_PASSWORD | oras login :5000 -u $ZR_USER --password-stdin - ``` - -- [Pushing Artifacts to Zot Registry](https://zotregistry.dev/user-guides/user-guide-datapath/#push-an-artifact) - - ``` - oras push --plain-http :5000/hello-artifact:v2 \ - --config config.json:application/vnd.acme.rocket.config.v1+json \ - artifact.txt:text/plain -d -v - ``` - -- [Pulling Artifacts from Zot Registry](https://zotregistry.dev/user-guides/user-guide-datapath/#pull-an-artifact) - - ``` - oras pull --plain-http :5000/hello-artifact:v2 -d -v - ``` - -[artifacts]: https://github.com/opencontainers/image-spec/blob/main/artifacts-guidance.md -[distribution-spec]: https://github.com/opencontainers/distribution-spec/ diff --git a/docs/concepts/_category_.json b/docs/concepts/_category_.json deleted file mode 100644 index aab4cc33..00000000 --- a/docs/concepts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Concepts", - "position": 50, - "link": { - "type": "generated-index", - "description": "Concepts" - } -} \ No newline at end of file diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx deleted file mode 100644 index f3c9bd56..00000000 --- a/docs/concepts/artifact.mdx +++ /dev/null @@ -1,262 +0,0 @@ ---- -title: OCI artifact -sidebar_position: 1 ---- - -# Understanding OCI artifacts - -The Open Container Initiative (OCI) organization has played -a crucial role in defining the industry-standard specifications for container -formats, runtime, and artifacts. -OCI artifacts encompass an extensive variety of content types, from signatures, -Software Bill of Materials (SBOMs), Helm charts, container images, to Open Policy Agent (OPA) -bundles and more, thereby lending incredible flexibility to how containerized -applications are packaged, delivered, and updated. - -This article will delve into OCI artifacts created using a manifest defined as a part of -the OCI image specification. - -## The Anatomy of an OCI artifact - -The structure of an OCI Artifact includes an Image Manifest or an Image Index -that points to other OCI artifacts. These artifacts can be stored and accessed from -[content addressable storage][cas] like a registry, or an on-disk storage like -an [OCI-Layout][oci-layout] directory. - -The OCI artifact can be referenced using a *tag* -or a *digest*. The digest is a hash of the OCI artifact manifest or index and -should be assumed to be immutable where as the tag may be mutable. - -A *tag* resolves to a data structure called the [descriptor][descriptor] which -contains the digest of the manifest or index. - -![Diagram showing relationship and fiels of a tag image and index](/img/concepts/artifact/tag_relations.png) - -### The Significance of Annotations - -Annotations in OCI artifacts offer a means of adding metadata to various -components, including the Image Manifest, Image Index and Image Layers. -These annotations hold key-value pairs that represent either the metadata -of the OCI artifact or blobs, such as the creation time, or data of the artifact itself. - -```json -{ - ... - "annotations": { - "oci.opencontainers.image.created": "2023-01-02T03:04:05Z", - "com.example.information": "useful-info" - } -} -``` - -### Determining the artifact type - -For OCI artifacts the **type** of the artifact may be determined from the `artifactType` property -in the image manifest or index. This property was introduced in v1.1 of the [image specification][image-properties]. - -In cases when the `artifactType` property is not defined, the `config.mediaType` property may be used to determine -the type of the artifact as shown in the diagram below. - -```mermaid -flowchart TD - B{Is\nmanifest.artifactType\ndefined?} - B -->|Yes| C[type=manifest.artifactType] - B -->|No| E[type=manifest.config.mediaType] -``` - -For artifact authors, the sections below should help deciding on the blob and -config mediaTypes. - -## Dissecting the Manifest - -The structure of the artifact depends on the purpose of the artifact and content. -The manifest is a JSON document that contains the metadata for the artifact. -Artifacts may have files that are stored as blobs or metadata that is stored in the manifest -as annotations. The manifest may also contain references to other artifacts. - -### Artifacts with blobs - -Let's delve into an OCI artifact that uses an [Image Manifest][image-manifest]. -Below is an example where artifact type is `application/vnd.example+type`. The artifact -also has blobs that are referenced in the manifest in the `layers` property. It is -important to note that the `config` property is required in the manifest and -in this case the config is an empty blob as per the [empty descriptor guidance][empty-descriptor]. - -```json - { - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "artifactType": "application/vnd.example+type", - "config": { - "mediaType": "application/vnd.oci.empty.v1+json", - "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", - "size": 2 - }, - "layers": [ - { - "mediaType": "application/vnd.oci.image.layer.v1.tar", - "digest": "sha256:d2a84f4b8b650937ec8f73cd8be2c74add5a911ba64df27458ed8229da804a26", - "size": 12, - "annotations": { - "org.opencontainers.image.title": "hello.txt" - } - } - ], - "annotations": { - "org.opencontainers.image.created": "2023-08-03T00:21:51Z" - } -} -``` - -### Artifacts with config - -Clients have been using the `config.mediaType` property to declare the artifact type. -For OCI artifacts that have a valid config blob the config blob may use its own -mediaType and the `artifactType` property can be set to indicate the type of artifact. - -```json - { - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "artifactType": "application/vnd.example+type", - "config": { - "mediaType": "application/vnd.example.config.v1+json", - "digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03", - "size": 123 - }, - "layers": [ - { - "mediaType": "application/vnd.example.data.v1.tar+gzip", - "digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317", - "size": 1234 - } - ] - } -``` - -#### Prior Art - -Before version 1.1 of the [image specification][image-spec], the `config.mediaType` -was used to indicate the type of the artifact. -For example the artifact type below for the helm chart is `application/vnd.cncf.helm.config.v1+json` -as the manifest does not have the `artifactType` property. - -```json -{ - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "config": { - "mediaType": "application/vnd.cncf.helm.config.v1+json", - "digest": "sha256:34bf03806938a59ee7dc3e2c33e314d0eaef573313ff9dcc677113502d568523", - "size": 145 - }, - "layers": [ - { - "mediaType": "application/vnd.cncf.helm.chart.content.v1.tar+gzip", - "digest": "sha256:4d80464e9d8e9f3ba92e6ead6d3b5afd0532cb0a81e980599a0bced99fdc6e01", - "size": 3763 - } - ] -} -``` - -### Annotations only artifacts - -Artifacts may store metadata in the manifest as annotations and need not have a config or blobs. -For these the `artifactType` property is used to declare the type of the artifact. -The config property is required in the manifest and for maximum compatibility -an empty layer is also created as per the [empty descriptors guidance][empty-descriptor]. - -```json -{ - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "artifactType": "application/vnd.example+type", - "config": { - "mediaType": "application/vnd.oci.empty.v1+json", - "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", - "size": 2 - }, - "layers": [ - { - "mediaType": "application/vnd.oci.empty.v1+json", - "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", - "size": 2 - } - ], - "annotations": { - "oci.opencontainers.image.created": "2023-01-02T03:04:05Z", - "com.example.info": "useful-info" - } -} -``` - -### Artifact authoring decision tree - -Putting it all together with the types of artifacts listed above and -[Artifact Guidance in the image specification][artifact-guidelines], the decision tree -below should help determine what fields to set when creating an artifact. - -```mermaid -flowchart TD - HasBlob{Artifact has
at least one file?} - HasConfigData{Artifact has additional
metadata config blob?} - - Artifact_NoBlobs[Specify artifactType,
set config and layers
to empty descriptors.] - Artifact_NoConfig[Specify artifactType,
set config to empty descriptor,
include file in layers, ] - Artifact_WithConfig[Specify artifactType,
specify config blob and mediaType,
include files in layers.] - - HasBlob -- No --> Artifact_NoBlobs - HasBlob -- Yes --> HasConfigData - HasConfigData -- Yes --> Artifact_WithConfig - HasConfigData -- No --> Artifact_NoConfig -``` - -### Harnessing Image Indexes - -One of the key advantages of OCI artifacts is their ability to utilize [Image Indexes][image-index], -allowing the bundling of various OCI artifacts. - -The Image Index is a higher-level construct in the OCI Image Specification that can point to -multiple Image Manifests, each suitable for a different platform or architecture or filtered by annotation. -It helps to group related artifacts together, providing a single entry-point for accessing any specific -artifact depending on the required condition. - -## Best Practices and Limitations - -While working with OCI artifacts, keep in mind that client tools and registries -are in the process of implementing v1.1 version of the OCI image and distribution specifications. - -- When clients or registries support the `artifactType` property, the `config.mediaType` -can be set to _application/vnd.oci.empty.v1+json_ if the artifact doesn't have a config. -blob as per the [empty descriptor guidance][empty-descriptor]. -- As a rule of thumb, keep the manifest size manageable by avoiding excessive annotations -and leveraging blobs for larger data chunks. - -## The Road Ahead - -The evolution of OCI artifacts is a journey in progress. While the current specification -does not permit an empty config blob, it's plausible that future updates might -make config and blobs optional eliminating the need for the empty blob. - -By understanding OCI artifacts and their role in representing -container images, developers and DevOps teams can ensure the smooth deployment -and execution of containerized applications. The open and standardized nature of -OCI artifacts promotes interoperability among different clouds and platforms, -enabling seamless container orchestration and scaling across cloud and -on-premises infrastructures. - -To learn more about the OCI Image Specification and Image Manifests, you can -refer to the official [OCI Image Specification GitHub repository]( -https://github.com/opencontainers/image-spec) and explore the detailed -specifications. - -[cas]: https://en.wikipedia.org/wiki/Content-addressable_storage -[oci-layout]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md -[descriptor]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/descriptor.md -[image-spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/spec.md -[image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#image-manifest -[image-properties]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#image-manifest-property-descriptions -[empty-descriptor]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#guidance-for-an-empty-descriptor -[image-index]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-index.md#image-index-property-descriptions -[artifact-guidelines]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#guidelines-for-artifact-usage diff --git a/docs/concepts/reference.mdx b/docs/concepts/reference.mdx deleted file mode 100644 index b88934a8..00000000 --- a/docs/concepts/reference.mdx +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Reference -sidebar_position: 3 ---- - -# Understanding References in the Open Container Initiative (OCI) Standard - -One of the core concepts when dealing with container images or -[OCI artifacts](artifact.mdx) is the notion of a reference. -Let's dive deep into this concept, especially within the context of -the Open Container Initiative (OCI) standard. - -## Image or Artifact References: Breaking Down the Components - -An image reference is essentially the 'address' or 'identifier' you use to -pull or manage a specific container image or OCI artifact. - -There are primarily two contexts in which you'll encounter references: - -1. Interacting with a registry to pull or push images. -2. Interacting with a local OCI Layout store to manage local content. - -Let's take a look at the components of an reference in these 2 scenarios. - -### What a Reference Means in the Registry - -When you pull or push an artifact or image from a registry, you need to specify the reference. -This reference is a combination of three parts: - -1. **Registry**: This is akin to the home or the server where your images or artifacts are stored. -Think of it as the overarching domain. Examples include Docker Hub (docker.io), -GitHub Container Registry (ghcr.io), or your own private registry. -2. **Repository**: This is a segment of the reference, after the registry where a particular -application or service's images are stored. -The repository doesn't necessarily follow a hierarchy within the registry, meaning `a/b/c` -and `a/b/c/d` are both valid and distinct repositories, with no implied hierarchy between them. -3. **Tag or Digest**: This is the last part indicating the version of the image or artifact -you want to pull or push. - -#### References by Tag - -- **Tag**: Tags are user-friendly references to specific image or artifact versions. -Common tags include `latest`, `v1.0`, -or any other description that makes sense for versioning or identiying and resolve to a digest. -These are typically human readable and easy to remember. - -![Diagram showing example of by tag reference](/img/concepts/reference/by_tag.png) - -:::caution -Tags are mutable. This means that the same tag can point to different digests over time. -::: - -#### References by Digest - -Reference by a digest is a unique, immutable identifier for a specific image or artifact. -Typically represented as a SHA256 hash of the image's content, the digest guarantees -you're pulling or referencing the exact version of the image and artifact and is **immutable**. - -![Diagram showing example of by digest reference](/img/concepts/reference/by_digest.png) - -:::note -The digest is the most precise way to reference an image. -However, it's not very user-friendly. -This is why tags are more commonly used. -A tag always resolves to a digest. -::: - -#### References by Tag and Digest - -Putting it all together, a reference includes a registry, a repository, and a tag or a digest in the context -of a **registry**. - -```mermaid -graph LR - A["Registry (e.g., docker.io)"] - B["Repository (e.g., library/nginx)"] - C["Tag (e.g., latest)"] - D["Digest (e.g., sha256:abc123...)"] - A --> B - B --> C - B --> D -``` - -### What a Reference Means in OCI Layout - -In the OCI Layout specification, a reference can be a tag or a digest. -The OCI Layout defines how image data should be stored on disk. -This layout facilitates image distribution, making it easier for tools to push and pull images. -The references in the OCI Layout help in uniquely identifying an image and its components. - -The layout directory contains a file called `index.json` that contains the references to the image's components. -The below `index.json` file contains a reference to a manifest file and it can be accessed as `v1` or the digest -`sha256:921f70dafac450afd63cc4210b2086cb4290ef7d51249eb79c4777e731b87746`. - -```json -{ - "schemaVersion": 2, - "manifests": [ - { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:921f70dafac450afd63cc4210b2086cb4290ef7d51249eb79c4777e731b87746", - "size": 555, - "annotations": { - "org.opencontainers.image.created": "2023-08-19T00:05:47Z", - "org.opencontainers.image.ref.name": "v1" - }, - "artifactType": "application/example" - } - ] -} -``` - -For a detailed understanding, refer to the [OCI Layout Specification][oci-layout-index]. - -### How OCI Uses Image References - -In the OCI standard, when a client (like docker) needs to pull an image, -it uses the combined image reference to precisely identify and retrieve the -right image or artifact from a registry. - -However, it's worth noting that certain implementations, such as docker, provide -defaults or shortcuts. For instance, if you were to use docker to pull an image -using the reference `nginx`, docker would automatically resolve this to -`docker.io/library/nginx:latest`. Here, `docker.io` is the default registry and -`library/nginx` is the repository with a 'library' prefix for official images and `latest` is the -default tag. - -### Conclusion - -Understanding the components of an `reference` is vital when working with containers or OCI artifacts. -These references ensure that clients are addressing the desired version of the image or artifact. -Having a solid grasp of foundational concepts like image references becomes even more essential -as you start to use image and artifacts across your cloud native environments. - -[oci-layout-index]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md#indexjson-file \ No newline at end of file diff --git a/docs/concepts/reference_by_digest.dot b/docs/concepts/reference_by_digest.dot deleted file mode 100644 index 455747ac..00000000 --- a/docs/concepts/reference_by_digest.dot +++ /dev/null @@ -1,25 +0,0 @@ -# To generate the image used, run the following command -# dot -Tpng -o static/img/concepts/reference/by_digest.png docs/concepts/reference_by_digest.dot -digraph G { - graph [ - dpi=600 - fontname = "Helvetica,Arial,sans-serif" - ] - node [shape=record style="rounded,filled" fontname="Arial"] - edge [] - subgraph cluster1 - { - color="#ebf8fe" - style="rounded,filled" - ref:f0 -> registry - ref:f1 -> repository - ref:f2 -> digest - ref [label="docker.io|/|library/nginx|@|sha256:aabbcc..", fillcolor="#f5f3f2", color="#e0d8d4" ]; - - registry [color="#d7d5ec" ] - repository [color="#cae8e6"] - digest [label="digest" color="#e6fabc"] - - } -} - diff --git a/docs/concepts/reference_by_tag.dot b/docs/concepts/reference_by_tag.dot deleted file mode 100644 index c060c98c..00000000 --- a/docs/concepts/reference_by_tag.dot +++ /dev/null @@ -1,25 +0,0 @@ -# To generate the image used, run the following command -# dot -Tpng -o static/img/concepts/reference/by_tag.png docs/concepts/reference_by_tag.dot -digraph G { - graph [ - dpi=600 - fontname = "Helvetica,Arial,sans-serif" - ] - node [shape=record style="rounded,filled" fontname="Arial"] - edge [] - subgraph cluster1 - { - color="#ebf8fe" - style="rounded,filled" - ref:f0 -> registry - ref:f1 -> repository - ref:f2 -> tag - ref [label="docker.io|/|library/nginx|:|alpine", fillcolor="#f5f3f2", color="#e0d8d4" ]; - - registry [color="#d7d5ec" ] - repository [color="#cae8e6"] - tag [label="tag" color="#e6fabc"] - - } -} - diff --git a/docs/concepts/reftypes.dot b/docs/concepts/reftypes.dot deleted file mode 100644 index e208d973..00000000 --- a/docs/concepts/reftypes.dot +++ /dev/null @@ -1,88 +0,0 @@ -digraph reftypes{ - rankdir = LR; - nodesep=0.5 - splines=ortho - graph [ - fontname = "Helvetica,Arial,sans-serif" - dpi=600 - ] - node [ - style=filled - pencolor="#00000044" // frames color - fontname="Helvetica,Arial,sans-serif" - penwidth=1 - ] - edge [ - arrowsize=0.5 - labelfontcolor="#00000080" - penwidth=2 - ] - - - { - rank=same - color="#00000080" - artifact [ - color="#88000022" - shape=plain - label=< - - -
Manifest
OCI Artifact
> - ] - - dot1 [shape=point width=0] - dot2 [shape=point width=0] - artifact -> dot1 [dir=back] - dot1 -> dot2 [arrowhead=none] - } - - { - - label="Referrers" - signature [ - fillcolor=lightyellow - label=< - - - -
Signature
...
subject : descriptor
> - shape=plain - ] - - { - rank=same - sbom [ - rank=min - fillcolor="#88ff0022" - label=< - - - -
SBOM
...
subject : descriptor
> - shape=plain - ] - dot21 [shape=point width=0] - sbom -> dot21 [dir=back] - } - - - - sbomsig [ - newrank=true - fillcolor=lightyellow - label=< - - - -
Signature
...
subject : descriptor
> - shape=plain - ] - - dot21 -> sbomsig:f0 [arrowhead=none; weight=20] - } - - dot1 -> signature:f0 [arrowhead=none; weight=20] - dot2 -> sbom:f0 [arrowhead=none; weight=20] - -} \ No newline at end of file diff --git a/docs/concepts/reftypes.mdx b/docs/concepts/reftypes.mdx deleted file mode 100644 index a53b3f77..00000000 --- a/docs/concepts/reftypes.mdx +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: Attached Artifacts -sidebar_position: 1 ---- - -# Attaching and listing reference types - -The OCI distribution specification allows us to "link" [OCI artifacts](artifact.mdx) -through the use of the concept of reference types. -Artifacts can be tied to one another by defining one as a subject of another. -This is crucial for maintaining dependencies between different artifacts and -enabling the movement of artifacts and their dependencies between environments. - -## Implementing Reference Types in OCI artifacts - -The concept of linking or relating OCI artifacts is achieved using the concept -of reference types, where one artifact can be set as a subject to another. -In this context, "subject" refers to the target of a reference. - -### The Art of Associating Artifacts - -Consider a typical cloud-native environment with countless OCI artifacts. -Often, it's imperative to manage relationships between them—say, an OCI artifact's -signatures, or metadata about an artifact. This is where reference types come into the picture. - -A reference type enables an OCI artifact to refer to another, creating a defined -link or association between them. This association can be for various purposes, -such as versioning, supply chain artifacts (signatures, SBOM, etc.), and dependencies. - -![OCI artifact with refererrs pointing to the artifact](/img/concepts/reftypes.png) - -## Creating a Reference Artifact - -OCI Artifacts may be stored in a content-addressable storage system or OCI Layout directory. -For the purpose of this guide, we'll use the OCI Distribution Specification to -create and list reference types. - -The creation of a reference artifact is a two-step process: - -- **Step One**: PUT an artifact, say Artifact A, using the PUT Manifest and -blob upload APIs if the artifact has blob content. The prerequisite for a reference -type is that the subject artifact must be known so that it may be added to the subject. - -- **Step Two**: Put another artifact, say Artifact B, which refers to Artifact A. -In this case, Artifact A is the 'subject' of Artifact B. - -This is done using the [push workflow][push-workflow] in the distribution specification. - -```mermaid -sequenceDiagram - participant C as Client - participant R as Registry - C->>R: PUT /v2//manifests/ Artifact A - R-->>C: 201 Created - C->>R: PUT /v2//manifests/ Artifact B with reference to Artifact A - R-->>C: 201 Created -``` - -In this sequence, the client first uploads Artifact A to the registry. -Next, the client uploads Artifact B to the same registry, but this time with a -reference to Artifact A by specifying the digest of Artifact A as the subject. -The association is now established in the registry. - -:::tip NOTE -The specification does allow pushing the reference artifact **without** requiring -the presense of the the `subject` in the target registry or OCI-Layout. -::: - -The following example shows the manifest of Artifact B with a reference to Artifact A -in the `subject` field. - -```json - { - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "artifactType" : "application/example", - "config": { - "mediaType": "application/vnd.oci.empty.v1+json", - "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", - "size": 2 - }, - "layers": [ - { - "mediaType": "application/vnd.oci.image.layer.v1.tar", - "digest": "sha256:d2a84f4b8b650937ec8f73cd8be2c74add5a911ba64df27458ed8229da804a26", - "size": 12, - "annotations": { - "org.opencontainers.image.title": "attach/hello.txt" - } - } - ], - "subject": { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:5e140a61e16155b30356685a6801e5250339bfb11370e70573d28d4ff2dc89cf", - "size": 477 - }, - "annotations": { - "org.opencontainers.image.created": "2023-08-05T06:58:38Z" - } -} -``` - -## Listing Referrers - -Once an artifact has one or more referring artifacts, it's often necessary to -list these referrers for various purposes such as tracking dependencies, updates -or obtaining metadata of the artifact. -The OCI [Distribution Specification][listing-referrers] defines an API endpoint -(`/v2//referrers/`) for this purpose. - -If the registry does not support listing referrers, then the [referrers tag schema][tag-schema] -may be used to obtain a client created non-dynamic index of referrers. - -For the purpose of this guide we will use the [referrers API][listing-referrers]. - -### Listing all referrers - -In this sequence, the client requests a list of all referrers to a specific artifact -from the registry, which then responds with the list. -The list may be paginated if the number of referrers is large. - -```mermaid -sequenceDiagram - participant C as Client - participant R as Registry - C->>R: GET /v2//referrers/ - R-->>C: 200 OK (List of all referrers) -``` - -### Listing referrers with a specific artifact type - -In this sequence, the client requests a list of referrers to a specific artifact -of a certain media type from the registry, which then responds with the filtered list. -The response will include the `OCI-Filters-Applied: artifactType` header to indicate -that the response is filtered by the `artifactType` query parameter. - -The artifact type is determied by the same rules as per -[OCI artifacts guidlines](artifact.mdx#determining-the-artifact-type). - -```mermaid -sequenceDiagram - participant C as Client - participant R as Registry - C->>R: GET /v2//referrers/?artifactType= - R-->>C: 200 OK (List of referrers of specific media type) -``` - -The request below lists shows an example for listing referrers of a specific media type. - -```json -GET /v2/hello-world/referrers/sha256:5e140a6..?artifactType=application%2Fexample HTTP/1.1 - -// response -Content-Type: application/vnd.oci.image.index.v1+json -Oci-Filters-Applied: artifactType - -{ - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.index.v1+json", - "manifests": [ - { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:a10d2cf503458e48996a3e3030c75fb5f5cd967e21a38ca69ce6c1e1dee5fd27", - "size": 677, - "annotations": { - "org.opencontainers.image.created": "2023-08-05T07:08:43Z" - }, - "artifactType": "application/example" - } - ] -} -``` - -## Fetching the reference artifact - -Once the referrers have been queried, the client may fetch the reference artifact -using the digest that is returned in the list of referrers. -The client may then use the digest to fetch the artifact contents using the -[pull workflow][pull-workflow] as described in the distribution specification. - -```mermaid -sequenceDiagram - participant C as Client - participant R as Registry - - Note over C,R: Pull Workflow Starts - - C->>R: GET /v2//manifests/ - R-->>C: 200 OK, return manifest - - Note over C,R: If manifest has config - - C->>R: GET /v2//blobs/ (Config) - R-->>C: 200 OK, return config - - Note over C,R: If manifest has blobs - - C->>R: GET /v2//blobs/ (Blob 1) - R-->>C: 200 OK/307 Redirect, return blob 1 - - C->>R: GET /v2//blobs/ (Blob 2) - R-->>C: 200 OK/307 Redirect return blob 2 - - Note over C,R: Save to OCI Layout or file system - - C->>+C: Save manifest, config and blobs - Note over C: Pull Workflow Ends -``` - -## The Power of Associations - -The introduction of Reference Types (Associations) opens a world of possibilities in -managing and linking of OCI Artifacts while also empowering the following scenarios: - -- Discovery and distribution of artifacts like SBOMs or signatures for supply chain. -- Movement of a graph of OCI content across environments. -- Content management of a graph of artifacts by archiving, deleting or moving them -together. - -To further explore this concept, dive deeper into the -[OCI Distribution Specification][distribution-spec] and the [OCI Image Specification][image-spec]. -These comprehensive guides will provide more insights into the use of -reference types and other details of managing OCI Artifacts. - -[listing-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers -[pull-workflow]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pull -[push-workflow]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#push -[tag-schema]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#referrers-tag-schema -[distribution-spec]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md -[image-spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/spec.md diff --git a/docs/concepts/tag_relations.dot b/docs/concepts/tag_relations.dot deleted file mode 100644 index 5978d76f..00000000 --- a/docs/concepts/tag_relations.dot +++ /dev/null @@ -1,66 +0,0 @@ -# To generate the image used, run the following command -# dot -Tpng -o tag_relations.png tag_relations.dot -digraph git_basics { - graph [ - dpi=600 - fontname = "Helvetica,Arial,sans-serif" - ] - node [ - style=filled - pencolor="#00000044" // frames color - fontname="Helvetica,Arial,sans-serif" - penwidth=1 - ] - edge [ - arrowsize=0.5 - labelfontcolor="#00000080" - penwidth=2 - ] - - tag [ - label=<Tag> - shape=box - color=lightcyan4 - fillcolor=lightcyan1 - ] - - subgraph manifests { - rank=same - manifest [ - color="#88000022" - shape=plain - label=< - - - - - - -
Manifest
schema : string
artifactType : string
config : descriptor
annotations : map[string]string
subject : descriptor
> - ] - - index [ - shape=plain - color="#88000022" - label=< - - -
Index
manifests : [ ]descriptor
> - ] - } - - blobs [ - fillcolor="#88ff0022" - label=< - - - - -
Blobs
config blob
layer blobs
...
> - shape=plain - ] - - tag -> manifest - tag -> index -> manifest - manifest -> blobs -} \ No newline at end of file diff --git a/docs/glossary.mdx b/docs/glossary.mdx deleted file mode 100644 index e04847da..00000000 --- a/docs/glossary.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Glossary -sidebar_position: 80 ---- - -# Glossary - -### Annotations - -[Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) are string key-value pairs similar to labels. -Annotations are supported by OCI Image Manifest and OCI Content Descriptors. -You can refer to our [how-to guide](./how_to_guides/manifest_annotations.mdx) to understand how ORAS CLI could be used to add them. - -### Artifacts - -Artifacts are a conceptual piece of content stored as [Blobs](#blob) with an accompanying Manifest containing a [Config](#config). -We can [push](./commands/oras_push.mdx), -[pull](./commands/oras_pull.mdx), -[attach](./commands/oras_attach.mdx) artifacts using the ORAS CLI. -In order to understand the usage better, -you may follow the steps in our [quick start guide](./quickstart.mdx). - -### Blob - -Blob (which stands for Binary Large Objects) is the content stored by a registry and is addressable by a Digest. -ORAS allows you to [fetch](./commands/oras_blob_fetch.mdx), -[delete](./commands/oras_blob_delete.mdx) -and [push](./commands/oras_blob_push.mdx) blobs. - -### Config - -[Config](https://github.com/opencontainers/image-spec/blob/main/config.md) is the JSON format describing images for use with a container runtime and execution tool and its relationship to filesystem changesets. -You may use [`oras manifest fetch-config`](./commands/oras_manifest_fetch-config.mdx) to check out the config of your artifact. - -### Container Images - -A [container image](https://www.docker.com/resources/what-container/#:~:text=A%20Docker%20container%20image%20is,tools%2C%20system%20libraries%20and%20settings.) is a small, standalone, -executable file that contains all the components required to run an application, -including the code, runtime, system tools, system libraries, and settings. - -### Content Descriptors - -A [Content Descriptor](https://github.com/opencontainers/image-spec/blob/main/descriptor.md) (or simply Descriptor) describes the disposition of the targeted content. -It includes the type of the content, -a content identifier (digest), -and the byte-size of the raw content. -Optionally, it includes the type of artifact it is describing. - -### Digest - -A [digest](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests) is a property of a Descriptor which uniquely identifies content by taking a collision-resistant hash of the bytes. - -### Distribution-spec - -The [OCI Distribution Spec](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) defines an API protocol to facilitate and standardize the distribution of content. - -### Extensions - -The Distribution Specification Project includes a process and API for prototyping and testing [extensions](https://github.com/opencontainers/distribution-spec/blob/main/extensions/README.md) to the Distribution API. - -### Image Layout - -The [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) is the directory structure for OCI content-addressable blobs and location-addressable references (refs). -It must contain a `blobs` directory, `oci-layout` file and an `index.json` file. -To learn more, check out the [how-to guide](./how_to_guides/distributing_oci_layouts.mdx) on OCI Layouts. - -### Image Manifests - -An [image manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md#image-manifest) provides a configuration and set of layers for a single container image for a specific architecture and operating system. - -### Image-spec - -The [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/main/spec.md) defines an OCI Image, -consisting of an image manifest, -an image index (optional), -a set of filesystem layers, -and a configuration. - -### Image Index Specification - -The [image index](https://github.com/opencontainers/image-spec/blob/main/image-index.md) is a higher-level manifest which points to specific image manifests, ideal for one or more platforms. -It is a multi-descriptor entry point. - -### Local Registry - -A registry is a place where container images and artifacts can easily be stored and accessed. -Whereas, a local registry (like [zot](https://zotregistry.dev/)) is a registry that is present on our local machine. -You can follow our [quick start guide](./quickstart.mdx) if you would like to try using zot registry. - -### Manifest Referrers API - -Artifact-manifest provides the ability to reference artifacts to existing artifacts. Reference artifacts include signatures, -SBoMs and many other types. -The [manifest `referrers` API](https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md) returns all artifacts that have a `subject` of the given manifest digest. - -### Referrer API - -The Referrers API returns a list of manifests that reference a blob. -You can understand how to use this API by referring to the [details](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers) given in the distribution spec. - -### Referrer Tag Schema - -The Referrer Tag Schema helps to pull the current list of referrers based on different digest formats or tags. - -### Registry - -A registry is like a central repository where you can store, share and manage container images and artifacts. - -### Remote Registry - -A remote registry is when our registry is remotely available such as Docker Hub, ghcr.io, etc. -We can use ORAS CLI to perform many operations such as [pushing](./commands/oras_push.mdx), -[pulling](./commands/oras_pull.mdx), -[attaching](./commands/oras_attach.mdx) artifacts. - -### Software Bill of Materials - -A codebase's open source and third-party components are listed in a software Bill of Materials (SBOM). -Additionally, an SBOM provides the versions of the components used in the codebase, -their patch status, -and the licences that govern them. - -### Supply Chain Security - -Supply chain security emphasises risk management of outside vendors, suppliers, logistics, and transportation. -It recognises, assesses, and reduces risks related to collaborating with other organisations as a part of your supply chain. - -### Tags - -Tags are used to define keys and values and associate them with resources by adding metadata to resources. \ No newline at end of file diff --git a/docs/how_to_guides/_category_.json b/docs/how_to_guides/_category_.json deleted file mode 100644 index ce3a449a..00000000 --- a/docs/how_to_guides/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "How-to Guides", - "position": 20, - "link": { - "type": "generated-index", - "description": "A guide to ORAS CLI" - } -} \ No newline at end of file diff --git a/docs/how_to_guides/authentication.mdx b/docs/how_to_guides/authentication.mdx deleted file mode 100644 index 0dd7ac9f..00000000 --- a/docs/how_to_guides/authentication.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Authentication -sidebar_position: 1 ---- - -# Authentication - -There are two ways we will be covering in this guide to authenticate with OCI Registries. - -### Method 1: Authentication Using the `config` File - -This method is straightforward but insecure. It may be used for testing purposes. In this method, the command will store the credentials in `~/.docker/config.json` which is the same file used as the docker client. - -Please note that if you have previously used `docker login`, the credentials will get reused. - -You may use the `-c`/`--config` option to specify an alternate location. - -:::info - -While ORAS leverages the local docker client config store, ORAS does NOT have a dependency on Docker Desktop running or being installed. ORAS can be used independently of a local docker daemon. - -::: - -You can either make use of [`oras login`](../commands/oras_login.mdx) or provide explicit credentials via options, for example, - -``` -oras pull -u username -p password myregistry.io/myimage:latest -``` -However, you will get a warning message stating that the credentials will be stored unencrypted in the `config` file. - -### Method 2: Authentication Using Docker Credential Helper - -The native keychain of the operating system is an external credential store that the Docker Engine can use to store user credentials. It is safer to use an external store than to keep credentials in the Docker configuration file (`~/.docker/config.json`). - -An external helper program is needed to interact with a specific keychain or external store. Docker requires the helper program to be in the client’s host `$PATH`. - -Prerequisites to follow through with these commands: -1. According to your operating system, you may download a credential helper from among these: - - [D-Bus Secret Service](https://github.com/docker/docker-credential-helpers/releases) - - [Apple macOS keychain](https://github.com/docker/docker-credential-helpers/releases) - - [Microsoft Windows Credential Manager](https://github.com/docker/docker-credential-helpers/releases) - - [pass](https://www.passwordstore.org/) -2. [Docker Credential Helpers](https://github.com/docker/docker-credential-helpers) - -**Step 1** - -Configure the credential store in the `~/.docker/config.json` file. Your file should look similar to this: - -``` -{ - ... - "credStore": "pass" - ... -} -``` - -**Note**: Please replace pass with the credential helper you want to use. - -**Step 2** - -Before running the [`oras login`](../commands/oras_login.mdx) command, make sure you have logged out once so that the next time you enter your credentials, they get stored in the credential store. - -``` -$ oras login localhost:5000 -Username: deepeshaburse -Password: -Login Succeeded -``` - -Your credential helper has been set up, the next time you run `oras login`, you should see an output like this: - -``` -Authenticating with existing credentials... -Login Succeeded -``` \ No newline at end of file diff --git a/docs/how_to_guides/distributing_oci_layouts.mdx b/docs/how_to_guides/distributing_oci_layouts.mdx deleted file mode 100644 index 69761d8e..00000000 --- a/docs/how_to_guides/distributing_oci_layouts.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Distributing OCI Layouts -sidebar_position: 6 ---- - -# Distributing OCI Layouts - -The directory structure for OCI content-addressable blobs and location-addressable references (refs) is called the [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). An OCI Image needs to include: - -- `blobs` directory: Each hash algorithm's directory and its children, which make up the object names in the blobs subdirectories, will hold the real content. - -- `oci-layout` file: This JSON object indicates the base of an Open Container Image Layout and provides information about the current image-layout version. - -- `index.json` file: The image index is a multi-descriptor entry point. - -## Creating an OCI Image - -### Step 1: Writing in the Dockerfile - -Put the following commands in the `Dockerfile` in order to run an image of Alpine Linux. - -``` -FROM alpine -CMD echo 'hello world!' -``` - -Our image is based on alpine and runs the command `echo hello world!`. - -### Step 2: Building the image using docker - -``` -docker buildx create —use -``` - -This command is used to create a new instance of a builder with a single node based on the current configuration. - - -``` -docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1 -``` - -Expected output: -``` -[+] Building 7.0s (7/7) FINISHED                 docker-container:hungry_wilson - => [internal] booting buildkit                                            3.0s - => => pulling image moby/buildkit:buildx-stable-1                         2.5s - => => creating container buildx_buildkit_hungry_wilson0                   0.5s - - - - => => exporting manifest sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd17  0.0s - => => exporting config sha256:5e9872dc690060c52e4ea6e9357aaebb9d9187b44a  0.0s - => => sending tarball                                                     0.0s -``` - -This command has multiple parts to break down: - -`build` is needed to build the OCI Image based on the Dockerfile we provide. -hello-world:v1 is the name and tag associated with the image built. - -| Flag | Description | -|--------------|------------------------------------------------------| -| file or -f | Name of the Dockerfile (default: PATH/Dockerfile) | -| output or -o | Output destination (format: type=local,dest=path) | - -### Step 3: View the OCI Image - -If you would like to view the image, you will need to extract the `.tar` file first. - -``` -mkdir hello-world -tar -xf ./hello-world.tar -C hello-world -``` - -## Push the OCI Image to a Repository - -You may use [`oras copy`](../commands/oras_cp.mdx) to push the OCI Image from your local disk to a repository. - -In the following example, we are pushing the image to a local registry like zot: - -``` -oras cp --from-oci-layout ./hello-world.tar:v1 localhost:5000/hello-artifact:v1 -``` - -Expected output: - -``` -Copied [oci-layout] ./hello-world.tar:v1 => [registry] localhost:5000/hello-artifact:v1 -Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809 -``` - -## Pull the OCI Image from a Repository - -You can pull the OCI image using the [`oras pull`](../commands/oras_pull.mdx) command. - -``` -oras pull localhost:5000/hello-artifact:v1 -``` - -Expected Output: - -``` -Downloaded empty artifact -Pulled [registry] localhost:5000/hello-artifact:v1 -Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809 -``` - -If you would like to access the artifact files from the OCI layout archive, you may run: - -``` -oras pull --oci-layout hello-world.tar:v1 -``` - -Expected Output: - -``` -Downloaded empty artifact -Pulled [oci-layout] hello-world.tar:v1 -Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809 -``` \ No newline at end of file diff --git a/docs/how_to_guides/go_script.mdx b/docs/how_to_guides/go_script.mdx deleted file mode 100644 index 312c613e..00000000 --- a/docs/how_to_guides/go_script.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Go Scripting -sidebar_position: 90 ---- - -# Scripting ORAS in Go - -It is possible to use the ORAS CLI in Go scripts. When you are scripting ORAS in Go, the parameters should be specified just like they are on the command line. - -For example: - -```go -package main -import ( - "fmt" - "os" - "strings" - "oras.land/oras/cmd/oras/root" -) -func main() { - // change below array to play with your own cmd args: - args := []string{"repo", "ls", "mcr.microsoft.com"} - cmd := root.New() - cmd.SetArgs(args) - fmt.Printf("Executing 'oras %s':", strings.Join(args, " ")) - err := cmd.Execute() - if err != nil { - fmt.Errorf("Failed to execute : %w", err) - os.Exit(-1) - } - os.Exit(0) -} -``` - -To run this example: -``` -mkdir example -cd example -go mod init example -go mod edit --require oras.land/oras@v1.1.0-rc.1 -# copy the example code into the directory... -cat >main.go -go mod tidy -go run main.go -``` diff --git a/docs/how_to_guides/manifest_annotations.mdx b/docs/how_to_guides/manifest_annotations.mdx deleted file mode 100644 index b59aeb19..00000000 --- a/docs/how_to_guides/manifest_annotations.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Manifest Annotations -sidebar_position: 5 ---- - -# Manifest Annotations - -[Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md), which are supported by [OCI Image Manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md#image-manifest) and [OCI Content Descriptors](https://github.com/opencontainers/image-spec/blob/main/descriptor.md), are also supported by `oras`. - -## By Adding a Key-Value Pair - -### Pushing with Annotation - -``` -oras push --annotation "key=val" localhost:5000/hello:v1 artifact.txt -``` - -Expected Output: - -``` -Uploading a948904f2f0f artifact.txt -Uploaded a948904f2f0f artifact.txt -Pushed [registry] localhost:5000/hello:v1 -Digest: sha256:6a1df0710d2fbd3179202ff70f40c28bfa9c7ec3b9d6fc282609a904d13b86e9 -``` - -### Attaching with Annotations - -``` -oras attach --artifact-type doc/example --annotation "key1=val1" --annotation "key2=val2" localhost:5000/hello:v1 attach.txt -``` - -Expected Output: -``` -Uploading 56f86ed6584a attach.txt -Uploaded 56f86ed6584a attach.txt -Attached to [registry] localhost:5000/hello@sha256:00d4dc3c98f5060b2fd751bc77e415e995ece8d6d2e8d630bbd6de371f44fc3a -Digest: sha256:fae55c9d8640525a49d7ac18a36390e2cdc2742c68d68487882703f22df69ae7 -``` - -## Using a JSON File - -### Make Annotations File - -Users can make annotations to the manifest, the config, and individual files (i.e. layers) by the `--annotation-file file` option if they would like to do so using a a `.json` file. - -The annotations file is a JSON file with the following format: - -```json -{ - "": { - "": "annotation_value" - } -} -``` - -There are two special filenames / entries: -- `$config` is reserved for the annotation of the manifest config. -- `$manifest` is reserved for the annotation of the manifest itself. - -For instance, the following annotation file `annotations.json`: - -```json -{ - "$config": { - "hello": "world" - }, - "$manifest": { - "foo": "bar" - }, - "cake.txt": { - "fun": "more cream" - } -} -``` - -### Pushing the File With Annotations - -In order to add annotations using the `annotations.json`, you may run the following command: - -``` -oras push --annotation-file annotations.json localhost:5000/club:party cake.txt juice.txt -``` - -The push command would upload the blob and put a manifest. Running the following command to output the manifest: - -``` -oras manifest fetch localhost:5000/club:party --pretty -``` - -Expected Output: - -```json -{ - "schemaVersion": 2, - "config": { - "mediaType": "application/vnd.oci.image.config.v1+json", - "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", - "size": 2, - "annotations": { - "hello": "world" - } - }, - "layers": [ - { - "mediaType": "application/vnd.oci.image.layer.v1.tar", - "digest": "sha256:22af0898315a239117308d39acd80636326c4987510b0ec6848e58eb584ba82e", - "size": 6, - "annotations": { - "fun": "more cream", - "org.opencontainers.image.title": "cake.txt" - } - }, - { - "mediaType": "application/vnd.oci.image.layer.v1.tar", - "digest": "sha256:be6fe11876282442bead98e8b24aca07f8972a763cd366c56b4b5f7bcdd23eac", - "size": 7, - "annotations": { - "org.opencontainers.image.title": "juice.txt" - } - } - ], - "annotations": { - "foo": "bar" - } -} -``` diff --git a/docs/how_to_guides/manifest_config.mdx b/docs/how_to_guides/manifest_config.mdx deleted file mode 100644 index f356b071..00000000 --- a/docs/how_to_guides/manifest_config.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Manifest Config -sidebar_position: 4 ---- - -# Manifest Config - -According to [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md#image-manifest-property-descriptions), -the property `config` is required by an image manifest. -Since `oras` does not make use of the configuration object, an empty JSON object `{}` is used by default when pushing, and never being fetched when pulling. - -The descriptor of the default configuration object is fixed as follows. - -```json -{ - "mediaType": "application/vnd.oci.image.config.v1+json", - "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", - "size": 2 -} -``` - -## Customize config - -To push a file `hi.txt` with the custom manifest config file `config.json`, you can run: - -``` -oras push --config config.json localhost:5000/hello:latest hi.txt -``` - -The media type of the config is set to the default value `application/vnd.unknown.config.v1+json`. - -Similar to the file reference, it is possible to change the media type of the manifest config. To push a file `hi.txt` with the custom manifest config file `config.json` with the custom media type `application/vnd.oras.config.v1+json`, run - -``` -oras push --config config.json:application/vnd.oras.config.v1+json localhost:5000/hello:latest hi.txt -``` - -In addition, it is possible to pass a null device `/dev/null` (`NUL` on Windows) to `oras` for an empty config file. - -``` -oras push --config /dev/null:application/vnd.oras.config.v1+json localhost:5000/hello:latest hi.txt -``` - -## Docker behaviors - -The config used by `oras` is not a real config. -Therefore, the pushed image cannot be recognized or pulled by `docker` as expected. -In this section, docker behaviors are shown given various configs. - -### Empty config file - -``` -$ oras push --export-manifest /dev/null localhost:5000/hello:latest hi.txt -Uploading a948904f2f0f hi.txt -Pushed localhost:5000/hello:latest -Digest: sha256:34897815cbf060e1d11b4c2938c7476d9326269e2179aef3559ce25af11a9ced -$ docker pull localhost:5000/hello:latest -latest: Pulling from hello -a948904f2f0f: Extracting [==================================================>] 12B/12B -unexpected end of JSON input -``` - -### Empty JSON object - -``` -$ cat config.json -{} -$ oras push --config config.json localhost:5000/hello:latest hi.txt -Uploading a948904f2f0f hi.txt -Pushed localhost:5000/hello:latest -Digest: sha256:44d13da4d42a20ceed7ee3411b103a6f82ef02a2eac981d5e3d799c41e3015d7 -$ docker pull localhost:5000/hello:latest -latest: Pulling from hello -a948904f2f0f: Pulling fs layer -invalid rootfs in image configuration -``` - -### Arbitrary OS - -``` -$ cat config.json -{ - "architecture": "cloud", - "os": "oras" -} -$ oras push --config config.json localhost:5000/hello:latest hi.txt -Uploading a948904f2f0f hi.txt -Pushed localhost:5000/hello:latest -Digest: sha256:e6428c9cb88505a1859a01f4b7602bdb263d5f65399ef72d3397afd9bfb25b2c -$ docker pull localhost:5000/hello:latest -latest: Pulling from hello -a948904f2f0f: Extracting [==================================================>] 12B/12B -operating system is not supported -``` - -### Arbitrary config media type - -``` -$ oras push --artifact-type application/vnd.oras.config.v1+json localhost:5000/hello:latest hi.txt -Uploading a948904f2f0f hi.txt -Pushed localhost:5000/hello:latest -Digest: sha256:5d8ea018049870aab566350660b9a003c646a7f955f9996d35cc0c71bf41b3d0 -$ docker pull localhost:5000/hello:latest -Error response from daemon: Encountered remote "application/vnd.oras.config.v1+json"(unknown) when fetching -``` - -Layers are not pulled in this case. Thus **it is encouraged to specify customized config media type**. - -Additionally, the latest version of `dockerd` recognizes OCI manifests and does not verify the OCI config media type. - -## Push / Pull config - -As mentioned in the beginning of this doc, the manifest config is not used by `oras` and is not worth pulling in most scenarios. -However, it is still possible to push pullable config with the `oras` CLI by leveraging [Manifest Annotations](./manifest_annotations.mdx). - -``` -$ cat config.json -{ - "foo": "bar" -} -$ cat annotations.json -{ - "$config": { - "org.opencontainers.image.title": "config.json" - } -} -$ oras push --config config.json --annotation-file annotations.json localhost:5000/hello:latest hi.txt -Uploading a948904f2f0f hi.txt -Uploading 57f840b6073c config.json -Pushed localhost:5000/hello:latest -Digest: sha256:12e3de7e4a65ffc46a6158ac2df07ecc6fd1af8b0109b4c42a90067f7e907f43 -$ oras pull -a localhost:5000/hello:latest -Downloaded a948904f2f0f hi.txt -Downloaded 57f840b6073c config.json -Pulled localhost:5000/hello:latest -Digest: sha256:12e3de7e4a65ffc46a6158ac2df07ecc6fd1af8b0109b4c42a90067f7e907f43 -``` diff --git a/docs/how_to_guides/pushing_and_pulling.mdx b/docs/how_to_guides/pushing_and_pulling.mdx deleted file mode 100644 index 54e54f7c..00000000 --- a/docs/how_to_guides/pushing_and_pulling.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Pushing and Pulling -sidebar_position: 2 ---- - -All users can access container images stored in centralized repositories called OCI registries. Pushing OCI artifacts to the registries is the first step in distributing them. These artifacts can be pulled by other people and used in their own environment once they have been stored. - -# Pushing - -## Pushing artifacts with single file - -Pushing a single file artifact involves referencing the unique artifact type and a file. -Defining an Artifact uses the `config.mediaType` as the unique artifact type. If a config object is provided, the `mediaType` extension defines the config filetype. If a `null` config is passed, the config extension must be removed. - -See: [Defining a Unique Artifact Type](https://github.com/opencontainers/artifacts/blob/main/artifact-authors.md#defining-a-unique-artifact-type) - -The following sample defines a new Artifact Type of **Acme Rocket**, using `application/vnd.acme.rocket.config` as the `manifest.config.mediaType`. - -- Create a sample file to push/pull as an artifact - - ``` - echo "hello world" > artifact.txt - ``` - -- Push the sample file to the registry: - - ``` - oras push localhost:5000/hello-artifact:v1 \ - --artifact-type application/vnd.acme.rocket.config \ - ./artifact.txt - ``` - -- Pull the file from the registry: - - ``` - rm -f artifact.txt # first delete the file - oras pull localhost:5000/hello-artifact:v1 - cat artifact.txt # should print "hello world" - ``` - -- Push the sample file, with a layer `mediaType`, using the format `filename[:type]`: - - ``` - oras push localhost:5000/hello-artifact:v2 \ - --artifact-type application/vnd.acme.rocket.config \ - artifact.txt:text/plain - ``` - -## Pushing artifacts with config files - -The [OCI distribution-spec](https://github.com/opencontainers/distribution-spec/) provides for storing optional config objects. These can be used by the artifact to determine how or where to process and/or route the blobs. When providing a config object, the version and file type is required. - -- Create a config file - - ``` - echo "{\"name\":\"foo\",\"value\":\"bar\"}" > config.json - ``` - -- Push an artifact, with the `config.json` file - - ``` - oras push localhost:5000/hello-artifact:v2 \ - --config config.json:application/vnd.acme.rocket.config.v1+json \ - artifact.txt:text/plain - ``` - -## Pushing artifacts with multiple files - -Just as container images support multiple "layers" represented as blobs, ORAS supports pushing multiple layers. The layer type is up to the artifact author. You may push `.tar` representing a collection of files, individual files like `.yaml`, `.txt` or whatever your artifact should be represented as. Each layer type should have a `mediaType` representing the type of blob content. -In this example, we'll push a collection of files. - -- A single file (`artifact.txt`) that represents overview content that might be displayed as a repository overview -- A collection of files (`docs/*`) that represents detailed content. When specifying a directory, ORAS will automatically tar the contents. - -See [OCI Artifacts](https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage) for more details. - -- Create additional blobs - - ``` - mkdir docs - echo "Docs on this artifact" > ./docs/readme.md - echo "More content for this artifact" > ./docs/readme2.md - ``` - -- Create a config file, referencing the entry doc file - - ``` - echo "{\"doc\":\"readme.md\"}" > config.json - ``` - -- Push multiple files with different `mediaTypes`: - - ``` - oras push localhost:5000/hello-artifact:v2 \ - --config config.json:application/vnd.acme.rocket.config.v1+json \ - artifact.txt:text/plain \ - ./docs/:application/vnd.acme.rocket.docs.layer.v1+tar - ``` - -- The push will generate a manifest. Run the following command to output the manifest: - - ``` - oras manifest fetch localhost:5000/hello-artifact:v2 --pretty - ``` - - Results in: - - ```json - { - "schemaVersion": 2, - "config": { - "mediaType": "application/vnd.acme.rocket.config.v1+json", - "digest": "sha256:7aa5d0dee9a3a73c81db4356cf7aa5666e175d96e68ee763eeb977bd7ba59ee5", - "size": 20 - }, - "layers": [ - { - "mediaType": "text/plain", - "digest": "sha256:a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447", - "size": 12, - "annotations": { - "org.opencontainers.image.title": "artifact.txt" - } - }, - { - "mediaType": "application/vnd.acme.rocket.docs.layer.v1+tar", - "digest": "sha256:20ae7d51e2365405e6942439140d897548e1d4610db60354aef8a5ce1f1699a7", - "size": 196, - "annotations": { - "io.deis.oras.content.digest": "sha256:4329ea6c620ca4e9cedc5f5e8040432114cb5d64fc53107ea870db149e3d2b9e", - "io.deis.oras.content.unpack": "true", - "org.opencontainers.image.title": "docs" - } - } - ] - } - ``` - -# Pulling - -Pulling artifacts involves specifying the content addressable artifact, along with the type of artifact. - -``` -oras pull localhost:5000/hello-artifact:v2 -``` - -## Using cache when pulling artifacts - -ORAS pulls the artifact into a content-addressable storage (CAS) cache if the content is not available locally to save bandwidth and disk I/O. -Once the content is availabe in the cache, ORAS copies the artifact to the desired location. -The cache directory is specified by using the environment variable `ORAS_CACHE`. If not specified, cache is not used. - -``` -# Set cache root -export ORAS_CACHE=~/.oras/cache -``` - -``` -# Pull artifacts as usual -oras pull localhost:5000/hello:latest -``` diff --git a/docs/how_to_guides/verifying_binaries.mdx b/docs/how_to_guides/verifying_binaries.mdx deleted file mode 100644 index 37411dae..00000000 --- a/docs/how_to_guides/verifying_binaries.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Validating ORAS CLI Binaries -sidebar_position: 10 ---- - -# Validating ORAS CLI Binaries - -After finding your [target release](https://github.com/oras-project/oras/releases), -you may find the releaser's information under the `notes` section. - -The following commands can be used to verify the ORAS CLI binaries using GPG: - -### Step 1: - -First, we import the releaser's GPG Key which can be used for verification (here we have imported [Billy Zha](https://github.com/qweeah)'s key): - -``` -$ curl -sSL https://github.com/qweeah.gpg | gpg --import - -``` - -You can find the [GPG keys](https://github.com/oras-project/oras/blob/main/KEYS) which have been used for ORAS releases. - -### Step 2: - -You can run the following command to check if the key has been imported: - -``` -$ gpg --list-keys -pub rsa4096 2023-02-28 [SC] [expires: 2024-02-28] - BE6FA8DDA48D4C230091A0A9276D8A724CE1C704 -uid [ unknown] Billy Zha -``` - -### Step 3: - -Verify our binaries using the command: - -``` -$ gpg --verify oras_1.0.0_linux_amd64.tar.gz.asc oras_1.0.0_linux_amd64.tar.gz -gpg: Signature made Mon Mar 20 15:51:28 2023 IST -gpg: using RSA key BE6FA8DDA48D4C230091A0A9276D8A724CE1C704 -gpg: Good signature from "Billy Zha " [unknown] -``` \ No newline at end of file diff --git a/docs/index.mdx b/docs/index.mdx deleted file mode 100644 index 53733af8..00000000 --- a/docs/index.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Introduction -sidebar_position: 10 ---- - - - -## Introduction - -Registries are evolving as generic artifact stores. -To enable this goal, the ORAS project provides a way to -push and pull OCI Artifacts to and from OCI Registries. - -Users seeking a generic registry client can benefit from the [ORAS CLI](./installation.mdx), while -developers can build their own clients on top of one of the [ORAS client libraries](./client_libraries/overview.mdx). - -## What are OCI Registries? - -The [Open Container Initiative](https://opencontainers.org/) (OCI) -defines the specifications and standards for container technologies. -This includes the API for working with container registries, known -formally as the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md). -(a.k.a. the "distribution-spec"). - -The distribution-spec was written based on an open-source registry server originally -released by the company [Docker](http://docker.com/), which lives on -GitHub at [distribution/distribution](https://github.com/distribution/distribution) -(now a [CNCF](https://www.cncf.io/) project). - -There are now a number of other open-source and commercial distribution-spec -implementations, a list of which can be found [here](https://github.com/opencontainers/oci-conformance/tree/main/distribution-spec). -Registries that implement the distribution-spec are referred to herein as **OCI Registries**. - -## What are OCI Artifacts? - -For a long time (pretty much since the beginning), people have been using/abusing OCI Registries -to store non-container things. For example, you could upload a video to Docker Hub -by just stuffing the video file into a layer in a Docker image (don't do this). - -The [OCI Artifacts](https://github.com/opencontainers/artifacts) project is an attempt to -define an opinionated way to leverage OCI Registries for arbitrary artifacts without masquerading -them as container images. - -Specifically, [OCI Image Manifests](https://github.com/opencontainers/image-spec/blob/main/manifest.md) -have a required field known as `config.mediaType`. According to the -[guidelines](https://github.com/opencontainers/artifacts/blob/main/artifact-authors.md) -provided by OCI Artifacts, this field provides the ability to differentiate between various types of artifacts. - -Artifacts stored in an OCI Registry using this method are referred to herein as **OCI Artifacts**. - -## How ORAS works - -ORAS works similarly to tools you may already be familiar with, such as `docker`. It allows you to -push (upload) and pull (download) things to and from an OCI Registry, and also handles login (authentication) -and token flow (authorization). What ORAS does differently is -shift the focus from container images to other types of artifacts. - -ORAS is the de facto tool for working with OCI Artifacts. It treats media types as a critical -piece of the puzzle. Container images are never assumed to be the artifact in question. - -By default, when pushing artifacts using ORAS, the `config.mediaType` field is set to unknown: - -``` -application/vnd.unknown.config.v1+json -``` - -Authors of new OCI Artifacts are thus encouraged to define their own media types specific to -their artifact, which their custom client(s) know how to operate on. - -If you wish to start publishing OCI Artifacts right away, take a look at the [ORAS CLI](./installation.mdx). -Developers who wish to provide their own user experience should use one of the -[ORAS client libraries](./client_libraries/overview.mdx). \ No newline at end of file diff --git a/docs/installation.mdx b/docs/installation.mdx deleted file mode 100644 index 67fe98c8..00000000 --- a/docs/installation.mdx +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Installation -sidebar_position: 15 ---- - -# Installation - -This guide demonstrates the installation steps of ORAS CLI on different platforms. - -## Homebrew - -Install `oras` using [Homebrew](https://brew.sh/): - -```bash -brew install oras -``` - -## Snap - -Install `oras` using [Snap](https://snapcraft.io/store): - -```bash -snap install oras -``` - -## Release artifacts - -Install ORAS from the latest [release artifacts](https://github.com/oras-project/oras/releases): - -### Linux - -If you want to install ORAS on an AMD64-based Linux machine, run the following command: - -```bash -VERSION="1.1.0" -curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_linux_amd64.tar.gz" -mkdir -p oras-install/ -tar -zxf oras_${VERSION}_*.tar.gz -C oras-install/ -sudo mv oras-install/oras /usr/local/bin/ -rm -rf oras_${VERSION}_*.tar.gz oras-install/ -``` -:::note - -If you want to install ORAS on an ARM64-based Linux machine, you can download it from `https://github.com/oras-project/oras/releases/download/v1.1.0/oras_1.1.0_linux_arm64.tar.gz`. - -::: - -### macOS - -If you want to install ORAS on a Mac computer with Apple silicon, run the following command: - -```bash -VERSION="1.1.0" -curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_darwin_arm64.tar.gz" -mkdir -p oras-install/ -tar -zxf oras_${VERSION}_*.tar.gz -C oras-install/ -sudo mv oras-install/oras /usr/local/bin/ -rm -rf oras_${VERSION}_*.tar.gz oras-install/ -``` -:::note - -If you want to install ORAS on an Intel-based Mac, you can download it from `https://github.com/oras-project/oras/releases/download/v1.1.0/oras_1.1.0_darwin_amd64.tar.gz`. - -::: - -### Windows - -- You can install ORAS CLI on Windows using [WinGet (Windows Package Manager)](https://github.com/microsoft/winget-pkgs): - -```bash -winget install oras --version 1.1.0 -``` - -- Alternatively, you can install ORAS CLI using `.exe` installer. Add `%USERPROFILE%\bin\` to your `PATH` environment variable so that `oras.exe` can be found. - -```cmd -set VERSION="1.1.0" -curl.exe -sLO "https://github.com/oras-project/oras/releases/download/v%VERSION%/oras_%VERSION%_windows_amd64.zip" -tar.exe -xvzf oras_%VERSION%_windows_amd64.zip -mkdir -p %USERPROFILE%\bin\ -copy oras.exe %USERPROFILE%\bin\ -set PATH=%USERPROFILE%\bin\;%PATH% -``` - -## Docker Image - -A public Docker image containing the CLI is available on [GitHub Container Registry](https://github.com/orgs/oras-project/packages/container/package/oras): - -``` -docker run -it --rm -v $(pwd):/workspace ghcr.io/oras-project/oras:v1.1.0 help -``` -:::note - -The default WORKDIR in the image is `/workspace`. - -::: - -## Nix - -Nix is a tool that takes a unique approach to package management and system configuration. - -The Nix Packages collection ([Nixpkgs](https://github.com/NixOS/nixpkgs)) is a set of over 80 000 packages for the Nix package manager. - -oras also has a [Nix package](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/tools/oras/default.nix) available in the Nixpkgs repository. - -:::info - -You can install nix CLI from [here](https://nixos.org/download.html). - -::: - -You can install oras using the following command: - -```bash -nix-env -iA nixpkgs.oras -``` - -## Verify - -```shell -$ oras version -Version: 1.1.0 -Go version: go1.21.0 -Git commit: 7079c468a06fb5815c99395eb4aaf46dd459d3fa -Git tree state: clean -``` - -You can check out our [how-to guide](./how_to_guides/verifying_binaries.mdx) if you would like to verify ORAS CLI Binaries. \ No newline at end of file diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx deleted file mode 100644 index 099caa17..00000000 --- a/docs/quickstart.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Quick Start -sidebar_position: 14 ---- - -# Distributing OCI artifacts using ORAS - -To distribute OCI artifacts, we need to understand OCI registries. -These registries store container images and other artifacts for easy access. -Distributing OCI artifacts means pushing them to these registries so others can pull them for use. - -We will be using [zot registry](https://zotregistry.dev/) in this guide. -Zot registry is an OCI-native container registry for distributing container images and OCI artifacts. - -In order to follow the steps given, you would be required to install the ORAS CLI. -You can follow the [installation guide](./installation.mdx) to do so. - -## Install zot registry - -We will be running zot using docker. However, you can refer to their [installation guide](https://zotregistry.dev/install-guides/install-guide-linux/) to find more ways to install the registry. - -**Prerequisites** -- [Docker](https://www.docker.com/) - -``` -docker run -d -p 5000:5000 --name oras-quickstart ghcr.io/project-zot/zot-linux-amd64:latest -``` - -## Distribution of OCI artifacts - -Let's push an OCI artifact to the registry using the ORAS CLI. - -### Step 1: Create a sample file - -``` -echo "hello world" > artifact.txt -``` - -### Step 2: Push an artifact - -```bash -oras push --plain-http localhost:5000/hello-artifact:v1 \ - --artifact-type application/vnd.acme.rocket.config \ - artifact.txt:text/plain -``` - -``` -Uploading a948904f2f0f artifact.txt -Uploaded a948904f2f0f artifact.txt -Pushed [registry] localhost:5000/hello-artifact:v1 -Digest: sha256:bcdd6799fed0fca0eaedfc1c642f3d1dd7b8e78b43986a89935d6fe217a09cee -``` - -After pushing the artifact, it can be seen in the zot user interface at [http://localhost:5000/](http://localhost:5000/) - -![Screenshot of how the interface should look on pushing](/img/introduction-to-registries-tutorial-zot.png) - -### Step 3: Pull the artifact - -Let's now pull the artifact we have pushed in the pervious step. - -``` -oras pull localhost:5000/hello-artifact:v1 -``` - -``` -Downloading a948904f2f0f artifact.txt -Downloaded a948904f2f0f artifact.txt -Pulled [registry] localhost:5000/hello-artifact:v1 -Digest: sha256:19e1b5170646a1500a1ac56bad28675ab72dc49038e69ba56eb7556ec478859f -``` - -## Attach an artifact - -First, let's create another sample file to attach to the previously uploaded artifact. - -### Step 1: Create a sample file - -``` -echo "hello world" > hi.txt -``` - -### Step 2: Attach the file - -You can use the command below to attach `hi.txt` to the artifact we pushed above: - -``` -oras attach --artifact-type doc/example localhost:5000/hello-artifact:v1 hi.txt -``` - -``` -Exists a948904f2f0f hi.txt -Attached to [registry] localhost:5000/hello-artifact@sha256:327db68f73d0ed53d528d927a6703c00739d7c1076e50762c3f6641b51b76fdc -Digest: sha256:bcdd6799fed0fca0eaedfc1c642f3d1dd7b8e78b43986a89935d6fe217a09cee -``` - -### Step 3: View referrers - -``` -oras discover localhost:5000/hello-artifact:v1 -``` - -``` -Discovered 1 artifact referencing v1 -Digest: sha256:327db68f73d0ed53d528d927a6703c00739d7c1076e50762c3f6641b51b76fdc - -Artifact Type Digest -doc/example sha256:bcdd6799fed0fca0eaedfc1c642f3d1dd7b8e78b43986a89935d6fe217a09cee -``` - -**Note:** For settings up a registry with TLS follow [these steps](https://github.com/project-zot/zot/blob/main/examples/README.md#network). - -## Clean up - -Stop and remove the running quick start registry and the uploaded content. - -``` -docker rm $(docker stop oras-quickstart) -``` - -## Conclusion - -You can now successfully push OCI artifacts to your zot registry! - -As OCI registries are used to securely store and share container images, they greatly help with collaboration and code sharing. They enable teams to acquire and use images and artifacts through a standardized artifact interface. This is why it is considered to play a crucial role in maintaining consistency among teams. \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 515b5f08..b7f6d7e5 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -53,6 +53,7 @@ const config = { // Remove this to remove the "edit this page" links. editUrl: "https://github.com/oras-project/oras-www/tree/main/", + includeCurrentVersion: false, }, blog: { showReadingTime: true,