diff --git a/docs/development/authentication.md b/docs/development/authentication.md index 25642cc83..8aef9e9d6 100644 --- a/docs/development/authentication.md +++ b/docs/development/authentication.md @@ -9,6 +9,7 @@ SPDX-License-Identifier: Apache-2.0 The following document provides an introduction around the different authentication methods that can take place during an image build when using the Build operator. - [Overview](#overview) +- [Build Secrets Annotation](#build-secrets-annotation) - [Authentication for Git](#authentication-for-git) - [Basic authentication](#basic-authentication) - [SSH authentication](#ssh-authentication) @@ -20,7 +21,32 @@ The following document provides an introduction around the different authenticat ## 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. +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 definion of [secrets](https://kubernetes.io/docs/concepts/configuration/secret/) in which the require sensitive data will be stored. + +## Build Secrets Annotation + +Users need to add an annotation `build.build.dev/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: + +```yaml +apiVersion: v1 +data: + .dockerconfigjson: xxxxx +kind: Secret +metadata: + annotations: + build.build.dev/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: + +```sh +kubectl -n ${namespace} create secret docker-registry example-secret --docker-server=${docker-server} --docker-username="${username}" --docker-password="${password}" --docker-email=me@here.com +kubectl -n ${namespace} annotate secrets example-secret build.build.dev/referenced.secret='true' +``` ## Authentication for Git @@ -44,6 +70,7 @@ metadata: annotations: tekton.dev/git-0: github.com tekton.dev/git-1: gitlab.com + build.build.dev/referenced.secret: "true" type: kubernetes.io/ssh-auth data: ssh-privatekey: @@ -64,6 +91,7 @@ metadata: annotations: tekton.dev/git-0: https://github.com tekton.dev/git-1: https://gitlab.com + build.build.dev/referenced.secret: "true" type: kubernetes.io/basic-auth stringData: username: @@ -118,6 +146,7 @@ kubectl --namespace create secret docker-registry \ --docker-password= \ --docker-email=me@here.com +kubectl --namespace annotate secrets build.build.dev/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.