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

Include buildpack RFC0013 in specification #68

Closed
wants to merge 7 commits into from
Closed

Include buildpack RFC0013 in specification #68

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b79533d
Include buildpack RFC0013 in specification
iainsproat Dec 12, 2019
ebbdcba
Revert "Include buildpack RFC0013 in specification"
stonish Dec 12, 2019
257dcca
RFC0013 moved to platform specification
iainsproat Dec 12, 2019
f826067
Corrects error in json schema for io.buildpacks.project data type
iainsproat Dec 12, 2019
5f00729
Moved flag from Build phase to Export phase
iainsproat Dec 13, 2019
334e1c4
RFC0013: renames `source-metadata` to `project-metadata`
iainsproat Dec 17, 2019
32c757e
Removes project-metadata flag
iainsproat Jan 23, 2020
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
28 changes: 27 additions & 1 deletion platform.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Examples of a platform might include:
5. [Data Format](#data-format)
1. [order.toml (TOML)](#order.toml-(toml))
2. [group.toml (TOML)](#group.toml-(toml))
3. [project-metadata.toml (TOML)](#project-metadata.toml-(toml))

## Stacks

Expand Down Expand Up @@ -61,7 +62,8 @@ The platform MUST ensure that:
- The image config's `Env` field has the environment variable `CNB_GROUP_ID` set to the primary GID of the user specified in the `User` field.
- The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID.
- The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image.


#### Detection phase
To initiate the detection phase, the platform MUST invoke the `/cnb/lifecycle/detector` executable with the user and environment defined in the build image config.
Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values.

Expand All @@ -76,6 +78,7 @@ Where:
- `-group` MUST specify output to a `group.toml` file path as defined in the [Data Format](#data-format) section.
- `-plan` MUST specify output to a Build Plan as defined in the [Buildpack Interface Specification](buildpack.md).

#### Build phase
To initiate the build phase, the platform MUST invoke the `/cnb/lifecycle/builder` executable with the user and environment defined in the build image config.
Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values.

Expand All @@ -89,6 +92,12 @@ Where:
- `-group` MUST specify input from a `group.toml` file path as defined in the [Data Format](#data-format) section.
- `-plan` MUST specify input from a Build Plan as defined in the [Buildpack Interface Specification](buildpack.md).

#### Export phase
Copy link
Member

Choose a reason for hiding this comment

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

Adding the Export phase and it's usage here without also adding the Analyze and Restore phases to the spec seems more confusing to me than omitting all three.

Copy link
Contributor

Choose a reason for hiding this comment

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

Isn't that a bit out of scope of their proposed change, though?

Copy link
Contributor

Choose a reason for hiding this comment

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

Ah I see, (at least I think I'm understanding): you're suggesting we don't add it to the spec proper, but instead include the feature in the lifecycle, but leave the exporter out of the spec until we add all three missing phases and generally overhaul the lifecycle in the spec?

Copy link
Member

Choose a reason for hiding this comment

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

I am happy to own updating the platform spec, it's long overdue. Afterward we can accept incremental changes.

Given that this is a specification rather than documentation adding Exporter with just this one flag is more confusing than not having it at all. By choosing to document a single flag we incorrectly imply something about its importance.

Copy link
Member

Choose a reason for hiding this comment

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

Is CNB_PLATFORM_DIR part of the spec though if we're reserving that keyword?

To initiate the export phase, the platform MUST invoke the `/cnb/lifecycle/exporter` executable with the user and environment defined in the build image config.

The platform MAY provide a [`project-metadata.toml`](#project-metadata.toml-(toml)) file in the platform directory.
The platform MAY provide a `-platform` flag or `CNB_PLATFORM_DIR` environment variable to specify the path of the platform directory. If not provided, the default is `/platform`.

### Run Image

The platform MUST provide the lifecycle with a reference to the run image during the export phase.
Expand Down Expand Up @@ -122,6 +131,11 @@ The buildpacks directory MUST contain unarchived buildpacks such that:
- Each top-level directory is a buildpack ID.
- Each second-level directory is a buildpack version.

## Exported Image
The Exported image containing the compiled application is generated by the Build Image during the [Export Phase](#export-phase).

If the `/cnb/lifecycle/exporter` is provided with a `project-metadata.toml` file in the Platform directory, the lifecycle MUST add a `io.buildpacks.project` image config label to the Exported image. This label value is encoded JSON format of the `project-metadata.toml` contents, as described in the [data-format](#data-format) section.
Copy link
Member

@sclevine sclevine Feb 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

@ekcasey any thoughts about using io.buildpacks.project.metadata instead of io.buildpacks.project to match the other labels? I noticed this key was already added to the lifecycle.

Copy link
Member

Choose a reason for hiding this comment

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

@sclevine that suggestion makes sense to me

Copy link
Member

Choose a reason for hiding this comment

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

here ya go - buildpacks/lifecycle#257


## Security Considerations

The platform SHOULD run each phase of the lifecycle in an isolated container to prevent untrusted app and buildpack code from accessing storage credentials needed during the export and analysis phases.
Expand Down Expand Up @@ -179,3 +193,15 @@ group = [
Where:

- Both `id` and `version` MUST be present for each buildpack object in a group.

### project-metadata.toml (TOML)

```toml
[source]
type = "<source type>"

[source.version]

[source.metadata]

```