-
Notifications
You must be signed in to change notification settings - Fork 112
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #669 from qu1queee/readme_reorganize
Readme reorganize
- Loading branch information
Showing
6 changed files
with
401 additions
and
124 deletions.
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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! | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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/). |
Oops, something went wrong.