Skip to content

Commit 0c4cb02

Browse files
author
Souvik Sarkar
committed
authenticate pipelines using git secret
draft side frills minor corrections refactoring modifying aaaitional resources some more tweaks to xref anchors intermediate changes based on comments incorporating review comments incorporating review comments removed vale related stuff from gitignore small correction
1 parent 4aac378 commit 0c4cb02

12 files changed

+334
-5
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ dev_guide/builds/images/chained-build.png.cache
1414
.gem
1515
bin
1616
commercial_package
17+

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1467,6 +1467,8 @@ Topics:
14671467
File: using-pods-in-a-privileged-security-context
14681468
- Name: Securing webhooks with event listeners
14691469
File: securing-webhooks-with-event-listeners
1470+
- Name: Authenticating pipelines using git secret
1471+
File: authenticating-pipelines-using-git-secret
14701472
- Name: Viewing pipeline logs using the OpenShift Logging Operator
14711473
File: viewing-pipeline-logs-using-the-openshift-logging-operator
14721474
- Name: GitOps

‎cicd/pipelines/authenticating-pipelines-using-git-secret.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
[id="authenticating-pipelines-using-git-secret"]
2+
= Authenticating pipelines using git secret
3+
include::modules/common-attributes.adoc[]
4+
include::modules/pipelines-document-attributes.adoc[]
5+
:context: authenticating-pipelines-using-git-secret
6+
7+
toc::[]
8+
9+
A Git secret consists of credentials to securely interact with a Git repository, and is often used to automate authentication. In {pipelines-title}, you can use Git secrets to authenticate pipeline runs and task runs that interact with a Git repository during execution.
10+
11+
A pipeline run or a task run gains access to the secrets through the associated service account. {pipelines-shortname} support the use of Git secrets as annotations (key-value pairs) for basic authentication and SSH-based authentication.
12+
13+
include::modules/op-understanding-credential-selection.adoc[leveloffset=+1]
14+
15+
include::modules/op-configuring-basic-authentication-for-git.adoc[leveloffset=+1]
16+
17+
include::modules/op-configuring-ssh-authentication-for-git.adoc[leveloffset=+1]
18+
19+
include::modules/op-using-ssh-authentication-in-git-type-tasks.adoc[leveloffset=+1]
20+
21+
include::modules/op-using-secrets-as-a-nonroot-user.adoc[leveloffset=+1]
22+
23+
include::modules/op-limiting-secret-access-to-specific-steps.adoc[leveloffset=+1]

‎modules/op-about-pipelinerun.adoc

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,13 @@
33
// *openshift_pipelines/op-creating-applications-with-cicd-pipelines.adoc
44

55
[id="about-pipelinerun_{context}"]
6-
= Pipeline run
6+
= PipelineRun
77

8-
A _pipeline run_ is the running instance of a pipeline. It instantiates a pipeline for execution with specific inputs, outputs, and execution parameters on a cluster. A corresponding task run is created for each task automatically in the pipeline run.
8+
A `PipelineRun` is a type of resource that binds a pipeline, workspaces, credentials, and a set of parameter values specific to a scenario to run the CI/CD workflow.
99

10-
All the tasks in the pipeline are executed in the defined sequence until all tasks are successful or a task fails. The `status` field tracks and stores the progress of each task run in the pipeline run for monitoring and auditing purpose.
10+
A _pipeline run_ is the running instance of a pipeline. It instantiates a pipeline for execution with specific inputs, outputs, and execution parameters on a cluster. It also creates a task run for each task in the pipeline run.
11+
12+
The pipeline runs the tasks sequentially until they are complete or a task fails. The `status` field tracks and the progress of each task run and stores it for monitoring and auditing purposes.
1113

1214
The following example runs the `build-and-deploy` pipeline with relevant resources and parameters:
1315
[source,yaml]
@@ -37,8 +39,12 @@ spec:
3739
storage: 500Mi
3840
----
3941
<1> Pipeline run API version `v1beta1`.
40-
<2> Specifies the type of Kubernetes object. In this example, `PipelineRun`.
42+
<2> The type of Kubernetes object. In this example, `PipelineRun`.
4143
<3> Unique name to identify this pipeline run.
4244
<4> Name of the pipeline to be run. In this example, `build-and-deploy`.
43-
<5> Specifies the list of parameters required to run the pipeline.
45+
<5> The list of parameters required to run the pipeline.
4446
<6> Workspace used by the pipeline run.
47+
48+
.Additional resources
49+
50+
* xref:../../cicd/pipelines/authenticating-pipelines-using-git-secret.adoc#authenticating-pipelines-using-git-secret[Authenticating pipelines using git secret]

‎modules/op-configuring-basic-authentication-for-git.adoc

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *openshift-docs/cicd/pipelines/authenticating-pipelines-using-git-secret.adoc
4+
5+
[id="op-configuring-basic-authentication-for-git_{context}"]
6+
= Configuring basic authentication for Git
7+
8+
[role="_abstract"]
9+
For a pipeline to retrieve resources from password-protected repositories, you must configure the basic authentication for that pipeline.
10+
11+
To configure basic authentication for a pipeline, update the `secret.yaml`, `serviceaccount.yaml`, and `run.yaml` files with the credentials from the Git secret for the specified repository. When you complete this process, {pipelines-shortname} can use that information to retrieve the specified pipeline resources.
12+
13+
[NOTE]
14+
====
15+
For GitHub, authentication using plain password is deprecated. Instead, use a link:https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token[personal access token].
16+
====
17+
18+
.Procedure
19+
20+
. In the `secret.yaml` file, specify the username and password or link:https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token[GitHub personal access token] to access the target Git repository.
21+
+
22+
[source,yaml,subs="attributes+"]
23+
----
24+
apiVersion: v1
25+
kind: Secret
26+
metadata:
27+
name: basic-user-pass <1>
28+
annotations:
29+
tekton.dev/git-0: https://github.com
30+
type: kubernetes.io/basic-auth
31+
stringData:
32+
username: <2>
33+
password: <3>
34+
----
35+
<1> Name of the secret. In this example, `basic-user-pass`.
36+
<2> Username for the Git repository.
37+
<3> Password for the Git repository.
38+
39+
+
40+
. In the `serviceaccount.yaml` file, associate the secret with the appropriate service account.
41+
+
42+
[source,yaml,subs="attributes+"]
43+
----
44+
apiVersion: v1
45+
kind: ServiceAccount
46+
metadata:
47+
name: build-bot <1>
48+
secrets:
49+
- name: basic-user-pass <2>
50+
----
51+
<1> Name of the service account. In this example, `build-bot`.
52+
<2> Name of the secret. In this example, `basic-user-pass`.
53+
+
54+
. In the `run.yaml` file, associate the service account with a task run or a pipeline run.
55+
+
56+
* Associate the service account with a task run:
57+
+
58+
[source,yaml,subs="attributes+"]
59+
----
60+
apiVersion: tekton.dev/v1beta1
61+
kind: TaskRun
62+
metadata:
63+
name: build-push-task-run-2 <1>
64+
spec:
65+
serviceAccountName: build-bot <2>
66+
taskRef:
67+
name: build-push <3>
68+
----
69+
<1> Name of the task run. In this example, `build-push-task-run-2`.
70+
<2> Name of the service account. In this example, `build-bot`.
71+
<3> Name of the task. In this example, `build-push`.
72+
+
73+
* Associate the service account with a `PipelineRun` resource:
74+
+
75+
[source,yaml,subs="attributes+"]
76+
----
77+
apiVersion: tekton.dev/v1beta1
78+
kind: PipelineRun
79+
metadata:
80+
name: demo-pipeline <1>
81+
namespace: default
82+
spec:
83+
serviceAccountName: build-bot <2>
84+
pipelineRef:
85+
name: demo-pipeline <3>
86+
----
87+
<1> Name of the pipeline run. In this example, `demo-pipeline`.
88+
<2> Name of the service account. In this example, `build-bot`.
89+
<3> Name of the pipeline. In this example, `demo-pipeline`.
90+
+
91+
. Apply the changes.
92+
+
93+
[source,terminal]
94+
----
95+
$ kubectl apply --filename secret.yaml,serviceaccount.yaml,run.yaml
96+
----

