Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix broken links, tables and typos #1632

Merged
merged 1 commit into from
Jul 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,16 @@ Documentation inspired from https://github.com/tektoncd/pipeline/blob/ce7591acec

## Getting started

1. [Ramp up on kubernetes and CRDs](#ramp-up)
1. Create [a GitHub account](https://github.com/join)
1. Setup
1. [Ramp up on kubernetes and CRDs](#ramp-up)
2. Create [a GitHub account](https://github.com/join)
3. Setup
[GitHub access via SSH](https://help.github.com/articles/connecting-to-github-with-ssh/)
1. [Create and checkout a repo fork](#checkout-your-fork)
1. Install [requirements](#requirements)
1. [Set up a Kubernetes cluster](#create-a-cluster-and-a-repo)
1. Set up your [shell environment](#environment-setup)
1. [Configure kubectl to use your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
1. [Install Shipwright Build in your cluster](#install-shipwright-build)
4. [Create and checkout a repo fork](#checkout-your-fork)
5. Install [requirements](#requirements)
6. [Set up a Kubernetes cluster](#create-a-cluster-and-a-repo)
7. Set up your [shell environment](#environment-setup)
8. [Configure kubectl to use your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
9. [Install Shipwright Build in your cluster](#install-shipwright-build)

### Ramp up

Expand Down Expand Up @@ -58,9 +58,9 @@ The Go tools require that you clone the repository to the

To check out this repository:

1. Create your own
1. Create your own
[fork of this repo](https://help.github.com/articles/fork-a-repo/)
1. Clone it to your machine:
2. Clone it to your machine:

```shell
mkdir -p ${GOPATH}/src/github.com/shipwright-io
Expand All @@ -78,27 +78,27 @@ _Adding the `upstream` remote sets you up nicely for regularly

You must install these tools:

1. [`go`](https://golang.org/doc/install): The language Shipwright Build is
1. [`go`](https://golang.org/doc/install): The language Shipwright Build is
built in
1. [`git`](https://help.github.com/articles/set-up-git/): For source control
1 [`ko`](https://github.com/ko-build/ko): To build and deploy changes.
1. [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/): For
2. [`git`](https://help.github.com/articles/set-up-git/): For source control
3. [`ko`](https://github.com/ko-build/ko): To build and deploy changes.
4. [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/): For
interacting with your kube cluster

### Create a cluster and a repo

1. Follow the instructions in the Kubernetes doc to [Set up a kubernetes cluster](https://kubernetes.io/docs/setup/)
1. Set up a container image repository for pushing images. Any container image registry that is accessible to your cluster can be used for your repository. This can be a public registry like [Docker Hub](https://docs.docker.com/docker-hub/), [quay.io](https://quay.io), or a container registry runs by your cloud provider
2. Set up a container image repository for pushing images. Any container image registry that is accessible to your cluster can be used for your repository. This can be a public registry like [Docker Hub](https://docs.docker.com/docker-hub/), [quay.io](https://quay.io), or a container registry runs by your cloud provider

**Note**: We support Kubernetes version 1.27 to 1.29. 1 cluster worker node for basic usage, 2+ cluster worker nodes for HA

## Environment Setup

To run your controller, you'll need to set these environment variables (we recommend adding them to your `.bashrc`):

1. `GOPATH`: If you don't have one, simply pick a directory and add `export
1. `GOPATH`: If you don't have one, simply pick a directory and add `export
GOPATH=...`
1. `$GOPATH/bin` on `PATH`: This is so that tooling installed via `go get` will
2. `$GOPATH/bin` on `PATH`: This is so that tooling installed via `go get` will
work properly.

`.bashrc` example:
Expand Down Expand Up @@ -126,11 +126,11 @@ The following set of steps highlight how to deploy a Build controller pod into a
./hack/install-tekton.sh
```

1. Set your `KO_DOCKER_REPO` environment variable. This will be the container
2. Set your `KO_DOCKER_REPO` environment variable. This will be the container
image registry you push to, or `kind.local` if you're using
[KinD](https://kind.sigs.k8s.io).

1. Build and deploy the controller from source, from within the root of the repo:
3. Build and deploy the controller from source, from within the root of the repo:

```sh
ko apply -P -R -f deploy/
Expand Down
36 changes: 18 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,28 +166,28 @@ To find out more on what's the best strategy or what else can Shipwright do for

### Read the Docs

| Version | Docs | Examples |
| ------- | ------------------------------ | --------------------------- |
| HEAD | [Docs @ HEAD](docs/README.md) | [Examples @ HEAD](samples) |
| [v0.12.0](https://github.com/shipwright-io/build/releases/tag/v0.12.0) | [Docs @ v0.12.0](https://github.com/shipwright-io/build/tree/v0.12.0/docs) | [Examples @ v0.12.0](https://github.com/shipwright-io/build/tree/v0.12.0/samples) |
| [v0.11.0](https://github.com/shipwright-io/build/releases/tag/v0.11.0) | [Docs @ v0.11.0](https://github.com/shipwright-io/build/tree/v0.11.0/docs) | [Examples @ v0.11.0](https://github.com/shipwright-io/build/tree/v0.11.0/samples) |
| [v0.10.0](https://github.com/shipwright-io/build/releases/tag/v0.10.0) | [Docs @ v0.10.0](https://github.com/shipwright-io/build/tree/v0.10.0/docs) | [Examples @ v0.10.0](https://github.com/shipwright-io/build/tree/v0.10.0/samples) |
| [v0.9.0](https://github.com/shipwright-io/build/releases/tag/v0.9.0) | [Docs @ v0.9.0](https://github.com/shipwright-io/build/tree/v0.9.0/docs) | [Examples @ v0.9.0](https://github.com/shipwright-io/build/tree/v0.9.0/samples) |
| [v0.8.0](https://github.com/shipwright-io/build/releases/tag/v0.8.0) | [Docs @ v0.8.0](https://github.com/shipwright-io/build/tree/v0.8.0/docs) | [Examples @ v0.8.0](https://github.com/shipwright-io/build/tree/v0.8.0/samples) |
| [v0.7.0](https://github.com/shipwright-io/build/releases/tag/v0.7.0) | [Docs @ v0.7.0](https://github.com/shipwright-io/build/tree/v0.7.0/docs) | [Examples @ v0.7.0](https://github.com/shipwright-io/build/tree/v0.7.0/samples) |
| [v0.6.0](https://github.com/shipwright-io/build/releases/tag/v0.6.0) | [Docs @ v0.6.0](https://github.com/shipwright-io/build/tree/v0.6.0/docs) | [Examples @ v0.6.0](https://github.com/shipwright-io/build/tree/v0.6.0/samples) |
| [v0.5.1](https://github.com/shipwright-io/build/releases/tag/v0.5.1) | [Docs @ v0.5.1](https://github.com/shipwright-io/build/tree/v0.5.1/docs) | [Examples @ v0.5.1](https://github.com/shipwright-io/build/tree/v0.5.1/samples) |
| [v0.5.0](https://github.com/shipwright-io/build/releases/tag/v0.5.0) | [Docs @ v0.5.0](https://github.com/shipwright-io/build/tree/v0.5.0/docs) | [Examples @ v0.5.0](https://github.com/shipwright-io/build/tree/v0.5.0/samples) |
| [v0.4.0](https://github.com/shipwright-io/build/releases/tag/v0.4.0) | [Docs @ v0.4.0](https://github.com/shipwright-io/build/tree/v0.4.0/docs) | [Examples @ v0.4.0](https://github.com/shipwright-io/build/tree/v0.4.0/samples) |
| [v0.3.0](https://github.com/shipwright-io/build/releases/tag/v0.3.0) | [Docs @ v0.3.0](https://github.com/shipwright-io/build/tree/v0.3.0/docs) | [Examples @ v0.3.0](https://github.com/shipwright-io/build/tree/v0.3.0/samples) |
| [v0.2.0](https://github.com/shipwright-io/build/releases/tag/v0.2.0) | [Docs @ v0.2.0](https://github.com/shipwright-io/build/tree/v0.2.0/docs) | [Examples @ v0.2.0](https://github.com/shipwright-io/build/tree/v0.2.0/samples) |
| [v0.1.1](https://github.com/shipwright-io/build/releases/tag/v0.1.1) | [Docs @ v0.1.1](https://github.com/shipwright-io/build/tree/v0.1.1/docs) | [Examples @ v0.1.1](https://github.com/shipwright-io/build/tree/v0.1.1/samples) |
| [v0.1.0](https://github.com/shipwright-io/build/releases/tag/v0.1.0) | [Docs @ v0.1.0](https://github.com/shipwright-io/build/tree/v0.1.0/docs) | [Examples @ v0.1.0](https://github.com/shipwright-io/build/tree/v0.1.0/samples) |
| Version | Docs | Examples |
|------------------------------------------------------------------------|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| HEAD | [Docs @ HEAD](docs/README.md) | [Examples @ HEAD](samples) |
| [v0.12.0](https://github.com/shipwright-io/build/releases/tag/v0.12.0) | [Docs @ v0.12.0](https://github.com/shipwright-io/build/tree/v0.12.0/docs) | [Examples @ v0.12.0](https://github.com/shipwright-io/build/tree/v0.12.0/samples) |
| [v0.11.0](https://github.com/shipwright-io/build/releases/tag/v0.11.0) | [Docs @ v0.11.0](https://github.com/shipwright-io/build/tree/v0.11.0/docs) | [Examples @ v0.11.0](https://github.com/shipwright-io/build/tree/v0.11.0/samples) |
| [v0.10.0](https://github.com/shipwright-io/build/releases/tag/v0.10.0) | [Docs @ v0.10.0](https://github.com/shipwright-io/build/tree/v0.10.0/docs) | [Examples @ v0.10.0](https://github.com/shipwright-io/build/tree/v0.10.0/samples) |
| [v0.9.0](https://github.com/shipwright-io/build/releases/tag/v0.9.0) | [Docs @ v0.9.0](https://github.com/shipwright-io/build/tree/v0.9.0/docs) | [Examples @ v0.9.0](https://github.com/shipwright-io/build/tree/v0.9.0/samples) |
| [v0.8.0](https://github.com/shipwright-io/build/releases/tag/v0.8.0) | [Docs @ v0.8.0](https://github.com/shipwright-io/build/tree/v0.8.0/docs) | [Examples @ v0.8.0](https://github.com/shipwright-io/build/tree/v0.8.0/samples) |
| [v0.7.0](https://github.com/shipwright-io/build/releases/tag/v0.7.0) | [Docs @ v0.7.0](https://github.com/shipwright-io/build/tree/v0.7.0/docs) | [Examples @ v0.7.0](https://github.com/shipwright-io/build/tree/v0.7.0/samples) |
| [v0.6.0](https://github.com/shipwright-io/build/releases/tag/v0.6.0) | [Docs @ v0.6.0](https://github.com/shipwright-io/build/tree/v0.6.0/docs) | [Examples @ v0.6.0](https://github.com/shipwright-io/build/tree/v0.6.0/samples) |
| [v0.5.1](https://github.com/shipwright-io/build/releases/tag/v0.5.1) | [Docs @ v0.5.1](https://github.com/shipwright-io/build/tree/v0.5.1/docs) | [Examples @ v0.5.1](https://github.com/shipwright-io/build/tree/v0.5.1/samples) |
| [v0.5.0](https://github.com/shipwright-io/build/releases/tag/v0.5.0) | [Docs @ v0.5.0](https://github.com/shipwright-io/build/tree/v0.5.0/docs) | [Examples @ v0.5.0](https://github.com/shipwright-io/build/tree/v0.5.0/samples) |
| [v0.4.0](https://github.com/shipwright-io/build/releases/tag/v0.4.0) | [Docs @ v0.4.0](https://github.com/shipwright-io/build/tree/v0.4.0/docs) | [Examples @ v0.4.0](https://github.com/shipwright-io/build/tree/v0.4.0/samples) |
| [v0.3.0](https://github.com/shipwright-io/build/releases/tag/v0.3.0) | [Docs @ v0.3.0](https://github.com/shipwright-io/build/tree/v0.3.0/docs) | [Examples @ v0.3.0](https://github.com/shipwright-io/build/tree/v0.3.0/samples) |
| [v0.2.0](https://github.com/shipwright-io/build/releases/tag/v0.2.0) | [Docs @ v0.2.0](https://github.com/shipwright-io/build/tree/v0.2.0/docs) | [Examples @ v0.2.0](https://github.com/shipwright-io/build/tree/v0.2.0/samples) |
| [v0.1.1](https://github.com/shipwright-io/build/releases/tag/v0.1.1) | [Docs @ v0.1.1](https://github.com/shipwright-io/build/tree/v0.1.1/docs) | [Examples @ v0.1.1](https://github.com/shipwright-io/build/tree/v0.1.1/samples) |
| [v0.1.0](https://github.com/shipwright-io/build/releases/tag/v0.1.0) | [Docs @ v0.1.0](https://github.com/shipwright-io/build/tree/v0.1.0/docs) | [Examples @ v0.1.0](https://github.com/shipwright-io/build/tree/v0.1.0/samples) |

### Dependencies

| Dependency | Supported versions |
| -------------------------------------| ---------------------------- |
|--------------------------------------|------------------------------|
| [Kubernetes](https://kubernetes.io/) | v1.27.\*, v1.28.\*, v1.29.\* |
| [Tekton](https://tekton.dev) | v0.50.\*, v0.53.\*, v0.56.\* |

Expand Down
4 changes: 2 additions & 2 deletions docs/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ A `Build` resource can specify a source type, such as a Git repository or an OCI
- `source.type` - Specify the type of the data-source. Currently, the supported types are "Git", "OCIArtifact", and "Local".
- `source.git.url` - Specify the source location using a Git repository.
- `source.git.cloneSecret` - For private repositories or registries, the name references a secret in the namespace that contains the SSH private key or Docker access credentials, respectively.
- `source.git.revision` - A specific revision to select from the source repository, this can be a commit, tag or branch name. If not defined, it will fallback to the Git repository default branch.
- `source.git.revision` - A specific revision to select from the source repository, this can be a commit, tag 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.

By default, the Build controller does not validate that the Git repository exists. If the validation is desired, users can explicitly define the `build.shipwright.io/verify.repository` annotation with `true`. For example:
Expand Down Expand Up @@ -283,7 +283,7 @@ spec:

### Defining ParamValues

A `Build` resource can specify _paramValues_ for parameters that are defined in the referenced `BuildStrategy`. You specify these parameter values to control how the steps of the build strategy behave. You can overwrite values in the `BuildRun` resource. See the related [documentation](./buildrun.md#defining-params) for more information.
A `Build` resource can specify _paramValues_ for parameters that are defined in the referenced `BuildStrategy`. You specify these parameter values to control how the steps of the build strategy behave. You can overwrite values in the `BuildRun` resource. See the related [documentation](buildrun.md#defining-paramvalues) for more information.

The build strategy author can define a parameter as either a simple string or an array. Depending on that, you must specify the value accordingly. The build strategy parameter can be specified with a default value. You must specify a value in the `Build` or `BuildRun` for parameters without a default.

Expand Down
4 changes: 2 additions & 2 deletions docs/buildrun.md
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,7 @@ The following table illustrates the different states a BuildRun can have under i
| False | BuildRunAmbiguousBuild | Yes | The defined `BuildRun` uses both `spec.build.name` and `spec.build.spec`. Only one of them is allowed at the same time. |
| False | BuildRunBuildFieldOverrideForbidden | Yes | The defined `BuildRun` uses an override (e.g. `timeout`, `paramValues`, `output`, or `env`) in combination with `spec.build.spec`, which is not allowed. Use the `spec.build.spec` to directly specify the respective value. |
| 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. |
| False | StepOutOfMemory | Yes | The BuildRun Pod failed because a step went out of memory. |
| False | StepOutOfMemory | Yes | The BuildRun Pod failed because a step went out of memory. |

**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 Expand Up @@ -524,4 +524,4 @@ For every BuildRun controller reconciliation, the `buildSpec` in the status of t

The `BuildRun` resource abstracts the image construction by delegating this work to the Tekton Pipeline [TaskRun](https://github.com/tektoncd/pipeline/blob/main/docs/taskruns.md). Compared to a Tekton Pipeline [Task](https://github.com/tektoncd/pipeline/blob/main/docs/tasks.md), a `TaskRun` runs all `steps` until completion of the `Task` or until a failure occurs in the `Task`.

During the Reconcile, the `BuildRun` controller will generate a new `TaskRun`. The controller will embed in the `TaskRun` `Task` definition the requires `steps` to execute during the execution. These `steps` are defined in the strategy defined in the `Build` resource, either a `ClusterBuildStrategy` or a `BuildStrategy`.
During the Reconcile, the `BuildRun` controller will generate a new `TaskRun`. The controller will embed in the `TaskRun` `Task` definition the required `steps` to execute during the execution. These `steps` are defined in the strategy defined in the `Build` resource, either a `ClusterBuildStrategy` or a `BuildStrategy`.
Loading