Merge 755125cf84 into 85ca62d2ef

* Updated the tekton documentation to use the new buildpack task supporting the extension. #814

Signed-off-by: cmoulliard <cmoulliard@redhat.com>

* Add additional words to vale dictionary

Signed-off-by: cmoulliard <cmoulliard@redhat.com>

* Extend the documentation to have a chapter covering extension. Add new pipeline parameters

Signed-off-by: cmoulliard <cmoulliard@redhat.com>

* Review the scenario and tested it using ubi8 and jammy builder images

Signed-off-by: cmoulliard <cmoulliard@redhat.com>

* Fix some vale vocabularies

Signed-off-by: cmoulliard <cmoulliard@redhat.com>

* Remove the cache workspace as not used and documented part of task's documentation

Signed-off-by: cmoulliard <cmoulliard@redhat.com>

* Switch the builder image to use: cnbs/sample-builder

Signed-off-by: cmoulliard <cmoulliard@redhat.com>

---------

Signed-off-by: cmoulliard <cmoulliard@redhat.com>

.github/styles/config/vocabularies/Buildpacks/accept.txt

@@ -11,3 +11,9 @@ Rebasing
 SBOM(?s)
 semver
 Syft
+[Tt]ekton
+[Kk]ubernetes
+uid
+Minikube
+kubectl
+Quarkus

.github/workflows/main.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Install Dependencies
         run: sudo apt-get install make curl jq
       - name: Install pack
-        uses: buildpacks/github-actions/setup-pack@v5.8.8
+        uses: buildpacks/github-actions/setup-pack@v5.9.1
         with:
           pack-version: '0.36.0'
       - name: Test

content/docs/app-journey.md

@@ -1,6 +1,6 @@
 +++
 title="An App's Brief Journey from Source to Image"
-weight=2
+weight=3
 getting-started=true
 +++
 

content/docs/buildpack-basics.md

@@ -0,0 +1,97 @@
++++
+title="Basics of BuildPacks"
+weight=2
+getting-started=true
++++
+
+## Basic Concepts
+
+### What is a Buildpack?
+
+A `buildpack` is software that transforms application source code into
+executable files by analyzing the code and determining the best way to
+build it.
+
+![buildpacks](/images/what.svg)
+
+Buildpacks have many shapes and forms. For example, a 'Distribution BuildPack'
+is a pre-built and tested buildpack that is ready for distribution to
+application developers. A Distribution Buildpack includes a set of buildpacks
+that are packaged together and can be used to build applications in different
+environments. 
+
+'Paketo Buildpacks' is a distribution buildpack for building applications in
+Java, Go, Python, Ruby, etc. The buildpacks included in 'Paketo Buildpacks'
+work together to create application container images that can run on any
+platform that supports container images (e.g., Cloud Foundry, Docker,
+Kubernetes, etc.).
+
+### What is a Builder?
+
+A builder is an image that contains all the components necessary to
+execute a build (for example, an ordered combination of buildpacks, a build
+image and other files and configurations).
+
+![create-builder diagram](/images/create-builder.svg)
+
+### What is a Lifecycle?
+
+A lifecycle is a series of steps that are used to create and manage a
+buildpack. The cumulative `create` step can be used to `analyze`, `detect`,
+`restore`, `build`, and `export` buildpack execution. All of these steps are
+part of a lifecycle. You can also re-enter a lifecycle using `rebase` to push
+the latest changes to an existing buildpack.
+
+![lifecycle](/images/lifecycle.png)
+
+`launcher` is an independent step that can be used to launch the application
+at any time. 
+
+### How BuildPacks add Efficiency to Code Iterations
+
+#### Building with Containers:
+
+Here's a quick look at how much manual effort is needed when working with
+containers, especially when major changes to the application need to be
+re-built.
+
+![Working with Containers](/images/rebase-containers.png)
+
+#### Building with BuildPacks:
+
+With BuildPacks, a lot of the steps mentioned above are automated. However,
+the true power of BuildPack is evident when 'rebasing' a newer iteration of the
+application code. With a layered approach, only incremental changes are
+rebuilt, greatly improving the time and efficiency of the build process.
+
+![Working with BuildPacks](/images/rebase-buildpacks.png)
+
+### What is a Platform
+
+A platform coordinates builds by invoking the lifecycle binary together with
+the buildpacks and the application source code in order to produce an
+executable OCI image.
+
+A platform can be a:
+
+- A local CLI tool
+- A plugin for a continuous integration service
+- A cloud application platform
+
+## Who uses Buildpacks (Personas)
+
+### App Developers
+
+Regular Application developers that utilize Buildpacks in their app packaging
+workflows.
+
+### Platform Operators
+
+Platform Operators are organizations or service providers (e.g., kpack,
+Tekton, Fly.io, Digital Ocean, Google Cloud, Heroku, SalesForce, etc.) that
+incorporates Buildpacks within their products to make buildpack functionality
+available to their end-users (typically, application developers). 
+
+### Buildpack Authors
+
+Buildpacks' internal developers working on Buildpack features.

