From 9808d1e5878d6f6fef396d9978eade74a20bde5d Mon Sep 17 00:00:00 2001 From: Tyler Phelan Date: Thu, 7 Oct 2021 15:58:18 -0400 Subject: [PATCH] Disambiguate an image resource from a built OCI image --- README.md | 4 +-- docs/image.md | 32 +++++++++--------- docs/legacy-cnb-servicebindings.md | 14 ++++---- docs/logs.md | 2 -- docs/secrets.md | 4 +-- docs/stack.md | 4 +-- docs/store.md | 2 +- docs/tutorial.md | 53 +++++++++++++++--------------- 8 files changed, 57 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 727d3cea8..49b9e8a1b 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ kpack extends [Kubernetes](https://kubernetes.io/docs/concepts/extend-kubernetes kpack provides a declarative builder resource that configures a Cloud Native Buildpacks build configuration with the desired buildpack order and operating system stack. -kpack provides a declarative image resource that builds an image and schedules image rebuilds on source changes and from builder buildpack and builder stack updates. +kpack provides a declarative image resource that builds an OCI image and schedules rebuilds on source changes and from builder buildpack and builder stack updates. -kpack also provides a build type to execute a single Cloud Native Buildpack image build. +kpack also provides a build type to execute a single Cloud Native Buildpack OCI image build. ![kpack gif](docs/assets/node-min.gif) diff --git a/docs/image.md b/docs/image.md index 04cebf1da..c13831cd1 100644 --- a/docs/image.md +++ b/docs/image.md @@ -1,7 +1,7 @@ -# Images +# Image Resources -Images provide a configuration for kpack to build and maintain a docker image utilizing [Cloud Native Buildpacks](http://buildpacks.io). -kpack will monitor the inputs to the image configuration to rebuild the image when the underlying source or the builder's buildpacks or stacks have changed. +Image resources provide a configuration for kpack to build and maintain a docker image utilizing [Cloud Native Buildpacks](http://buildpacks.io). +kpack will monitor the inputs to the image resource to rebuild the OCI image when the underlying source or the builder's buildpacks or stacks have changed. Corresponding `kp` cli command docs [here](https://github.com/vmware-tanzu/kpack-cli/blob/main/docs/kp_image.md). @@ -69,7 +69,7 @@ The `builder` field describes the [builder resource](builders.md) that will buil - `name`: The name of the Builder resource in kubernetes. - `kind`: The type as defined in kubernetes. This will always be Builder. -> Note: This image can only reference builders defined in the same namespace. This is not true for ClusterBuilders because they are not namespace scoped. +> Note: This image resource can only reference builders defined in the same namespace. This is not true for ClusterBuilders because they are not namespace scoped. ### Source Configuration @@ -155,7 +155,7 @@ See the kubernetes documentation on [setting environment variables](https://kube ### Cosign Configuration #### Cosign Signing Secret -Images can be signed with cosign when a cosign formatted secret is added to the service account used to build the image. +OCI images built by kpack can be signed with cosign when a cosign formatted secret is added to the service account configured on the image resource. The secret can be added using the cosign CLI or manually. To create a cosign signing secret through the cosign CLI, when targetted to the Kubernetes cluster, use: @@ -165,11 +165,11 @@ Alternatively, create the cosign secret and provide your own cosign key files ma ```shell script % kubectl create secret generic --from-literal=cosign.password= --from-file= ``` -- ``: The name of the secret. Ensure that the secret is created in the same namespace as the eventual image config. +- ``: The name of the secret. Ensure that the secret is created in the same namespace as the eventual image resource. - ``: The password provided to encrypt the private key. If not present, an empty password will be used. - ``: The cosign private key file generated with `cosign generate-key-pair`. -After adding the cosign secret, the secret must be added to the list of `secrets` attached to the service account resource that is building the image. +After adding the cosign secret, the secret must be added to the list of `secrets` on the service account that the image is configured with. #### Adding Cosign Annotations By default, the build number and build timestamp information will be added to the cosign signing annotations. Users can specify additional cosign annotations under the spec key. @@ -203,7 +203,7 @@ Which provides a JSON response similar to: ``` #### Push Cosign Signature to a Different Location -Cosign signatures can be pushed to a different registry from where the image is located. To enable this, add the corresponding annotation to the cosign secret resource. +Cosign signatures can be pushed to a different registry from where the built OCI image is written to. To enable this, add the corresponding annotation to the cosign secret resource. ``` metadata: name: ... @@ -216,10 +216,12 @@ data: ``` This will be equivalent to setting `COSIGN_REPOSITORY` as specified in cosign [Specifying Registry](https://github.com/sigstore/cosign#specifying-registry) -The same service account that has that cosign secret attached, and would be used for signing and building the image, would require that the registry credentials for this other repository be placed under the listed `secrets` and is not required to be listed in `imagePullSecrets`. It should be noted that if you wish to push the signatures to the same registry but a different path from the image, the credential used must have access to both paths. You cannot use two separate credentials for the same registry with different paths. +The service account configured on the image resource must have registry credentials for the other registry configured in the `secrets` list (they do not need to be configured as `imagePullSecrets`). + +It should be noted that if you wish to push the signatures to the same registry but a different repository as the image resource `tag`, the credential used must have access to both paths. You cannot use two separate credentials for the same registry. #### Cosign Legacy Docker Media Types -To sign images in a registry that does not fully support OCI media types, legacy equivalents can be used by adding the corresponding annotation to the cosign secret resource: +To sign docker images in a registry that does not fully support OCI media types, legacy equivalents can be used by adding the corresponding annotation to the cosign secret resource: ``` metadata: name: ... @@ -232,7 +234,7 @@ data: ``` This will be equivalent to setting `COSIGN_DOCKER_MEDIA_TYPES=1` as specified in the cosign [registry-support](https://github.com/sigstore/cosign#registry-support) -### Sample Image with a Git Source +### Sample Image Resource with a Git Source ```yaml apiVersion: kpack.io/v1alpha2 @@ -277,7 +279,7 @@ Source for github can also be specified in the ssh format if there is a correspo revision: main ``` -### Sample Image with hosted zip or jar as a source +### Sample Image Resource with hosted zip or jar as a source ```yaml apiVersion: kpack.io/v1alpha2 @@ -314,9 +316,9 @@ spec: #### Status -When an image has successfully built with its current configuration, its status will report the up to date fully qualified built image reference. +When an image resource has successfully built with its current configuration, its status will report the up to date fully qualified built OCI image reference. -If you are using `kubectl` this information is available with `kubectl get ` or `kubectl describe `. +If you are using `kubectl` this information is available with `kubectl get ` or `kubectl describe `. ```yaml status: @@ -376,6 +378,6 @@ To create the notary secret used by kpack for image signing, run the following c ```shell script % kubectl create secret generic --from-literal=password= --from-file=$HOME/.docker/trust/private/.key ``` -- ``: The name of the secret. Ensure that the secret is created in the same namespace as the eventual image config. +- ``: The name of the secret. Ensure that the secret is created in the same namespace as the eventual image resource. - ``: The password provided to encrypt the private key. - `.key`: The private key file. diff --git a/docs/legacy-cnb-servicebindings.md b/docs/legacy-cnb-servicebindings.md index 898309b1a..5815e07ea 100644 --- a/docs/legacy-cnb-servicebindings.md +++ b/docs/legacy-cnb-servicebindings.md @@ -4,19 +4,19 @@ CNB service bindings have been deprecated in `kpack.io/v1alpha2`. They are still ## kpack.io/v1alpha1 CNB Service Bindings -kpack Images can be configured with Service Bindings as described in the [Cloud Native Buildpacks Bindings specification](https://github.com/buildpacks/spec/blob/adbc70f5672e474e984b77921c708e1475e163c1/extensions/bindings.md). +kpack image resources can be configured with Service Bindings as described in the [Cloud Native Buildpacks Bindings specification](https://github.com/buildpacks/spec/blob/adbc70f5672e474e984b77921c708e1475e163c1/extensions/bindings.md). -At build-time, service bindings are handled by the buildpacks being used for that Image. Check the desired buildpack documentation for details on the service bindings it supports. +At build-time, service bindings are handled by the buildpacks being used for that Build. Check the desired buildpack documentation for details on the service bindings it supports. -To configure an Image with a service binding, you must create the following: +To configure an image resource with a service binding, you must create the following: * A Secret containing the service binding data * The Secret `stringData` field must contain key-value pairs of `:`. For each key-value pair, a file will be created that is accessible during build. * A ConfigMap containing the metadata for the service binding - * The ConfigMap must have the fields `data.kind` and `data.provider` populated. The buildpacks used to build the image will handle the service bindings based on these fields. -* An Image referencing that Secret and ConfigMap in the `spec.build.bindings` field. + * The ConfigMap must have the fields `data.kind` and `data.provider` populated. The buildpacks used to build the OCI image will handle the service bindings based on these fields. +* An Image resource referencing that Secret and ConfigMap in the `spec.build.bindings` field. -### Sample maven app Image with a settings.xml service binding: +### Sample maven app Image resource with a settings.xml service binding: ```yaml apiVersion: kpack.io/v1alpha1 @@ -57,7 +57,7 @@ data: provider: sample ``` -The above example will result in the following files being available during Builds of the Image matching the [directory layout](https://github.com/buildpacks/spec/blob/adbc70f5672e474e984b77921c708e1475e163c1/extensions/bindings.md#example-directory-structure) of the CNB spec: +The above example will result in the following files being available during Builds matching the [directory layout](https://github.com/buildpacks/spec/blob/adbc70f5672e474e984b77921c708e1475e163c1/extensions/bindings.md#example-directory-structure) of the CNB spec: ```plain diff --git a/docs/logs.md b/docs/logs.md index 95e6b6a40..48c2b9dda 100644 --- a/docs/logs.md +++ b/docs/logs.md @@ -1,5 +1,3 @@ # kpack logs -Tailing the build logs is possible with the kpack log utility. - Logs can be read with the `kp build logs` command [here](https://github.com/vmware-tanzu/kpack-cli/blob/main/docs/kp_build_logs.md). diff --git a/docs/secrets.md b/docs/secrets.md index 6dee13c9d..04962e421 100644 --- a/docs/secrets.md +++ b/docs/secrets.md @@ -1,6 +1,6 @@ # Secrets -kpack utilizes kubernetes secrets to configure credentials to publish images to docker registries and access private github repositories. +kpack utilizes kubernetes secrets to configure credentials to publish OCI images to docker registries and access private github repositories. Corresponding `kp` cli command docs [here](https://github.com/vmware-tanzu/kpack-cli/blob/main/docs/kp_secret.md). @@ -112,7 +112,7 @@ stringData: ### Service Account -To use these secrets with kpack create a service account and reference the service account in image and build config. When configuring the image resource, reference the `name` of your registry credential and the `name` of your git credential. +To use these secrets with kpack create a service account and reference the service account in image and build resources. When configuring the image resource, reference the `name` of your registry credential and the `name` of your git credential. ```yaml apiVersion: v1 diff --git a/docs/stack.md b/docs/stack.md index 5ef2d804b..a50efed63 100644 --- a/docs/stack.md +++ b/docs/stack.md @@ -29,7 +29,7 @@ spec: ### Using a private registry -To use images from a private registry, you have to add a `serviceAccountRef` referencing a serviceaccount with the secrets needed to pull from this registry. +To use stack images from a private registry, you have to add a `serviceAccountRef` referencing a serviceaccount with the secrets needed to pull from this registry. ```yaml spec: @@ -42,7 +42,7 @@ spec: ### Updating a stack -The stack resource will not poll for updates. A CI/CD tool is needed to update the resource with new digests when new images are available. +The stack resource will not poll for updates. A CI/CD tool is needed to update the resource with new digests when new stack images are available. ### Suggested stacks diff --git a/docs/store.md b/docs/store.md index 3eec3da49..c1ca5c4bc 100644 --- a/docs/store.md +++ b/docs/store.md @@ -1,6 +1,6 @@ # Stores -A store resource is a repository of [buildpacks](http://buildpacks.io/) packaged in [buildpackages](https://buildpacks.io/docs/buildpack-author-guide/package-a-buildpack/) that can be used by kpack to build images. +A store resource is a repository of [buildpacks](http://buildpacks.io/) packaged in [buildpackages](https://buildpacks.io/docs/buildpack-author-guide/package-a-buildpack/) that can be used by kpack to build OCI images. The store will be referenced by a [builder](builders.md) resource. diff --git a/docs/tutorial.md b/docs/tutorial.md index 215e1ec8a..a88ef1e25 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -12,7 +12,7 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource > Get the kp cli from the [github release](https://github.com/vmware-tanzu/kpack-cli/releases) ### Tutorial -1. Create a secret with push credentials for the docker registry that you plan on publishing images to with kpack. +1. Create a secret with push credentials for the docker registry that you plan on publishing OCI images to with kpack. The easiest way to do that is with `kubectl secret create docker-registry` @@ -39,7 +39,7 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource > Note: Learn more about kpack secrets with the [kpack secret documentation](secrets.md) -1. Create a service account that references the registry secret created above +2. Create a service account that references the registry secret created above ```yaml apiVersion: v1 @@ -59,9 +59,9 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource kubectl apply -f service-account.yaml ``` -1. Create a cluster store configuration +3. Create a cluster store configuration - A store resource is a repository of [buildpacks](http://buildpacks.io/) packaged in [buildpackages](https://buildpacks.io/docs/buildpack-author-guide/package-a-buildpack/) that can be used by kpack to build images. Later in this tutorial you will reference this store in a Builder configuration. + A store resource is a repository of [buildpacks](http://buildpacks.io/) packaged in [buildpackages](https://buildpacks.io/docs/buildpack-author-guide/package-a-buildpack/) that can be used by kpack to build OCI images. Later in this tutorial you will reference this store in a Builder configuration. We recommend starting with buildpacks from the [paketo project](https://github.com/paketo-buildpacks). The example below pulls in java and nodejs buildpacks from the paketo project. @@ -84,7 +84,7 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource > Note: Buildpacks are packaged and distributed as buildpackages which are docker images available on a docker registry. Buildpackages for other languages are available from [paketo](https://github.com/paketo-buildpacks). -1. Create a cluster stack configuration +4. Create a cluster stack configuration A stack resource is the specification for a [cloud native buildpacks stack](https://buildpacks.io/docs/concepts/components/stack/) used during build and in the resulting app image. @@ -109,9 +109,9 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource kubectl apply -f stack.yaml ``` -1. Create a Builder configuration - - A Builder is the kpack configuration for a [builder image](https://buildpacks.io/docs/concepts/components/builder/) that includes the stack and buildpacks needed to build an image from your app source code. +5. Create a Builder configuration + + A Builder is the kpack configuration for a [builder image](https://buildpacks.io/docs/concepts/components/builder/) that includes the stack and buildpacks needed to build an OCI image from your app source code. The Builder configuration will write to the registry with the secret configured in step one and will reference the stack and store created in step three and four. The builder order will determine the order in which buildpacks are used in the builder. @@ -145,15 +145,15 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource kubectl apply -f builder.yaml ``` -1. Apply a kpack image configuration +6. Apply a kpack image resource - An image configuration is the specification for an image that kpack should build and manage. + An image resource is the specification for an OCI image that kpack should build and manage. - We will create a sample image that builds with the builder created in step five. + We will create a sample image resource that builds with the builder created in step five. The example included here utilizes the [Spring Pet Clinic sample app](https://github.com/spring-projects/spring-petclinic). We encourage you to substitute it with your own application. - Create an image configuration: + Create an image resource: ```yaml apiVersion: kpack.io/v1alpha2 @@ -177,18 +177,19 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource - If you are using your application source, replace `source.git.url` & `source.git.revision`. > Note: To use a private git repo follow the instructions in [secrets](secrets.md) - Apply that image to the cluster + Apply that image resource to the cluster + ```bash kubectl apply -f image.yaml ``` - You can now check the status of the image. + You can now check the status of the image resource. ```bash kubectl -n default get images ``` - You should see that the image has an unknown READY status as it currently building. + You should see that the image resource has an unknown READY status as it is currently building. ``` NAME LATESTIMAGE READY @@ -201,7 +202,7 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource kp build logs tutorial-image -n default ``` - Once the image finishes building you can get the fully resolved built image with `kubectl get` + Once the image resource finishes building you can get the fully resolved built OCI image with `kubectl get` ``` kubectl -n default get image tutorial-image @@ -213,11 +214,11 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource default tutorial-image index.docker.io/your-project/app@sha256:6744b... True ``` - The latest image is available to be used locally via `docker pull` and in a kubernetes deployment. + The latest OCI image is available to be used locally via `docker pull` and in a kubernetes deployment. -1. Run the built app locally +8. Run the built app locally - Download the latest image available in step #6 and run it with docker. + Download the latest OCI image available in step #6 and run it with docker. ```bash docker run -p 8080:8080 @@ -240,16 +241,16 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource :: Built with Spring Boot :: 2.2.2.RELEASE ``` -1. kpack rebuilds +9. kpack rebuilds - We recommend updating the kpack image configuration with a CI/CD tool when new commits are ready to be built. + We recommend updating the kpack image resource with a CI/CD tool when new commits are ready to be built. > Note: You can also provide a branch or tag as the `spec.git.revision` and kpack will poll and rebuild on updates! - We can simulate an update from a CI/CD tool by updating the `spec.git.revision` on the image configured in step #6. + We can simulate an update from a CI/CD tool by updating the `spec.git.revision` on the image resource used in step #6. If you are using your own application please push an updated commit and use the new commit sha. If you are using Spring Pet Clinic you can update the revision to: `4e1f87407d80cdb4a5a293de89d62034fdcbb847`. - Edit the image configuration with: + Edit the image resource with: ``` kubectl -n default edit image tutorial-image ``` @@ -274,8 +275,6 @@ This tutorial will walk through creating a kpack [builder](builder.md) resource > Note: This second build should be notably faster because the buildpacks are able to leverage the cache from the previous build. -1. Next steps +10. Next steps - The next time new buildpacks are added to the store, kpack will automatically rebuild the builder. If the updated buildpacks were used by the tutorial image, kpack will automatically create a new build to rebuild your image. - - + The next time new buildpacks are added to the store, kpack will automatically rebuild the builder. If the updated buildpacks were used by the tutorial image resource, kpack will automatically create a new build to rebuild your OCI image.