Update README and docs

Update README to include embedded Build example as the main example. Fix markdown linter warnings. Add new invalid BuildRun option in docs.
shipwright-io · Mar 22, 2022 · 1eaa049 · 1eaa049
1 parent 699958c
commit 1eaa049
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 55 deletions.
diff --git a/README.md b/README.md
@@ -32,27 +32,27 @@ Shipwright supports any tool that can build container images in Kubernetes clust
 
 ## Try It!
 
-* We assume you already have a Kubernetes cluster (v1.20+). If you don't, you can use [KinD](https://kind.sigs.k8s.io), which you can install by running [`./hack/install-kind.sh`](./hack/install-kind.sh).
+- We assume you already have a Kubernetes cluster (v1.20+). If you don't, you can use [KinD](https://kind.sigs.k8s.io), which you can install by running [`./hack/install-kind.sh`](./hack/install-kind.sh).
 
-* We also require a Tekton installation (v0.27+). To install the newest supported version, run:
+- We also require a Tekton installation (v0.27+). To install the newest supported version, run:
 
  ```bash
  kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.30.0/release.yaml
  ```
 
-* Install the Shipwright deployment. To install the latest version, run:
+- Install the Shipwright deployment. To install the latest version, run:
 
  ```bash
  kubectl apply --filename https:/shipwright-io/build/releases/download/v0.8.0/release.yaml
  ```
 
-* Install the Shipwright strategies. To install the latest version, run:
+- Install the Shipwright strategies. To install the latest version, run:
 
  ```bash
  kubectl apply --filename https:/shipwright-io/build/releases/download/v0.8.0/sample-strategies.yaml
  ```
 
