Skip to content

Commit

Permalink
Update README and docs
Browse files Browse the repository at this point in the history 
Update README to include embedded Build example as the main example.

Fix markdown linter warnings.

Add new invalid BuildRun option in docs.
  • Loading branch information
@HeavyWombat
HeavyWombat committed Mar 22, 2022
1 parent 762592e commit 7d1cf1d
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 55 deletions.
74 changes: 26 additions & 48 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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://github.com/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://github.com/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>
Expand All @@ -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://github.com/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://github.com/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
Expand All @@ -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!
Expand Down Expand Up @@ -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://github.com/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://github.com/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://github.com/shipwright-io/build/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
Expand Down
40 changes: 33 additions & 7 deletions docs/buildrun.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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://github.com/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.
Expand Down Expand Up @@ -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_) |
Expand All @@ -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://github.com/tektoncd/pipeline/blob/main/docs/taskruns.md#monitoring-execution-status) for populating the BuildRun ones, with some exceptions.
Expand Down

0 comments on commit 7d1cf1d

Please sign in to comment.