Update builder implementation to 0.1 Builder Spec

[jromero]

Description

The builder has recently been spec'd via RFC (official spec upcoming).

Proposed solution

• Ensure all environment variables and labels on image are present and correct
• Validate builder API.
  • If value is missing, assume API 0.1 with proper necessary changes to make it compatible.

[dfreilich]

In order to be compliant with the specification, we need to make the following changes:

Env

• The image config's Env field has the environment variable CNB_APP_DIR set to the application directory of the build environment
• The image config's Env field has the environment variable CNB_LAYERS_DIR set to a directory in the builder
• The image config's Env field has the environment variable CNB_PLATFORM_DIR set to a directory in the builder
• The image config's Env field has the environment variable CNB_PLATFORM_DIR set to a directory in the builder
• The image config's Env field has the environment variable SERVICE_BINDING_ROOT set to a directory in the builder, if any services are bound

New Labels

• The image config's Labels field has the label io.buildpacks.builder.api, set to 0.1
• The image config's Labels field has the label io.buildpacks.lifecycle.version, set to the lifecycle version (greater than 0.9.0)
• The image config's Labels field has the label io.buildpacks.lifecycle.apis, set to a JSON object representing the lifecycle apis (taken from what we currently set within the io.buildpacks.builder.metadata)

The io.buildpacks.lifecycle.apis data should look like:

{
  "buildpack": {
    "deprecated": ["<list of versions>"],
    "supported": ["<list of versions>"]
  },
  "platform": {
    "deprecated": ["<list of versions>"],
    "supported": ["<list of versions>"]
  }
}

Changes to Existing Labels

• We should change our current io.buildpacks.builder.metadata labels to match the RFC metadata field, by removing the lifecycle top-level key (and all sub information)

Additional Requirements

We should follow all of the spec recommendations for what a build image should look like, which would require us also setting:

• The image config's Labels field has the label io.buildpacks.stack.maintainer set to the name of the stack maintainer.
• The image config's Labels field has the label io.buildpacks.stack.homepage set to the homepage of the stack.
• The image config's Labels field has the label io.buildpacks.stack.distro.name set to the name of the stack's OS distro.
• The image config's Labels field has the label io.buildpacks.stack.distro.version set to the version of the stack's OS distro.
• The image config's Labels field has the label io.buildpacks.stack.released set to the release date of the stack.
• The image config's Labels field has the label io.buildpacks.stack.description set to the description of the stack.
• The image config's Labels field has the label io.buildpacks.stack.metadata set to additional metadata related to the stack.

[jromero]

Waiting for spec PR buildpacks/spec#193 to be approved.

[jimil749]

Hello @jromero! I am relatively new to buildpacks project, but would love to get involved and potentially contribute. Any pointers to get started?

[jromero]

Here are a few resources I think would help (in some reasonable order):

• Talks: Watch a few videos to get a general sense of the buildpacks project and it's value proposition.
• Concepts: Learn about the concepts
• Altoros created a really good blog post series. Here are a few that would help:
  • Cloud Native Buildpacks: Streamlining the Creation of Docker Images
  • Cloud Native Buildpacks: How to Design a Custom Builder
  • Cloud Native Buildpacks: Creating a Stack for Custom Components
• Docs:
  • https://buildpacks.io/docs/concepts/components/builder/
  • https://buildpacks.io/docs/operator-guide/create-a-builder/
• Status: The project uses milestones to track work for specific specifications
  • https://github.com/buildpacks/spec/milestone/17
  • (more issues may be added as we finalize builder 0.1 spec)
• Branch: This is where the specification is being worked.
  • https://github.com/buildpacks/spec/blob/extensions/builder/0.1/extensions/builder.md

Places to get help:

• Slack - #spec is a good channel for this issue, #general works better for general questions
• Office Hours (we may also discuss ongoing efforts in Working Group meetings)
  • See calendar for all meetings

[jimil749]

Thanks for the elaborated response @jromero! Excited to get started! :)

[jromero]

Update from ongoing conversation:

During our discussion today @ecasey and I came to the realization that maybe we’ve been thinking about the builder spec wrong.

We’d like to propose that the builder is just one of the components that may be produced and distributed as part of the distribution spec.

Envision the distribution spec not only detailing how buildpacks are distributed but also how other components are distributed. ie. “If you want to distribute an image of the run image, it must be done as such.” Same for build image, buildpacks (already in place), lifecycle, etc. Last but not least, distributing a builder would simply refer to the other components it must include plus any additional considerations.

[jjbustamante]

After a bunch of discussion, we ended up creating a PR to add the builder spec to the distribution spec. Once that's done, we can come back to this issue and check what else is required next

[jjbustamante]

Block by spec PR 363