- Name: Buildpack URIs
- Start Date: 02/07/2020
- Status: Implemented
- CNB Pull Request: rfcs#56
- CNB Issue: (leave blank)
- Supersedes: "N/A"
A set of predefined URIs for referring to buildpacks from various sources (protocols).
Please note that the scheme denotes protocol and not type.
Given that we support a multitude of sources for buildpacks, a certain level of ambiguity has naturally presented itself. We currently try to resolve the various sources through a complex set of rules yet the ambiguity to users still exists. In config files, this ambiguity is at times resolved by introducing a separate key name to signify the source (protocol).
The aim of this RFC is to propose a set of URI schemes that could be used in both CLI arguments and config files while solving the ambiguity problem.
A few references to further express the problem:
- A poll to understand what users expect when providing buildpacks and there is overlap of sources.
- Issue to provide additional clarity in logs due to ambiguity.
- A conversation when trying to determine how to provide reference to all buildpacks in builder.
- Issue where an
imagekey was added to differentiate between directory and image.
| Name | Format | Examples |
|---|---|---|
| Relative | <path> |
./my/buildpack.tgz/home/user/my/buildpack.tgz |
| Filesystem | file://[<host>]/<path> |
file:///my/buildpack.tgzfile:///home/user/my/buildpack.tgz |
| URL | http[s]://<host>/<path> |
http://example.com/my/buildpack.tgzhttps://example.com/my/buildpack.tgz |
| Docker | docker://[<host>]/<path>[:<tag>⏐@<digest>] |
docker://gcr.io/distroless/nodejsdocker:///ubuntu:latestdocker:///ubuntu@sha256:45b23dee08... |
| CNB Registry | cnb://[<host>]/[<id>[@<version>]] |
cnb:///my-org/my-bpcnb://index.buildpack.io/my-org/my-bpcnb://index.buildpack.io/my-org/[email protected] |
| CNB Builder Resource | urn:cnb:builder[:<id>[@<version>]] |
urn:cnb:builderurn:cnb:builder:bp.idurn:cnb:builder:[email protected] |
| CNB Registry Resource | urn:cnb:registry[:<id>[@<version>]] |
urn:cnb:registry:bp.idurn:cnb:registry:[email protected] |
A URI without a scheme is treated as a relative reference as per RFC 3986 section 4.1.
The filesystem scheme is the implementation of RFC 8089.
The URL scheme is the implementation of RFC 7230.
The docker scheme denotes the use of the Docker HTTP API v2 protocol.
<host>is optional and defaults toindex.docker.io.- Similar to the
filescheme, there is a minimal declaration for omitting host by using a simple slash (/). eg.docker:/ubuntu:latest
The cnb scheme resolves buildpacks using the buildpacks registry described in RFC #22.
<host>is optional and would default to a host predefined (or configured) in the platform.- Similar to the
filescheme, there is a minimal declaration for omitting host by using a simple slash (/). eg.cnb:/my-org/[email protected]
The defined URNs are resource names to buildpacks where they reside is predetermined. For example, in urn:cnb:builder,
there is only a single builder in the build context. In urn:cnb:registry, the registry is similarly provided as a
default to the platform.
urn:cnb:builder- A reference to ALL the buildpacks in the builder.urn:cnb:builder:bp.id- A reference to a buildpack with idbp.idin the builder.urn:cnb:builder:[email protected]- A reference to a buildpack with idbp.idat the specific versionbp.version.
urn:cnb:registry:bp.id- A reference to a buildpack by idbp.idin the registry.urn:cnb:registry:[email protected]- A reference to a buildpack with idbp.idat the specific versionbp.version.
Certain pack CLI arguments would take URIs supported instead of the current inconsistent format.
Some examples:
pack build my-app \
--buildpack urn:cnb:builder:[email protected] \ # buildpack from builder
--buildpack file:///home/user/path/to/buildpack/ \ # absolute via file
--buildpack /home/user/path/to/buildpack/ \ # absolute via schemeless
--buildpack ../path/to/buildpack/ \ # relative file
--buildpack docker:/cnbs/some-package \ # Docker Hub image
--buildpack docker://gcr.io/cnbs/sample-package-2:bionic \ # GCR image (with tag)
--buildpack cnb://index.buildpack.io/my-org/[email protected] \ # buildpack from registry
--buildpack urn:cnb:builder # All buildpacks in builderConfig files would replace image with uri, using the docker:// scheme, where applicable.
package.toml:
[buildpack]
uri = "."
[[dependencies]]
uri = "docker:/my/image:latest"
# ...builder.toml:
# ...
[[buildpacks]]
uri = "./my/buildpacks/"
[[buildpacks]]
uri = "docker:/my/image:latest"
# ...pack could provide additional logic in order for users to have a nicer user experience when providing references
via CLI. For example, pack could have an order of precedence to make a best guess at which type of reference
they are referring to or provide additional feedback if it's ambiguous.
- The user would need to type an additional scheme prefix for any URI which is not a relative reference.
A different flag or config properties to signify the different protocols and would render the need for URI moot.
An alternative to docker is to use a more generic term such as oci. There is an official
OCI distribution spec based on Docker HTTP
API v2 but it's direct compatibility would require additional research. Additionally, oci scheme has an overlap with
Oracle Cloud Infrastructure Object Storage Service.
- Predefined set of URI schemes for OCI images created by Skopeo.
- from=builder syntax.
- Where would this be documented long-term?
- Answer: As an extension spec. See spec changes.
- How does
urn:cnb:registry:[email protected]translate to anamespace+nameas detailed in RFC #22?- Answer:
As of now, a namespace/name is an acceptable form of buildpack ID (like ID is a superset). So think defining the URN as
urn:cnb:registry:<id>@<version>is sufficient for this proposal. In a future proposal we might define more strict rule about ID, but this definition would stay the same.
- Answer:
This RFC would yield a new extension spec.