mirror of https://github.com/knative/docs.git
Edits + Syncing samples in README.md and build.md (#229)
This commit is contained in:
RichieEscarez
Google Prow Robot
parent
b3feaf4164
commit
35ce148182
|
|
@ -56,15 +56,15 @@ spec:
|
||||||
serviceAccountName: build-auth-example
|
serviceAccountName: build-auth-example
|
||||||
source:
|
source:
|
||||||
git:
|
git:
|
||||||
url: https://github.com/sample/build-sample.git
|
url: https://github.com/example/build-example.git
|
||||||
revision: master
|
revision: master
|
||||||
steps:
|
steps:
|
||||||
- name: ubuntu-example
|
- name: ubuntu-example
|
||||||
image: ubuntu
|
image: ubuntu
|
||||||
args: ["ubuntu-build-example", "SECRETS.md"]
|
args: ["ubuntu-build-example", "SECRETS-example.md"]
|
||||||
steps:
|
steps:
|
||||||
- image: gcr.io/sample-builders/build-sample
|
- image: gcr.io/example-builders/build-example
|
||||||
args: ['echo', 'hello', 'build']
|
args: ['echo', 'hello-example', 'build']
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
310
build/builds.md
310
build/builds.md
|
|
@ -1,86 +1,188 @@
|
||||||
# Builds
|
# Knative `Build` resources
|
||||||
|
|
||||||
This document defines what "Builds" are and their capabilities.
|
Use the `Build` resource object to create and run on-cluster processes to
|
||||||
|
completion.
|
||||||
|
|
||||||
|
To create a build in Knative, you must define a configuration file, in which
|
||||||
|
specifies one or more container images that you have implemented to perform
|
||||||
|
and complete a task.
|
||||||
|
|
||||||
|
A build runs until all `steps` have completed or until a failure occurs.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
* [Syntax](#syntax)
|
||||||
|
* [Steps](#steps)
|
||||||
|
* [Template](#template)
|
||||||
|
* [Source](#source)
|
||||||
|
* [Service Account](#service-account)
|
||||||
|
* [Volumes](#volumes)
|
||||||
|
* [Examples](#examples)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Syntax
|
||||||
|
|
||||||
|
To define a configuration file for a `Build` resource, you can specify the
|
||||||
|
following fields:
|
||||||
|
|
||||||
|
* Required:
|
||||||
|
* [`apiVersion`][kubernetes-overview] - Specifies the API version, for example
|
||||||
|
`build.knative.dev/v1alpha1`.
|
||||||
|
* [`kind`][kubernetes-overview] - Specify the `Build` resource object.
|
||||||
|
* [`metadata`][kubernetes-overview] - Specifies data to uniquely identify the
|
||||||
|
`Build` resource object, for example a `name`.
|
||||||
|
* [`spec`][kubernetes-overview] - Specifies the configuration information for
|
||||||
|
your `Build` resource object. Build steps must be defined through either of
|
||||||
|
the following fields:
|
||||||
|
* [`steps`](#steps) - Specifies one or more container images that you want
|
||||||
|
to run in your build.
|
||||||
|
* [`template`](#template) - Specifies a reusable build template that
|
||||||
|
includes one or more `steps`.
|
||||||
|
* Optional:
|
||||||
|
* [`source`](#source) - Specifies a container image that provides information
|
||||||
|
to your build.
|
||||||
|
* [`serviceAccountName`](#service-account) - Specifies a `ServiceAccount`
|
||||||
|
resource object that enables your build to run with the defined
|
||||||
|
authentication information.
|
||||||
|
* [`volumes`](#volumes) - Specifies one or more volumes that you want to make
|
||||||
|
available to your build.
|
||||||
|
|
||||||
|
[kubernetes-overview]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
|
||||||
|
|
||||||
|
The following example is a non-working sample where most of the possible
|
||||||
|
configuration fields are used:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: build.knative.dev/v1alpha1
|
||||||
|
kind: Build
|
||||||
|
metadata:
|
||||||
|
name: example-build-name
|
||||||
|
spec:
|
||||||
|
serviceAccountName: build-auth-example
|
||||||
|
source:
|
||||||
|
git:
|
||||||
|
url: https://github.com/example/build-example.git
|
||||||
|
revision: master
|
||||||
|
steps:
|
||||||
|
- name: ubuntu-example
|
||||||
|
image: ubuntu
|
||||||
|
args: ["ubuntu-build-example", "SECRETS-example.md"]
|
||||||
|
steps:
|
||||||
|
- image: gcr.io/example-builders/build-example
|
||||||
|
args: ['echo', 'hello-example', 'build']
|
||||||
|
steps:
|
||||||
|
- name: dockerfile-pushexample
|
||||||
|
image: gcr.io/example-builders/push-example
|
||||||
|
args: ["push", "${IMAGE}"]
|
||||||
|
volumeMounts:
|
||||||
|
- name: docker-socket-example
|
||||||
|
mountPath: /var/run/docker.sock
|
||||||
|
volumes:
|
||||||
|
- name: example-volume
|
||||||
|
emptyDir: {}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Steps
|
||||||
|
|
||||||
|
The `steps` field is required if the `template` field is not defined. You
|
||||||
|
define one or more `steps` fields to define the body of a build.
|
||||||
|
|
||||||
|
Each `steps` in a build must specify a `Builder`, or type of container image that
|
||||||
|
adheres to the [Knative builder contract](./builder-contract.md). For each of
|
||||||
|
the of the `steps` fields, or container images that you define:
|
||||||
|
|
||||||
|
* The `Builder`-type container images are run and evaluated in order, starting
|
||||||
|
from the top of the configuration file.
|
||||||
|
* Each container image runs until completion or until the first failure is
|
||||||
|
detected.
|
||||||
|
|
||||||
|
For details about how to ensure that you implement each step to align with the
|
||||||
|
"builder contract", see the [`Builder`](./builder-contract.md) reference topic.
|
||||||
|
|
||||||
|
|
||||||
## What is a Build?
|
#### Template
|
||||||
|
|
||||||
A `Build` is the main custom resource introduced by this project.
|
The `template` field is a required if no `steps` are defined. Specifies a
|
||||||
Builds are a "run to completion" resource. They start evaluating upon
|
[`BuildTemplate`](./build-templates.md) resource object, in which includes
|
||||||
creation and run until they are `Complete` (or until the first failing
|
repeatable or sharable build `steps`.
|
||||||
step, resulting in a `Failed` status).
|
|
||||||
|
|
||||||
### Elements of a Build
|
For examples and more information about build templates, see the
|
||||||
|
[`BuildTemplate`](./build-templates.md) reference topic.
|
||||||
|
|
||||||
* [Source](#source)
|
|
||||||
* [Steps or Template](#steps-or-template)
|
|
||||||
* [Service Account](#service-account)
|
|
||||||
* [Volumes](#volumes)
|
|
||||||
|
|
||||||
#### Source
|
#### Source
|
||||||
|
|
||||||
Builds may define a `source:`. A `source:` describes the context with which to
|
Optional. Specifies a container image. Use the `source` field to provide your
|
||||||
seed the build. This context is put into `/workspace`, a volume that is
|
build with data or context that is needed by your build. The data is placed into
|
||||||
mounted into the `source:` and all of the `steps:`.
|
the `/workspace` directory within a mounted
|
||||||
|
[volume](https://kubernetes.io/docs/concepts/storage/volumes/) and is available
|
||||||
|
to all `steps` of your build.
|
||||||
|
|
||||||
Currently, the following types of source are supported:
|
The currently supported types of sources include:
|
||||||
* `git:` can specify a `url:` and a `revision:`.
|
|
||||||
|
|
||||||
* `custom:` can specify an arbitrary container specification, similar to
|
* `git` - A Git based repository. Specify the `url` field to define the
|
||||||
steps (see below).
|
location of the container image. Specify a `revision` field to define a
|
||||||
|
branch name, tag name, commit SHA, or any ref. [Learn more about revisions in
|
||||||
|
Git](https://git-scm.com/docs/gitrevisions#_specifying_revisions).
|
||||||
|
|
||||||
* `gcs:` can specify an archive stored at Cloud Storage.
|
* `gcs` - An archive that is located in Google Cloud Storage.
|
||||||
|
|
||||||
|
* `custom` - An arbitrary container image.
|
||||||
#### Steps or Template
|
|
||||||
|
|
||||||
The body of a build is defined through either a set of inlined `steps:` or by
|
|
||||||
instantiating a [build template](./build-templates.md).
|
|
||||||
|
|
||||||
`steps:` is a series of Kubernetes container references adhering to the [builder
|
|
||||||
contract](./builder-contract.md). These containers are evaluated in order,
|
|
||||||
until the first failure (or the last container completes successfully).
|
|
||||||
|
|
||||||
|
|
||||||
#### Service Account
|
#### Service Account
|
||||||
|
|
||||||
Builds (like Pods) run as a particular service account. If none is specified, it
|
Optional. Specifies the `name` of a `ServiceAccount` resource object. Use the
|
||||||
is run as the "default" service account in the namespace of the Build.
|
`serviceAccountName` field to run your build with the privileges of the
|
||||||
|
specified service account. If no `serviceAccountName` field is specified,
|
||||||
|
your build runs using the
|
||||||
|
[`default` service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#use-the-default-service-account-to-access-the-api-server)
|
||||||
|
that is in the
|
||||||
|
[namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
|
||||||
|
of the `Build` resource object.
|
||||||
|
|
||||||
A custom service account can be specified via `serviceAccountName: build-bot`.
|
For examples and more information about specifying service accounts,
|
||||||
Service account names other than `build-bot` are acceptable.
|
see the [`ServiceAccount`](./auth.md) reference topic.
|
||||||
|
|
||||||
Service accounts can be used to project certain types of credentials into the
|
|
||||||
context of a Build automagically. For more information on how this process is
|
|
||||||
configured and how it works, see the [credential](./auth.md).
|
|
||||||
|
|
||||||
|
|
||||||
#### Volumes
|
#### Volumes
|
||||||
|
|
||||||
Builds can specify a collection of volumes to make available to their build
|
Optional. Specifies one or more
|
||||||
steps. These complement the volumes that are implicitly created as part of
|
[volumes](https://kubernetes.io/docs/concepts/storage/volumes/) that you want
|
||||||
the [builder contract](./builder-contract.md).
|
to make available to your build, including all the build steps. Add volumes to
|
||||||
|
complement the volumes that are implicitly
|
||||||
|
[created during a build step](./builder-contract.md).
|
||||||
|
|
||||||
Volumes can be used in a wide variety of ways, just as in Kubernetes itself.
|
For example, use volumes to accomplish one of the following common tasks:
|
||||||
Common examples include:
|
|
||||||
|
|
||||||
* Mounting in Kubernetes secrets (a manual alternative to [our service account
|
* [Mount a Kubernetes secrets(./auth.md).
|
||||||
model](./auth.md)).
|
|
||||||
|
|
||||||
* Creating an extra `emptyDir` volume to act as a multi-step cache (maybe even
|
* Creat an `emptyDir` volume to act as a cache for use across multiple build
|
||||||
a persistent volume for inter-build caching).
|
steps. Consider using a persistent volume for inter-build caching.
|
||||||
|
|
||||||
* Mounting in the host's Docker socket to perform Dockerfile builds.
|
* Mount a host's Docker socket to use a `Dockerfile` for container image
|
||||||
|
builds.
|
||||||
|
|
||||||
|
|
||||||
### Example Builds
|
### Examples
|
||||||
|
|
||||||
This section outlines a number of simple illustrative builds with fully inlined
|
Use these code snippets to help you understand how to define your Knative builds.
|
||||||
specifications. For examples of Builds that leverage templates, see [the build
|
|
||||||
template documentation](./build-templates.md).
|
|
||||||
|
|
||||||
|
Tip: See the collection of simple
|
||||||
|
[test builds](https://github.com/knative/build/tree/master/test) for
|
||||||
|
additional code samples, including working copies of the following snippets:
|
||||||
|
|
||||||
#### With `git` by branch, tag, commit or ref
|
* [`git` as `source`](#using-git)
|
||||||
|
* [`gcs` as `source`](#using-gcs)
|
||||||
|
* [`custom` as `source`](#using-custom)
|
||||||
|
* [Mounting extra volumes](#using-an-extra-volume)
|
||||||
|
* [Pushing an image](#using-steps-to-push-images)
|
||||||
|
* [Authenticating with `ServiceAccount`](#using-a-serviceaccount)
|
||||||
|
|
||||||
|
#### Using `git`
|
||||||
|
|
||||||
|
Specifying `git` as your `source`:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
spec:
|
spec:
|
||||||
|
|
@ -93,11 +195,9 @@ spec:
|
||||||
args: ["cat", "README.md"]
|
args: ["cat", "README.md"]
|
||||||
```
|
```
|
||||||
|
|
||||||
The `revision` field accepts a branch name, tag name, commit SHA, or any ref.
|
#### Using `git`
|
||||||
See https://git-scm.com/docs/gitrevisions#_specifying_revisions for more
|
|
||||||
information.
|
|
||||||
|
|
||||||
#### With a `gcs` source
|
Specifying `gcs` as your `source`:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
spec:
|
spec:
|
||||||
|
|
@ -111,7 +211,9 @@ spec:
|
||||||
args: ["ls"]
|
args: ["ls"]
|
||||||
```
|
```
|
||||||
|
|
||||||
#### With a `custom` source
|
#### Using `custom`
|
||||||
|
|
||||||
|
Specifying `custom` as your `source`:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
spec:
|
spec:
|
||||||
|
|
@ -124,7 +226,9 @@ spec:
|
||||||
args: ["cat", "README.md"]
|
args: ["cat", "README.md"]
|
||||||
```
|
```
|
||||||
|
|
||||||
#### With an extra volume
|
#### Using an extra volume
|
||||||
|
|
||||||
|
Mounting multiple volumes:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
spec:
|
spec:
|
||||||
|
|
@ -147,31 +251,85 @@ spec:
|
||||||
emptyDir: {}
|
emptyDir: {}
|
||||||
```
|
```
|
||||||
|
|
||||||
#### With a private `git` repo via a custom service-account
|
#### Using `steps` to push images
|
||||||
|
|
||||||
|
Defining a `steps` to push a container image to a repository.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
spec:
|
spec:
|
||||||
# Here build-bot is a ServiceAccount that's had an extra Secret attached
|
parameters:
|
||||||
# with `type: kubernetes.io/basic-auth`. The username and password are
|
- name: IMAGE
|
||||||
# specified per usual, and there is an additional annotation on the Secret
|
description: The name of the image to push
|
||||||
# of the form: `build.knative.dev/git-0: https://github.com`, which
|
- name: DOCKERFILE
|
||||||
# directs us to configure this basic authentication for use with GitHub
|
description: Path to the Dockerfile to build.
|
||||||
# through Git.
|
default: /workspace/Dockerfile
|
||||||
serviceAccountName: build-bot
|
|
||||||
|
|
||||||
source:
|
|
||||||
git:
|
|
||||||
url: https://github.com/google/secret-sauce.git
|
|
||||||
revision: master
|
|
||||||
steps:
|
steps:
|
||||||
- image: ubuntu
|
- name: build-and-push
|
||||||
args: ["cat", "SECRETS.md"]
|
image: gcr.io/kaniko-project/executor
|
||||||
|
args:
|
||||||
|
- --dockerfile=${DOCKERFILE}
|
||||||
|
- --destination=${IMAGE}
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Lots of trivial examples
|
#### Using a `ServiceAccount`
|
||||||
|
|
||||||
For a variety of additional (mostly trivial) examples, see also our [tests
|
Specifying a `ServiceAccount` to access a private `git` repository:
|
||||||
directory](https://github.com/knative/build/tree/master/test).
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: build.knative.dev/v1alpha1
|
||||||
|
kind: Build
|
||||||
|
metadata:
|
||||||
|
name: test-build-with-serviceaccount-git-ssh
|
||||||
|
labels:
|
||||||
|
expect: succeeded
|
||||||
|
spec:
|
||||||
|
serviceAccountName: test-build-robot-git-ssh
|
||||||
|
source:
|
||||||
|
git:
|
||||||
|
url: git@github.com:knative/build.git
|
||||||
|
revision: master
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- name: config
|
||||||
|
image: ubuntu
|
||||||
|
command: ["/bin/bash"]
|
||||||
|
args: ["-c", "cat README.md"]
|
||||||
|
```
|
||||||
|
|
||||||
|
Where `serviceAccountName: test-build-robot-git-ssh` references the following
|
||||||
|
`ServiceAccount`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: v1
|
||||||
|
kind: ServiceAccount
|
||||||
|
metadata:
|
||||||
|
name: test-build-robot-git-ssh
|
||||||
|
secrets:
|
||||||
|
- name: test-git-ssh
|
||||||
|
```
|
||||||
|
|
||||||
|
And `name: test-git-ssh`, references the following `Secret`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: v1
|
||||||
|
kind: Secret
|
||||||
|
metadata:
|
||||||
|
name: test-git-ssh
|
||||||
|
annotations:
|
||||||
|
build.knative.dev/git-0: github.com
|
||||||
|
type: kubernetes.io/ssh-auth
|
||||||
|
data:
|
||||||
|
# Generated by:
|
||||||
|
# cat id_rsa | base64 -w 1000000
|
||||||
|
ssh-privatekey: LS0tLS1CRUdJTiBSU0EgUFJJVk.....[example]
|
||||||
|
# Generated by:
|
||||||
|
# ssh-keyscan github.com | base64 -w 100000
|
||||||
|
known_hosts: Z2l0aHViLmNvbSBzc2g.....[example]
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: For a working copy of this `ServiceAccount` example, see the
|
||||||
|
[build/test/git-ssh](https://github.com/knative/build/tree/master/test/git-ssh)
|
||||||
|
code sample.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue