From 168b37d087c97083a385ff3aaa21d98e9913b6db Mon Sep 17 00:00:00 2001 From: Peter Delaney Date: Tue, 17 Jul 2018 17:38:31 -0700 Subject: [PATCH] Update auth.md (#137) Copy edits, and shift to procedural steps for setting up authentication. --- build/auth.md | 283 +++++++++++++++++++++++++------------------------- 1 file changed, 142 insertions(+), 141 deletions(-) diff --git a/build/auth.md b/build/auth.md index ba4a2a912..7ddcab0e4 100644 --- a/build/auth.md +++ b/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: - name: ssh-key - annotations: - build.knative.dev/git-0: https://github.com # Described below -type: kubernetes.io/ssh-auth -data: - ssh-privatekey: - # This is non-standard, but its use is encouraged to make this more secure. - known_hosts: -``` + ```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: + ssh-privatekey: + # This is non-standard, but its use is encouraged to make this more secure. + known_hosts: + ``` -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: - name: build-bot -secrets: -- name: ssh-key -``` + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: build-bot + 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: - name: build-with-ssh-auth -spec: - serviceAccountName: build-bot - steps: - ... -``` + ```yaml + apiVersion: build.knative.dev/v1alpha1 + kind: Build + metadata: + name: build-with-ssh-auth + 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: - name: basic-user-pass - annotations: - build.knative.dev/git-0: https://github.com # Described below -type: kubernetes.io/basic-auth -data: - username: - password: -``` + ```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: + username: + password: + ``` -Next, direct a `ServiceAccount` to use this `Secret`: +1. Next, direct a `ServiceAccount` to use this `Secret`: -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: build-bot -secrets: -- name: basic-user-pass -``` + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: build-bot + 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: - name: build-with-basic-auth -spec: - serviceAccountName: build-bot - steps: - ... -``` + ```yaml + apiVersion: build.knative.dev/v1alpha1 + kind: Build + metadata: + name: build-with-basic-auth + 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: - name: basic-user-pass - annotations: - build.knative.dev/docker-0: https://gcr.io # Described below -type: kubernetes.io/basic-auth -data: - username: - password: -``` + ```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: + username: + password: + ``` -Next, direct a `ServiceAccount` to use this `Secret`: +1. Direct a `ServiceAccount` to use this `Secret`: -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: build-bot -secrets: -- name: basic-user-pass -``` + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: build-bot + 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: - name: build-with-basic-auth -spec: - serviceAccountName: build-bot - steps: - ... -``` + ```yaml + apiVersion: build.knative.dev/v1alpha1 + kind: Build + metadata: + name: build-with-basic-auth + 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: ``` -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: ``` -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`.