Enhance auth document with a build secret annotation

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:
+
+```yaml
+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.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: <base64 <~/.ssh/id_rsa>
@@ -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: <cleartext username>
@@ -118,6 +146,7 @@ kubectl --namespace <YOUR_NAMESPACE> create secret docker-registry <CONTAINER_RE
   --docker-username=<USERNAME> \
   --docker-password=<PASSWORD> \
   [email protected]
+kubectl --namespace <YOUR_NAMESPACE> annotate secrets docker-registry 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.