Skip to content

Commit d8b32ae

Browse files
caniszczykcaniszczyk
authored
Merge pull request #67 from cyphar/umoci
projects: add umoci proposal
2 parents 23591dd + fe4ccae commit d8b32ae

File tree

2 files changed

+230
-0
lines changed

2 files changed

+230
-0
lines changed

‎README.md

+1
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+
* [umoci](proposals/umoci.md)
2930

3031
## Voting
3132

‎proposals/umoci.md

+229
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# OCI umoci Project Proposal #
2+
3+
## Abstract ##
4+
The need for a "works out of the box" image tool that is supported by OCI has been clear for several years.
5+
umoci was initially developed to fulfil this requirement, and after several years of development and wide-spread production usage, we feel it is time to include it within the OCI.
6+
The following proposal outlines how this would be achieved.
7+
8+
## Background ##
9+
To quote the description of umoci from [the project website][umoci]:
10+
11+
> umoci is a free software tool for manipulating and interacting with container
12+
> images in the standardised Open Container Initiative’s image format. It
13+
> provides one of the most flexible image management toolsets, requiring
14+
> neither a daemon nor any particular filesystem setup. It is already used in a
15+
> variety of different projects and by several companies.
16+
17+
umoci is primarily used as a command-line tool, and can be used to perform fundamental operations on an OCI container image.
18+
An example session looks like
19+
20+
```ShellSession
21+
## Unpack an existing image (image directory "opensuse" with tag "leap") into
22+
## an OCI runtime-spec bundle in the directory "bundle".
23+
##
24+
% umoci unpack --image opensuse:leap bundle
25+
26+
## Start the container in "bundle" using the default generated configuration
27+
## and make some changes to the container filesystem. Note that is not
28+
## necessary to use containers in order to change the filesystem, umoci doesn't
29+
## care how you modify the rootfs.
30+
##
31+
## Note that only modifications in "bundle/rootfs" will have any effect on
32+
## "umoci repack". Of particular note is that you can only change the image
33+
## configuration through "umoci config" and not by modifying
34+
## "bundle/config.json".
35+
##
36+
% runc run -b bundle ctr
37+
ctr# zypper in -y foobarbaz
38+
ctr# exit
39+
% echo foo > bundle/rootfs/README
40+
41+
## Based on the changes made above, build a new layer on top of the original
42+
## image and replace "opensuse:leap" with the new image. If you wish to create
43+
## a new image tag and leave the old one alone, pass a different value to
44+
## --image here (though it must be in the same image directory "opensuse").
45+
##
46+
% umoci repack --image opensuse:new-leap bundle
47+
48+
## Modify the configuration of the image to specify a new author.
49+
##
50+
% umoci config --image opensuse:leap \
51+
> --author="Aleksa Sarai <cyphar@cyphar.com>" \
52+
> --config.workingdir="/var/www"
53+
54+
## Garbage-collect any unreferenced blobs in the image (directory "opensuse").
55+
## umoci does not do this automatically, so users should do this after
56+
## completing all operations on an image.
57+
##
58+
$ umoci gc --layout opensuse
59+
```
60+
61+
umoci has a fairly minimal feature set, and was intended from the outset to implement all of the key features which are needed from a reference implementation of the OCI Image Specifications.
62+
The help page for the latest version of `umoci` (`0.4.5` at the time of writing) is provided below:
63+
64+
```
65+
NAME:
66+
umoci - umoci modifies Open Container images
67+
68+
USAGE:
69+
umoci [global options] command [command options] [arguments...]
70+
71+
VERSION:
72+
0.4.5
73+
74+
AUTHOR:
75+
Aleksa Sarai <asarai@suse.com>
76+
77+
COMMANDS:
78+
raw advanced internal image tooling
79+
help, h Shows a list of commands or help for one command
80+
81+
image:
82+
config modifies the image configuration of an OCI image
83+
unpack unpacks a reference into an OCI runtime bundle
84+
repack repacks an OCI runtime bundle into a reference
85+
new creates a blank tagged OCI image
86+
tag creates a new tag in an OCI image
87+
remove, rm removes a tag from an OCI image
88+
stat displays status information of an image manifest
89+
insert insert content into an OCI image
90+
91+
layout:
92+
gc garbage-collects an OCI image's blobs
93+
init create a new OCI layout
94+
list, ls lists the set of tags in an OCI layout
95+
96+
GLOBAL OPTIONS:
97+
--verbose alias for --log=info
98+
--log value set the log level (debug, info, [warn], error, fatal) (default: "warn")
99+
--help, -h show help
100+
--version, -v print the version
101+
```
102+
103+
For a more detailed explanation of umoci, see the [project website's guide][umoci-guide].
104+
105+
[umoci]: https://umo.ci/
106+
[umoci-guide]: https://umo.ci/quick-start/
107+
108+
## Proposal ##
109+
Change the ownership of the existing umoci project from openSUSE:
110+
111+
https://github.com/openSUSE/umoci
112+
113+
And move it inside the `opencontainers` organisation:
114+
115+
https://github.com/opencontainers/umoci
116+
117+
The import paths will correspondingly be "github.com/opencontainers/umoci" (umoci 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).
118+
In the future we may opt to use vanity imports (such as "umo.ci/cmd/umoci").
119+
120+
The project's domain "umo.ci" will also be transferred to the Linux Foundation so that it can be managed by someone other than the maintainers (though maintainers must maintain the necessary administrative access to maintain the website).
121+
122+
### Initial Maintainers ###
123+
Initial maintainers of the umoci project would be:
124+
125+
* Aleksa Sarai <cyphar@cyphar.com> (@cyphar)
126+
* Tycho Andersen <tycho@tycho.ws> (@tych0)
127+
* Vincent Batts <vbatts@hashbangbash.com> (@vbatts)
128+
129+
### Code of Conduct ###
130+
This project would incorporate (by reference) the OCI [Code of Conduct][code-of-conduct].
131+
132+
[code-of-conduct]: https://github.com/opencontainers/org/blob/master/CODE_OF_CONDUCT.md
133+
134+
### Governance and Releases ###
135+
This project would initially incorporate the Governance and Release processes from [the OCI project template][oci-template], with two modifications:
136+
137+
* Self-LGTMs are permitted.
138+
* Minor (`1.y`), point (`1.2.z`), and release candidate (`1.2.3~rcN`) releases only require 2 LGTMs.
139+
140+
The motivation for these changes is that the set of maintainers is rather small, so many of the [OCI project template rules][oci-template] will require unanimous votes which is an unfair burden on merging code changes.
141+
142+
[oci-template]: https://github.com/opencontainers/project-template
143+
144+
### Project Communications ###
145+
The proposed project would continue to use existing channels in use by the OCI developer community for communication including:
146+
147+
* GitHub for issues and pull requests.
148+
* The [`dev@opencontainers.org`][oci-ml] email list.
149+
* The weekly OCI developer community conference call.
150+
* The `#opencontainers` IRC channel on Freenode.
151+
* The [OCI Slack workspace][oci-slack].
152+
* The [OCI Matrix Room][oci-matrix].
153+
154+
[oci-ml]: mailto:dev@opencontainers.org
155+
[oci-slack]: https://opencontainers.slack.com/
156+
[oci-matrix]: https://matrix.to/#/#opencontainers:matrix.org
157+
158+
### Roadmap ###
159+
umoci still has a fairly ambitious scope of work (much of it outside the scope of the OCI Image Specification), and this work would continue under OCI.
160+
Examples of such work include:
161+
162+
* Security hardening by porting umoci to [libpathrs][libpathrs].
163+
* Re-thinking the method by which images are referenced in the command-line.
164+
* Expanded support for configuring descriptor annotations in arbitrarily-structured OCI metadata trees.
165+
* Committing to a stable Go API and releasing a version 1.0 of the project.
166+
* Experimental design work for [a new OCI Image Specification layer format (code-named "OCIv2")][ociv2].
167+
* Hookable execution to allow for custom "storage drivers" to be defined by users (to avoid the maintenance overhead of supporting such drivers within umoci).
168+
This would effectively allow for higher-level tools to implement both image-build caching (by skipping the extraction of layers which are already available) and overlay filesystem support (by injecting `mount(8)` operations between layer extractions).
169+
170+
[libpathrs]: https://github.com/openSUSE/libpathrs
171+
[ociv2]: https://hackmd.io/@cyphar/ociv2-brainstorm
172+
173+
## Frequently Asked Questions (FAQ)
174+
> *Does this proposal change the OCI Charter?*
175+
176+
This proposal does not intend to amend the [OCI Charter][oci-charter].
177+
178+
[oci-charter]: https://github.com/opencontainers/tob/blob/master/CHARTER.md
179+
180+
> *Where does umoci fit into the OCI suite of projects?*
181+
182+
umoci is intended to be a *reference implementation of the OCI Image Specification* as a "works out of the box" image manipulation tool, which provides a minimally abstracted set of operations to avoid users having to implement the OCI Image Specification themselves.
183+
It is intended to fill a similar role to runc within the OCI Runtime Specification -- that is, being a "boring container infrastructure tool" which larger systems can leverage.
184+
185+
Note that this proposal should not be interpreted as being intended to make the OCI prescribe the use of umoci for existing or new projects to use instead of their own OCI Image Specification implementation.
186+
This proposal for umoci's inclusion is intended to make it easier for users who do not wish to implement the OCI Image Specification themselves to have a basic building block they can use for whatever system they are developing.
187+
While umoci is usable on its own, it is expected that the vast majority of umoci's users will be consuming it as part of a larger build system which uses umoci internally to abstract away the specifics of the OCI Image Specification.
188+
189+
> *What about image-tools?*
190+
191+
The original intention of umoci was to be a wrapper around the OCI image-tools and slowly upstream the work.
192+
Unfortunately, in the past 4 years, the image-tools project has not developed at a consistent pace -- and umoci works today and is fairly widely used.
193+
It is far more important that the OCI provide a solid "works out of the box" image manipulation tool, and umoci is (in our view) the best candidate for this role.
194+
195+
In a future proposal, we may decide to sub-tree merge the OCI image-tools project into umoci (and archive the original project) in order to maintain the legacy of the work done by previous contributors and maintainers.
196+
Alternatively we may decide to split out the validation code from the OCI image-tools project and place it inside an OCI conformance project.
197+
However, we believe that these decisions should be considered a separate topic to the question of umoci's inclusion in the OCI.
198+
199+
> *Why bless umoci over other alternative tools?*
200+
201+
umoci is the only OCI image manipulation tool which was designed to be usable as a component to build other image-building tools.
202+
This has proven to be a practical benefit, with several tools ([KIWI][kiwi], [stacker][stacker], and several others) being built on top of umoci.
203+
In addition, umoci has been used by the [LXC project][lxc-oci] to support OCI-based images from *outside* the OCI ecosystem, something that was only reasonable because of umoci's unopinionated stance on images.
204+
umoci has seen production usage for several years as part of the [Open Build Project][obs]'s build system, building container images using [kiwi][kiwi].
205+
206+
[kiwi]: https://osinside.github.io/kiwi/building/build_docker_container.html
207+
[stacker]: https://github.com/anuvu/stacker
208+
[lxc-oci]: https://github.com/lxc/lxc/blob/lxc-4.0.2/templates/lxc-oci.in
209+
[obs]: https://openbuildservice.org/
210+
211+
> *How do we avoid the runc issue with implementation-specific quirks becoming a de-facto standard?*
212+
213+
When developing new features in umoci (which are within the scope of the OCI Image Specification), a strong effort will be made to include those features in the upstream specification.
214+
In addition, any new features that are in the scope of the OCI Image Specification will be marked as strictly experimental and unsupported, to ensure that users do not depend on their stability until the relevant feature (or an equivalent feature) is included in the OCI Image Specification.
215+
The scope of the OCI Image Specification is thankfully smaller than the OCI Runtime Specification, so this should not be as much of a concern as with runc.
216+
However, the maintainers will be mindful of the issue and will make use of their experiences working on runc and the OCI Runtime Specification to avoid this situation occurring with umoci and the OCI Image Specification.
217+
218+
For the avoidance of doubt, any such features will require explcit user action to enable such that the user is made clearly aware that they are using an unsupported feature.
219+
Examples include requiring the user to:
220+
221+
* Specify a scary-sounding build tag during compilation to enable the feature (`go build -tag 'EXCEPTIONALLY-UNSTABLE--featureXYZ'`); or
222+
* Pass a scary-sounding flag (such as `--seriously-do-not-depend-on-this-feature`); or
223+
* Use a scary function name (such as `VeryUnstableFeature_FuncXyz`).
224+
225+
And all of the above requirements will be documented with an explicit warning that explains to the user why this policy is important.
226+
227+
> *Who are the other target users of umoci?*
228+
229+
End-users who want a simple tool to deal with OCI images, and developers of image-building tools that want a tried and tested implementation of the OCI image format.

0 commit comments

Comments
 (0)