-* Generate a secret to access your container registry, such as one on [Docker Hub](https://hub.docker.com/) or [Quay.io](https://quay.io/):
+- Generate a secret to access your container registry, such as one on [Docker Hub](https://hub.docker.com/) or [Quay.io](https://quay.io/):
 
  ```bash
  REGISTRY_SERVER=https://index.docker.io/v1/ REGISTRY_USER=<your_registry_user> REGISTRY_PASSWORD=<your_registry_password>
@@ -63,54 +63,32 @@ Shipwright supports any tool that can build container images in Kubernetes clust
  --docker-email=<your_email>
  ```
 
-* Create a *Build* object, replacing `<REGISTRY_ORG>` with the registry username your `push-secret` secret have access to:
+- Create and submit your *BuildRun* object, replacing `<REGISTRY_ORG>` with the registry username your `push-secret` secret have access to:
 
  ```bash
- REGISTRY_ORG=<your_registry_org>
- cat <<EOF | kubectl apply -f -
- apiVersion: shipwright.io/v1alpha1
- kind: Build
- metadata:
- name: buildpack-nodejs-build
- spec:
- source:
- url: https:/shipwright-io/sample-nodejs
- contextDir: source-build
- strategy:
- name: buildpacks-v3
- kind: ClusterBuildStrategy
- output:
- image: docker.io/${REGISTRY_ORG}/sample-nodejs:latest
- credentials:
- name: push-secret
- EOF
- ```
-
-To view the *Build* which you just created:
-
- ```
- $ kubectl get builds
- 
- NAME REGISTERED REASON BUILDSTRATEGYKIND BUILDSTRATEGYNAME CREATIONTIME
- buildpack-nodejs-build True Succeeded ClusterBuildStrategy buildpacks-v3 68s
- ``` 
-* Submit your *BuildRun*:
-
- ```bash
- cat <<EOF | kubectl create -f -
+ kubectl create --filename - <<EOF
  apiVersion: shipwright.io/v1alpha1
  kind: BuildRun
  metadata:
  generateName: buildpack-nodejs-buildrun-
  spec:
- buildRef:
- name: buildpack-nodejs-build
+ buildSpec:
+ source:
+ url: https:/shipwright-io/sample-nodejs
+ contextDir: source-build
+ strategy:
+ name: buildpacks-v3
+ kind: ClusterBuildStrategy
+ output:
+ image: docker.io/${REGISTRY_ORG}/sample-nodejs:latest
+ credentials:
+ name: push-secret
  EOF
  ```
 
-* Wait until your *BuildRun* is completed and then you can view it as follows:
+- Wait until your *BuildRun* is completed and then you can view it as follows:
 
- ```
+ ```bash
  $ kubectl get buildruns
  
  NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME
@@ -123,7 +101,7 @@ To view the *Build* which you just created:
  kubectl get buildrun --output name | xargs kubectl wait --for=condition=Succeeded --timeout=180s
  ```
 
-* After your *BuildRun* is completed, check your container registry, you will find the new generated image uploaded there.
+- After your *BuildRun* is completed, check your container registry, you will find the new generated image uploaded there.
 
 ## Please tell us more!
 
@@ -175,16 +153,16 @@ Our sample build strategies are all functional on linux/amd64. Their support on
 
 We host weekly meetings for users, contributors, maintainers and anyone interested in the project. The weekly meetings take place on Mondays at 1pm UTC.
 
-* Meeting [minutes](https:/shipwright-io/community/issues?q=is%3Aissue+label%3Acommunity+label%3Ameeting)
-* Public calendar [invite](https://calendar.google.com/calendar/u/1?cid=Y19iMWVndjc3anUyczJkbWNkM2R1ZnAxazhuNEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
+- Meeting [minutes](https:/shipwright-io/community/issues?q=is%3Aissue+label%3Acommunity+label%3Ameeting)
+- Public calendar [invite](https://calendar.google.com/calendar/u/1?cid=Y19iMWVndjc3anUyczJkbWNkM2R1ZnAxazhuNEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
 
 ### Want to contribute
 
 We are so excited to have you!
 
-* See [CONTRIBUTING.md](CONTRIBUTING.md) for an overview of our processes
-* See [DEVELOPMENT.md](DEVELOPMENT.md) for how to get started
-* See [HACK.md](HACK.md) for how to build, test & run
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for an overview of our processes
+- See [DEVELOPMENT.md](DEVELOPMENT.md) for how to get started
+- See [HACK.md](HACK.md) for how to build, test & run
  (advanced reading material)
 - Look at our
  [good first issues](https:/shipwright-io/build/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)

diff --git a/docs/buildrun.md b/docs/buildrun.md
@@ -81,6 +81,31 @@ spec:
  name: buildpack-nodejs-build-namespaced
 ```
 
+_Please note:_ The `BuildRef` and `BuildSpec` are mutually exclusive.
+
+### Defining the BuildSpec
+
+Alternatively to `BuildRef`, a complete `BuildSpec` can be embedded into the `BuildRun` to be used for the build.
+
+```yaml
+apiVersion: shipwright.io/v1alpha1
+kind: BuildRun
+metadata:
+ name: buildpack-nodejs-buildrun-namespaced
+spec:
+ buildSpec:
+ source:
+ url: https:/shipwright-io/sample-go.git
+ contextDir: source-build
+ strategy:
+ kind: ClusterBuildStrategy
+ name: buildpacks-v3
+ output:
+ image: foo/bar:latest
+```
+
+_Please note:_ The `BuildRef` and `BuildSpec` are mutually exclusive.
+
 ### Defining ParamValues
 
 A `BuildRun` resource can define _paramValues_ for parameters specified in the build strategy. If a value has been provided for a parameter with the same name in the `Build` already, then the value from the `BuildRun` will have precedence.
@@ -248,13 +273,13 @@ The `status.conditions` hosts different fields, like `status`, `reason` and `mes
 
 The following table illustrates the different states a BuildRun can have under its `status.conditions`:
 
-| Status | Reason | CompletionTime is set | Description |
-| --- | --- | --- | --- |
-| Unknown | Pending  | No | The BuildRun is waiting on a Pod in status Pending. |
-| Unknown | Running  | No | The BuildRun has been validate and started to perform its work. |l
-| Unknown | Running  | No | The BuildRun has been validate and started to perform its work. |
-| Unknown | BuildRunCanceled  | No | The user requested the BuildRun to be canceled. This results in the BuildRun controller requesting the TaskRun be canceled. Cancellation has not been done yet. |
-| True | Succeeded  | Yes | The BuildRun Pod is done. |
+| Status  | Reason  | CompletionTime is set | Description |
+| ---  | ---  | --- | --- |
+| Unknown  | Pending | No | The BuildRun is waiting on a Pod in status Pending. |
+| Unknown  | Running | No | The BuildRun has been validate and started to perform its work. |l
+| Unknown  | Running | No | The BuildRun has been validate and started to perform its work. |
+| Unknown  | BuildRunCanceled | No | The user requested the BuildRun to be canceled. This results in the BuildRun controller requesting the TaskRun be canceled. Cancellation has not been done yet. |
+| True  | Succeeded | Yes | The BuildRun Pod is done. |
 | False | Failed | Yes | The BuildRun failed in one of the steps. |
 | False | BuildRunTimeout | Yes | The BuildRun timed out. |
 | False | UnknownStrategyKind | Yes | The Build specified strategy Kind is unknown. (_options: ClusterBuildStrategy or BuildStrategy_) |
@@ -276,6 +301,7 @@ The following table illustrates the different states a BuildRun can have under i
 | False | BuildNotFound | Yes | The related Build in the BuildRun was not found. |
 | False | BuildRunCanceled | Yes | The BuildRun and underlying TaskRun were canceled successfully. |
 | False | BuildRunNameInvalid | Yes | The defined `BuildRun` name (`metadata.name`) is invalid. The `BuildRun` name should be a [valid label value](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). |
+| False | BuildRunInvalid | Yes | The defined `BuildRun` fields are invalid, i.e. a disallowed combination of fields is used. |
 | False | PodEvicted | Yes | The BuildRun Pod was evicted from the node it was running on. See [API-initiated Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/) and [Node-pressure Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/node-pressure-eviction/) for more information. |
 
 _Note_: We heavily rely on the Tekton TaskRun [Conditions](https:/tektoncd/pipeline/blob/main/docs/taskruns.md#monitoring-execution-status) for populating the BuildRun ones, with some exceptions.