content/docs/for-buildpack-authors/tutorials/basic-buildpack/06_caching.md

@@ -84,7 +84,7 @@ Reusing layer 'examples/node-js:node-js'
 Now, let's implement the caching logic.  We need to record the version of the NodeJS runtime that is used in a build.  On subsequent builds, the caching logic will detect if the NodeJS version is the same as the version in the cached layer.  We restore the previous layer from the cache if the current requested NodeJS version matches the previous NodeJS runtime version.
 
 <!-- test:file=node-js-buildpack/bin/build -->
-```
+```bash
 #!/usr/bin/env bash
 set -eo pipefail
 

content/docs/for-platform-operators/how-to/integrate-ci/tekton.md

@@ -9,16 +9,14 @@ weight=6
 
 [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`).
+The CNB project has created a reference "task" for performing buildpacks builds with or without extensions (aka Dockerfile to be applied) top
+of the [lifecycle][lifecycle] tool (i.e. they do not use `pack`).
 
-<!--more-->
+The [Buildpacks Phases Task][buildpacks-phases] calls the individual [lifecycle][lifecycle] binaries (prepare, analyze, detect, restore, build or extender, export), to run each phase in a separate container. 
 
-They are:
+The uid and gid as defined part of the builder image will be used to build the image. 
 
-1. [buildpacks][buildpacks-task] `task` &rarr; This task, which we recommend using, calls the `creator` binary of the
-   [lifecycle][lifecycle] to construct, and optionally publish, a runnable image.
-2. [buildpacks-phases][buildpacks-phases] `task` &rarr; This task calls the individual [lifecycle][lifecycle] binaries, to run each phase in a separate container.
+The different parameters to customize the task are defined part of the task's documentation under the section `parameters`.
 
 ## Set Up
 
@@ -32,28 +30,22 @@ Before we get started, make sure you've got the following installed:
 
 ### 1. Install Tekton and Tekton Dashboard
 
-To start, set up `Tekton`, using the Tekton [documentation][tekton-setup].
+To start, set up a `Tekton` version `>= 1.0`, using the Tekton [documentation][tekton-setup].
 
 We also recommend using the `Tekton dashboard`. To install it, follow the steps in the [dashboard docs][tekton-dashboard-setup], and
 start the dashboard server.
 
+> NOTE: If you run Tekton on a Kind or Minikube Kubernetes cluster, be sure to set the `coschedule` flag to `disabled` within the `feature-flags` ConfigMap.
+
 ### 2. Install the Buildpacks Task
 
-Install the latest version of the buildpacks task (currently `0.6`), by running:
+Install the latest version of the buildpacks task (currently `0.3`), by running:
 
 ```shell
-kubectl apply -f https://raw.githubusercontent.com/tektoncd/catalog/master/task/buildpacks/0.6/buildpacks.yaml
+kubectl apply -f https://raw.githubusercontent.com/tektoncd/catalog/refs/heads/main/task/buildpacks-phases/0.3/buildpacks-phases.yaml
 ```
 
-### 3. Install git-clone Task
-
-For our `pipeline`, we will use the `git-clone` task to clone a repository. Install the latest version (currently `0.4`), by running:
-
-```shell
-kubectl apply -f https://raw.githubusercontent.com/tektoncd/catalog/master/task/git-clone/0.4/git-clone.yaml
-```
-
-### 4. Define and Apply Tekton Pipeline Resources
+### 3. Define and Apply Tekton Pipeline Resources
 
 In order to set up our pipeline, we will need to define a few things:
 
@@ -63,9 +55,9 @@ In order to set up our pipeline, we will need to define a few things:
 - PersistentVolumeClaim &rarr; A `PersistentVolumeClaim` (a general Kubernetes concept, generally shortened to PVC) is
   a request for storage by a user.
 
-#### 4.1 PVCs
+#### 4.1 Persistent Volume
 
-Create a file `resources.yml` that defines a `PersistentVolumeClaim`:
+Create a file `resources.yml` that defines a `PersistentVolumeClaim` able to store the git cloned project and buildpacks files:
 
 ```yaml
 apiVersion: v1
@@ -83,12 +75,12 @@ spec:
 #### 4.2 Authorization
 
 > NOTE: You don't need to use authorization if you are pushing to a local registry. However, if you are pushing to a
-> remote registry (e.g. `DockerHub`, `GCR`), you need to add authorization
+> remote registry (e.g. `DockerHub`, `GCR`, `quay.io), you need to add authorization
 
 Create a `Secret` containing username and password that the build should use to authenticate to the container registry.
 
 ```shell
-kubectl create secret docker-registry docker-user-pass \
+kubectl create secret docker-registry registry-user-pass \
     --docker-username=<USERNAME> \
     --docker-password=<PASSWORD> \
     --docker-server=<LINK TO REGISTRY, e.g. https://index.docker.io/v1/ > \
@@ -103,57 +95,70 @@ kind: ServiceAccount
 metadata:
   name: buildpacks-service-account
 secrets:
-  - name: docker-user-pass
+  - name: registry-user-pass
 ```
+> NOTE: This service account will be used by Tekton in order to mount the credentials as docker config file part of the pod running buildpacks 
 
 #### 4.3 Pipeline
 
 Create a file `pipeline.yml` that defines the `Pipeline`, and relevant resources:
 
 ```yaml
-apiVersion: tekton.dev/v1beta1
+apiVersion: tekton.dev/v1
 kind: Pipeline
 metadata:
   name: buildpacks-test-pipeline
 spec:
   params:
+    - name: git-url
+      type: string
+      description: URL of the project to git clone
+    - name: source-subpath
+      type: string
+      description: The subpath within the git project
     - name: image
       type: string
       description: image URL to push
+    - name: builder
+      type: string
+      description: builder image URL
+    - name: env-vars
+      type: array
+      description: env vars to pass to the lifecycle binaries
   workspaces:
     - name: source-workspace # Directory where application source is located. (REQUIRED)
-    - name: cache-workspace # Directory where cache is stored (OPTIONAL)
   tasks:
     - name: fetch-repository # This task fetches a repository from github, using the `git-clone` task you installed
       taskRef:
-        name: git-clone
+        resolver: http
+        params:
+          - name: url
+            value: https://raw.githubusercontent.com/tektoncd/catalog/refs/heads/main/task/git-clone/0.9/git-clone.yaml
       workspaces:
         - name: output
           workspace: source-workspace
       params:
         - name: url
-          value: https://github.com/buildpacks/samples
-        - name: subdirectory
-          value: ""
+          value: "$(params.git-url)"
         - name: deleteExisting
           value: "true"
-    - name: buildpacks # This task uses the `buildpacks` task to build the application
+    - name: buildpacks # This task uses the `buildpacks phases` task to build the application
       taskRef:
-        name: buildpacks
+        name: buildpacks-phases
       runAfter:
         - fetch-repository
       workspaces:
         - name: source
           workspace: source-workspace
-        - name: cache
-          workspace: cache-workspace
       params:
         - name: APP_IMAGE
           value: "$(params.image)"
         - name: SOURCE_SUBPATH
-          value: "apps/java-maven" # This is the path within the samples repo you want to build (OPTIONAL, default: "")
-        - name: BUILDER_IMAGE
-          value: paketobuildpacks/builder:base # This is the builder we want the task to use (REQUIRED)
+          value: "$(params.source-subpath)"
+        - name: CNB_BUILDER_IMAGE
+          value: "$(params.builder)"
+        - name: CNB_ENV_VARS
+          value: "$(params.env-vars[*])"
     - name: display-results
       runAfter:
         - buildpacks
@@ -185,12 +190,13 @@ kubectl apply -f resources.yml -f sa.yml -f pipeline.yml
 Create a file `run.yml`, which defines the `PipelineRun`:
 
 ```yaml
-apiVersion: tekton.dev/v1beta1
+apiVersion: tekton.dev/v1
 kind: PipelineRun
 metadata:
   name: buildpacks-test-pipeline-run
 spec:
-  serviceAccountName: buildpacks-service-account # Only needed if you set up authorization
+  taskRunTemplate:
+    serviceAccountName: buildpacks-service-account # Only needed if you set up authorization
   pipelineRef:
     name: buildpacks-test-pipeline
   workspaces:
@@ -198,11 +204,16 @@ spec:
       subPath: source
       persistentVolumeClaim:
         claimName: buildpacks-source-pvc
-    - name: cache-workspace
-      subPath: cache
-      persistentVolumeClaim:
-        claimName: buildpacks-source-pvc
   params:
+    - # The url of the git project to clone (REQURED).
+      name: git-url
+      value: https://github.com/buildpacks/samples
+    - # This is the path within the git project you want to build (OPTIONAL, default: "")
+      name: source-subpath
+      value: "apps/java-maven"
+    - # This is the builder image we want the task to use (REQUIRED).
+      name: builder
+      value: cnbs/sample-builder:noble
     - name: image
       value: <REGISTRY/IMAGE NAME, eg gcr.io/test/image > # This defines the name of output image
 ```
@@ -225,27 +236,73 @@ kubectl describe pipelinerun buildpacks-test-pipeline-run
 
 or by using the Tekton Dashboard.
 
-Once the application is successfully built, you can pull it and run it by running:
+Once the application is successfully built, you can pull and run it by running:
 
 ```shell
-docker pull some-output-image
+docker | podman pull <REGISTRY/IMAGE NAME>
+docker | podman run -it <REGISTRY/IMAGE NAME>
 ```
 
-### 7. Cleanup (Optional)
+### 7. Using extension
+
+If your builder image supports the [extension][extension] mechanism able to customize the [build][extension-build] or the [run (aka execution)][extension-run], then you can replay this scenario by simply changing within the `PipelineRun` resource file the builder parameter
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  name: buildpacks-test-pipeline-run
+spec:
+  taskRunTemplate:
+    serviceAccountName: buildpacks-service-account
+  pipelineRef:
+    name: buildpacks-test-pipeline
+  workspaces:
+    - name: source-workspace
+      subPath: source
+      persistentVolumeClaim:
+        claimName: buildpacks-source-pvc
+  params:
+    - name: image
+      value: <REGISTRY/IMAGE NAME, eg gcr.io/test/image>
+    - name: git-url
+      value: https://github.com/quarkusio/quarkus-quickstarts
+    - name: source-subpath
+      value: "getting-started"  
+    - name: builder
+      value: paketobuildpacks/builder-ubi8-base:0.1.30
+    - name: env-vars
+      value:
+      - BP_JVM_VERSION=21
+```
+When the build process starts, then you should see, part of the extender step, if you build a Java runtime (Quarkus, Spring boot, etc) such log messages if the extension installs by example a different JDK
+```txt
+2025-06-27T11:32:25.067007701Z time="2025-06-27T11:32:25Z" level=info msg="Performing slow lookup of group ids for root"
+2025-06-27T11:32:25.067243910Z time="2025-06-27T11:32:25Z" level=info msg="Running: [/bin/sh -c echo ${build_id}]"
+2025-06-27T11:32:25.095150183Z 9e447871-e415-4018-a860-d5a66d925a57
+2025-06-27T11:32:25.096877516Z time="2025-06-27T11:32:25Z" level=info msg="Taking snapshot of full filesystem..."
+2025-06-27T11:32:25.280396774Z time="2025-06-27T11:32:25Z" level=info msg="Pushing layer oci:/kaniko/cache/layers/cached:a035cdb3949daa8f4e7b2c523ea0d73741c7c2d5b09981c261ebae99fd2f3233 to cache now"
+2025-06-27T11:32:25.280572023Z time="2025-06-27T11:32:25Z" level=info msg="RUN microdnf --setopt=install_weak_deps=0 --setopt=tsflags=nodocs install -y openssl-devel java-21-openjdk-devel nss_wrapper which && microdnf clean all"
+2025-06-27T11:32:25.280577315Z time="2025-06-27T11:32:25Z" level=info msg="Cmd: /bin/sh"
+2025-06-27T11:32:25.280578398Z time="2025-06-27T11:32:25Z" level=info msg="Args: [-c microdnf --setopt=install_weak_deps=0 --setopt=tsflags=nodocs install -y openssl-devel java-21-openjdk-devel nss_wrapper which && microdnf clean all]"
+...
+```
+
+### 8. Cleanup (Optional)
 
 To clean up, run:
 
 ```shell
-kubectl delete taskrun --all
-kubectl delete pvc --all
-kubectl delete pv --all
+kubectl delete -n default pipelinerun buildpacks-test-pipeline-run
+kubectl delete -n default pipeline buildpacks-test-pipeline
+kubectl delete -n default buildpacks-phases
+kubectl delete -n default pvc buildpacks-source-pvc
 ```
 
 ## References
 
-The Buildpacks tasks can be accessed at:
+The Buildpacks task can be accessed at:
 
-- [Buildpacks Task Source][buildpacks-task]
 - [Buildpacks Phases Task Source][buildpacks-phases]
 
 Some general resources for Tekton are:
@@ -262,6 +319,8 @@ Some general resources for Tekton are:
 [tekton-setup]: https://tekton.dev/docs/getting-started/
 [tekton-dashboard-setup]: https://tekton.dev/docs/dashboard/
 [tekton-concepts]: https://tekton.dev/docs/concepts/
-[git-clone-task]: https://github.com/tektoncd/catalog/tree/master/task/git-clone
 [kubectl-install]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
 [tekton-auth]: https://tekton.dev/docs/pipelines/auth/
+[extension]: https://buildpacks.io/docs/for-buildpack-authors/tutorials/basic-extension/02_why-dockerfiles/
+[extension-build]: https://buildpacks.io/docs/for-buildpack-authors/tutorials/basic-extension/04_build-dockerfile/
+[extension-run]: https://buildpacks.io/docs/for-buildpack-authors/tutorials/basic-extension/06_run-dockerfile-extend/

data/podman/setup.yml

@@ -75,7 +75,7 @@
 
         1. Add the SSH key for the podman VM to your keychain:
             ```shell=zsh
-            ssh-add -k "$HOME/.ssh/podman-machine-default"
+            ssh-add -k $(podman system connection list --format="{{.URI}} {{.Identity}}" | grep root |  cut -d' ' -f2)
             ```
         2. Change default connection to use `root`:
             ```shell=zsh