docs: Refactor docs (#398)

* docs: Refactor docs

Signed-off-by: jannfis <jann@mistrust.net>

* Fix spelling

Signed-off-by: jannfis <jann@mistrust.net>

* Fix spelling

Signed-off-by: jannfis <jann@mistrust.net>

* Sort expect

Signed-off-by: jannfis <jann@mistrust.net>

1 files changed, 245 insertions, 0 deletions

diff --git a/docs/basics/authentication.md b/docs/basics/authentication.md
new file mode 100644
index 0000000..ffcc343
--- /dev/null
+++ b/docs/basics/authentication.md
@@ -0,0 +1,245 @@
+# Authentication in Argo CD Image Updater
+
+There are several scenarios where Argo CD Image Updater needs to authenticate
+to external systems in order to fulfil its duties. 
+
+## <a name="auth-kubernetes"></a>Authentication to Kubernetes
+
+If you are running Argo CD Image Updater as a Kubernetes workload in the
+`kubernetes` API access mode (which is the default), it uses the token of a
+ServiceAccount mounted to its pod to authenticate at the Kubernetes API.
+
+The name of this ServiceAccount is `argocd-image-updater`, and it gets
+created through the installation manifests in the installation namespace.
+The ServiceAccount is accompanied with an appropriate Kubernetes RBAC
+Role that holds the required permissions, and a RoleBinding to bind the
+Role to the ServiceAccount.
+
+In the default installation scenario, i.e. Argo CD Image Updater installed
+to the `argocd` namespace, no further configuration has to done in order
+for Argo CD Image Updater to access the Kubernetes API. If your Argo CD
+installation is in a different namespace than `argocd`, you would have
+to adapt the RoleBinding to bind to the ServiceAccount in the correct
+namespace.
+
+## <a name="auth-argocd"></a>Authentication to Argo CD
+
+If you are using Argo CD Image Updater to connect to Argo CD via its API,
+you will need to create credentials in Argo CD and provide them to the
+Image Updater.
+
+This usually involves the following steps:
+
+1. Create a local user with `apiKey` capabilities in Argo CD
+1. Generate an authentication token for that user
+1. Create appropriate RBAC permissions for that user in Argo CD
+1. Configure Argo CD Image Updater to connect to the Argo CD API endpoint
+   instead of the Kubernetes API
+1. Configure Argo CD Image Updater to use the credentials created in steps 1
+   and 2 for authenticating at the Argo CD API
+
+A complete walk-through can be found in the installation guide.
+
+## <a name="auth-registries"></a>Authentication to container registries
+
+If you are using private registries, or private repositories on public
+registries, chances are that you will need to have Argo CD Image Updater use
+credentials to access the registry.
+
+Credentials can be configured either on a per registry basis or on a per image
+basis. You can also use a mixed setup where credentials are configured in both
+ways.
+
+If credentials are configured on a per registry basis, all requests to that
+registry will use these credentials, without requiring any further
+configuration. Also, credentials configured for a registry will be cached
+for a configurable time and don't have to be re-read for every authentication
+requests. This can be useful especially for situations where you use tokens
+with a limited life time that are generated externally, and don't want to
+regenerate the token for each request.
+
+However, you can override the credentials used for authentication to the same
+registry on a per image basis, e.g. if you use repositories on the registry
+that require a different set of credentials.
+
+You can read more about
+[configuration credentials at the registry level]()
+and
+[configuration credentials at the image level]()
+for more details on how to configure either mechanisms.
+
+### <a name="auth-registries-creds-sources"></a>Types of supported credential sources
+
+Argo CD Image Updater can source credentials for accessing registries using the
+following mechanisms:
+
+* Secrets stored in Kubernetes. Argo CD Image Updater can either use a typical
+  Docker pull secret, or a custom secret with credentials in a certain format.
+
+* An environment variable available to Argo CD Image Updater (for example,
+  an environment variable mounted to the pod from a secret)
+
+* A script that, when executed, outputs the credentials to stdout.
+
+The following sections describe the configuration format to be used for the
+different types of credential sources.
+
+### <a name="auth-registries-pull-secret"></a>Using a pull secret
+
+A pull secret is a secret with a well-defined format, that can also be used
+by Kubernetes' container engine to pull container images from registries.
+
+These secrets typically have a field `.dockerconfigjson` in the `.data`
+section, which holds a JSON string with the appropriate credentials.
+
+In its default configuration, Argo CD Image Updater can only read secrets
+from the same namespace where it is installed to.
+
+Pull secrets can be referenced as follows in credentials configuration:
+
+```
+pullsecret:<namespace>/<secret_name>
+```
+
+Where `<namespace>` is the namespace the secret resides in, and `<secret_name>`
+is the name of the Secret resource.
+
+You can create a pull secret by using `kubectl`. The following command would
+create a pull secret for Docker Hub named `dockerhub-secret` in the namespace
+`argocd`:
+
+```shell
+kubectl create -n argocd secret docker-registry dockerhub-secret \
+  --docker-username someuser \
+  --docker-password s0m3p4ssw0rd \
+  --docker-registry "https://registry-1.docker.io"
+```
+
+This secret could then be referred to as
+
+```
+pullsecret:argocd/dockerhub-secret
+```
+
+### <a name="auth-registries-generic-secret"></a>Using a generic secret
+
+Argo CD Image Updater can also retrieve credentials from a field in a generic
+Secret. This may be useful if you have similar credentials for a different set
+of registries, and don't want to maintain a unique pull-secret for each
+registry.
+
+The credentials can be stored in any field of the Secret's `.data` section,
+but credentials must be stored in the format `<username>:<password>`.
+
+To retrieve the credentials from a generic secret, you must specify the field
+name along with the namespace and name of the secret like follows:
+
+```
+secret:<namespace>/<secret_name>#<field_name>
+```
+
+E.g. if you have stored your credentials in the field `creds` in the secret
+`some-secret` in the namespace `argocd`, you would refer to it as
+
+```
+secret:argocd/some-secret#creds
+```
+
+### <a name="auth-registries-env"></a>Using an environment variable
+
+Argo CD Image Updater can read credentials from an environment variable. This
+can be useful for testing purposes (e.g. when using the command
+`argocd-image-updater test` to test access to a registry), or if you have the
+environment variable to use mounted from a secret to the `argocd-image-updater`
+pod.
+
+To retrieve credentials from an environment variable, you must specify the name
+of the environment variable as follows:
+
+```
+env:<name_of_environment_variable>
+```
+
+The credentials passed via environment variables must be specified in the format
+`<username>:<password>`, e.g. to store credentials in an environment variable
+named `DOCKER_HUB_CREDS`:
+
+```
+DOCKER_HUB_CREDS=someuser:s0m3p4ssw0rd
+```
+
+And then, to use this environment variable, reference it as
+
+```
+env:DOCKER_HUB_CREDS
+```
+
+### <a name="auth-registries-script"></a>Using a script to generate credentials
+
+Argo CD Image Updater supports using credentials that are generated by an
+external script. In order to retrieve the credentials, Argo CD Image Updater
+will execute a user configured script or executable, and parse its output.
+
+Having a script generate the credentials can be useful if your registry does
+require a short-lived token for authentication which is issued by a third
+party system, possibly with this third party system requiring a different set
+of credentials. A prominent example would be ECR on aws.
+
+Referencing a script used to output the credentials is done as follows:
+
+```
+ext:<full_path_to_script>
+```
+
+When executing the script, Argo CD Image Updater does not pass any arguments
+to it.
+
+The executed script is expected to output exactly one line to stdout, which
+holds the credentials used for accessing the registry in the format
+`<username>:<password>`. Please note that the output should contain a newline
+character. For example, the most simple form of such a script would be:
+
+```bash
+#!/bin/sh
+
+echo "someuser:s0mep4ssw0rd"
+```
+
+When executing on Kubernetes, the script to be executed must exist in the
+Image Updater container's file system. You can either mount the script from
+a config map, or use an init container to copy it. Make sure that the script
+is executable.
+
+For example, if above script would exist at `/usr/local/bin/creds.sh`, it
+would be referenced as
+
+```
+ext:/usr/local/bin/creds.sh
+```
+
+Please keep in mind that executing scripts to retrieve credentials can become
+expensive. If possible, use this method only on a per-registry level with
+proper caching. Read more about this in the
+[Registry configuration]()
+section of the docs.
+
+* A typical pull secret, i.e. a secret containing a `.dockerconfigjson` field
+  which holds a Docker client configuration with auth information in JSON
+  format. This kind of secret is specified using the notation
+  `pullsecret:<namespace>/<secret_name>`
+
+* A custom secret, which has the credentials stored in a configurable field in
+  the format `<username>:<password>`. This kind of secret is specified using
+  the notation `secret:<namespace>/<secret_name>#<field_in_secret>`
+
+* An environment variable which holds the credentials in the format
+  `<username>:<password>`. This kind of secret is specified using the notation
+  `env:<env_var_name>`.
+
+* A script that outputs credentials on a single line to stdout, in the format
+  `<username:password>`. This can be used to support external authentication
+  mechanisms. You can specify this kind of secret in the notation
+  `ext:/path/to/script`. Please note that the script must be referenced as
+  absolute path, and must be executable (i.e. have the `+x` bit set). You
+  can add scripts to `argocd-image-updater` by using an init container.
+