Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[ Configuration ] Capitalize MUST through document #403

Closed
wants to merge 1 commit into from
Closed

[ Configuration ] Capitalize MUST through document #403

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,8 +87,8 @@ See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [Se

* **`terminal`** (bool, optional) specifies whether you want a terminal attached to that process. Defaults to false.
* **`cwd`** (string, required) is the working directory that will be set for the executable. This value MUST be an absolute path.
* **`env`** (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution. Elements in the array are specified as Strings in the form "KEY=value". The left hand side must consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
* **`args`** (string, required) executable to launch and any flags as an array. The executable is the first element and must be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable.
* **`env`** (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution. Elements in the array are specified as Strings in the form "KEY=value". The left hand side MUST consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
* **`args`** (string, required) executable to launch and any flags as an array. The executable is the first element and MUST be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is awkward. The “… first element…” sentence is a bundle requirement, but I really don't care if we require that or not. Bundles that don't have an executable at that path (in the container's mount namespace after all the mounts, etc., etc. are setup?) will fail. But checking for that ahead of time, without actually launching the container, seems difficult and/or unstable. I'd rather reword this to cite execv(3) informatively, but allow bundle validators to ignore it.

The “… $PATH…” sentence is a runtime requirement, and probably needs a “MUST” and a link to something more explicit (like execv(3)). Do we need to distinguish between bundle and runtime requirements in this file (see also #404)?

And if both of those points are too involved for this PR and I should spin them out into follow-up issues/PRs, that's fine with me.


For Linux-based systems the process structure supports the following process specific fields:

Expand Down Expand Up @@ -167,8 +167,8 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are

## Platform-specific configuration

* **`os`** (string, required) specifies the operating system family this image must run on. Values for os must be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment).
* **`arch`** (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch must be in the list specified by the Go Language document for [`$GOARCH`](https://golang.org/doc/install/source#environment).
* **`os`** (string, required) specifies the operating system family this image MUST run on. Values for os MUST be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment).
Copy link
Contributor

@wking wking Apr 27, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What sort of requirement is that first MUST? Is it “the runtime MUST generate an error if invoked with a config.json whose os is incompatible with the host platform”? Or is it “the bundle-validator MUST generate an error if os is incompatible with the content the bundle's other content (e.g. linux in os, but only Windows binaries in the bundle's rootfs)? I think the first sentence needs to be reworded to make the condition less ambiguous, or we should reword it to just be informative (e.g. “… image runs on.”).

For the second MUST, I doubt we want to require a compliant runtime support all Go architectures itself. And there is a benefit to pointing runtime/bundle authors at the Go set, but not much benefit in making that a hard limit (see also opencontainers/image-spec#29). Maybe reword that sentence to something like:

The runtime MUST generate an error if it does not support the configured os.
Bundles SHOULD use—and runtimes SHOULD understand—os entries listed in the Go Language document for $GOOS.

* **`arch`** (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch MUST be in the list specified by the Go Language document for [`$GOARCH`](https://golang.org/doc/install/source#environment).

### Example

Expand Down