‎modules/op-configuring-ssh-authentication-for-git.adoc

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *openshift-docs/cicd/pipelines/authenticating-pipelines-using-git-secret.adoc
4+
5+
[id="op-configuring-ssh-authentication-for-git_{context}"]
6+
= Configuring SSH authentication for Git
7+
8+
[role="_abstract"]
9+
For a pipeline to retrieve resources from repositories configured with SSH keys, you must configure the SSH-based authentication for that pipeline.
10+
11+
To configure SSH-based authentication for a pipeline, update the `secret.yaml`, `serviceaccount.yaml`, and `run.yaml` files with the credentials from the SSH private key for the specified repository. When you complete this process, {pipelines-shortname} can use that information to retrieve the specified pipeline resources.
12+
13+
[NOTE]
14+
====
15+
Consider using SSH-based authentication rather than basic authentication.
16+
====
17+
18+
.Procedure
19+
20+
. Generate an link:https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent[SSH private key], or copy an existing private key, which is usually available in the `~/.ssh/id_rsa` file.
21+
. In the `secret.yaml` file, set the value of `ssh-privatekey` to the name of the SSH private key file, and set the value of `known_hosts` to the name of the known hosts file.
22+
+
23+
[source,yaml,subs="attributes+"]
24+
----
25+
apiVersion: v1
26+
kind: Secret
27+
metadata:
28+
name: ssh-key <1>
29+
annotations:
30+
tekton.dev/git-0: github.com
31+
type: kubernetes.io/ssh-auth
32+
stringData:
33+
ssh-privatekey: <2>
34+
known_hosts: <3>
35+
----
36+
<1> Name of the secret containing the SSH private key. In this example, `ssh-key`.
37+
<2> Name of the file containing the SSH private key string.
38+
<3> Name of the file containing a list of known hosts.
39+
+
40+
[CAUTION]
41+
====
42+
If you omit the private key, {pipelines-shortname} accepts the public key of any server.
43+
====
44+
+
45+
. Optional: To specify a custom SSH port, add `:<port number>` to the end of the `annotation` value. For example, `tekton.dev/git-0: github.com:2222`.
46+
. In the `serviceaccount.yaml` file, associate the `ssh-key` secret with the `build-bot` service account.
47+
+
48+
[source,yaml,subs="attributes+"]
49+
----
50+
apiVersion: v1
51+
kind: ServiceAccount
52+
metadata:
53+
name: build-bot <1>
54+
secrets:
55+
- name: ssh-key <2>
56+
----
57+
<1> Name of the service account. In this example, `build-bot`.
58+
<2> Name of the secret containing the SSH private key. In this example, `ssh-key`.
59+
+
60+
. In the `run.yaml` file, associate the service account with a task run or a pipeline run.
61+
+
62+
* Associate the service account with a task run:
63+
+
64+
[source,yaml,subs="attributes+"]
65+
----
66+
apiVersion: tekton.dev/v1beta1
67+
kind: TaskRun
68+
metadata:
69+
name: build-push-task-run-2 <1>
70+
spec:
71+
serviceAccountName: build-bot <2>
72+
taskRef:
73+
name: build-push <3>
74+
----
75+
<1> Name of the task run. In this example, `build-push-task-run-2`.
76+
<2> Name of the service account. In this example, `build-bot`.
77+
<3> Name of the task. In this example, `build-push`.
78+
+
79+
* Associate the service account with a pipeline run:
80+
+
81+
[source,yaml,subs="attributes+"]
82+
----
83+
apiVersion: tekton.dev/v1beta1
84+
kind: PipelineRun
85+
metadata:
86+
name: demo-pipeline <1>
87+
namespace: default
88+
spec:
89+
serviceAccountName: build-bot <2>
90+
pipelineRef:
91+
name: demo-pipeline <3>
92+
----
93+
<1> Name of the pipeline run. In this example, `demo-pipeline`.
94+
<2> Name of the service account. In this example, `build-bot`.
95+
<3> Name of the pipeline. In this example, `demo-pipeline`.
96+
+
97+
. Apply the changes.
98+
+
99+
[source,terminal]
100+
----
101+
$ kubectl apply --filename secret.yaml,serviceaccount.yaml,run.yaml
102+
----

