shipwright-io · openshift-merge-robot · Mar 30, 2021 · Mar 24, 2021 · Mar 24, 2021 · Mar 24, 2021
diff --git a/.docs/shipwright-logo-lightbg-512.png b/.docs/shipwright-logo-lightbg-512.png
diff --git a/README.md b/README.md
@@ -13,153 +13,148 @@ SPDX-License-Identifier: Apache-2.0
  <a href="https://pkg.go.dev/mod/github.com/shipwright-io/build"> <img src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white"></a>
 </p>
 
-# Shipwright - a framework for building container images on Kubernetes
+# ![shipwright-logo](./.docs/shipwright-logo-lightbg-512.png)
 
-Shipwright is an extensible framework for building container images on Kubernetes. With Shipwright,
-developers can define and reuse build strategies that build container images for their CI/CD
-pipelines. Any tool that builds images within a container can be supported, such
-as [Kaniko](https:/GoogleContainerTools/kaniko),
-[Cloud Native Buildpacks](https://buildpacks.io/), and [Buildah](https://buildah.io/).
+Shipwright is an extensible framework for building container images on Kubernetes.
 
-## Dependencies
+## Why?
 
-| Dependency | Supported versions |
-| -------------------------------------| ---------------------------- |
-| [Kubernetes](https://kubernetes.io/) | v1.17.\*, v1.18.\*, v1.19.\* |
-| [Tekton](https://tekton.dev) | v0.21.0 |
-
-## Build Strategies
+With Shipwright, developers get a simplified approach for building container images, by defining a minimal YAML that does not require
+any previous knowledge of containers or container tooling. All you need is your source code in git and access to a container registry.
 
-The following [Build Strategies](docs/buildstrategies.md) are installed by default:
+Shipwright supports any tool that can build container images in Kubernetes clusters, such as:
 
-* [Source-to-Image](docs/buildstrategies.md#source-to-image)
-* [Buildpacks-v3](docs/buildstrategies.md#buildpacks-v3)
-* [Buildah](docs/buildstrategies.md#buildah)
-* [Kaniko](docs/buildstrategies.md#kaniko)
-* [ko](docs/buildstrategies.md#ko)
+- [Kaniko](https:/GoogleContainerTools/kaniko)
+- [Cloud Native Buildpacks](https://buildpacks.io/)
+- [Buildah](https://buildah.io/)
 
-Users have the option to define their own `BuildStrategy` or `ClusterBuildStrategy` resources and make them available for consumption via the `Build` resource.
+## Try It!
 
-## Custom Resources
+* We assume you already have a Kubernetes cluster (v1.17+). 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).
 
-Shipwright defines four CRDs:
-
-* The `BuildStrategy` CRD and the `ClusterBuildStrategy` CRD is used to register a strategy.
-* The `Build` CRD is used to define a build configuration.
-* The `BuildRun` CRD is used to start the actually image build using a registered strategy.
-
-## Read the Docs
-
-| Version | Docs | Examples |
-| ------- | ------------------------------ | --------------------------- |
-| HEAD | [Docs @ HEAD](/docs/README.md) | [Examples @ HEAD](/samples) |
-| [v0.3.0](https:/shipwright-io/build/releases/tag/v0.3.0) | [Docs @ v0.3.0](https:/shipwright-io/build/tree/v0.3.0/docs) | [Examples @ v0.3.0](https:/shipwright-io/build/tree/v0.3.0/samples) |
-| [v0.2.0](https:/shipwright-io/build/releases/tag/v0.2.0) | [Docs @ v0.2.0](https:/shipwright-io/build/tree/v0.2.0/docs) | [Examples @ v0.2.0](https:/shipwright-io/build/tree/v0.2.0/samples) |
-| [v0.1.1](https:/shipwright-io/build/releases/tag/v0.1.1) | [Docs @ v0.1.1](https:/shipwright-io/build/tree/v0.1.1/docs) | [Examples @ v0.1.1](https:/shipwright-io/build/tree/v0.1.1/samples) |
-| [v0.1.0](https:/shipwright-io/build/releases/tag/v0.1.0) | [Docs @ v0.1.0](https:/shipwright-io/build/tree/v0.1.0/docs) | [Examples @ v0.1.0](https:/shipwright-io/build/tree/v0.1.0/samples) |
-
-## Examples
-
-Examples of `Build` resource using the example strategies installed by default.
-
-* [`buildah`](samples/build/build_buildah_cr.yaml)
-* [`buildpacks-v3-heroku`](samples/build/build_buildpacks-v3-heroku_cr.yaml)
-* [`buildpacks-v3`](samples/build/build_buildpacks-v3_cr.yaml)
-* [`kaniko`](samples/build/build_kaniko_cr.yaml)
-* [`source-to-image`](samples/build/build_source-to-image_cr.yaml)
-
-## Try it!
-
-* Get a [Kubernetes](https://kubernetes.io/) cluster and [`kubectl`](https://kubernetes.io/docs/reference/kubectl/overview/) set up to connect to your cluster.
-* Clone this repository from GitHub at the v0.3.0 tag:
+* We also require a Tekton installation (v0.19+). To install the latest version, run:
 
  ```bash
- $ git clone --branch v0.3.0 https:/shipwright-io/build.git
- ...
- $ cd build/
+ $ kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.20.1/release.yaml
  ```
 
- _Coming soon - install Shipwright Build via kubectl!_
-
-* Install [Tekton](https://cloud.google.com/tekton) by running [hack/install-tekton.sh](hack/install-tekton.sh), it installs v0.21.0.
+* Install the Shipwright deployment. To install the latest version, run:
 
  ```bash
- $ hack/install-tekton.sh
+ $ kubectl apply --filename https:/shipwright-io/build/releases/download/nightly/nightly-2021-03-24-1616591545.yaml
  ```
 
-* Install Shipwright and sample strategies via `make`:
+* Install the Shipwright strategies. To install the latest version, run:
 
  ```bash
- $ make install
+ $ kubectl apply --filename https:/shipwright-io/build/releases/download/nightly/default_strategies.yaml
  ```
 
-* Add a push secret to your container image repository, such as one on Docker Hub or 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/):
 
- ```yaml
- $ kubectl create secret generic push-secret \
- --from-file=.dockerconfigjson=$HOME/.docker/config.json \
- --type=kubernetes.io/dockerconfigjson
+ ```bash
+ $ REGISTRY_SERVER=https://index.docker.io/v1/ REGISTRY_USER=<your_registry_user> REGISTRY_PASSWORD=<your_registry_password>
+ $ kubectl create secret docker-registry push-secret \
+ --docker-server=$REGISTRY_SERVER \
+ --docker-username=$REGISTRY_USER \
+ --docker-password=$REGISTRY_PASSWORD \
+ [email protected]
  ```
 
-* Create a [Cloud Native Buildpacks](samples/build/build_buildpacks_v3_cr.yaml) build, replacing
- `<MY_REGISTRY>/<MY_USERNAME>/<MY_REPO>` with the registry hostname, username, and repository your
- cluster has access to and that you have permission to push images to.
+* Create a Build object, replacing `<REGISTRY_ORG>` with the registry username your `push-secret` secret have access to:
 
  ```bash
- $ kubectl apply -f - <<EOF
+ $ 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:/adambkaplan/shipwright-example-nodejs.git
+ url: https:/shipwright-io/sample-nodejs
+ contextDir: source-build
  strategy:
  name: buildpacks-v3
  kind: ClusterBuildStrategy
  output:
- image: <MY_REGISTRY>/<MY_USERNAME>/<MY_REPO>:latest
+ image: docker.io/${REGISTRY_ORG}/sample-nodejs:latest
  credentials:
  name: push-secret
  EOF
  ```
 
-* Run your build:
+ ```bash
+ $ kubectl get builds
+ NAME REGISTERED REASON BUILDSTRATEGYKIND BUILDSTRATEGYNAME CREATIONTIME
+ buildpack-nodejs-build True Succeeded ClusterBuildStrategy buildpacks-v3 68s
+ ```
+
+* Submit your buildrun:
 
  ```bash
- $ kubectl apply -f - <<EOF
+ $ cat <<EOF | kubectl create -f -
  apiVersion: shipwright.io/v1alpha1
  kind: BuildRun
  metadata:
- name: buildpack-nodejs-build-1
+ generateName: buildpack-nodejs-buildrun-
  spec:
  buildRef:
  name: buildpack-nodejs-build
- serviceAccount:
- name: default
  EOF
  ```
 
-## Roadmap
+* Wait until your buildrun is completed:
 
-### Build Strategies Support
+ ```bash
+ $ kubectl get buildruns
+ NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME
+ buildpack-nodejs-buildrun-xyzds True Succeeded 69s 2s
+ ```
+
+ or
+
+ ```bash
+ $ 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.
+
+## Please tell me more!
+
+Depending on your source code, you might want to build it differently with Shipwright.
+
+To find out more on what's the best strategy or what else can Shipwright do for you, please visit our [tutorial](./docs/tutorials/README.md)!
+
+## More information
+
+### Read the Docs
+
+| Version | Docs | Examples |
+| ------- | ------------------------------ | --------------------------- |
+| HEAD | [Docs @ HEAD](/docs/README.md) | [Examples @ HEAD](/samples) |
+| [v0.3.0](https:/shipwright-io/build/releases/tag/v0.3.0) | [Docs @ v0.3.0](https:/shipwright-io/build/tree/v0.3.0/docs) | [Examples @ v0.3.0](https:/shipwright-io/build/tree/v0.3.0/samples) |
+| [v0.2.0](https:/shipwright-io/build/releases/tag/v0.2.0) | [Docs @ v0.2.0](https:/shipwright-io/build/tree/v0.2.0/docs) | [Examples @ v0.2.0](https:/shipwright-io/build/tree/v0.2.0/samples) |
+| [v0.1.1](https:/shipwright-io/build/releases/tag/v0.1.1) | [Docs @ v0.1.1](https:/shipwright-io/build/tree/v0.1.1/docs) | [Examples @ v0.1.1](https:/shipwright-io/build/tree/v0.1.1/samples) |
+| [v0.1.0](https:/shipwright-io/build/releases/tag/v0.1.0) | [Docs @ v0.1.0](https:/shipwright-io/build/tree/v0.1.0/docs) | [Examples @ v0.1.0](https:/shipwright-io/build/tree/v0.1.0/samples) |
+
+### Dependencies
+
+| Dependency | Supported versions |
+| -------------------------------------| ---------------------------- |
+| [Kubernetes](https://kubernetes.io/) | v1.17.\*, v1.18.\*, v1.19.\* |
+| [Tekton](https://tekton.dev) | v0.19.0, v0.20.\*, v0.21.0 |
 
-| Build Strategy | Alpha | Beta | GA |
-| ----------------------------------------------------------------------------------------------- | ----- | ---- | -- |
-| [Source-to-Image](samples/buildstrategy/source-to-image/buildstrategy_source-to-image_cr.yaml) | ☑ | | |
-| [Buildpacks-v3-heroku](samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_cr.yaml) | ☑️ | | |
-| [Buildpacks-v3](samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml) | ☑️ | | |
-| [Kaniko](samples/buildstrategy/kaniko/buildstrategy_kaniko_cr.yaml) | ☑️ | | |
-| [Buildah](samples/buildstrategy/buildah/buildstrategy_buildah_cr.yaml) | ☑️ | | |
+## Want to get involved?
 
-## Community meetings
+### Community meetings
 
-We host weekly meetings for contributors, maintainers and anyone interested in the project. The weekly meetings take place on Monday´s at 2pm UTC.
+We host weekly meetings for contributors, maintainers and anyone interested in the project. The weekly meetings take place on Mondays at 1pm UTC.
 
 * Meeting [minutes](https:/shipwright-io/build/issues?q=is%3Aissue+label%3Acommunity+label%3Ameeting+is%3Aopen)
 * Public calendar [invite](https://calendar.google.com/calendar/u/1?cid=Y19iMWVndjc3anUyczJkbWNkM2R1ZnAxazhuNEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
 
-## Want to contribute
+### Want to contribute
 
 We are so excited to have you!
 

diff --git a/docs/buildstrategies.md b/docs/buildstrategies.md
@@ -90,42 +90,6 @@ To install the namespaced scope strategy, use:
 kubectl apply -f samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_namespaced_cr.yaml
 ```
 
-### Try it
-
-To use this strategy follow this steps:
-
-- Create the Kubernetes secret that host the configuration to access the container registry.
-
-- Create a `Build` resource that uses `quay.io` or `DockerHub` image repository for pushing the image. Also, provide credentials to access it.
-
- ```yaml
- apiVersion: shipwright.io/v1alpha1
- kind: Build
- metadata:
- name: buildpack-nodejs-build
- spec:
- source:
- url: https:/sclorg/nodejs-ex
- strategy:
- name: buildpacks-v3
- kind: ClusterBuildStrategy
- output:
- image: quay.io/yourorg/yourrepo
- credentials: <your-kubernetes-container-registry-secret>
- ```
-
-- Start a `BuildRun` resource.
-
- ```yaml
- apiVersion: shipwright.io/v1alpha1
- kind: BuildRun
- metadata:
- name: buildpack-nodejs-buildrun
- spec:
- buildRef:
- name: buildpack-nodejs-build
- ```
-
 ---
 
 ## Kaniko

diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
@@ -0,0 +1,62 @@
+# Shipwright Build Tutorial
+
+So you just successfully built a container image via the [Try It!](../../README.md#try-it) section and you want to know more?
+
+At Shipwright, we've spent a lot of time trying to figure out the best ways to simplify the experience when
+building container images. Shipwright provides an alternative for securely building container images in your Kubernetes cluster.
+
+
+What if we could
+
+- Support any existing tooling for building container images in Kubernetes clusters.
+- Minimize the burden of learning a new tool for building images, by abstracting it from users.
+- Simplify the user experience when building images via a standardize minimal API.
+- Allow users to re-use their existing cluster for building and deploying container images.
+
+## Concepts
+
+| Concept | Description |
+| ----------- | ----------- |
+| **`Strategy`** | Refers to a particular tool that will be used when building a container image, such as Kaniko, Buildah, ko, etc. |
+| **`Build`** | Resource used to define a build configuration. |
+| **`BuildRun`** | Resource used to start the image build mechanism. |
+| **`BuildStrategy` / `ClusterBuildStrategy`** | Resource that holds a template that dictates how to build via a particular strategy. |
+| **`Dockerfile-less strategy`** | Is a category given to strategies that can build container images from source code, without the notion of a Dockerfile. |
+| **`Dockerfile-based strategy`** | Is a category given to strategies that can build container images from source code, with a reference to a Dockerfile. |
+
+With the above concepts in mind, lets see how they all play together.
+
+## Strategies
+
+Shipwright ships with a set of strategies that are available across the cluster.
+
+The default installation includes these [buildstrategies](/docs/buildstrategies.md):
+
+* [Buildpacks-v3](docs/buildstrategies.md#buildpacks-v3)
+* [Kaniko](docs/buildstrategies.md#kaniko)
+* [Source-to-Image](docs/buildstrategies.md#source-to-image)
+* [Buildah](docs/buildstrategies.md#buildah)
+* [ko](docs/buildstrategies.md#ko)
+
+For more information about strategies see the related [docs](/docs/buildstrategies.md).
+
+## Examples
+
+* [Example with Kaniko](/docs/tutorials/building_with_kaniko.md)
+
+* [Example with Buildpacks](/docs/tutorials/building_with_buildpacks.md)
+
+Depending on your source code you might want to try a specific example. The following table serves as a guide to help you understand which
+strategy to choose:
+
+| Sample code | Repository | ContextDir | Strategy Type | Strategy to use |
+| ----------- | ----------- | ------------- | ------------- | ------------- |
+| A go app with a Dockerfile | [shipwright-io/sample-go](https:/shipwright-io/sample-go) | `/docker-build` | Dockerfile-based | Kaniko, Buildah |
+| A go app | [shipwright-io/sample-go](https:/shipwright-io/sample-go) | `/source-build` | Dockerfile-less | buildpacks-v3, buildpacks-v3-heroku |
+| A ruby app | [shipwright-io/sample-ruby](https:/shipwright-io/sample-ruby) | `/source-build` | Dockerfile-less | buildpacks-v3, buildpacks-v3-heroku |
+| A java app with a Dockerfile | [hipwright-io/sample-jave](https:/shipwright-io/sample-java) | `/docker-build` | Dockerfile-based | Kaniko, Buildah |
+| Shipwright/Build | [shipwright-io/build](https:/shipwright-io/build) | `/cmd/manager` | Dockerfile-less | ko |
+
+_Note_: `ContextDir` is the path under the repository where the source code is located.
+
+_Note_: `Buildpacks-v3` support is provided via Paketo and Heroku. Paketo is our default tool, so any reference to buildpacks-v3 usually implies the usage of [Paketo](https://paketo.io/).