Platform spec rewrite #87
Conversation
platform.md
Outdated
|
|
||
| #### Rebase | ||
| Run image rebasing allows for fast stack updates for already-exported OCI images without require a rebuild. A rebase requires minimal data transfer when those images are stored on a Docker registry. | ||
| When a new stack version with the same stack ID is available, the app layers and launch layers SHOULD be rebased on the new run image by updating the image's configuration to point at the new run image. |
There was a problem hiding this comment.
Do we need to be more explicit than "rebased on the new run image"? Maybe something like:
create a new image using the app layers and launch layer on the new run image ...
Also, I'm not great at spec-speak, but maybe this should be "MUST" instead of "SHOULD"?
There was a problem hiding this comment.
Do we need to be more explicit than "rebased on the new run image"?
I took another stab at it. Let me know what you think.
Also, I'm not great at spec-speak, but maybe this should be "MUST" instead of "SHOULD"?
I think this is properly a SHOULD. It's up to the platform to kick off a rebase when a new run image is available. Platforms like pack can't do this automatically every time a new stack image is released. Therefore it is guidance to platform and/or end users rather than a requirement.
Signed-off-by: Emily Casey <ecasey@vmware.com>
Signed-off-by: Emily Casey <ecasey@vmware.com>
Signed-off-by: Emily Casey <ecasey@vmware.com>
Signed-off-by: Emily Casey <ecasey@vmware.com>
Signed-off-by: Emily Casey <ecasey@vmware.com>
Signed-off-by: Emily Casey <ecasey@vmware.com>
* Adds details to data format * Alphabetizes Signed-off-by: Emily Casey <ecasey@vmware.com>
Signed-off-by: Emily Casey <ecasey@vmware.com>
Co-authored-by: Ben Hale <bhale@vmware.com> Co-authored-by: Joe Kutner <jpkutner@gmail.com> Signed-off-by: Emily Casey <ecasey@vmware.com>
Signed-off-by: Emily Casey <ecasey@vmware.com>
ekcasey
force-pushed
the
platform-spec-rewrite
branch
from
ea40adc
to
2613b08
Compare
Signed-off-by: Emily Casey <ecasey@vmware.com>
…-rewrite Signed-off-by: Emily Casey <ecasey@vmware.com>
* Use bullet points to break up hard to read paragraphs * Consistent use of - vs * * Consistent capitalization of IF * Consistent captialization of bullet point lines Signed-off-by: Emily Casey <ecasey@vmware.com>
Signed-off-by: Emily Casey <ecasey@vmware.com>
* Removes duplicated compatibility rules * Clarifies language * Other minor cleanup Signed-off-by: Emily Casey <ecasey@vmware.com>
|
|
||
| ## Stacks | ||
| A **stack** is a contract defined by a **build image** and a **run image** that are only updated with security patches. |
There was a problem hiding this comment.
Maybe it's worth adding an explanation on why we combine a build image and a run image under the term stack and why we update it only in security patches.
I'm not sure what is the right place to add it.
Maybe if you move the stack definition to be after the build image and the run image definitions, you can add it there.
There was a problem hiding this comment.
Separate note: the contract isn't defined by the images, but by the functionality that the images provide.
There was a problem hiding this comment.
Maybe if we don't define stack by itself? Something like:
| A **stack** is a contract defined by a **build image** and a **run image** that are only updated with security patches. | |
| A **stack contract** is defined by a set of unchanging ABIs, command line interfaces, and functional behaviors. Images marked with a **stack ID** MUST implement the same contract. |
There was a problem hiding this comment.
Didn't realize this line was moved and not changed. We shouldn't block merging on fixing this.
There was a problem hiding this comment.
I went to add a version of this suggestion with an accompanying definition of stack ID but I wasn't convinced it was easier to understand.
Given that we already have this definition in the existing spec maybe we can punt this improvement (and a possible reordering of terminology) to a future PR. It might be easier to think about these types of incremental improvements after we get this monster merged.
There was a problem hiding this comment.
Should we create an issue to track this work?
|
|
||
| A **run image** is an OCI image that provides the base from which **app images** are built | ||
|
|
||
| The **build environment** refers to the containerized environment in which the lifecycle executes buildpacks. |
There was a problem hiding this comment.
Following my comment about the stack definition, I think it's better (if possible) to use a term after defining it.
Therefore I would move the build environment definition to be before the build image definition, and the app images definition to be before the run image definition.
There was a problem hiding this comment.
Hmm.... It gets tricky b/c app image references run image and run image references app image?
I don't want it to be confusing but some of these terms exist only in relationship to each other? Maybe we should just alphabetize them?
There was a problem hiding this comment.
I know that it isn't possible in every term but I think that if it's possible, it's worth doing so.
If you decide that it's not possible, I think it's better to leave it as is and not alphabetize them (at least now, I expect to read the definition of the term that I've just see in the previous definition).
There was a problem hiding this comment.
I'll try to reorganize a bit
There was a problem hiding this comment.
How about we do this in a self-contained PR after this merges?
platform.md
Outdated
| The **launcher** refers to a lifecycle executable packaged in the app image for the purpose of executing processes at runtime | ||
|
|
||
| #### Additional Terminology | ||
| An **image reference** refers to either a **tag reference** or **digest reference** |
There was a problem hiding this comment.
See the other comments about the order of the definitions (of course this is how I prefer to read it but maybe others have different opinion about it :) ).
| - IF `<skip-restore>` is `true` the `creator` SHALL skip layer analysis and skip the entire Restore phase. | ||
| - IF the platform provides one or more `<tag>` inputs they SHALL be treated as additional `<image>` inputs to the `exporter` | ||
|
|
||
| Outputs produced by `creator` are identical to those produced by `exporter`. |
There was a problem hiding this comment.
Maybe it's worth adding why a user would want to use the creator over the 5 phases separately.
There was a problem hiding this comment.
Is this just the difference b/t spec and documentation?
| Cache locality and availability MAY vary between platforms. | ||
|
|
||
| ## Data Format | ||
|
|
||
| ### order.toml (TOML) | ||
| ### Files |
There was a problem hiding this comment.
Maybe it's worth adding an example of each file (or pointing to a location in the samples repository with such examples).
There was a problem hiding this comment.
I think we should provide examples outside the spec in more friendly formats like (future) lifecycle docs.
There was a problem hiding this comment.
Sounds good but don't you think it's worth adding a link in the spec to these examples?
Anyway, if these examples don't exist yet, we can discuss it when it'll be relevant :)
| @@ -7,64 +7,114 @@ A platform orchestrates a lifecycle to make buildpack functionality available to | |||
| Examples of a platform might include: | |||
|
|
|||
| 1. A local CLI tool that uses buildpacks to create OCI images | |||
| 2. A plugin for a continuous integration service that uses buildpacks to create OCI images | |||
| 3. A cloud application platform that uses buildpacks to build source code before deployment | |||
There was a problem hiding this comment.
I'd prefer to keep the numbering explicit, so that it's easier to find sections without a markdown rendering tool For example, if someone says "see section 1, item 4b," it's difficult to find that item without rendering the document. Not having to render the document to read it is generally why I prefer markdown to other markups. That said, I'm okay with this change if others disagree with me (and if we make it consistently).
(On that note, I've noticed that many specifications avoid unordered (e.g., bulleted) lists entirely, because it makes referring to individual items difficult. Would be great if we could pick a consistent rule for lists like "always use 1. -> a. -> i. and never use explicit numbering")
There was a problem hiding this comment.
This numbering thing is a problem that I don’t think we have a good handle on yet. Including the numbers explicitly requires users to always remember to update them whenever a change is made (and even the best can forget updates). Also using ordered lists has a tendency to break links as data is inserted and remove (note the anchor names in the TOC).
My personal preferences run towards ordered lists for the same reasons you like them, but the downsides of using them are so high that I can’t justify it 😞
There was a problem hiding this comment.
if someone says "see section 1, item 4b," it's difficult to find that item without rendering the document
How likely are you to lookup "section 1, item 4b" in the unrendered version though? Given that we are a bit inconsistent right now I wonder if we could bring decide on guidelines and bring all the specs into compliance with them separately from this PR.
|
|
||
| The following is a non-exhaustive list of terms defined in the [OCI Image Format Specification](https://github.com/opencontainers/image-spec) used throughout this document: | ||
| * **image config** https://github.com/opencontainers/image-spec/blob/master/config.md#oci-image-configuration | ||
| * **imageID** - https://github.com/opencontainers/image-spec/blob/master/config.md#imageid |
There was a problem hiding this comment.
| * **imageID** - https://github.com/opencontainers/image-spec/blob/master/config.md#imageid | |
| * **ImageID** - https://github.com/opencontainers/image-spec/blob/master/config.md#imageid |
There was a problem hiding this comment.
I decided to go with consistent lower-casing for imageID and diffID
Co-authored-by: Stephen Levine <stephen.levine@gmail.com> Signed-off-by: Emily Casey <ecasey@vmware.com>
* don't capitalize non RFC 2119 words * small gramatiical fixes * improved launcher process selection Signed-off-by: Emily Casey <ecasey@vmware.com>
ekcasey
force-pushed
the
platform-spec-rewrite
branch
2 times, most recently
from
1085089
to
c7e09cc
Compare
Signed-off-by: Emily Casey <ecasey@vmware.com>
A hack so we can use illegal comments and still get syntax highlighting. Signed-off-by: Emily Casey <ecasey@vmware.com>
ekcasey
force-pushed
the
platform-spec-rewrite
branch
from
c7e09cc
to
c181659
Compare
* Fixes inaccurate commandline usage Signed-off-by: Emily Casey <ecasey@vmware.com>
Previously stack ID requirements including: * allowed characters * global uniqueness were only specified in the buildpack spec, in the buildpack.toml data formt section. This PR moves stack ID description and requirements in the Platform spec with the rest of the stack concepts. Clarifies stack concepts, incorporating feedback that surfaced in previous PR reviews #87 (comment). Signed-off-by: Emily Casey <ecasey@vmware.com>
When making decisions about whether or not to specify existing behavior, I defaulted to over-specifying, on the assumption that it would be easier to see the full breadth of what could be specified and remove things.