Skip to content

Commit 07c1ad6

Browse files
jdolitskyjdolitsky
committed
projects: add ORAS proposal
Signed-off-by: Josh Dolitsky <[email protected]>
1 parent c5cbfa7 commit 07c1ad6

File tree

2 files changed

+215
-0
lines changed

2 files changed

+215
-0
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ https://groups.google.com/a/opencontainers.org/forum/#!forum/tob (tob@opencontai
2626
* [Image Format Spec](proposals/image-format)
2727
* [SELinux](proposals/selinux.md)
2828
* [Tools](proposals/tools.md)
29+
* [ORAS](proposals/oras.md)
2930

3031
## Voting
3132

‎proposals/oras.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# OCI ORAS Project Proposal #
2+
3+
## Abstract ##
4+
5+
In order to provide OCI end users a method to publish and retrieve any type of content to/from an OCI registry, as well as a reference implementation for the OCI Distribution Specification, the [ORAS project][oras-project] should be moved under the opencontainers GitHub org.
6+
7+
[oras-project]: https://github.com/deislabs/oras
8+
9+
### ORAS Details ###
10+
11+
ORAS is a CLI that can publish arbitrary content to an OCI registry, with special features for setting mediatypes on manifest configs and on content.
12+
13+
Note: the manifest mediatype itself is always `application/vnd.oci.image.manifest.v1+json`.
14+
15+
Example - uploading rockets, a brand new type of package:
16+
17+
```
18+
# Create a thing
19+
printf '🚀' > rocket.txt
20+
21+
# Create a manifest config
22+
printf '{"RocketVersion":"v0.1.0"}' > rocket-config.json
23+
24+
# Upload your thing with a custom mediatype
25+
oras push localhost:5000/mystuff/myrocket:v0.1.0 rocket.txt:text/plain \
26+
--manifest-config rocket-config.json:application/vnd.acme.rocket.config.v1+json
27+
```
28+
29+
See manifest created:
30+
31+
```
32+
$ curl -s -H 'Accept: application/vnd.oci.image.manifest.v1+json' \
33+
http://localhost:5000/v2/mystuff/myrocket/manifests/v0.1.0 | jq
34+
{
35+
"schemaVersion": 2,
36+
"config": {
37+
"mediaType": "application/vnd.acme.rocket.config.v1+json",
38+
"digest": "sha256:310175f34d2d4d5cba3418be06ddd1ef948147d729516d78318ec7f5c2d83d49",
39+
"size": 26
40+
},
41+
"layers": [
42+
{
43+
"mediaType": "text/plain",
44+
"digest": "sha256:ebbc0b2870eb323f2b6cffa5c493ceef81ae7eb36afc73d4e0367301631daec5",
45+
"size": 4,
46+
"annotations": {
47+
"org.opencontainers.image.title": "rocket.txt"
48+
}
49+
}
50+
]
51+
}
52+
```
53+
54+
Get that thing:
55+
56+
```
57+
$ curl -s http://localhost:5000/v2/mystuff/myrocket/blobs/sha256:ebbc0b2870eb323f2b6cffa5c493ceef81ae7eb36afc73d4e0367301631daec5
58+
🚀
59+
```
60+
61+
#### Additional Usage ####
62+
63+
ORAS is built primarily on top of Go packages provided by [containerd][containerd-project], but it also imports packages from the [docker/cli][dockercli-project], which enables "docker-style" auth login:
64+
65+
```
66+
oras login -u username -p password localhost:5000 -c rocket-creds.json
67+
```
68+
69+
There are also public Go packages available to build on top of ORAS. The following is the equivalent of the rocket example with the CLI above, but in Go:
70+
71+
```go
72+
package main
73+
74+
import (
75+
"context"
76+
"fmt"
77+
78+
"github.com/containerd/containerd/remotes/docker"
79+
"github.com/deislabs/oras/pkg/content"
80+
"github.com/deislabs/oras/pkg/oras"
81+
ocispec "github.com/opencontainers/image-spec/specs-go/v1"
82+
)
83+
84+
func main() {
85+
ctx := context.Background()
86+
resolver := docker.NewResolver(docker.ResolverOptions{})
87+
store := content.NewMemoryStore()
88+
89+
registryRootURL := "localhost:5000"
90+
registryNamespace := "mystuff/myrocket"
91+
92+
rocketVersion := "v0.1.0"
93+
rocketFileName := "rocket.txt"
94+
rocketMediaType := "text/plain"
95+
rocketContent := []byte("🚀")
96+
rocketDescriptor := store.Add(rocketFileName, rocketMediaType, rocketContent)
97+
98+
rocketConfigMediaType := "application/vnd.acme.rocket.config.v1+json"
99+
rocketConfigContent := []byte(fmt.Sprintf("{\"RocketVersion\":\"%s\"}", rocketVersion))
100+
rocketConfigDescriptor := store.Add("", rocketConfigMediaType, rocketConfigContent)
101+
102+
ref := fmt.Sprintf("%s/%s:%s", registryRootURL, registryNamespace, rocketVersion)
103+
_, err := oras.Push(ctx, resolver, ref, store, []ocispec.Descriptor{rocketDescriptor},
104+
oras.WithConfig(rocketConfigDescriptor))
105+
if err != nil {
106+
panic(err)
107+
}
108+
109+
fmt.Println("Pushed to", ref)
110+
fmt.Printf("\nTry:\n\ncurl -s -H 'Accept: application/vnd.oci.image.manifest.v1+json' \\\n" +
111+
" %s/v2/%s/manifests/%s | jq\n", registryRootURL, registryNamespace, rocketVersion)
112+
}
113+
```
114+
115+
You can see all features in the project [README][oras-readme].
116+
117+
[containerd-project]: https://github.com/containerd/containerd
118+
[dockercli-project]: https://github.com/docker/cli
119+
[oras-readme]: https://github.com/deislabs/oras/blob/master/README.md
120+
121+
## Proposal ##
122+
Change the ownership of the existing ORAS project from deislabs:
123+
124+
https://github.com/deislabs/oras
125+
126+
And move it inside the `opencontainers` organization:
127+
128+
https://github.com/opencontainers/oras
129+
130+
The import paths will correspondingly be "github.com/opencontainers/oras" (oras does have some Go API users, but since the project will be renamed -- and GitHub will add a redirect -- there will be no significant downstream impact of the change).
131+
132+
### Initial Maintainers ###
133+
Initial maintainers of the ORAS project would be:
134+
135+
* Josh Dolitsky <[email protected]> (@jdolitsky)
136+
* Shiwei Zhang <[email protected]> (@shizhMSFT)
137+
* Sajay Antony <[email protected]> (@sajayantony)
138+
* Steve Lasker <[email protected]> (@stevelasker)
139+
* Jimmy Zelinskie <[email protected]> (@jzelinskie)
140+
* Vincent Batts <[email protected]> (@vbatts)
141+
142+
### Code of Conduct ###
143+
This project would incorporate (by reference) the OCI [Code of Conduct][code-of-conduct].
144+
145+
[code-of-conduct]: https://github.com/opencontainers/org/blob/master/CODE_OF_CONDUCT.md
146+
147+
### Governance and Releases ###
148+
This project would incorporate the Governance and Releases processes from the [OCI project template][oci-project-template].
149+
150+
It should be noted that since ORAS is not a specification, it is not bound by the ordinary quorum and voting rules for specification release.
151+
As such, new versions will be released as regularly as needed without the need for a quorum vote.
152+
153+
Pull requests will require two (2) reviews (signified by "LGTM") from project maintainers.
154+
Maintainers are not allowed to review a pull request which they authored.
155+
156+
[oci-project-template]: https://github.com/opencontainers/project-template
157+
158+
### Project Communications ###
159+
The proposed project would continue to use existing channels in use by the OCI developer community for communication including:
160+
161+
* GitHub for issues and pull requests.
162+
* The [`[email protected]`][oci-ml] email list.
163+
* The weekly OCI developer community conference call.
164+
* The `#opencontainers` IRC channel on Freenode.
165+
* The [OCI Slack workspace][oci-slack].
166+
* The [OCI Matrix Room][oci-matrix].
167+
168+
[oci-ml]: mailto:[email protected]
169+
[oci-slack]: https://opencontainers.slack.com/
170+
[oci-matrix]: https://matrix.to/#/#opencontainers:matrix.org
171+
172+
## Frequently Asked Questions (FAQ)
173+
> *Does this proposal change the OCI Charter?*
174+
175+
This proposal does not in any way intend to amend the [OCI Charter][oci-charter].
176+
177+
[oci-charter]: https://github.com/opencontainers/tob/blob/master/CHARTER.md
178+
179+
> *Where does ORAS fit into the OCI suite of projects?*
180+
181+
ORAS is intended to be a *reference implementation of the OCI Distribution Specification*.
182+
183+
As ORAS was designed to handle any type of content, it will serve to exercise the spec
184+
to make it more independent of details that may have leaked in from image-spec or Docker.
185+
186+
> *Why bless ORAS over other alternative tools?*
187+
188+
ORAS has already been used successfully in the wild as a building block for
189+
publishing custom content to an OCI registry.
190+
191+
The following projects are already successfully using ORAS to work with custom artifacts:
192+
193+
- [Helm][helm-usage]
194+
- [Conftest][conftest-usage]
195+
- [Singularity][singularity-usage]
196+
197+
[helm-usage]: https://github.com/helm/helm/search?q=oras
198+
[conftest-usage]: https://github.com/instrumenta/conftest/search?q=oras
199+
[singularity-usage]: https://github.com/sylabs/singularity/search?q=oras
200+
201+
> *How do we avoid the runc issue with implementation-specific quirks becoming a de-facto standard?*
202+
203+
When developing new features in ORAS (which are within the scope of the OCI Distribution Specification),
204+
a strong effort will be made to include those features in the upstream specification.
205+
206+
> *Who are the other target users of ORAS?*
207+
208+
Users seeking a common way to store different types of content (not just container runtime images),
209+
using the OCI Distribution Spec as the baseline API.
210+
211+
> *How do you pronounce ORAS?*
212+
213+
The name ORAS is actually an acronym for "OCI Registry As Storage",
214+
but when speaking of it, you can say "or-ahs".

0 commit comments

Comments
 (0)