diff --git a/config.toml b/config.toml
index 0b432d95..141260d8 100644
--- a/config.toml
+++ b/config.toml
@@ -3,7 +3,7 @@ title = "Shipwright"
enableRobotsTXT = true
-# Hugo allows theme composition (and inheritance). The precedence is from left to right.
+# Hugo enables theme composition (and inheritance). The precedence is from left to right.
theme = ["docsy"]
# Will give values to .Lastmod etc.
@@ -82,13 +82,13 @@ copyright = "The Shipwright Contributors"
# This menu appears only if you have at least one [params.versions] set.
version_menu = "Releases"
-# Flag used in the "version-banner" partial to decide whether to display a
+# Flag used in the "version-banner" partial to decide whether to display a
# banner on every page indicating that this is an archived version of the docs.
# Set this flag to "true" if you want to display the banner.
archived_version = false
# The version number for the version of the docs represented in this doc set.
-# Used in the "version-banner" partial to display a version number for the
+# Used in the "version-banner" partial to display a version number for the
# current doc set.
version = "0.0"
@@ -132,12 +132,12 @@ footer_about_disable = false
# add "hide_feedback: true" to the page's front matter.
[params.ui.feedback]
enable = true
-# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
+# The responses that the reader sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
yes = 'Glad to hear it! Please tell us how we can improve.'
no = 'Sorry to hear that. Please tell us how we can improve.'
# Adds a reading time to the top of each doc.
-# If you want this feature, but occasionally need to remove the Reading time from a single page,
+# If you want this feature, but occasionally need to remove the Reading time from a single page,
# add "hide_readingtime: true" to the page's front matter
[params.ui.readingtime]
enable = false
diff --git a/content/en/blog/posts/2020-11-30-intro-shipwright-pt2.md b/content/en/blog/posts/2020-11-30-intro-shipwright-pt2.md
index be338f92..d0d833bb 100644
--- a/content/en/blog/posts/2020-11-30-intro-shipwright-pt2.md
+++ b/content/en/blog/posts/2020-11-30-intro-shipwright-pt2.md
@@ -17,25 +17,25 @@ build container images on Kubernetes.
## Recap - From Binaries to Images
-Recall in [Part 1](/blog/2020/10/21/introducing-shipwright-part-1/), developers who moved from
+Recall in [Part 1](/blog/2020/10/21/introducing-shipwright-part-1/), developers who moved from
VM-based deployments to [Kubernetes](https://kubernetes.io/) needed to shift their unit of delivery
from binaries to container images. Teams adopted various tools to accomplish this task, ranging
from [Docker/Moby](https://mobyproject.org/) to [Cloud-Native Buildpacks](https://buildpacks.io/).
New cloud-native applications like [Jenkins-X](https://jenkins-x.io/) and
[Tekton](https://tekton.dev/) have emerged to deliver these container images on Kubernetes.
-[Jenkins](https://www.jenkins.io/) - the predecessor to Jenkins-X - has continued to play a
+[Jenkins](https://www.jenkins.io/) - the predecessor to Jenkins-X - has continued to play a
prominent role in automating the building and testing of applications.
Building a container image on Kubernetes is not a simple feat. There are a wide variety of tools
available, some which require knowledge on how to write a Dockerfile, others which do not or are
-tailored for specific programming languages. For CI/CD platforms like Tekton, setting up a build
+tailored for specific programming languages. For CI/CD platforms like Tekton, setting up a build
pipeline requires extensive configuration and customization. These are burdens that are difficult
to overcome for many development teams.
## Shipwright Builds - A Framework for Building Images
With Shipwright, we want to create an open and flexible framework that allows teams to easily build
-container images on Kubernetes. Much of the work has been inspired by OpenShift/okd, which provides
+container images on Kubernetes. Much of the work has been inspired by OpenShift/okd, which provides
its own API for building images. At the heart of every build are the following core components:
1. Source code - the "what" you are trying to build
@@ -62,18 +62,18 @@ Developers who use docker are familiar with this process:
The Build API consists of four core Custom Resource Definitions (CRDs):
-1. `BuildStrategy` and `ClusterBuildStrategy` - defines how to build an application for an image
+1. `BuildStrategy` and `ClusterBuildStrategy` - defines how to build an application for an image
building tool.
2. `Build` - defines what to build, and where the application should be delivered.
3. `BuildRun` - invokes the build, telling the Kubernetes cluster when to build your application.
### BuildStrategy and ClusterBuildStrategy
-`BuildStrategy` and `ClusterBuildStrategy` are related APIs to define how a given tool should be
+`BuildStrategy` and `ClusterBuildStrategy` are related APIs to define how a given tool should be
used to assemble an application. They are distinguished by their scope - `BuildStrategy` objects
are namespace scoped, whereas `ClusterBuildStrategy` objects are cluster scoped.
-The spec consists of a `buildSteps` object, which look and feel like Kubernetes `Container`
+The spec consists of a `buildSteps` object, which look and feel like Kubernetes `Container`
specifications. Below is an example spec for Kaniko, which can build an image from a
Dockerfile within a container:
@@ -142,7 +142,7 @@ is possible.
### BuildRun
-Each `BuildRun` object invokes a build on your cluster. You can think of these as a Kubernetes
+Each `BuildRun` object invokes a build on your cluster. You can think of these as a Kubernetes
`Jobs` or Tekton `TaskRuns` - they represent a workload on your cluster, ultimately resulting in a
running `Pod`.
@@ -169,9 +169,9 @@ step:
1. `/tekton/home`
2. `/workspace`
-Where do these directories come from? Shipwright is built on top of [Tekton](https://tekton.dev/),
-taking advantage of its features to simpify CI/CD workloads. Among the things that Tekton provides
-is a Linux user `$HOME` directory (`/tekton/home`) and a workspace where the application can be
+Where do these directories come from? Shipwright is built on top of [Tekton](https://tekton.dev/),
+taking advantage of its features to simpify CI/CD workloads. Among the things that Tekton provides
+is a Linux user `$HOME` directory (`/tekton/home`) and a workspace where the application can be
assembled (`/workspace`).
## Try it!
@@ -185,6 +185,6 @@ If your cluster has [Operator Lifecycle Manager](https://olm.operatorframework.i
option 2 is the recommened approach. OLM will take care of installing Tekton as well as Shipwright.
The samples contain build strategies for container-based image build tools like
-[Kaniko](https://github.com/GoogleContainerTools/kaniko), [Buildah](https://buildah.io/),
-[Source-to-Image](https://github.com/openshift/source-to-image) and
+[Kaniko](https://github.com/GoogleContainerTools/kaniko), [Buildah](https://buildah.io/),
+[Source-to-Image](https://github.com/openshift/source-to-image) and
[Cloud-Native Buildpacks](https://buildpacks.io/).
diff --git a/content/en/docs/api/build.md b/content/en/docs/api/build.md
index 7ba758a4..12772393 100644
--- a/content/en/docs/api/build.md
+++ b/content/en/docs/api/build.md
@@ -16,7 +16,7 @@ weight: 10
## Overview
-A `Build` resource allows the user to define:
+A `Build` resource enables the user to define:
- source
- sources
@@ -41,19 +41,19 @@ When the controller reconciles it:
## Build Validations
-In order to prevent users from triggering `BuildRuns` (_execution of a Build_) that will eventually fail because of wrong or missing dependencies or configuration settings, the Build controller will validate them in advance. If all validations are successful, users can expect a `Succeeded` `Status.Reason`, however if any of the validations failed, users can rely on the `Status.Reason` and `Status.Message` fields, in order to understand the root cause.
+To prevent users from triggering `BuildRuns` (_execution of a Build_) that will eventually fail because of wrong or missing dependencies or configuration settings, the Build controller will validate them in advance. If all validations are successful, users can expect a `Succeeded` `Status.Reason`. However, if any validations fail, users can rely on the `Status.Reason` and `Status.Message` fields to understand the root cause.
| Status.Reason | Description |
| --- | --- |
| BuildStrategyNotFound | The referenced namespace-scope strategy doesn't exist. |
| ClusterBuildStrategyNotFound | The referenced cluster-scope strategy doesn't exist. |
-| SetOwnerReferenceFailed | Setting ownerreferences between a Build and a BuildRun failed. This is triggered when making use of the `build.shipwright.io/build-run-deletion` annotation in a Build. |
+| SetOwnerReferenceFailed | Setting ownerreferences between a Build and a BuildRun failed. This message is triggered when making use of the `build.shipwright.io/build-run-deletion` annotation in a Build. |
| SpecSourceSecretRefNotFound | The secret used to authenticate to git doesn't exist. |
| SpecOutputSecretRefNotFound | The secret used to authenticate to the container registry doesn't exist. |
| SpecBuilderSecretRefNotFound | The secret used to authenticate to the container registry doesn't exist.|
| MultipleSecretRefNotFound | More than one secret is missing. At the moment, only three paths on a Build can specify a secret. |
-| RuntimePathsCanNotBeEmpty | The Runtime feature is used, but the runtime path was not defined. This is mandatory. |
-| RemoteRepositoryUnreachable | The defined `spec.source.url` was not found. This validation only take place for http/https protocols. |
+| RuntimePathsCanNotBeEmpty | The Runtime feature is used, but the runtime path was not defined. This path is mandatory. |
+| RemoteRepositoryUnreachable | The defined `spec.source.url` was not found. This validation only takes place for HTTP/HTTPS protocols. |
## Configuring a Build
@@ -72,8 +72,8 @@ The `Build` definition supports the following fields:
- Optional:
- `spec.parameters` - Refers to a list of `name-value` that could be used to loosely type parameters in the `BuildStrategy`.
- `spec.dockerfile` - Path to a Dockerfile to be used for building an image. (_Use this path for strategies that require a Dockerfile_)
- - `spec.sources` - [Sources](#Sources) describes a slice of artifacts that will be imported into project context, before the actual build process starts.
- - `spec.runtime` - Runtime-Image settings, to be used for a multi-stage build. ⚠️ Deprecated
+ - `spec.sources` - [Sources](#Sources) describes a slice of artifacts to import into project context before the actual build process starts.
+ - `spec.runtime` - Runtime-Image settings to use for a multi-stage build. ⚠️ Deprecated
- `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example `5m`. The default is ten minutes. The value can be overwritten in the `BuildRun`.
- `metadata.annotations[build.shipwright.io/build-run-deletion]` - Defines if delete all related BuildRuns when deleting the Build. The default is `false`.
@@ -81,13 +81,13 @@ The `Build` definition supports the following fields:
A `Build` resource can specify a Git source, together with other parameters like:
-- `source.credentials.name` - For private repositories, the name is a reference to an existing secret on the same namespace containing the `ssh` data.
-- `source.revision` - An specific revision to select from the source repository, this can be a commit or branch name. If not defined, it will fallback to the git repository default branch.
-- `source.contextDir` - For repositories where the source code is not located at the root folder, you can specify this path here. Currently, only supported by `buildah`, `kaniko` and `buildpacks` build strategies.
+- `source.credentials.name` - For private repositories, the name refers to an existing secret on the same namespace containing the `ssh` data.
+- `source.revision` - An specific revision to select from the source repository; this can be a commit or branch name. If not defined, it will fall back to the git repository default branch.
+- `source.contextDir` - For repositories where the source code is not located at the root folder, you can specify this path here. Currently, only supported by `buildah`, `kaniko`, and `buildpacks` build strategies.
By default, the Build controller won't validate that the Git repository exists. If the validation is desired, users can define the `build.shipwright.io/verify.repository` annotation with `true` explicitly. For example:
-Example of a `Build` with the **build.shipwright.io/verify.repository** annotation, in order to enable the `spec.source.url` validation.
+Example of a `Build` with the **build.shipwright.io/verify.repository** annotation to enable the `spec.source.url` validation.
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -102,9 +102,11 @@ spec:
contextDir: docker-build
```
-_Note_: The Build controller only validates two scenarios. The first one where the endpoint uses an `http/https` protocol, the second one when a `ssh` protocol (_e.g. `git@`_) is defined and none referenced secret was provided(_e.g. source.credentials.name_).
+_Note_: The Build controller validates only two scenarios:
+- When the endpoint uses an `http/https` protocol.
+- When the `ssh` protocol (_e.g., `git@`_) is defined but no referenced secret was provided(_e.g., source.credentials.name_).
-Example of a `Build` with a source with **credentials** defined by the user.
+The following example shows a `Build` where you use `credentials` to define a source:
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -118,7 +120,7 @@ spec:
name: source-repository-credentials
```
-Example of a `Build` with a source that specifies an specific subfolder on the repository.
+Example of a `Build` with a source that specifies a subfolder on the repository.
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -131,7 +133,7 @@ spec:
contextDir: renamed
```
-Example of a `Build` that specifies an specific branch on the git repository:
+Example of a `Build` that specifies a branch on the git repository:
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -155,7 +157,7 @@ A `Build` resource can specify the `BuildStrategy` to use, these are:
- [ko](buildstrategies.md#ko)
- [Source-to-Image](buildstrategies.md#source-to-image)
-Defining the strategy is straightforward, you need to define the `name` and the `kind`. For example:
+Defining the strategy is straightforward; you need to define the `name` and the `kind`. For example:
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -170,7 +172,9 @@ spec:
### Defining the Builder or Dockerfile
-A `Build` resource can specify an image containing the tools to build the final image. Users can do this via the `spec.builder` or the `spec.dockerfile`. For example, the user choose the `Dockerfile` file under the source repository.
+To define the image that contains the tools that build the final image, you specify the value of `spec.dockerfile` or `spec.builder` in a `Build` resource.
+
+In the following example, the `Build` resource sets the value of `spec.dockerfile` to `Dockerfile` under the source repository:
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -187,7 +191,7 @@ spec:
dockerfile: Dockerfile
```
-Another example, when the user chooses to use a `builder` image ( This is required for `source-to-image` buildStrategy, because for different code languages, they have different builders. ):
+Or, for example, the following `Build` resource employs the source-to-image (S2I) build strategy. It does this by setting the value of `spec.builder.image` to an image that can build the source code.
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -207,9 +211,9 @@ spec:
### Defining the Output
-A `Build` resource can specify the output where the image should be pushed. For external private registries it is recommended to specify a secret with the related data to access it.
+A `Build` resource can specify the output where the image should be pushed. For external private registries, it is recommended to specify a secret with the related data to access it.
-For example, the user specify a public registry:
+For example, the user specifies a public registry:
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -229,7 +233,7 @@ spec:
image: image-registry.openshift-image-registry.svc:5000/build-examples/nodejs-ex
```
-Another example, is when the user specifies a private registry:
+Another example is when the user specifies a private registry:
```yaml
apiVersion: shipwright.io/v1alpha1
@@ -282,9 +286,9 @@ At this initial stage, authentication is not supported therefore you can only do
**⚠️ Deprecated:** This feature is deprecated and will be removed in a future release.
See https://github.com/shipwright-io/community/blob/main/ships/deprecate-runtime.md for more information.
-Runtime-image is a new image composed with build-strategy outcome. On which you can compose a multi-stage image build, copying parts out the original image into a new one. This feature allows replacing the base-image of any container-image, creating leaner images, and other use-cases.
+A runtime-image is a new image composed with build-strategy outcome. On which you can compose a multi-stage image build, copying parts from the original image into a new one. This feature enables replacing the base image of any container image, creating leaner images, and other use-cases.
-The following examples illustrates how to the `runtime`:
+The following examples illustrate how to the `runtime`:
```yml
apiVersion: shipwright.io/v1alpha1
@@ -315,7 +319,7 @@ spec:
- start
```
-This build will produce a Node.js based application where a single directory is imported from the image built by buildpacks strategy. The data copied is using the `.spec.runtime.user` directive, and the image also runs based on it.
+This build will produce a Node.js-based application where a single directory is imported from the image built by buildpacks strategy. The data copied uses the `.spec.runtime.user` directive, and the image also runs based on it.
Please consider the description of the attributes under `.spec.runtime`:
@@ -326,19 +330,19 @@ Please consider the description of the attributes under `.spec.runtime`:
- `.run`: arbitrary commands to be executed as `RUN` blocks, before `COPY`
- `.user.name`: username employed on `USER` directive, and also to change ownership of files copied to the runtime-image
- `.user.group`: group name (or GID), employed to change ownership and on `USER` directive
-- `.paths`: list of files or directory paths to be copied to runtime-image, those can be defined as `