From bcee684c3682b046329b278dbbf1709d2a3aa385 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Sat, 28 Sep 2024 13:27:39 -0400 Subject: [PATCH 1/6] adds build and run image content Signed-off-by: Hanan Younes --- .../concepts/build-run-images.md | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 content/docs/for-platform-operators/concepts/build-run-images.md diff --git a/content/docs/for-platform-operators/concepts/build-run-images.md b/content/docs/for-platform-operators/concepts/build-run-images.md new file mode 100644 index 000000000..12c34b6e5 --- /dev/null +++ b/content/docs/for-platform-operators/concepts/build-run-images.md @@ -0,0 +1,94 @@ ++++ +title="Base image types" +weight=99 ++++ + +As you already know, `Cloud Native Buildpacks (CNBs)` transform your application source code into `OCI images` that can run on any cloud and include all of the components your application needs to build and run and. + + + +Each buildpack checks the source code and provides any relevant dependencies. Then, a `base image` is then generated from the application’s source code and these dependencies. + +## Base image types + +A `base image` is an `OCI image` containing the base, or initial set of layers, for other images. It is helpful to distinguish between two distinct types of images, `Build` and `Run` images. + +### Build image + +A `build image` is an `OCI image` that serves as the base image for the `build` environment in which buildpacks `lifecycle` is executed. + +A typical `build image` might determine: + +* The OS distro in the build environment +* OS packages installed in the build environment +* Trusted CA certificates in the build environment +* The default user in the build environment + +The platform must ensure that: + +* The image config's `User` field is set to a non-root user with a writable home directory +* The image config's `Env` field has the environment variable `CNB_USER_ID` set to the user [UID/SID](https://github.com/buildpacks/spec/blob/main/README.md#operating-system-conventions) of the user specified in the `User` field +* The image config's `Env` field has the environment variable `CNB_GROUP_ID` set to the primary group [GID/SID](https://github.com/buildpacks/spec/blob/main/README.md#operating-system-conventions) of the user specified in the `User` field +* The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`) + +The platform should ensure that: + +* The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. +* The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. +* The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. +* The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image. +* The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image. + +#### Anatomy of a build image + +Typically, a `build` image may include: + +* Shell +* C-compiler +* Minimal operating system distribution, such as Linux utilities that build systems might call out to +* Build time libraries + +### Run image + +A `run image` is an `OCI image` that serves as the base image for the final application image. + +A typical run image might determine: + +* The OS distro or distroless OS in the launch environment +* OS packages installed in the launch environment +* Trusted CA certificates in the launch environment +* The default user in the run environment + +The platform must ensure that: + +* The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`) + +The platform should ensure that: + +* The image config's `User` field is set to a user with a **DIFFERENT** user [UID/SID](https://github.com/buildpacks/spec/blob/main/README.md#operating-system-conventions) as the build image +* The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer +* The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image +* The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. +* The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image +* The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image +* The image config's `Label` field has the label `io.buildpacks.rebasable` set to `true` to indicate that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions (see [Compatibility Guarantees]([#compatibility-guarantees](https://github.com/buildpacks/spec/blob/main/platform.md#compatibility-guarantees))). + +#### Anatomy of a run image + +A `runtime` image may contain: + +* No-shell, unless it's needed by the application +* Runtime libraries, such as Libfreetype +* Runtime platforms, such as python interpreter, which are generally added by buildpacks + +For both build images and run images, the platform must ensure that: + +* The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) +* The build image config and the run image config both specify the same `os`, `architecture`, `variant` (if specified), `io.buildpacks.base.distro.name` (if specified), and `io.buildpacks.base.distro.version` (if specified) + +The platform should ensure that: + +* The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) +* The image config's `Label` field has the label `io.buildpacks.base.distro.name` set to the OS distribution and the label `io.buildpacks.base.distro.version` set to the OS distribution version + * For Linux-based images, each label should contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information + * For Windows-based images, `io.buildpacks.base.distro.name` should be empty; `io.buildpacks.base.distro.version` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) From c127bac4422dd822b2bb8bbbc8657571c3db2123 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Sun, 29 Sep 2024 17:32:12 -0400 Subject: [PATCH 2/6] fixes a broken link Signed-off-by: Hanan Younes --- .../docs/for-platform-operators/concepts/build-run-images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/for-platform-operators/concepts/build-run-images.md b/content/docs/for-platform-operators/concepts/build-run-images.md index 12c34b6e5..f2f8b39d6 100644 --- a/content/docs/for-platform-operators/concepts/build-run-images.md +++ b/content/docs/for-platform-operators/concepts/build-run-images.md @@ -71,7 +71,7 @@ The platform should ensure that: * The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. * The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image * The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image -* The image config's `Label` field has the label `io.buildpacks.rebasable` set to `true` to indicate that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions (see [Compatibility Guarantees]([#compatibility-guarantees](https://github.com/buildpacks/spec/blob/main/platform.md#compatibility-guarantees))). +* The image config's `Label` field has the label `io.buildpacks.rebasable` set to `true` to indicate that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions (see [Compatibility Guarantees](https://github.com/buildpacks/spec/blob/main/platform.md#compatibility-guarantees)). #### Anatomy of a run image From 18aa60558e2b5bc5a96fc8c3f84035c45bc54ab5 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Fri, 4 Oct 2024 19:03:28 -0400 Subject: [PATCH 3/6] renames the page and adds some feedback Signed-off-by: Hanan Younes --- .../concepts/{build-run-images.md => base-images.md} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename content/docs/for-platform-operators/concepts/{build-run-images.md => base-images.md} (94%) diff --git a/content/docs/for-platform-operators/concepts/build-run-images.md b/content/docs/for-platform-operators/concepts/base-images.md similarity index 94% rename from content/docs/for-platform-operators/concepts/build-run-images.md rename to content/docs/for-platform-operators/concepts/base-images.md index f2f8b39d6..9c564cc13 100644 --- a/content/docs/for-platform-operators/concepts/build-run-images.md +++ b/content/docs/for-platform-operators/concepts/base-images.md @@ -3,11 +3,11 @@ title="Base image types" weight=99 +++ -As you already know, `Cloud Native Buildpacks (CNBs)` transform your application source code into `OCI images` that can run on any cloud and include all of the components your application needs to build and run and. +As you already know, `Cloud Native Buildpacks (CNBs)` transform your application source code into `OCI images` that can run on any cloud. -Each buildpack checks the source code and provides any relevant dependencies. Then, a `base image` is then generated from the application’s source code and these dependencies. +Each buildpack checks the source code and provides any relevant dependencies in the form of layers. Then, buildpack-provided layers are placed atop a runtime `base image` to form the final application image. ## Base image types @@ -15,7 +15,7 @@ A `base image` is an `OCI image` containing the base, or initial set of layers, ### Build image -A `build image` is an `OCI image` that serves as the base image for the `build` environment in which buildpacks `lifecycle` is executed. +A `build image` is an `OCI image` that serves as the base image for the `build` environment in which the CNB `lifecycle` and buildpacks are executed. A typical `build image` might determine: @@ -48,7 +48,7 @@ Typically, a `build` image may include: * Minimal operating system distribution, such as Linux utilities that build systems might call out to * Build time libraries -### Run image +### Runtime image A `run image` is an `OCI image` that serves as the base image for the final application image. @@ -73,7 +73,7 @@ The platform should ensure that: * The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image * The image config's `Label` field has the label `io.buildpacks.rebasable` set to `true` to indicate that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions (see [Compatibility Guarantees](https://github.com/buildpacks/spec/blob/main/platform.md#compatibility-guarantees)). -#### Anatomy of a run image +#### Anatomy of a runtime base image A `runtime` image may contain: From c808d4459c434a9554ad80316fc59798b1b5f316 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Sat, 5 Oct 2024 17:07:53 -0400 Subject: [PATCH 4/6] uses runtime vs run image Signed-off-by: Hanan Younes --- .../for-platform-operators/concepts/base-images.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/docs/for-platform-operators/concepts/base-images.md b/content/docs/for-platform-operators/concepts/base-images.md index 9c564cc13..51143ac10 100644 --- a/content/docs/for-platform-operators/concepts/base-images.md +++ b/content/docs/for-platform-operators/concepts/base-images.md @@ -11,7 +11,7 @@ Each buildpack checks the source code and provides any relevant dependencies in ## Base image types -A `base image` is an `OCI image` containing the base, or initial set of layers, for other images. It is helpful to distinguish between two distinct types of images, `Build` and `Run` images. +A `base image` is an `OCI image` containing the base, or initial set of layers, for other images. It is helpful to distinguish between two distinct types of images, `Build` and `Runtime` images. ### Build image @@ -50,9 +50,9 @@ Typically, a `build` image may include: ### Runtime image -A `run image` is an `OCI image` that serves as the base image for the final application image. +A `runtime image` is an `OCI image` that serves as the base image for the final application image. -A typical run image might determine: +A typical runtime image might determine: * The OS distro or distroless OS in the launch environment * OS packages installed in the launch environment @@ -81,10 +81,10 @@ A `runtime` image may contain: * Runtime libraries, such as Libfreetype * Runtime platforms, such as python interpreter, which are generally added by buildpacks -For both build images and run images, the platform must ensure that: +For both build images and runtime images, the platform must ensure that: * The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) -* The build image config and the run image config both specify the same `os`, `architecture`, `variant` (if specified), `io.buildpacks.base.distro.name` (if specified), and `io.buildpacks.base.distro.version` (if specified) +* The build image config and the runtime image config both specify the same `os`, `architecture`, `variant` (if specified), `io.buildpacks.base.distro.name` (if specified), and `io.buildpacks.base.distro.version` (if specified) The platform should ensure that: From 432d72f7ba15f41a0548ce0b187556d4a0c5b4c4 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Thu, 10 Oct 2024 20:10:17 -0400 Subject: [PATCH 5/6] adds reviewer feedback and updates page links Signed-off-by: Hanan Younes --- .../concepts/base-images.md | 41 +------------------ .../concepts/builder.md | 7 ++-- 2 files changed, 6 insertions(+), 42 deletions(-) diff --git a/content/docs/for-platform-operators/concepts/base-images.md b/content/docs/for-platform-operators/concepts/base-images.md index 51143ac10..08382141c 100644 --- a/content/docs/for-platform-operators/concepts/base-images.md +++ b/content/docs/for-platform-operators/concepts/base-images.md @@ -24,21 +24,6 @@ A typical `build image` might determine: * Trusted CA certificates in the build environment * The default user in the build environment -The platform must ensure that: - -* The image config's `User` field is set to a non-root user with a writable home directory -* The image config's `Env` field has the environment variable `CNB_USER_ID` set to the user [UID/SID](https://github.com/buildpacks/spec/blob/main/README.md#operating-system-conventions) of the user specified in the `User` field -* The image config's `Env` field has the environment variable `CNB_GROUP_ID` set to the primary group [GID/SID](https://github.com/buildpacks/spec/blob/main/README.md#operating-system-conventions) of the user specified in the `User` field -* The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`) - -The platform should ensure that: - -* The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. -* The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. -* The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. -* The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image. -* The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image. - #### Anatomy of a build image Typically, a `build` image may include: @@ -59,20 +44,6 @@ A typical runtime image might determine: * Trusted CA certificates in the launch environment * The default user in the run environment -The platform must ensure that: - -* The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`) - -The platform should ensure that: - -* The image config's `User` field is set to a user with a **DIFFERENT** user [UID/SID](https://github.com/buildpacks/spec/blob/main/README.md#operating-system-conventions) as the build image -* The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer -* The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image -* The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. -* The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image -* The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image -* The image config's `Label` field has the label `io.buildpacks.rebasable` set to `true` to indicate that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions (see [Compatibility Guarantees](https://github.com/buildpacks/spec/blob/main/platform.md#compatibility-guarantees)). - #### Anatomy of a runtime base image A `runtime` image may contain: @@ -81,14 +52,6 @@ A `runtime` image may contain: * Runtime libraries, such as Libfreetype * Runtime platforms, such as python interpreter, which are generally added by buildpacks -For both build images and runtime images, the platform must ensure that: - -* The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) -* The build image config and the runtime image config both specify the same `os`, `architecture`, `variant` (if specified), `io.buildpacks.base.distro.name` (if specified), and `io.buildpacks.base.distro.version` (if specified) - -The platform should ensure that: +For more details on `build` and `runtime` images, you can check out the [specification][spec] -* The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) -* The image config's `Label` field has the label `io.buildpacks.base.distro.name` set to the OS distribution and the label `io.buildpacks.base.distro.version` set to the OS distribution version - * For Linux-based images, each label should contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information - * For Windows-based images, `io.buildpacks.base.distro.name` should be empty; `io.buildpacks.base.distro.version` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) +[spec]: https://github.com/buildpacks/spec/blob/main/platform.md#build-image diff --git a/content/docs/for-platform-operators/concepts/builder.md b/content/docs/for-platform-operators/concepts/builder.md index 8b85704db..4e002efee 100644 --- a/content/docs/for-platform-operators/concepts/builder.md +++ b/content/docs/for-platform-operators/concepts/builder.md @@ -20,14 +20,15 @@ A builder consists of the following components: * [Buildpacks][buildpack] * A [lifecycle][lifecycle] -* A [build image](/docs/for-app-developers/concepts/base-images/build/) -* A reference to a [run image](/docs/for-app-developers/concepts/base-images/run/) +* A [build image][build-image] +* A reference to a [run image][run-image] ### Resources To learn how to create your own builder, see our [Operator's Guide][operator-guide]. -[builder-config]: /docs/reference/builder-config/ [buildpack]: /docs/for-platform-operators/concepts/buildpack/ [lifecycle]: /docs/for-platform-operators/concepts/lifecycle/ [operator-guide]: /docs/for-platform-operators/ +[build-image]: /docs/for-platform-operators/concepts/base-images.md +[run-image]: /docs/for-platform-operators/concepts/base-images.md From 803cc63fea8827874815f709519a8c46d5804c2f Mon Sep 17 00:00:00 2001 From: Aidan Delaney Date: Tue, 22 Oct 2024 06:56:26 +0100 Subject: [PATCH 6/6] Update content/docs/for-platform-operators/concepts/builder.md Signed-off-by: Aidan Delaney --- content/docs/for-platform-operators/concepts/builder.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/for-platform-operators/concepts/builder.md b/content/docs/for-platform-operators/concepts/builder.md index 4e002efee..6d435735b 100644 --- a/content/docs/for-platform-operators/concepts/builder.md +++ b/content/docs/for-platform-operators/concepts/builder.md @@ -30,5 +30,5 @@ To learn how to create your own builder, see our [Operator's Guide][operator-gui [buildpack]: /docs/for-platform-operators/concepts/buildpack/ [lifecycle]: /docs/for-platform-operators/concepts/lifecycle/ [operator-guide]: /docs/for-platform-operators/ -[build-image]: /docs/for-platform-operators/concepts/base-images.md -[run-image]: /docs/for-platform-operators/concepts/base-images.md +[build-image]: /docs/for-platform-operators/concepts/base-images +[run-image]: /docs/for-platform-operators/concepts/base-images