forked from shipwright-io/website
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Generate adoc copies in /content/en/docs to shipwright-io#78
- Loading branch information
Showing
10 changed files
with
2,081 additions
and
43 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,6 +8,3 @@ PLATFORMS | |
|
|
||
| DEPENDENCIES | ||
| asciidoctor (~> 2.0, >= 2.0.17) | ||
|
|
||
| BUNDLED WITH | ||
| 2.3.7 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,165 @@ | ||
| --- | ||
| title: Authentication during builds | ||
| --- | ||
|
|
||
| :toc: | ||
| :toclevels: 4 | ||
|
|
||
| The following document provides an introduction around the different authentication methods that can take place during an image build when using the Build controller. | ||
|
|
||
| == Overview | ||
|
|
||
| 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. Overall, the authentication is done via the definition of https://kubernetes.io/docs/concepts/configuration/secret/[secrets] in which the require sensitive data will be stored. | ||
|
|
||
| == Build Secrets Annotation | ||
|
|
||
| Users need to add an annotation `build.shipwright.io/referenced.secret: "true"` to a build secret so that build controller can decide to take a reconcile action when a secret event (`create`, `update` and `delete`) happens. Below is a secret example with build annotation: | ||
|
|
||
| [source,yaml] | ||
| ---- | ||
| apiVersion: v1 | ||
| data: | ||
| .dockerconfigjson: xxxxx | ||
| kind: Secret | ||
| metadata: | ||
| annotations: | ||
| build.shipwright.io/referenced.secret: "true" | ||
| name: secret-docker | ||
| type: kubernetes.io/dockerconfigjson | ||
| ---- | ||
|
|
||
| This annotation will help us filter secrets which are not referenced on a Build instance. That means if a secret doesn't have this annotation, then although event happens on this secret, Build controller will not reconcile. Being able to reconcile on secrets events allow the Build controller to re-trigger validations on the Build configuration, allowing users to understand if a dependency is missing. | ||
|
|
||
| If you are using `kubectl` command create secrets, then you can first create build secret using `kubectl create secret` command and annotate this secret using `kubectl annotate secrets`. Below is an example: | ||
|
|
||
| [source,terminal] | ||
| ---- | ||
| kubectl -n ${namespace} create secret docker-registry example-secret --docker-server=${docker-server} --docker-username="${username}" --docker-password="${password}" [email protected] | ||
| kubectl -n ${namespace} annotate secrets example-secret build.shipwright.io/referenced.secret='true' | ||
| ---- | ||
|
|
||
| == Authentication for Git | ||
|
|
||
| There are two ways for authenticating into Git (_applies to both GitLab or GitHub_): SSH and basic authentication. | ||
|
|
||
| === SSH authentication | ||
|
|
||
| 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. | ||
|
|
||
| As seen in the following example, there are three things to notice: | ||
|
|
||
| * The Kubernetes secret should be of the type `kubernetes.io/ssh-auth` | ||
| * 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. | ||
|
|
||
| [source,yaml] | ||
| ---- | ||
| apiVersion: v1 | ||
| kind: Secret | ||
| metadata: | ||
| name: secret-git-ssh-auth | ||
| annotations: | ||
| build.shipwright.io/referenced.secret: "true" | ||
| type: kubernetes.io/ssh-auth | ||
| data: | ||
| ssh-privatekey: <base64 <~/.ssh/id_rsa> | ||
| ---- | ||
|
|
||
| === Basic authentication | ||
|
|
||
| The Basic authentication is very similar to the ssh one, but with the following differences: | ||
|
|
||
| * The Kubernetes secret should be of the type `kubernetes.io/basic-auth` | ||
| * The `stringData` should host your user and password in clear text. | ||
|
|
||
| [source,yaml] | ||
| ---- | ||
| apiVersion: v1 | ||
| kind: Secret | ||
| metadata: | ||
| name: secret-git-basic-auth | ||
| annotations: | ||
| build.shipwright.io/referenced.secret: "true" | ||
| type: kubernetes.io/basic-auth | ||
| stringData: | ||
| username: <cleartext username> | ||
| password: <cleartext password> | ||
| ---- | ||
|
|
||
| === Usage of git secret | ||
|
|
||
| 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. | ||
|
|
||
| Depending on the secret type, there are two ways of doing this: | ||
|
|
||
| When using ssh auth, users should follow: | ||
|
|
||
| [source,yaml] | ||
| ---- | ||
| apiVersion: shipwright.io/v1alpha1 | ||
| kind: Build | ||
| metadata: | ||
| name: buildah-golang-build | ||
| spec: | ||
| source: | ||
| url: [email protected]:eduardooli/newtaxi.git | ||
| credentials: | ||
| name: secret-git-ssh-auth | ||
| ---- | ||
|
|
||
| When using basic auth, users should follow: | ||
|
|
||
| [source,yaml] | ||
| ---- | ||
| apiVersion: shipwright.io/v1alpha1 | ||
| kind: Build | ||
| metadata: | ||
| name: buildah-golang-build | ||
| spec: | ||
| source: | ||
| url: https://gitlab.com/eduardooli/newtaxi.git | ||
| credentials: | ||
| name: secret-git-basic-auth | ||
| ---- | ||
|
|
||
| == Authentication to container registries | ||
|
|
||
| For pushing images to private registries, users require to define a secret in their respective namespace. | ||
|
|
||
| === Docker Hub | ||
|
|
||
| Follow the following command to generate your secret: | ||
|
|
||
| [source,terminal] | ||
| ---- | ||
| kubectl --namespace <YOUR_NAMESPACE> create secret docker-registry <CONTAINER_REGISTRY_SECRET_NAME> \ | ||
| --docker-server=<REGISTRY_HOST> \ | ||
| --docker-username=<USERNAME> \ | ||
| --docker-password=<PASSWORD> \ | ||
| [email protected] | ||
| kubectl --namespace <YOUR_NAMESPACE> annotate secrets <CONTAINER_REGISTRY_SECRET_NAME> build.shipwright.io/referenced.secret='true' | ||
| ---- | ||
|
|
||
| _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. | ||
| _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. | ||
|
|
||
| === Usage of registry secret | ||
|
|
||
| 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. | ||
| For container registries, the secret should be placed under the `spec.output.credentials` path. | ||
|
|
||
| [source,yaml] | ||
| ---- | ||
| apiVersion: shipwright.io/v1alpha1 | ||
| kind: Build | ||
| metadata: | ||
| name: buildah-golang-build | ||
| ... | ||
| output: | ||
| image: docker.io/foobar/sample:latest | ||
| credentials: | ||
| name: <CONTAINER_REGISTRY_SECRET_NAME> | ||
| ---- | ||
|
|
||
| == References | ||
|
|
||
| See more information in the official Tekton https://github.com/tektoncd/pipeline/blob/main/docs/auth.md#configuring-ssh-auth-authentication-for-git[documentation] for authentication. |
Oops, something went wrong.