knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update auth.md (#137) 

Copy edits, and shift to procedural steps for setting up authentication.
This commit is contained in:
Peter Delaney 2018-07-17 17:38:31 -07:00 committed by Google Prow Robot
parent f68f841dcf
commit 168b37d087
1 changed files with 142 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

283
build/auth.md
View File

@ -1,6 +1,6 @@
# Authentication # Authentication
This document serves to define how authentication is provided during execution This document defines how authentication is provided during execution
of a build. of a build.
The build system supports two types of authentication, using Kuberernetes' The build system supports two types of authentication, using Kuberernetes'
@ -9,7 +9,7 @@ first-class `Secret` types:
* `kubernetes.io/basic-auth` * `kubernetes.io/basic-auth`
* `kubernetes.io/ssh-auth` * `kubernetes.io/ssh-auth`
`Secret`s of these types can be made available to the `Build` by attaching them Secrets of these types can be made available to the `Build` by attaching them
to the `ServiceAccount` as which it runs. to the `ServiceAccount` as which it runs.
### Exposing credentials to the build ### Exposing credentials to the build
@ -17,176 +17,177 @@ to the `ServiceAccount` as which it runs.
In their native form, these secrets are unsuitable for consumption by Git and In their native form, these secrets are unsuitable for consumption by Git and
Docker. For Git, they need to be turned into (some form of) `.gitconfig`. For Docker. For Git, they need to be turned into (some form of) `.gitconfig`. For
Docker, they need to be turned into a `~/.docker/config.json` file. Also, Docker, they need to be turned into a `~/.docker/config.json` file. Also,
while each of these supports having multiple credentials for multiple domains, while each of these supports has multiple credentials for multiple domains,
those credentials typically need to be blended into a single canonical keyring. those credentials typically need to be blended into a single canonical keyring.
To solve this, prior to even the `Source` step, all builds execute a credential To solve this, before the `Source` step, all builds execute a credential
initialization process that accesses each of its secrets and aggregates them initialization process that accesses each of its secrets and aggregates them
into their respective files in `$HOME`. into their respective files in `$HOME`.
## SSH authentication (Git) ## SSH authentication (Git)
First, define a `Secret` containing your SSH private key. 1. Define a `Secret` containing your SSH private key:
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: Secret kind: Secret
metadata: metadata:
name: ssh-key name: ssh-key
annotations: annotations:
build.knative.dev/git-0: https://github.com # Described below build.knative.dev/git-0: https://github.com # Described below
type: kubernetes.io/ssh-auth type: kubernetes.io/ssh-auth
data: data:
ssh-privatekey: <base64 encoded> ssh-privatekey: <base64 encoded>
# This is non-standard, but its use is encouraged to make this more secure. # This is non-standard, but its use is encouraged to make this more secure.
known_hosts: <base64 encoded> known_hosts: <base64 encoded>
``` ```
To generate the value of `ssh-privatekey`, copy the value of (for example) `cat id_rsa | base64`. 1. Generate the value of `ssh-privatekey` by copying the value of (for example)
`cat id_rsa | base64`.
Then copy the value of `cat ~/.ssh/known_hosts | base64` to the `known_hosts` field. 1. Copy the value of `cat ~/.ssh/known_hosts | base64` to the `known_hosts` field.
Next, direct a `ServiceAccount` to use this `Secret`: 1. Next, direct a `ServiceAccount` to use this `Secret`:
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: ServiceAccount kind: ServiceAccount
metadata: metadata:
name: build-bot name: build-bot
secrets: secrets:
- name: ssh-key - name: ssh-key
``` ```
Then use that `ServiceAccount` in your `Build`: 1. Then use that `ServiceAccount` in your `Build`:
```yaml ```yaml
apiVersion: build.knative.dev/v1alpha1 apiVersion: build.knative.dev/v1alpha1
kind: Build kind: Build
metadata: metadata:
name: build-with-ssh-auth name: build-with-ssh-auth
spec: spec:
serviceAccountName: build-bot serviceAccountName: build-bot
steps: steps:
... ...
``` ```
To execute the build: 1. Execute the build:
```shell ```shell
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
``` ```
When the build executes, before steps execute, a `~/.ssh/config` will be When the build executes, before steps execute, a `~/.ssh/config` will be
generated containing the key configured in the `Secret`, and this key will be generated containing the key configured in the `Secret`. This key is then
used to authenticate with the Git service. used to authenticate with the Git service.
## Basic Authentication (Git) ## Basic authentication (Git)
First, define a `Secret` containing the base64-encoded username and password 1. Define a `Secret` containing the base64-encoded username and password
the build should use to authenticate to a Git repository. that the build should use to authenticate to a Git repository:
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: Secret kind: Secret
metadata: metadata:
name: basic-user-pass name: basic-user-pass
annotations: annotations:
build.knative.dev/git-0: https://github.com # Described below build.knative.dev/git-0: https://github.com # Described below
type: kubernetes.io/basic-auth type: kubernetes.io/basic-auth
data: data:
username: <base64 encoded> username: <base64 encoded>
password: <base64 encoded> password: <base64 encoded>
``` ```
Next, direct a `ServiceAccount` to use this `Secret`: 1. Next, direct a `ServiceAccount` to use this `Secret`:
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: ServiceAccount kind: ServiceAccount
metadata: metadata:
name: build-bot name: build-bot
secrets: secrets:
- name: basic-user-pass - name: basic-user-pass
``` ```
Then use that `ServiceAccount` in your `Build`: 1. Use that `ServiceAccount` in your `Build`:
```yaml ```yaml
apiVersion: build.knative.dev/v1alpha1 apiVersion: build.knative.dev/v1alpha1
kind: Build kind: Build
metadata: metadata:
name: build-with-basic-auth name: build-with-basic-auth
spec: spec:
serviceAccountName: build-bot serviceAccountName: build-bot
steps: steps:
... ...
``` ```
To execute the build: 1. Execute the build:
```shell ```shell
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
``` ```
When this build executes, before steps execute, a `~/.gitconfig` will be When this build executes, before steps execute, a `~/.gitconfig` will be
generated containing the credentials configured in the `Secret`, and these generated containing the credentials configured in the `Secret`, and these
credentials will be used to authenticate with the Git repository. credentials are then used to authenticate with the Git repository.
## Basic Authentication (Docker) ## Basic authentication (Docker)
First, define a `Secret` containing the base64-encoded username and password 1. Define a `Secret` containing the base64-encoded username and password
the build should use to authenticate to a Docker registry. that the build should use to authenticate to a Docker registry:
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: Secret kind: Secret
metadata: metadata:
name: basic-user-pass name: basic-user-pass
annotations: annotations:
build.knative.dev/docker-0: https://gcr.io # Described below build.knative.dev/docker-0: https://gcr.io # Described below
type: kubernetes.io/basic-auth type: kubernetes.io/basic-auth
data: data:
username: <base64 encoded> username: <base64 encoded>
password: <base64 encoded> password: <base64 encoded>
``` ```
Next, direct a `ServiceAccount` to use this `Secret`: 1. Direct a `ServiceAccount` to use this `Secret`:
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: ServiceAccount kind: ServiceAccount
metadata: metadata:
name: build-bot name: build-bot
secrets: secrets:
- name: basic-user-pass - name: basic-user-pass
``` ```
Then use that `ServiceAccount` in your `Build`: 1. Use that `ServiceAccount` in your `Build`:
```yaml ```yaml
apiVersion: build.knative.dev/v1alpha1 apiVersion: build.knative.dev/v1alpha1
kind: Build kind: Build
metadata: metadata:
name: build-with-basic-auth name: build-with-basic-auth
spec: spec:
serviceAccountName: build-bot serviceAccountName: build-bot
steps: steps:
... ...
``` ```
To execute the build: 1. Execute the build:
```shell ```shell
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
``` ```
When this build executes, before steps execute, a `~/.docker/config.json` will When this build executes, before steps execute, a `~/.docker/config.json` will
be generated containing the credentials configured in the `Secret`, and these be generated containing the credentials configured in the `Secret`, and these
credentials will be used to authenticate with the Docker registry. credentials are then used to authenticate with the Docker registry.
### Guiding credential selection ### Guiding credential selection
A build may require many different types of authentication. For instance, a A build might require many different types of authentication. For instance, a
build might require access to multiple private Git repositories, and access to build might require access to multiple private Git repositories, and access to
many private Docker repositories. You can use annotations to guide which secret many private Docker repositories. You can use annotations to guide which secret
to use to authenticate to different resources, for example: to use to authenticate to different resources, for example:
@ -205,7 +206,7 @@ stringData:
password: <cleartext non-encoded> password: <cleartext non-encoded>
``` ```
This describes a "Basic Auth" (username and password) secret which should be This describes a "Basic Auth" (username and password) secret that should be
used to access Git repos at github.com and gitlab.com, as well as Docker used to access Git repos at github.com and gitlab.com, as well as Docker
repositories at gcr.io. repositories at gcr.io.
@ -225,19 +226,19 @@ data:
known_hosts: <base64 encoded> known_hosts: <base64 encoded>
``` ```
This describes an SSH key secret which should be used to access Git repos at This describes an SSH key secret that should be used to access Git repos at
github.com only. github.com only.
Credential annotation keys must begin with `build.knative.dev/docker-` or Credential annotation keys must begin with `build.knative.dev/docker-` or
`build.knative.dev/git-` and the value describes the URL of the host with which to use `build.knative.dev/git-`, and the value describes the URL of the host with
the credential. which to use the credential.
## Implementation Detail ## Implementation detail
### Docker `basic-auth` ### Docker `basic-auth`
Given URLs, usernames, and passwords of the form: `https://url{n}.com`, Given URLs, usernames, and passwords of the form: `https://url{n}.com`,
`user{n}`, and `pass{n}`. We will generate the following for Docker: `user{n}`, and `pass{n}`, generate the following for Docker:
```json ```json
=== ~/.docker/config.json === === ~/.docker/config.json ===
@ -257,12 +258,12 @@ Given URLs, usernames, and passwords of the form: `https://url{n}.com`,
``` ```
Docker doesn't support `kubernetes.io/ssh-auth`, so annotations on these types Docker doesn't support `kubernetes.io/ssh-auth`, so annotations on these types
will be ignored. are ignored.
### Git `basic-auth` ### Git `basic-auth`
Given URLs, usernames, and passwords of the form: `https://url{n}.com`, Given URLs, usernames, and passwords of the form: `https://url{n}.com`,
`user{n}`, and `pass{n}`. We will generate the following for Git: `user{n}`, and `pass{n}`, generate the following for Git:
``` ```
=== ~/.gitconfig === === ~/.gitconfig ===
[credential] [credential]
@ -281,7 +282,7 @@ https://user2:pass2@url2.com
### Git `ssh-auth` ### Git `ssh-auth`
Given hostnames, private keys, and `known_hosts` of the form: `url{n}.com`, Given hostnames, private keys, and `known_hosts` of the form: `url{n}.com`,
`key{n}`, and `known_hosts{n}`. We will generate the following for Git: `key{n}`, and `known_hosts{n}`, generate the following for Git:
``` ```
=== ~/.ssh/id_key1 === === ~/.ssh/id_key1 ===
{contents of key1} {contents of key1}
@ -302,16 +303,16 @@ Host url2.com
... ...
``` ```
NOTE: Since `known_hosts` is a non-standard extension of Note: Because `known_hosts` is a non-standard extension of
`kubernetes.io/ssh-auth`, when it is not present this will be generated via `kubernetes.io/ssh-auth`, when it is not present this will be generated
`ssh-keygen url{n}.com ` instead. through `ssh-keygen url{n}.com ` instead.
### Least Privilege ### Least privilege
The secrets as outlined here will be stored into `$HOME` (by convention the The secrets as outlined here will be stored into `$HOME` (by convention the
volume: `/builder/home`), and will be available to `Source` and all `Steps`. volume: `/builder/home`), and will be available to `Source` and all `Steps`.
For sensitive credentials that should not be made available to some steps, the For sensitive credentials that should not be made available to some steps,
mechanisms outlined here should not be used. Instead the user should declare an do not use the mechanisms outlined here. Instead, the user should declare an
explicit `Volume` from the `Secret` and manually `VolumeMount` it into the explicit `Volume` from the `Secret` and manually `VolumeMount` it into the
`Step`. `Step`.