Skip to content

Commit 27349bb

Browse files
qu1queeequ1queee
authored
Enhance documentation for the Build authentication methods (#370)
* For #353 Add documentation on the Build authentication methods that can happen during runtime * add copyright headers
1 parent eb190ad commit 27349bb

File tree

3 files changed

+149
-1
lines changed

3 files changed

+149
-1
lines changed

‎HACK.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,9 @@ End-to-end tests can also be executed with the context of private Git repositori
144144
| `TEST_PRIVATE_GITLAB` | `spec.source.url` | Private URL, like `[email protected]` |
145145
| `TEST_SOURCE_SECRET` | `spec.source.credentials.name` | Private repository credentials |
146146

147-
On using `TEST_SOURCE_SECRET`, the environment variable must contain the name of the Kubernetes Secret containing SSH private key, for given private Git repository. See [ssh-authentication](https://github.com/tektoncd/pipeline/blob/master/docs/auth.md#ssh-authentication-git). The secret definition must define the following annotations:
147+
On using `TEST_SOURCE_SECRET`, the environment variable must contain the name of the Kubernetes Secret containing SSH private key, for given private Git repository. See the [docs](/docs/development/authentication.md) for more information about authentication methods in the Build.
148+
149+
The secret definition must define the following annotations:
148150
- `tekton.dev/git-0: github.com`
149151
- `tekton.dev/git-1: gitlab.com`
150152

‎docs/development/authentication.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
<!--
2+
Copyright The Shipwright Contributors
3+
4+
SPDX-License-Identifier: Apache-2.0
5+
-->
6+
7+
# Understanding authentication at runtime
8+
9+
The following document provides an introduction around the different authentication methods that can take place during an image build when using the Build operator.
10+
11+
- [Overview](#overview)
12+
- [Authentication for Git](#authentication-for-git)
13+
- [Basic authentication](#basic-authentication)
14+
- [SSH authentication](#ssh-authentication)
15+
- [Usage of git secret](#usage-of-git-secret)
16+
- [Authentication to container registries](#authentication-to-container-registries)
17+
- [Docker Hub](#docker-hub)
18+
- [Usage of registry secret](#usage-of-registry-secret)
19+
- [References](#references)
20+
21+
## Overview
22+
23+
There are two places where users might need to define authentication when building images. Authentication to a container registry is the most common one, but also users might have the need to define authentications for pulling source-code from Git.
24+
25+
## Authentication for Git
26+
27+
There are two ways for authenticating into Git (_applies to both GitLab or GitHub_). Also, see more information in the official Tekton [docs](https://github.com/tektoncd/pipeline/blob/master/docs/auth.md#configuring-ssh-auth-authentication-for-git).
28+
29+
### SSH authentication
30+
31+
For the SSH authentication you must use the tekton annotations to specify the hostname(s) of the git repository providers that you use. This is github.com for GitHub, or gitlab.com for GitLab.
32+
33+
As seen in the following example, there are three things to notice:
34+
35+
- The Kubernetes secret should be of the type `kubernetes.io/ssh-auth`
36+
- The annotations include a value to support both github and gitlab
37+
- The `data.ssh-privatekey` can be generated by following the command example `base64 <~/.ssh/id_rsa`, where `~/.ssh/id_rsa` is the key used to authenticate into Git.
38+
39+
```yaml
40+
apiVersion: v1
41+
kind: Secret
42+
metadata:
43+
name: secret-git-ssh-auth
44+
annotations:
45+
tekton.dev/git-0: github.com
46+
tekton.dev/git-1: gitlab.com
47+
type: kubernetes.io/ssh-auth
48+
data:
49+
ssh-privatekey: <base64 <~/.ssh/id_rsa>
50+
```
51+
52+
### Basic authentication
53+
54+
The Basic authentication is very similar to the ssh one, but with the following differences:
55+
56+
- The Kubernetes secret should be of the type `kubernetes.io/basic-auth`
57+
- The `stringData` should host your user and password in clear text.
58+
59+
```yaml
60+
apiVersion: v1
61+
kind: Secret
62+
metadata:
63+
name: secret-git-basic-auth
64+
annotations:
65+
tekton.dev/git-0: https://github.com
66+
tekton.dev/git-1: https://gitlab.com
67+
type: kubernetes.io/basic-auth
68+
stringData:
69+
username: <cleartext username>
70+
password: <cleartext password>
71+
```
72+
73+
### Usage of git secret
74+
75+
With the right secret in place(_note: Ensure creation of secret in the proper Kubernetes namespace_), users should reference it on their Build YAML definitions.
76+
77+
Depending on the secret type, there are two ways of doing this:
78+
79+
When using ssh auth, users should follow:
80+
81+
```yaml
82+
apiVersion: build.dev/v1alpha1
83+
kind: Build
84+
metadata:
85+
name: buildah-golang-build
86+
spec:
87+
source:
88+
url: [email protected]:eduardooli/newtaxi.git
89+
credentials:
90+
name: secret-git-ssh-auth
91+
```
92+
93+
When using basic auth, users should follow:
94+
95+
```yaml
96+
apiVersion: build.dev/v1alpha1
97+
kind: Build
98+
metadata:
99+
name: buildah-golang-build
100+
spec:
101+
source:
102+
url: https://gitlab.com/eduardooli/newtaxi.git
103+
credentials:
104+
name: secret-git-basic-auth
105+
```
106+
107+
## Authentication to container registries
108+
109+
For pushing images to private registries, users require to define a secret in their respective namespace.
110+
111+
### Docker Hub
112+
113+
Follow the following command to generate your secret:
114+
115+
```sh
116+
kubectl --namespace <YOUR_NAMESPACE> create secret docker-registry <CONTAINER_REGISTRY_SECRET_NAME> \
117+
--docker-server=<REGISTRY_HOST> \
118+
--docker-username=<USERNAME> \
119+
--docker-password=<PASSWORD> \
120+
[email protected]
121+
```
122+
123+
_Notes:_ When generating a secret to access docker hub, the `REGISTRY_HOST` value should be `https://index.docker.io/v1/`, the username is the Docker ID.
124+
_Notes:_ The value of `PASSWORD` can be your user docker hub password, or an access token. A docker access token can be created via _Account Settings_, then _Security_ in the sidebar, and the _New Access Token_ button.
125+
126+
### Usage of registry secret
127+
128+
With the right secret in place (_note: Ensure creation of secret in the proper Kubernetes namespace_), users should reference it on their Build YAML definitions.
129+
For container registries, the secret should be placed under the `spec.output.credentials` path.
130+
131+
```yaml
132+
apiVersion: build.dev/v1alpha1
133+
kind: Build
134+
metadata:
135+
name: buildah-golang-build
136+
...
137+
output:
138+
image: docker.io/foobar/sample:latest
139+
credentials:
140+
name: <CONTAINER_REGISTRY_SECRET_NAME>
141+
```
142+
143+
## References
144+
145+
See more information in the official Tekton [documentation](https://github.com/tektoncd/pipeline/blob/master/docs/auth.md#configuring-ssh-auth-authentication-for-git) for authentication.

‎docs/development/deploying.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ The following set of steps highlight how to deploy a Build operator pod into an
1616
docker push eeeoo/build-operator:master
1717
popd
1818
```
19+
1920
Just to illustrate the above, you can find the image in [dockerhub](https://hub.docker.com/repository/docker/eeeoo/build-operator)
2021

2122
2. Reference the generated image name in the [operator.yaml](../../deploy/operator.yaml). The `spec.template.containers[0].image` value should be modified.

0 commit comments

Comments
 (0)