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

Distribution Spec (v3) - Build Image Artifact format #266

Merged
merged 5 commits into from
Dec 1, 2021
Merged

Distribution Spec (v3) - Build Image Artifact format #266

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d5850f8
feat: build-image distribution spec
jimil749 Nov 1, 2021
c4bb0de
minor nits
jimil749 Nov 3, 2021
7fddd7a
update UID/SID with relevant footnotes
jimil749 Nov 10, 2021
7f9b9b6
update user field with UID/SID instead of username
jimil749 Nov 11, 2021
24c2179
Update distribution.md
jromero Nov 29, 2021
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
33 changes: 32 additions & 1 deletion distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ This document specifies the artifact format and the delivery mechanism for the b
- [Artifact Format](#artifact-format)
- [Buildpackage](#buildpackage)
- [Lifecycle](#lifecycle)

- [Build Image](#build-image)
## Distribution API Version

This document specifies Distribution API version `0.3`.
Expand Down Expand Up @@ -155,3 +155,34 @@ Where:
* contain an array of deprecated APIs:
* should only contain `0.x` or major versions
* should only contain APIs that correspond to a spec release
### Build Image

The following defines how a build image SHOULD be packaged for distribution as an OCI Image. The build image is the component that provides the base image from which the build environment is constructed.

The image configuration refers to the OCI Image configuration as mentioned [here](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).

#### Image Configuration

The Build Image MUST contain the following configurations:

* Image Config's `config.User` field MUST be set to the user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID with a writable home directory.
Copy link
Member

Choose a reason for hiding this comment

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

Should this include a GID to match CNB_GROUP_ID?

Copy link
Member

Choose a reason for hiding this comment

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

FWIW, I believe this was transposed from the platform API which I don't see having that either.

Copy link
Member

Choose a reason for hiding this comment

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

Hm, I guess it can be optional if the primary group is the intended group.

Copy link
Member

Choose a reason for hiding this comment

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

Additional finding: Google and Heroku builders only use user (not even uid).

Google: "User": "cnb"
Heroku: "User": "heroku"

* Image Config's `os` field MUST be set to the underlying operating system used by the build image.
* Image Config's `architecture` field MUST be set to the underlying operating system architecture used by the build image.
* Image Config's `variant` field MUST be set to the underlying architecture variant.

#### Environment Variables

The Build Image MUST contain the following Environment Variables:

* Image Config's `config.Env` field MUST have the environment variable `CNB_USER_ID` set to the user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID of the user specified in the `User` field.
* Image Config's `config.Env` field MUST have the environment variable `CNB_GROUP_ID` set to the primary group [†](README.md#operating-system-conventions)GID/[‡](README.md#operating-system-conventions)SID of the user specified in the `User` field.
* Image Config's `config.Env` field MUST have the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`).

#### Labels

The Build Image SHOULD contain the following Labels on the image configuration:

| Label | Description
|------- |------------
| `io.buildpacks.distribution.name` | A string denoting the operating system distribution
| `io.buildpacks.distribution.version` | A string denoting the operating system version