add docs for blob auth

Signed-off-by: Bohan Chen <bohanc@vmware.com>

Author: Bohan Chen

docs/build.md

@@ -95,6 +95,10 @@ The `source` field is a composition of a source code location and a `subpath`. I
     - `git`: (Source Code is a git repository)
         - `url`: The git repository url. Both https and ssh formats are supported; with ssh format requiring a [ssh secret](secrets.md#git-secrets).
         - `revision`: The git revision to use. This value may be a commit sha, branch name, or tag.
+        - `auth`: Optional auth to use with blob source. Leave empty for no auth, "secret" for providing auth [via Secret](secrets.md#blob-secrets), or "helper" to use service account IAM (specific to each IaaS).
+             > Note: Only [Microsoft Azure](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview)
+             > and [Google Cloud Platform](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#kubernetes-sa-to-iam)
+             > helpers are currently implemented, contributions are welcome to `pkg/blob/<iaas>_keychain.go`.
     - `subPath`: A subdirectory within the source folder where application code resides. Can be ignored if the source code resides at the `root` level.
 
 * Blob

docs/image.md

@@ -99,11 +99,16 @@ The `source` field is a composition of a source code location and a `subpath`. I
       blob:
         url: ""
         stripComponents: 0
+        auth: "" | "secret" | "helper"
       subPath: ""
     ```
     - `blob`: (Source Code is a blob/jar in a blobstore)
         - `url`: The URL of the source code blob. This blob needs to either be publicly accessible or have the access token in the URL
         - `stripComponents`: Optional number of directory components to strip from the blobs content when extracting.
+        - `auth`: Optional auth to use with blob source. Leave empty for no auth, "secret" for providing auth [via Secret](secrets.md#blob-secrets), or "helper" to use service account IAM (specific to each IaaS).
+             > Note: Only [Microsoft Azure](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview)
+             > and [Google Cloud Platform](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#kubernetes-sa-to-iam)
+             > helpers are currently implemented, contributions are welcome to `pkg/blob/<iaas>_keychain.go`.
     - `subPath`: A subdirectory within the source folder where application code resides. Can be ignored if the source code resides at the `root` level.
 
 * Registry

docs/secrets.md

@@ -126,6 +126,26 @@ stringData:
   password: <generated-token>
 ```
 
+### Blob Secrets
+
+Secrets are used with a `kpack.io/blob` annotation that references a hostname for a blob location. Only one of username/password, bearer, or authorization is allowed.
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: blob-secret
+  annotations:
+    kpack.io/blob: my-blob-store.com
+stringData:
+  username: <username>
+  password: <password>
+
+  bearer: <oauth2 token>
+
+  authorization: <third-party-auth-header>
+```
+
 ### Service Account
 
 To use these secrets with kpack create a service account and reference the service account in image and build resources. When configuring the image resource, reference the `name` of your registry credential and the `name` of your git credential.