mirror of https://github.com/knative/docs.git
Update auth.md (#137)
Copy edits, and shift to procedural steps for setting up authentication.
This commit is contained in:
Peter Delaney
Google Prow Robot
parent
f68f841dcf
commit
168b37d087
221
build/auth.md
221
build/auth.md
|
|
@ -1,6 +1,6 @@
|
|||
# Authentication
|
||||
|
||||
This document serves to define how authentication is provided during execution
|
||||
This document defines how authentication is provided during execution
|
||||
of a build.
|
||||
|
||||
The build system supports two types of authentication, using Kuberernetes'
|
||||
|
|
@ -9,7 +9,7 @@ first-class `Secret` types:
|
|||
* `kubernetes.io/basic-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.
|
||||
|
||||
### 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
|
||||
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,
|
||||
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.
|
||||
|
||||
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
|
||||
into their respective files in `$HOME`.
|
||||
|
||||
## SSH authentication (Git)
|
||||
|
||||
First, define a `Secret` containing your SSH private key.
|
||||
1. Define a `Secret` containing your SSH private key:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: ssh-key
|
||||
annotations:
|
||||
build.knative.dev/git-0: https://github.com # Described below
|
||||
type: kubernetes.io/ssh-auth
|
||||
data:
|
||||
type: kubernetes.io/ssh-auth
|
||||
data:
|
||||
ssh-privatekey: <base64 encoded>
|
||||
# This is non-standard, but its use is encouraged to make this more secure.
|
||||
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
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: build-bot
|
||||
secrets:
|
||||
- name: ssh-key
|
||||
```
|
||||
secrets:
|
||||
- name: ssh-key
|
||||
```
|
||||
|
||||
Then use that `ServiceAccount` in your `Build`:
|
||||
1. Then use that `ServiceAccount` in your `Build`:
|
||||
|
||||
```yaml
|
||||
apiVersion: build.knative.dev/v1alpha1
|
||||
kind: Build
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: build.knative.dev/v1alpha1
|
||||
kind: Build
|
||||
metadata:
|
||||
name: build-with-ssh-auth
|
||||
spec:
|
||||
spec:
|
||||
serviceAccountName: build-bot
|
||||
steps:
|
||||
...
|
||||
```
|
||||
```
|
||||
|
||||
To execute the build:
|
||||
1. Execute the build:
|
||||
|
||||
```shell
|
||||
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
|
||||
```
|
||||
```shell
|
||||
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Basic Authentication (Git)
|
||||
## Basic authentication (Git)
|
||||
|
||||
First, define a `Secret` containing the base64-encoded username and password
|
||||
the build should use to authenticate to a Git repository.
|
||||
1. Define a `Secret` containing the base64-encoded username and password
|
||||
that the build should use to authenticate to a Git repository:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: basic-user-pass
|
||||
annotations:
|
||||
build.knative.dev/git-0: https://github.com # Described below
|
||||
type: kubernetes.io/basic-auth
|
||||
data:
|
||||
type: kubernetes.io/basic-auth
|
||||
data:
|
||||
username: <base64 encoded>
|
||||
password: <base64 encoded>
|
||||
```
|
||||
```
|
||||
|
||||
Next, direct a `ServiceAccount` to use this `Secret`:
|
||||
1. Next, direct a `ServiceAccount` to use this `Secret`:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: build-bot
|
||||
secrets:
|
||||
- name: basic-user-pass
|
||||
```
|
||||
secrets:
|
||||
- name: basic-user-pass
|
||||
```
|
||||
|
||||
Then use that `ServiceAccount` in your `Build`:
|
||||
1. Use that `ServiceAccount` in your `Build`:
|
||||
|
||||
```yaml
|
||||
apiVersion: build.knative.dev/v1alpha1
|
||||
kind: Build
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: build.knative.dev/v1alpha1
|
||||
kind: Build
|
||||
metadata:
|
||||
name: build-with-basic-auth
|
||||
spec:
|
||||
spec:
|
||||
serviceAccountName: build-bot
|
||||
steps:
|
||||
...
|
||||
```
|
||||
```
|
||||
|
||||
To execute the build:
|
||||
1. Execute the build:
|
||||
|
||||
```shell
|
||||
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
|
||||
```
|
||||
```shell
|
||||
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
|
||||
```
|
||||
|
||||
When this build executes, before steps execute, a `~/.gitconfig` will be
|
||||
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
|
||||
the build should use to authenticate to a Docker registry.
|
||||
1. Define a `Secret` containing the base64-encoded username and password
|
||||
that the build should use to authenticate to a Docker registry:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: basic-user-pass
|
||||
annotations:
|
||||
build.knative.dev/docker-0: https://gcr.io # Described below
|
||||
type: kubernetes.io/basic-auth
|
||||
data:
|
||||
type: kubernetes.io/basic-auth
|
||||
data:
|
||||
username: <base64 encoded>
|
||||
password: <base64 encoded>
|
||||
```
|
||||
```
|
||||
|
||||
Next, direct a `ServiceAccount` to use this `Secret`:
|
||||
1. Direct a `ServiceAccount` to use this `Secret`:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: build-bot
|
||||
secrets:
|
||||
- name: basic-user-pass
|
||||
```
|
||||
secrets:
|
||||
- name: basic-user-pass
|
||||
```
|
||||
|
||||
Then use that `ServiceAccount` in your `Build`:
|
||||
1. Use that `ServiceAccount` in your `Build`:
|
||||
|
||||
```yaml
|
||||
apiVersion: build.knative.dev/v1alpha1
|
||||
kind: Build
|
||||
metadata:
|
||||
```yaml
|
||||
apiVersion: build.knative.dev/v1alpha1
|
||||
kind: Build
|
||||
metadata:
|
||||
name: build-with-basic-auth
|
||||
spec:
|
||||
spec:
|
||||
serviceAccountName: build-bot
|
||||
steps:
|
||||
...
|
||||
```
|
||||
```
|
||||
|
||||
To execute the build:
|
||||
1. Execute the build:
|
||||
|
||||
```shell
|
||||
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
|
||||
```
|
||||
```shell
|
||||
kubectl apply -f secret.yaml serviceaccount.yaml build.yaml
|
||||
```
|
||||
|
||||
When this build executes, before steps execute, a `~/.docker/config.json` will
|
||||
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
|
||||
|
||||
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
|
||||
many private Docker repositories. You can use annotations to guide which secret
|
||||
to use to authenticate to different resources, for example:
|
||||
|
|
@ -205,7 +206,7 @@ stringData:
|
|||
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
|
||||
repositories at gcr.io.
|
||||
|
||||
|
|
@ -225,19 +226,19 @@ data:
|
|||
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.
|
||||
|
||||
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
|
||||
the credential.
|
||||
`build.knative.dev/git-`, and the value describes the URL of the host with
|
||||
which to use the credential.
|
||||
|
||||
## Implementation Detail
|
||||
## Implementation detail
|
||||
|
||||
### Docker `basic-auth`
|
||||
|
||||
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
|
||||
=== ~/.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
|
||||
will be ignored.
|
||||
are ignored.
|
||||
|
||||
### Git `basic-auth`
|
||||
|
||||
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 ===
|
||||
[credential]
|
||||
|
|
@ -281,7 +282,7 @@ https://user2:pass2@url2.com
|
|||
### Git `ssh-auth`
|
||||
|
||||
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 ===
|
||||
{contents of key1}
|
||||
|
|
@ -302,16 +303,16 @@ Host url2.com
|
|||
...
|
||||
```
|
||||
|
||||
NOTE: Since `known_hosts` is a non-standard extension of
|
||||
`kubernetes.io/ssh-auth`, when it is not present this will be generated via
|
||||
`ssh-keygen url{n}.com ` instead.
|
||||
Note: Because `known_hosts` is a non-standard extension of
|
||||
`kubernetes.io/ssh-auth`, when it is not present this will be generated
|
||||
through `ssh-keygen url{n}.com ` instead.
|
||||
|
||||
### Least Privilege
|
||||
### Least privilege
|
||||
|
||||
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`.
|
||||
|
||||
For sensitive credentials that should not be made available to some steps, the
|
||||
mechanisms outlined here should not be used. Instead the user should declare an
|
||||
For sensitive credentials that should not be made available to some steps,
|
||||
do not use the mechanisms outlined here. Instead, the user should declare an
|
||||
explicit `Volume` from the `Secret` and manually `VolumeMount` it into the
|
||||
`Step`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue