Skip to content

Commit 23ab9ff

Browse files
abrennan89abrennan89
authored
Merge pull request #37610 from sounix000/authenticating-pipelines-using-git-secret-RHDEVDOCS-2815
RHDEVDOCS-2815 Authenticating pipelines using git secret
2 parents ac4e691 + 0c4cb02 commit 23ab9ff

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)