docs: add registry authentication documentation (#1267)

Signed-off-by: Austin Vazquez <[email protected]>

README.md

@@ -143,16 +143,34 @@ memory: 4GiB
 snapshotters: 
     - soci
 
-# creds_helpers: a list of credential helpers that will be installed and configured automatically. 
-# Supported Credential Helpers List: 
+# creds_helpers: a list of credential helpers which can be used by Finch's container runtime stack. (optional)
+#
+# Finch currently supports Linux based credential helpers through its guest machine for macOS and Windows or natively
+# for Linux. All credential helpers are expected to have `docker-credential-*` naming convention.
+# Finch provides two modes of operation for credential helpers: managed and bring-your-own.
+#
+# Managed credential helpers:
+# Managed credential helpers are installed and configured by Finch. This means the credential helper binary will be downloaded
+# to the host machine and a config.json will be created and configured inside the $HOME/.finch directory if it does not already exist.
+# Finch will ensure the credential helper binary is made available to its container runtime stack with no additional action required by
+# the user.
+#
+# Supported list of managed credential helpers: 
 # - ecr-login https://github.com/awslabs/amazon-ecr-credential-helper
-# Once the option has been set the credential helper will be installed on either finch vm init or finch vm start. 
-# The binary will be downloaded on the host machine and a config.json will be created and populated inside the ~/.finch/ folder 
-# if it doesn't already exist. If it already exists, the value of credsStore will be overwritten. 
-# To opt out of using the credential helper, remove the value from the credsStore parameter of config.json 
-# and remove the creds_helper value from finch.yaml. 
-# To completely remove the credential helper, either remove the binary from ~/.finch/creds-helpers or remove the creds-helpers
-# folder entirely. (optional)
+#
+# Bring-your-own credential helpers:
+# Finch does offer support for users to bring their own credential helpers. In this use-case, users will still configure
+# the credential helper in finch.yaml similar to a managed credential helper; however, unlike managed credential helpers
+# users will also need to provide the credential helper binary through $HOME/.finch/cred-helpers. Finch will ensure
+# this binary is available to the container runtime stack in the guest machine. Note: Finch currently only supports
+# guest credential helper integration, therefore users will need to provide Linux credential helper binaries. Host
+# credential helper support is not yet available.
+#
+# For both managed and bring-your-own credential helpers, once configured in finch.yaml the user will need to run
+# finch vm init or finch vm start for the configuration to take affect. To remove credential helper integration, users
+# should remove the credential helper's configuration in $HOME/.finch/config.json and the creds_helpers configuration
+# from finch.yaml. To completely remove the credential helper, either remove the binary from $HOME/.finch/creds-helpers or
+# remove the directory entirely.
 creds_helpers: 
   - ecr-login
 

docs/registry-authentication.md

@@ -0,0 +1,84 @@
+# Registry Authentication
+
+Finch supports multiple methods for authenticating with container registries to push and pull images.
+
+## macOS and Windows
+
+### Credential Helpers (Recommended)
+
+Finch enables authentication using guest credential helpers. Guest credential helpers are expected to follow
+the `docker-credential-*` naming convention.
+
+Finch offers two types of credential helper integrations:
+
+1. Managed credential helpers
+1. Bring-Your-Own (BYO) credential helpers
+
+#### Managed Credential Helpers
+
+Managed credential helpers are installed and configured by Finch. This means the credential helper binary will be downloaded
+to the host machine and a config.json will be created and configured inside the `$HOME/.finch` directory if it does not already
+exist. Finch will ensure the credential helper binary is available to its container runtime stack with no additional action
+required by the user.
+
+##### Amazon ECR Credential Helper
+
+The Amazon ECR credential helper enables seamless authentication with Amazon Elastic Container Registry (ECR).
+This helper automatically handles the retrieval and renewal of ECR credentials for both public and private repositories.
+
+###### Installation and Setup
+
+1. Add `ecr-login` to `creds-helpers` in `finch.yaml`.
+
+    ```yaml
+    creds-helpers:
+      - ecr-login
+    ```
+
+1. Stop and start the Finch guest machine for configuration to take effect.
+
+    ```bash
+    finch vm stop
+    finch vm start
+    ```
+
+1. Verify credential helper configuration has been added to `$HOME/.finch/config.json`.
+For example:
+
+    ```json
+    {
+        "credsStore": "ecr-login"
+    }
+    ```
+
+#### Bring-Your-Own (BYO) Credential Helpers
+
+Bring-Your-Own credential helpers enables users to plug-and-play their own custom credential helpers.
+
+##### Installation and Setup
+
+1. Add credential helper to `creds-helpers` in `finch.yaml`.
+
+    ```yaml
+    creds-helpers:
+      - secretservice
+    ```
+
+1. Download and install the Linux credential helper binary to `$HOME/.finch/creds-helpers` directory.
+1. Add credential helper configuration to `$HOME/.finch/config.json`.
+
+### Basic username/password authentication
+
+Finch enables users to use basic username/password to authenticate with container image registries via `finch login` command.
+
+```bash
+localhost:~$ finch login
+Enter Username: username
+Enter Password: 
+```
+
+If the login has been successful, you should see:
+
+```bash
+Login Succeeded
+```