docs(crd): update Community Documentation for Installation part (#1282)

Signed-off-by: dkarpele <[email protected]>

Author: dkarpele

README.md

@@ -9,24 +9,25 @@
 
 Argo CD Image Updater is a tool to automatically update the container
 images of Kubernetes workloads which are managed by Argo CD. In a nutshell,
-it will track image versions specified by annotations on the Argo CD
-Application resources and update them by setting parameter overrides using
-the Argo CD API.
+it uses a dedicated ImageUpdater CR to define how to track and
+update image versions for your Argo CD Applications. When a new image is available,
+it updates the application by setting parameter overrides, either through the
+Argo CD API or by committing changes to a Git repository.
 
-Currently it will only work with applications that are built using *Kustomize*
+Currently, it will only work with applications that are built using *Kustomize*
 or *Helm* tooling. Applications built from plain YAML or custom tools are not
 supported yet (and maybe never will). 
 
 ## Documentation
 
 Read
 [the documentation](https://argocd-image-updater.readthedocs.io/en/stable/)
-for more information on how to setup and run Argo CD Image Updater and to get
+for more information on how to set up and run Argo CD Image Updater and to get
 known to its features and limitations.
 
 Above URL points to the documentation for the current release. If you are
 interested in documentation of upcoming features, check out the
-[the latest documentation](https://argocd-image-updater.readthedocs.io/en/latest/)
+[latest documentation](https://argocd-image-updater.readthedocs.io/en/latest/)
 which is up-to-date with the master branch.
 
 ## Current status
@@ -37,11 +38,6 @@ yet for *critical* production workloads, but feel free to give it a spin.
 We're very interested in feedback on usability and the user experience as well
 as in bug discoveries and enhancement requests.
 
-**Important note:** Until the first stable version (i.e. `v1.0`) is released,
-breaking changes between the releases must be expected. We will do our best
-to indicate all breaking changes (and how to un-break them) in the
-[Changelog](CHANGELOG.md)
-
 ## Contributing
 
 You are welcome to contribute to this project by means of raising issues for
@@ -58,17 +54,14 @@ Also, if you want to contribute code, please make sure that your code
 * is well commented,
 * and last but not least is compatible with our license and CLA
 
-Please note that in the current early phase of development, the code base is
-a fast moving target and lots of refactoring will happen constantly.
-
 ## License
 
 `argocd-image-updater` is open source software, released under the
 [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0)
 
 ## Things that are planned (roadmap)
 
-The following things are on the roadmap until the `v1.0` release
+The following things are on the roadmap
 
 * [ ] Extend Argo CD functionality to be able to update images for other types
   of applications.

docs/contributing/development.md

@@ -22,9 +22,9 @@ important targets are:
 
 * `test` - this will run all the unit tests
 
-* `image` - this will build the Docker image
+* `docker-build` - this will build the Docker image
 
-* `manifests` - this will build the installation manifests for Kubernetes from
+* `build-installer` - this will build the installation manifests for Kubernetes from
   the Kustomize sources
 
 * `serve-docs` will render the documentation at localhost:8000 (requires Docker)

docs/index.md

@@ -11,8 +11,7 @@ that are managed by
     course to
     [contribute](./contributing/start.md) by many means.
 
-    There will be (probably a lot of) breaking changes from release to
-    release as development progresses until version 1.0. We will do our
+    We will do our
     best to indicate any breaking change and how to un-break it in the
     respective
     [release notes](https://github.com/argoproj-labs/argocd-image-updater/releases).

docs/install/installation.md

@@ -2,41 +2,24 @@
 
 ## Installation methods
 
-It is recommended to run Argo CD Image Updater in the same Kubernetes namespace
+It is recommended to run Argo CD Image Updater in the same Kubernetes
 cluster that Argo CD is running in, however, this is not a requirement. In fact,
 it is not even a requirement to run Argo CD Image Updater within a Kubernetes
 cluster or with access to any Kubernetes cluster at all.
 
-However, some features might not work without accessing Kubernetes, and it is
-strongly advised to use the first installation method.
+However, some features might not work without accessing Kubernetes.
 
-## <a name="install-kubernetes"></a>Method 1: Installing as Kubernetes workload in Argo CD namespace
+## <a name="install-kubernetes"></a>Installing as Kubernetes workload in Argo CD namespace
 
-The most straightforward way to run the image updater is to install it as a Kubernetes workload into the namespace where
-Argo CD is running. Don't worry, without any configuration, it will not start messing with your workloads yet.
-
-!!!note
-    We also provide a Kustomize base in addition to the plain Kubernetes YAML
-    manifests. You can use it as remote base and create overlays with your
-    configuration on top of it. The remote base's URL is
-    `https://github.com/argoproj-labs/argocd-image-updater/manifests/base`. 
-    You can view the manifests [here](https://github.com/argoproj-labs/argocd-image-updater/tree/stable/manifests/base)
+The most straightforward way to run the image updater is to install it as a Kubernetes workload using the provided installation manifests. These manifests will set up the controller in its own dedicated namespace (`argocd-image-updater-system` by default).
+Don't worry, without creating any ImageUpdater custom resources, it will not start modifying your workloads yet.
 
 ### Apply the installation manifests
 
 ```shell
-kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml
+kubectl apply -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/config/install.yaml
 ```
 
-!!! warning
-    The installation manifests include `ClusterRoleBinding` resources that reference `argocd` namespace. If you are installing Argo CD into a different
-    namespace then make sure to update the namespace reference.
-
-!!!note "A word on high availability"
-    It is not advised to run multiple replicas of the same Argo CD Image Updater
-    instance. Just leave the number of replicas at 1, otherwise weird side
-    effects could occur.
-
 ### Configure the desired log level
 
 While this step is optional, we recommend to set the log level explicitly.
@@ -54,150 +37,15 @@ data:
 
 If you omit the `log.level` setting, the default `info` level will be used.
 
-## Method 2: Connect using Argo CD API Server
-
-If you are unable to install Argo CD Image Updater into the same Kubernetes
-cluster you can configure it to use the API of your Argo CD installation.
-
-If you chose to install the Argo CD Image Updater outside of the cluster where
-Argo CD is running in, the API must be exposed externally (i.e. using Ingress).
-If you have network policies in place, make sure that Argo CD Image Updater will
-be allowed to communicate with the Argo CD API, which is usually the service
-`argocd-server` in namespace `argocd` on port 443 and port 80.
-
-### Apply the manifests
-
-First, create a namespace and apply the manifests to your cluster
-
-```shell
-kubectl create namespace argocd-image-updater
-kubectl apply -n argocd-image-updater -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml
-```
-
-!!! warning
-    The installation manifests include `ClusterRoleBinding` resources that reference `argocd` namespace. If you are installing Argo CD into a different
-    namespace then make sure to update the namespace reference.
-
-!!!note "A word on high availability"
-    It is not advised to run multiple replicas of the same Argo CD Image Updater
-    instance. Just leave the number of replicas at 1, otherwise weird side
-    effects could occur.
-
-### Create a local user within Argo CD
-
-Argo CD Image Updater needs credential for accessing the Argo CD API. Using a
-[local user](https://argoproj.github.io/argo-cd/operator-manual/user-management/)
-is recommended, but a *project token* will work as well (although, this will
-limit updating to the applications of the given project obviously).
-
-Let's use an account named `image-updater` with appropriate API permissions.
-
-Add the following user definition to `argocd-cm`:
-
-```yaml
-data:
-  # ...
-  accounts.image-updater: apiKey
-```
-
-Now, you will need to create an access token for this user, which can be either
-done using the CLI or the Web UI. The following CLI command will create a named
-token for the user and print it to the console:
-
-```shell
-argocd account generate-token --account image-updater --id image-updater
-```
-
-Copy the token's value somewhere, you will need it later on.
-
-### Granting RBAC permissions in Argo CD
-
-The technical user `image-updater` we have configured in the previous step now
-needs appropriate RBAC permissions within Argo CD. Argo CD Image Updater needs
-the `update` and `get` permissions on the applications you want to manage.
-
-A most basic version that grants `get` and `update` permissions on all of the
-applications managed by Argo CD might look as follows:
-
-```text
-p, role:image-updater, applications, get, */*, allow
-p, role:image-updater, applications, update, */*, allow
-g, image-updater, role:image-updater
-```
-
-You might want to strip that down to apps in a specific project, or to specific
-apps, however.
-
-Put the RBAC permissions to Argo CD's `argocd-rbac-cm` ConfigMap and Argo CD will
-pick them up automatically.
-
-### Configure Argo CD endpoint
-
-If you run Argo CD Image Updater in another cluster than Argo CD, or if your
-Argo CD installation is not in namespace `argocd` or if you use a default or
-otherwise self-signed TLS certificate for Argo CD API endpoint, you probably
-need to divert from the default connection values.
-
-Edit the `argocd-image-updater-config` ConfigMap and add the following keys
-(the values are dependent upon your environment)
-
-```yaml
-data:
-  applications_api: argocd
-  # The address of Argo CD API endpoint - defaults to argocd-server.argocd
-  argocd.server_addr: <FQDN or IP of your Argo CD server>
-  # Whether to use GRPC-web protocol instead of GRPC over HTTP/2
-  argocd.grpc_web: "true"
-  # Whether to ignore invalid TLS cert from Argo CD API endpoint
-  argocd.insecure: "false"
-  # Whether to use plain text connection (http) instead of TLS (https)
-  argocd.plaintext: "false"
-```
-
-After changing values in the ConfigMap, Argo CD Image Updater needs to be
-restarted for the changes to take effect, i.e.
-
-```shell
-kubectl -n argocd-image-updater rollout restart deployment argocd-image-updater
-```
-
-### Configure API access token secret
-
-When installed from the manifests into a Kubernetes cluster, the Argo CD Image
-Updater reads the token required for accessing Argo CD API from an environment
-variable named `ARGOCD_TOKEN`, which is set from a field named
-`argocd.token` in a secret named `argocd-image-updater-secret`.
-
-The value for `argocd.token` should be set to the *base64 encoded* value of the
-access token you have generated above. As a short-cut, you can use generate
-secret with `kubectl` and apply it over the existing resource:
-
-```shell
-kubectl create secret generic argocd-image-updater-secret \
-  --from-literal argocd.token=$YOUR_TOKEN --dry-run -o yaml |
-  kubectl -n argocd-image-updater apply -f -
-```
-
-You must restart the `argocd-image-updater` pod after such a change, i.e run
-
-```shell
-kubectl -n argocd-image-updater rollout restart deployment argocd-image-updater
-```
-
-Or alternatively, simply delete the running pod to have it recreated by
-Kubernetes automatically.
-
 ## Running locally
 
-As long as you have access to the Argo CD API and your Kubernetes cluster from
-your workstation, running Argo CD Image Updater is simple. Make sure that you
-have your API token noted and that your Kubernetes client configuration points
-to the correct K8s cluster.
+As long as you have access to your Kubernetes cluster from
+your workstation, running Argo CD Image Updater is simple. Make sure that your
+Kubernetes client configuration points to the correct K8s cluster.
 
-Grab the binary (it does not have any external dependencies) and run:
+Grab the binary and run:
 
 ```bash
-export ARGOCD_TOKEN=<yourtoken>
 ./argocd-image-updater run \
   --kubeconfig ~/.kube/config
   --once
@@ -225,6 +73,9 @@ If opting for such an approach, you should make sure that:
 
 ## Metrics
 
+!!!note "Under Construction"
+    Please note that Prometheus metrics are not available in the initial CRD-based versions of Argo CD Image Updater. The functionality described below is planned for a future release. We are keeping this section as a reference for when metrics are re-introduced.
+
 Starting with v0.8.0, Argo CD Image Updater exports Prometheus-compatible
 metrics on a dedicated endpoint, which by default listens on TCP port 8081
 and serves data from `/metrics` path. This endpoint is exposed by a service