From a1e2e6c093d33b9bfc52521a09323c313d1fbd3e Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 14 Feb 2024 17:34:28 -0500 Subject: [PATCH] Clean up platform-operator section Signed-off-by: Natalie Arellano --- .../concepts/base-images/build.md | 6 +++++- .../docs/for-platform-operators/concepts/builder.md | 13 +++++++------ .../for-platform-operators/concepts/buildpack.md | 8 +++----- .../for-platform-operators/concepts/dockerfiles.md | 5 +++-- .../concepts/lifecycle/_index.md | 4 ++-- .../_index.md | 0 .../how-to/build-inputs/create-builder/_index.md | 10 ++++++++++ .../create-builder}/build-base.md | 4 +++- .../create-builder}/builder.md | 7 +++---- .../create-builder}/extensions.md | 2 ++ .../create-builder}/run-base.md | 4 +++- .../{ => build-inputs}/declare-source-metadata.md | 5 +++-- .../{prepare-build-inputs => build-inputs}/stack.md | 11 ++++++----- .../how-to/integrate-ci/circleci.md | 4 +++- .../how-to/integrate-ci/gitlab.md | 5 +++-- .../how-to/integrate-ci/kpack.md | 5 ++++- .../how-to/integrate-ci/pack/_index.md | 3 ++- .../how-to/integrate-ci/piper.md | 5 ++++- .../how-to/integrate-ci/tekton.md | 6 ++++-- .../tutorials/lifecycle/_index.md | 2 ++ 20 files changed, 72 insertions(+), 37 deletions(-) rename content/docs/for-platform-operators/how-to/{prepare-build-inputs => build-inputs}/_index.md (100%) create mode 100644 content/docs/for-platform-operators/how-to/build-inputs/create-builder/_index.md rename content/docs/for-platform-operators/how-to/{prepare-build-inputs => build-inputs/create-builder}/build-base.md (95%) rename content/docs/for-platform-operators/how-to/{prepare-build-inputs => build-inputs/create-builder}/builder.md (92%) rename content/docs/for-platform-operators/how-to/{prepare-build-inputs => build-inputs/create-builder}/extensions.md (86%) rename content/docs/for-platform-operators/how-to/{prepare-build-inputs => build-inputs/create-builder}/run-base.md (94%) rename content/docs/for-platform-operators/how-to/{ => build-inputs}/declare-source-metadata.md (93%) rename content/docs/for-platform-operators/how-to/{prepare-build-inputs => build-inputs}/stack.md (92%) diff --git a/content/docs/for-app-developers/concepts/base-images/build.md b/content/docs/for-app-developers/concepts/base-images/build.md index f30537b20..20b247e38 100644 --- a/content/docs/for-app-developers/concepts/base-images/build.md +++ b/content/docs/for-app-developers/concepts/base-images/build.md @@ -7,4 +7,8 @@ The **build image** provides the base image from which the build environment is -The build environment is the containerized environment in which the [lifecycle][lifecycle] (and thereby [buildpacks][buildpack]) are executed. +The build environment is the containerized environment in which the [lifecycle] +(and thereby [buildpacks][buildpack]) are executed. + +[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/ +[buildpack]: /docs/for-app-developers/concepts/buildpack/ diff --git a/content/docs/for-platform-operators/concepts/builder.md b/content/docs/for-platform-operators/concepts/builder.md index 9caf5d101..24d92804b 100644 --- a/content/docs/for-platform-operators/concepts/builder.md +++ b/content/docs/for-platform-operators/concepts/builder.md @@ -1,15 +1,16 @@ +++ -title="Builder" -weight=1 -summary="A builder is an image that contains all the components necessary to execute a build. A builder image is created by taking a build image and adding a lifecycle, buildpacks, and files that configure aspects of the build including the buildpack detection order and the location(s) of the run image" +title="What is a builder?" +weight=2 aliases=[ "/docs/using-pack/working-with-builders/" ] +++ -## What is a builder? +A `builder` is an OCI image containing +an ordered combination of [buildpacks][buildpack] and +a build-time base image, a [lifecycle] binary, and a reference to a runtime base image. -{{< param "summary" >}} + ![create-builder diagram](/docs/for-platform-operators/concepts/create-builder.svg) @@ -27,6 +28,6 @@ A builder consists of the following components: To learn how to create your own builder, see our [Operator's Guide][operator-guide]. [builder-config]: /docs/reference/builder-config/ -[operator-guide]: /docs/for-platform-operators/ [buildpack]: /docs/for-platform-operators/concepts/buildpack/ [lifecycle]: /docs/for-platform-operators/concepts/lifecycle/ +[operator-guide]: /docs/for-platform-operators/ diff --git a/content/docs/for-platform-operators/concepts/buildpack.md b/content/docs/for-platform-operators/concepts/buildpack.md index 8f4c95337..a3f133e02 100644 --- a/content/docs/for-platform-operators/concepts/buildpack.md +++ b/content/docs/for-platform-operators/concepts/buildpack.md @@ -1,11 +1,9 @@ +++ -title="Buildpack" -weight=2 +title="What is a buildpack?" +weight=1 +++ -## What is a buildpack? - -A buildpack is a set of executables that inspects your app source code and creates a plan to build and run your application. +A `buildpack` is software that examines your source code and determines the best way to build it. diff --git a/content/docs/for-platform-operators/concepts/dockerfiles.md b/content/docs/for-platform-operators/concepts/dockerfiles.md index bfa6d4c5e..e2a14da74 100644 --- a/content/docs/for-platform-operators/concepts/dockerfiles.md +++ b/content/docs/for-platform-operators/concepts/dockerfiles.md @@ -1,8 +1,9 @@ +++ -title="Dockerfiles" +title="What are image extensions?" +weight=99 +++ -Dockerfiles can be used to extend base images for buildpacks builds. +Image extensions generate Dockerfiles that can be used to extend base images for buildpacks builds. diff --git a/content/docs/for-platform-operators/concepts/lifecycle/_index.md b/content/docs/for-platform-operators/concepts/lifecycle/_index.md index 4d283f604..a029deec4 100644 --- a/content/docs/for-platform-operators/concepts/lifecycle/_index.md +++ b/content/docs/for-platform-operators/concepts/lifecycle/_index.md @@ -1,5 +1,5 @@ +++ -title="Lifecycle" +title="What is the lifecycle?" weight=3 include_summaries=true @@ -7,6 +7,6 @@ include_summaries=true ## What is the lifecycle? -The lifecycle orchestrates buildpack execution, then assembles the resulting artifacts into a final app image. +The `lifecycle` orchestrates buildpack execution, then assembles the resulting artifacts into an OCI image. diff --git a/content/docs/for-platform-operators/how-to/prepare-build-inputs/_index.md b/content/docs/for-platform-operators/how-to/build-inputs/_index.md similarity index 100% rename from content/docs/for-platform-operators/how-to/prepare-build-inputs/_index.md rename to content/docs/for-platform-operators/how-to/build-inputs/_index.md diff --git a/content/docs/for-platform-operators/how-to/build-inputs/create-builder/_index.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/_index.md new file mode 100644 index 000000000..46f91f519 --- /dev/null +++ b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/_index.md @@ -0,0 +1,10 @@ ++++ +title="Create a builder" +weight=1 +include_summaries=true ++++ + +A [builder][builder] is an OCI image with all the inputs needed for a buildpacks build, including +the build-time base image, a reference to a runtime base image, a lifecycle, and a set of buildpacks. + +[builder]: /docs/for-platform-operators/concepts/builder \ No newline at end of file diff --git a/content/docs/for-platform-operators/how-to/prepare-build-inputs/build-base.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base.md similarity index 95% rename from content/docs/for-platform-operators/how-to/prepare-build-inputs/build-base.md rename to content/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base.md index 62e5aac1f..27c4d5fd7 100644 --- a/content/docs/for-platform-operators/how-to/prepare-build-inputs/build-base.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base.md @@ -1,8 +1,10 @@ +++ title="Create a build base image" -weight=2 +weight=1 +++ +The build-time base image provides the OS-level dependencies for buildpacks at build-time. + ## Define a build base image for your CNB build diff --git a/content/docs/for-platform-operators/how-to/prepare-build-inputs/builder.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/builder.md similarity index 92% rename from content/docs/for-platform-operators/how-to/prepare-build-inputs/builder.md rename to content/docs/for-platform-operators/how-to/build-inputs/create-builder/builder.md index 84e73ad36..336cadb7b 100644 --- a/content/docs/for-platform-operators/how-to/prepare-build-inputs/builder.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/builder.md @@ -1,10 +1,9 @@ +++ -title="Create a builder" -weight=1 +title="Putting it all together" +weight=3 +++ -A [builder][builder] is an OCI image with all the inputs needed for a buildpacks build, including -the build-time base image, a reference to a runtime base image, a lifecycle, and a set of buildpacks. +After you have created a build-time base image and a runtime base image, you are ready to create your builder! diff --git a/content/docs/for-platform-operators/how-to/prepare-build-inputs/extensions.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/extensions.md similarity index 86% rename from content/docs/for-platform-operators/how-to/prepare-build-inputs/extensions.md rename to content/docs/for-platform-operators/how-to/build-inputs/create-builder/extensions.md index a7b6238ed..cae54bdcd 100644 --- a/content/docs/for-platform-operators/how-to/prepare-build-inputs/extensions.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/extensions.md @@ -3,6 +3,8 @@ title="Specify an image extension in a builder" weight=101 +++ +If you are using extensions, here is how to include them in a builder. + You're pretty sharp, and you know what your buildpack users will need. diff --git a/content/docs/for-platform-operators/how-to/prepare-build-inputs/run-base.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base.md similarity index 94% rename from content/docs/for-platform-operators/how-to/prepare-build-inputs/run-base.md rename to content/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base.md index 5c55221c7..3322fabad 100644 --- a/content/docs/for-platform-operators/how-to/prepare-build-inputs/run-base.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base.md @@ -1,8 +1,10 @@ +++ title="Create a run base image" -weight=3 +weight=2 +++ +The runtime base image provides the OS-level dependencies for applications at runtime. + ## Define a run base image for your CNB build diff --git a/content/docs/for-platform-operators/how-to/declare-source-metadata.md b/content/docs/for-platform-operators/how-to/build-inputs/declare-source-metadata.md similarity index 93% rename from content/docs/for-platform-operators/how-to/declare-source-metadata.md rename to content/docs/for-platform-operators/how-to/build-inputs/declare-source-metadata.md index 26d8e6e28..a8568786a 100644 --- a/content/docs/for-platform-operators/how-to/declare-source-metadata.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/declare-source-metadata.md @@ -1,13 +1,14 @@ +++ title="Declare source metadata" weight=3 -summary="Conventions for declaring information about application source code, to be included in the application image." +summary="Declare information about application source code, to be included as metadata in the application image." tags=["spec:platform/0.6", "spec:project-descriptor/0.2"] +++ ## Summary -The following are conventions for declaring different type of source inputs. This information is provided to the [lifecycle][lifecycle] using [project-metadata.toml][project-metadata]. +The following are conventions for declaring different type of source inputs. +This information is provided to the [lifecycle][lifecycle] using [project-metadata.toml][project-metadata]. ## Sources diff --git a/content/docs/for-platform-operators/how-to/prepare-build-inputs/stack.md b/content/docs/for-platform-operators/how-to/build-inputs/stack.md similarity index 92% rename from content/docs/for-platform-operators/how-to/prepare-build-inputs/stack.md rename to content/docs/for-platform-operators/how-to/build-inputs/stack.md index 2d41fe9be..7a3c42ce0 100644 --- a/content/docs/for-platform-operators/how-to/prepare-build-inputs/stack.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/stack.md @@ -1,16 +1,17 @@ +++ -title="Create a stack" -weight=4 +title="Create a stack (deprecated)" +weight=99 +++ +A stack is the grouping together of the build and run base images, represented by a unique ID. + **Note**: As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture. You can still configure the build and run base images for your CNB build. -To find out how, see [create a build base image](/docs/for-platform-operators/how-to/prepare-build-inputs/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/prepare-build-inputs/run-base/). +To find out how, see [create a build base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base/). -A stack is the grouping together of the build and run base images, represented by a unique ID. A stack ID identifies the configuration for the build and run base images, and it used to determined compatibility with available buildpacks, and rebasability when updated run images are available. If you're on an older Platform API version, you may still need to create a custom stack. To find out how, read on... @@ -26,7 +27,7 @@ Before we get started, make sure you've got the following installed: ## Creating a custom stack We will create a sample stack based on `Ubuntu Jammy Jellyfish`. To create a custom stack, we need to create customized build and run images. -To find out how, see [create a build base image](/docs/for-platform-operators/how-to/prepare-build-inputs/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/prepare-build-inputs/run-base/), then come back here. +To find out how, see [create a build base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base/), then come back here. ## Choose your stack ID diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/circleci.md b/content/docs/for-platform-operators/how-to/integrate-ci/circleci.md index 7f1c423e3..b3e176dad 100644 --- a/content/docs/for-platform-operators/how-to/integrate-ci/circleci.md +++ b/content/docs/for-platform-operators/how-to/integrate-ci/circleci.md @@ -3,7 +3,9 @@ title="CircleCI" weight=3 +++ -[CircleCI][circleci] is a continuous integration and delivery platform. The CNB project maintains an integration, called an [orb](https://circleci.com/orbs/), +[CircleCI][circleci] is a continuous integration and delivery platform. + +The CNB project maintains an integration, called an [orb](https://circleci.com/orbs/), which allows users to run [pack][pack] commands inside their pipelines. diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/gitlab.md b/content/docs/for-platform-operators/how-to/integrate-ci/gitlab.md index bf9e5eac6..870add3d4 100644 --- a/content/docs/for-platform-operators/how-to/integrate-ci/gitlab.md +++ b/content/docs/for-platform-operators/how-to/integrate-ci/gitlab.md @@ -3,8 +3,9 @@ title="Gitlab Auto DevOps" weight=4 +++ -[Gitlab][about-gitlab] is a web based DevOps platform. It uses [`pack`][pack] as part of the [Auto DevOps][devops] feature, to -build applications prior to deploying them. +[Gitlab][about-gitlab] is a web-based DevOps platform. The [Auto DevOps][devops] feature uses [`pack`][pack] +to build applications prior to deploying them. + ## Use diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/kpack.md b/content/docs/for-platform-operators/how-to/integrate-ci/kpack.md index d9a7f2b29..b7edbc01d 100644 --- a/content/docs/for-platform-operators/how-to/integrate-ci/kpack.md +++ b/content/docs/for-platform-operators/how-to/integrate-ci/kpack.md @@ -3,7 +3,10 @@ title="kpack" weight=2 +++ -[kpack][kpack] is a Kubernetes native platform, belonging to the [Buildpacks Community](https://github.com/buildpacks-community) organization. It utilizes unprivileged Kubernetes primitives to provide builds of OCI images as a platform implementation of Cloud Native Buildpacks (CNB). +[kpack][kpack] is a Kubernetes-native platform that uses unprivileged Kubernetes primitives to perform buildpacks builds and keep application images up-to-date. + +[kpack][kpack] is part of the [Buildpacks Community](https://github.com/buildpacks-community) organization. + ## Use diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/pack/_index.md b/content/docs/for-platform-operators/how-to/integrate-ci/pack/_index.md index d943e03d6..67d077c6d 100644 --- a/content/docs/for-platform-operators/how-to/integrate-ci/pack/_index.md +++ b/content/docs/for-platform-operators/how-to/integrate-ci/pack/_index.md @@ -6,7 +6,8 @@ aliases=["/docs/install-pack/", "/docs/tools/pack/cli/install/"] weight=1 +++ -Pack is a tool maintained by the Cloud Native Buildpacks project to support the use of buildpacks. +Pack is a CLI tool maintained by the CNB project to support the use of buildpacks. + It enables the following functionality: diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/piper.md b/content/docs/for-platform-operators/how-to/integrate-ci/piper.md index e72a6728b..461c0ec45 100644 --- a/content/docs/for-platform-operators/how-to/integrate-ci/piper.md +++ b/content/docs/for-platform-operators/how-to/integrate-ci/piper.md @@ -3,7 +3,10 @@ title='Project "Piper"' weight=5 +++ -[Project "Piper"][piper] (maintained by [SAP][sap]) is a set of ready-made Continuous Delivery pipelines for direct use in your project. It now also implements the CNB Platform spec as a step and makes it available in your Jenkins pipeline. +[Project "Piper"][piper] is a set of ready-made continuous delivery pipelines for direct use in your project. +It now also implements the CNB Platform spec as a step and makes it available in your Jenkins pipeline. + +[Project "Piper"][piper] is maintained by [SAP][sap]. diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/tekton.md b/content/docs/for-platform-operators/how-to/integrate-ci/tekton.md index 6096156fd..5cd1867b8 100644 --- a/content/docs/for-platform-operators/how-to/integrate-ci/tekton.md +++ b/content/docs/for-platform-operators/how-to/integrate-ci/tekton.md @@ -3,8 +3,10 @@ title="Tekton" weight=6 +++ -[Tekton][tekton] is an open-source CI/CD system platform implementation running on k8s. There are two Tekton `tasks` -maintained by the CNB project, both of which use the [lifecycle][lifecycle] directly (i.e. they do not use `pack`). +[Tekton][tekton] is an open-source CI/CD system running on k8s. + +The CNB project has created two reference "tasks" for performing buildpacks builds, +both of which use the [lifecycle][lifecycle] directly (i.e. they do not use `pack`). diff --git a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md index 4d2e2e74b..90f0f1148 100644 --- a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md +++ b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md @@ -4,3 +4,5 @@ weight=1 expand=true include_summaries=true +++ + +Coming soon! In the meantime check out this excellent [blog post](https://medium.com/buildpacks/unpacking-cloud-native-buildpacks-ff51b5a767bf) from our community.