‎modules/op-limiting-secret-access-to-specific-steps.adoc

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *openshift-docs/cicd/pipelines/authenticating-pipelines-using-git-secret.adoc
4+
5+
[id="op-limiting-secret-access-to-specific-steps_{context}"]
6+
= Limiting secret access to specific steps
7+
8+
By default, the secrets for {pipelines-shortname} are stored in the `$HOME/tekton/home` directory, and are available for all the steps in a task.
9+
10+
To limit a secret to specific steps, use the secret definition to specify a volume, and mount the volume in specific steps.

‎modules/op-running-a-pipeline.adoc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,3 +85,7 @@ Note the output of the previous command. You can access the application using th
8585
----
8686
$ tkn pipeline start build-and-deploy --last
8787
----
88+
89+
.Additional resources
90+
91+
* xref:../../cicd/pipelines/authenticating-pipelines-using-git-secret.adoc#authenticating-pipelines-using-git-secret[Authenticating pipelines using git secret]

‎modules/op-starting-pipelines.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,15 @@ Select *Add Credentials* if you want to specify an additional *Registry Server A
3333

3434
* For the *Authentication Type* `Basic Authentication`, specify the values for the *UserName* and *Password or Token* fields.
3535
* For the *Authentication Type* `SSH Keys`, specify the value of the *SSH Private Key* field.
36+
+
37+
[NOTE]
38+
====
39+
For basic authentication and SSH authentication, you can use annotations such as:
40+
41+
* `tekton.dev/git-0: https://github.com`
42+
* `tekton.dev/git-1: https://gitlab.com`.
43+
====
44+
+
3645
... Select the check mark to add the secret.
3746

3847
+

‎modules/op-understanding-credential-selection.adoc

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *openshift-docs/cicd/pipelines/authenticating-pipelines-using-git-secret.adoc
4+
5+
[id="op-understanding-credential-selection_{context}"]
6+
= Credential selection
7+
8+
A pipeline run or task run might require multiple authentications to access different Git repositories. Annotate each secret with the domains where {pipelines-shortname} can use its credentials.
9+
10+
A credential annotation key for Git secrets must begin with `tekton.dev/git-`, and its value is the URL of the host for which you want {pipelines-shortname} to use that credential.
11+
12+
In the following example, {pipelines-shortname} uses a `basic-auth` secret, which relies on a username and password, to access repositories at `github.com` and `gitlab.com`.
13+
14+
.Example: Multiple credentials for basic authentication
15+
[source,yaml,subs="attributes+"]
16+
----
17+
apiVersion: v1
18+
kind: Secret
19+
metadata:
20+
annotations:
21+
tekton.dev/git-0: github.com
22+
tekton.dev/git-1: gitlab.com
23+
type: kubernetes.io/basic-auth
24+
stringData:
25+
username: <1>
26+
password: <2>
27+
----
28+
<1> Username for the repository
29+
<2> Password or personal access token for the repository
30+
31+
You can also use an `ssh-auth` secret (private key) to access a Git repository.
32+
33+
.Example: Private key for SSH based authentication
34+
[source,yaml,subs="attributes+"]
35+
----
36+
apiVersion: v1
37+
kind: Secret
38+
metadata:
39+
annotations:
40+
tekton.dev/git-0: https://github.com
41+
type: kubernetes.io/ssh-auth
42+
stringData:
43+
ssh-privatekey: <1>
44+
----
45+
<1> Name of the file containing the SSH private key string.

0 commit comments

Comments
 (0)