docs: Clarifying override RBAC needs (#16964)

Signed-off-by: Ryan Shatford <ryan@shatford.com>
Signed-off-by: Dan Garfield <dan@codefresh.io>
Co-authored-by: Ryan Shatford <ryan@shatford.com>
Co-authored-by: Dan Garfield <dan@codefresh.io>

docs/CONTRIBUTING.md

@@ -1 +0,0 @@
-Please refer to [the Contribution Guide](https://argo-cd.readthedocs.io/en/latest/developer-guide/contributing/)

docs/SUPPORT.md

@@ -1,6 +0,0 @@
-# Support
-
-1. Make sure you've read [understanding the basics](understand_the_basics.md) the [getting started guide](getting_started.md).
-2. Looked for an answer in [the frequently asked questions](faq.md).
-3. Ask a question in [the Argo CD Slack channel ⧉](https://argoproj.github.io/community/join-slack).
-4. [Read issues, report a bug, or request a feature ⧉](https://github.com/argoproj/argo-cd/issues).

docs/assets/versions.css

@@ -1,172 +0,0 @@
-.md-header-nav__title {
-  display: flex;
-}
-
-.dropdown-caret {
-  display: inline-block !important;
-  position: absolute;
-  right: 4px;
-}
-
-.fa .fa-caret-down {
-  display: none !important;
-}
-
-.rst-other-versions {
-  text-align: right;
-}
-
-.rst-other-versions > dl, .rst-other-versions dt, .rst-other-versions small {
-  display: none;
-}
-
-.rst-other-versions > dl:first-child {
-  display: flex !important;
-  flex-direction: column;
-  line-height: 0px !important;
-}
-
-.rst-versions.shift-up .rst-other-versions {
-  display: flex !important;
-}
-
-.rst-versions .rst-other-versions {
-  display: none;
-}
-
-/* Version Warning */
-div[data-md-component=announce] {
-  background-color: rgba(255,145,0,.1);
-}
-div[data-md-component=announce]>div#announce-msg{
-  color: var(--md-admonition-fg-color);
-  font-size: .8rem;
-  text-align: center;
-  margin: 15px;
-}
-div[data-md-component=announce]>div#announce-msg>a{
-  color: var(--md-typeset-a-color);
-  text-decoration: underline;
-}
-
-/* from https://assets.readthedocs.org/static/css/badge_only.css,
-most styles have to be overriden here */
-.rst-versions{
-  position: relative !important;
-  bottom: 0;
-  left: 0;
-  width: 100px !important;
-  background: hsla(173, 100%, 24%, 1) !important;
-  font-family: inherit !important;
-  z-index: 0 !important;
-}
-.rst-versions a{
-  color:#2980B9;
-  text-decoration:none
-}
-.rst-versions .rst-badge-small{
-  display:none
-}
-.rst-versions .rst-current-version{
-  padding:12px;
-  background: hsla(173, 100%, 24%, 1) !important;
-  display:block;
-  text-align:right;
-  font-size:90%;
-  cursor:pointer;
-  color: white !important;
-  *zoom:1
-}
-.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{
-  display:table;content:""
-}
-.rst-versions .rst-current-version:after{
-  clear:both
-}
-.rst-versions .rst-current-version .fa{
-  color:#fcfcfc
-}
-.rst-versions .rst-current-version .fa-caret-down{
-  display: none;
-}
-.rst-versions.shift-up .rst-other-versions{
-  display:block
-}
-.rst-versions .rst-other-versions{
-  font-size:90%;
-  padding:12px;
-  color:gray;
-  display:none
-}
-.rst-versions .rst-other-versions hr{
-  display: none !important;
-  height: 0px !important;
-  border: 0px;
-  margin: 0px !important;
-  padding: 0px;
-  border-top: none !important;
-}
-.rst-versions .rst-other-versions dd{
-  display:inline-block;
-  margin:0
-}
-.rst-versions .rst-other-versions dd a{
-  display:inline-block;
-  padding: 1em 0em !important;
-  color:#fcfcfc;
-  font-size: .6rem !important;
-  white-space: nowrap;
-  text-overflow: ellipsis;
-  overflow: hidden;
-  width: 80px;
-}
-.rst-versions .rst-other-versions dd a:hover{
-  font-size: .7rem !important;
-  font-weight: bold;
-}
-.rst-versions.rst-badge{
-  display: block !important;
-  width: 100px !important;
-  bottom: 0px !important;
-  right: 0px !important;
-  left:auto;
-  border:none;
-  text-align: center !important;
-  line-height: 0;
-}
-.rst-versions.rst-badge .icon-book{
-  display: none;
-}
-.rst-versions.rst-badge .fa-book{
-  display: none !important;
-}
-.rst-versions.rst-badge.shift-up .rst-current-version{
-  text-align: left !important;
-}
-.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{
-  display: none !important;
-}
-.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{
-  display: none !important;
-}
-.rst-versions.rst-badge .rst-current-version{
-  width: 70px !important;
-  height: 2.4rem !important;
-  line-height:2.4rem !important;
-  padding: 0px 5px !important;
-  display: inline-block !important;
-  font-size: .6rem !important;
-  overflow: hidden !important;
-  text-overflow: ellipsis !important;
-  white-space: nowrap !important;
-  text-align: left !important;
-}
-@media screen and (max-width: 768px){
-  .rst-versions{
-      width:85%;
-      display:none
-  }
-  .rst-versions.shift{
-      display:block
-  }
-}

docs/assets/versions.js

@@ -1,44 +0,0 @@
-setTimeout(function() {
-  const callbackName = 'callback_' + new Date().getTime();
-  window[callbackName] = function (response) {
-  const div = document.createElement('div');
-  div.innerHTML = response.html;
-  document.querySelector(".md-header-nav > .md-header-nav__title").appendChild(div);
-  const container = div.querySelector('.rst-versions');
-  var caret = document.createElement('div');
-  caret.innerHTML = "<i class='fa fa-caret-down dropdown-caret'></i>"
-  caret.classList.add('dropdown-caret')
-  div.querySelector('.rst-current-version').appendChild(caret);
-  div.querySelector('.rst-current-version').addEventListener('click', function() {
-      const classes = container.className.split(' ');
-      const index = classes.indexOf('shift-up');
-      if (index === -1) {
-          classes.push('shift-up');
-      } else {
-          classes.splice(index, 1);
-      }
-      container.className = classes.join(' ');
-  });
-  }
-
-  var CSSLink = document.createElement('link');
-  CSSLink.rel='stylesheet';
-  CSSLink.href = '/assets/versions.css';
-  document.getElementsByTagName('head')[0].appendChild(CSSLink);
-
-  var script = document.createElement('script');
-  script.src = 'https://argo-cd.readthedocs.io/_/api/v2/footer_html/?'+
-      'callback=' + callbackName + '&project=argo-cd&page=&theme=mkdocs&format=jsonp&docroot=docs&source_suffix=.md&version=' + (window['READTHEDOCS_DATA'] || { version: 'latest' }).version;
-  document.getElementsByTagName('head')[0].appendChild(script);
-}, 0);
-
-// VERSION WARNINGS
-window.addEventListener("DOMContentLoaded", function() {
-  var rtdData = window['READTHEDOCS_DATA'] || { version: 'latest' };
-  if (rtdData.version === "latest") {
-    document.querySelector("div[data-md-component=announce]").innerHTML = "<div id='announce-msg'>You are viewing the docs for an unreleased version of Argo CD, <a href='https://argo-cd.readthedocs.io/en/stable/'>click here to go to the latest stable version.</a></div>"
-  }
-  else if (rtdData.version !== "stable") {
-    document.querySelector("div[data-md-component=announce]").innerHTML = "<div id='announce-msg'>You are viewing the docs for a previous version of Argo CD, <a href='https://argo-cd.readthedocs.io/en/stable/'>click here to go to the latest stable version.</a></div>"
-  }
-});

docs/basics/apps/destination.md

@@ -0,0 +1,62 @@
+# Application destination
+
+The *Application destination* defines where the *Application* should be synced
+to. The *Destination* is defined in the `.spec.destination` part of the
+*Application* Custom Resource.
+
+A *Destination* consists of a tuple of the *target cluster* and the target
+*namespace*.
+
+A *Destination* must be permitted in the *Application's* parent
+[Project](../projects/).
+
+## Target cluster
+
+The *target cluster*, as the name implies, defines the cluster where the
+application's resource manifests should be deployed to. The target cluster is
+specified using the `spec.destination.server` field, which contains either the
+URL to the Kubernetes API of the cluster, or its
+[symbolic name](../clusters/).
+
+There are two distinct types of values you can use here:
+
+* Either the local cluster where Argo CD is installed to, which is usually
+  `https://kubernetes.default.svc` with a symbolic name of `in-cluster`, or
+
+* A remote cluster, referenced by its API URL. Be aware that before you can
+  specify a remote cluster as a target cluster, it needs to be
+  [added to Argo CD's configuration properly](../clusters/).
+
+## Target namespace
+
+Depending on your Argo CD
+[installation type](../../getting_started/install.md#installation-types),
+your
+[target cluster's configuration](../clusters/)
+and your
+[project settings](../projects/#cluster-resources),
+your *Application* resource manifests may consist of cluster-scoped and
+namespace-scoped resources.
+
+Cluster-scoped resources obviously won't need a target namespace, but Argo CD
+needs to know to which target namespace the namespace-scoped resources shall
+be deployed to. This is set via the `.spec.destination.namespace` field.
+
+The target namespace has to exist in the target cluster unless the
+[sync option](../../syncing/)
+[namespace auto-creation](../../syncing/)
+has been set in the *Application* or an appropriate `Namespace` resource is part
+of the *Application's* resource manifests.
+
+Argo CD will not overwrite existing namespace configuration in any resource,
+so the final decision about a resource's target namespace will be made according
+to these rules:
+
+* If a resource has set `.metadata.namespace`, its value will be used as the
+  target namespace for that resource. In this case, the namespace has either to
+  exist in the target cluster, or an appropriate `Namespace` resource has to
+  be delivered together with the application's resource manifests.
+
+* Otherwise, the *target namespace* as defined in the *Application's*
+  `.spec.destination.namespace` field will be used as the target namespace for
+  the resource.

docs/basics/apps/index.md

@@ -0,0 +1,92 @@
+# Argo CD Applications
+
+## Overview
+
+*Applications* are at the heart of Argo CD. An *Application* is the entity that
+tells Argo CD where to find resources to deploy, where to deploy them and when
+to do it.
+
+You can think of an *Application* as a collection of one or more Kubernetes
+resources that are managed together on a Kubernetes cluster. These resources can
+be comprised of anything that is managable by the target Kubernetes cluster,
+and can also possibly span over multiple namespaces. There is no artifical limit
+of how many *Applications* you can configure in Argo CD, however, there might
+be other limits (such as, compute resource constraints).
+
+Each *Application* must be configured to have at least
+
+* a unique
+  [Name](#application-name),
+* a relationship to a
+  [Project](../projects/),
+* a [Source](source.md)
+  to define the source of the *Application's* resources and
+* a [Destination](destination.md)
+  to define the target of the *Application's* resources.
+
+Optionally, each *Application* can also have a
+[Sync Policy](../../syncing/policy.md)
+that controls how it will be synced to its destination.
+
+The relationship between a *Source* and an *Application* is always 1:n. That
+is, each *Application* must have exactly one *Source*, while you can create
+multiple *Applications* from a single *Source*.
+
+The same is true for the relationship between a *Destination* and an
+*Application*, which is also alway 1:n. Each *Application* is managed on
+exactly one *Destination*, but your *Destination* can contain multiple
+*Applications*. This also means, you cannot install the same application to
+multiple clusters, or multiple times on the same cluster.
+
+Along with its configuration, each *Application* also has a
+[sync state](../../syncing/states.md)
+that represents its current reconciliation status, and a
+[history](history.md)
+which contains recordings of previous states and reconciliation results.
+
+## Application name
+
+An *Application name* defines the name of the application. Application names
+are also the names of the Custom Resource in your cluster (defined using the
+`.metadata.name` field of the CR) and therefore must be unique within your Argo
+CD installation. It is not possible to have two applications with the same
+name, regardless of their *Source* and *Destination* configuration.
+
+It is recommended to use an easy to memorize naming scheme for applications,
+especially if you are going to install a similar application to multiple
+destinations. For example, if you have an *Application* you want to name
+`monitoring`, and this application would be deployed to multiple clusters,
+
+## Parent project
+
+Each *Application* must belong to a parent
+[project](../projects/)
+that specifies certain rules and additional configuration for *Applications*
+that belong to it. The project is specified using the `.spec.project` field,
+which must contain the *name* of the project to associate the application to.
+
+Argo CD ships a default project named `default`, which can be used if you
+haven't created other projects yet.
+
+## Sync Policy
+
+Each *Application* has a *Sync Policy* that defines how the *Application* should
+be synced to the target *Cluster*. This policy is set in the `.spec.syncPolicy`
+part of the *Application*.
+
+Specifying a *Sync Policy* for an *Application* is *optional*. If no policy is
+configured, the default policy will be used.
+
+You can read more about *Sync Policies* in the
+[Sync Policy documentation](../../syncing/policy.md).
+
+## Implementation details
+
+*Applications* are implemented as Kubernetes Custom Resources of kind
+`Application` in the `argoproj.io/v1alpha1` API and can be managed either using
+the Argo CD CLI, the web UI or the Kubernetes API.
+
+!!! note "About the location of Application resources"
+    *Application* resources live in the installation namespace in the cluster of
+    your Argo CD installation, which is `argocd` by default. *Application* resources
+    created in other namespaces or clusters will not be used up by Argo CD.

docs/basics/apps/manage.md

@@ -0,0 +1,72 @@
+# Managing Applications
+
+You can manage *Applications* via the argocd CLI, the web UI or the Kubernetes
+API. For managing *Applications* using either Argo CD's CLI or UI, 
+[RBAC permissions](../rbac.md).
+must be set-up for your user to allow manipulation of `applications` objects.
+
+The default `admin` user already has appropriate permissions to manipulate all
+existing *Applications* in your Argo CD installation.
+
+## Using the argocd CLI
+
+### List existing applications
+
+To list all applications that you have authorization for, use the
+`argocd app list` command. This will also give you the most important details
+ about the applications:
+
+```bash
+$ argocd app list
+NAME            CLUSTER                         NAMESPACE       PROJECT  STATUS  HEALTH   SYNCPOLICY  CONDITIONS  REPO                                             PATH            TARGET
+helm-guestbook  https://kubernetes.default.svc  helm-guestbook  default  Synced  Healthy  <none>      <none>      https://github.com/argoproj/argocd-example-apps  helm-guestbook  HEAD
+```
+
+### Get details about an application
+
+To get more detailed information about a specific *Application*, you can use the
+`argocd app get` command. This will also display the resources that are managed
+by the application:
+
+```bash
+$ argocd app get helm-guestbook
+Name:               helm-guestbook
+Project:            default
+Server:             https://kubernetes.default.svc
+Namespace:          helm-guestbook
+URL:                http://127.0.0.1:8088/applications/helm-guestbook
+Repo:               https://github.com/argoproj/argocd-example-apps
+Target:             HEAD
+Path:               helm-guestbook
+SyncWindow:         Sync Allowed
+Sync Policy:        <none>
+Sync Status:        Synced to HEAD (0d3eec0)
+Health Status:      Healthy
+
+GROUP  KIND        NAMESPACE       NAME            STATUS     HEALTH   HOOK     MESSAGE
+       Endpoints   helm-guestbook  helm-guestbook  Succeeded           PreSync  helm-guestbook created
+       Service     helm-guestbook  helm-guestbook  Synced     Healthy           service/helm-guestbook unchanged
+apps   Deployment  helm-guestbook  helm-guestbook  Synced     Healthy           deployment.apps/helm-guestbook configured
+```
+
+### Create new applications
+
+To create a new *Application*, use the `argocd app create` command. The
+following example creates an application `kustomize-guestbook` from the Argo
+CD example applications repository, with a sync option to auto create the
+target namespace:
+
+```bash
+$ argocd app create kustomize-guestbook \
+  --project default \
+  --repo https://github.com/argoproj/argocd-example-apps \
+  --path kustomize-guestbook \
+  --dest-namespace kustomize-guestbook \
+  --dest-server https://kubernetes.default.svc \
+  --sync-option CreateNamespace=true
+application 'kustomize-guestbook' created
+```
+
+## Using the web UI
+
+## Using the Kubernetes API

docs/basics/apps/overrides.md

@@ -1,8 +1,8 @@
-# Parameter Overrides
+# Override Parameters
 
 Argo CD provides a mechanism to override the parameters of Argo CD applications that leverages config management
 tools. This provides flexibility in having most of the application manifests defined in Git, while leaving room
-for *some* parts of the  k8s manifests determined dynamically, or outside of Git. It also serves as an alternative way of
+for *some* parts of the  k8s manifests to be determined dynamically, or outside of Git. It also serves as an alternative way of
 redeploying an application by changing application parameters via Argo CD, instead of making the 
 changes to the manifests in Git.
 
@@ -26,8 +26,56 @@ argocd app set guestbook -p ingress.enabled=true
 argocd app set guestbook -p ingress.hosts[0]=guestbook.myclusterurl
 ```
 
-The `argocd app set` [command](./commands/argocd_app_set.md) supports more tool-specific flags such as `--kustomize-image`, `--jsonnet-ext-var-str` etc
-flags. You can also specify overrides directly in the source field on application spec. Read more about supported options in corresponded tool [documentation](./application_sources.md).
+The `argocd app set` command supports more tool-specific flags such as `--kustomize-image`, `--jsonnet-ext-var-str` etc
+flags. You can also specify overrides directly in the source field on application spec.
+
+## RBAC Policy for Overrides
+In order to make changes outside of the GitOps pattern, someone needs to have the authorization
+to do so. This will include the `override` RBAC action, at a minimum, including the ability to `get`
+the application, project and repository.
+
+For example, you have a QA team that would like to modify values for many Applications and
+Projects during the testing phase and Sarah is assigned to the processing Application within the qa
+Project. Sarah will need to override the Helm parameters of the Application during their work so the
+RBAC will need to be configured correctly. They run `argocd account can-i override application
+'qa/processing'` and find out they do not have the permission.
+
+1. If needed, create a Role, `maintainer-qa-processing`, and assign Sarah to it. Give the Role
+   access to read the needed repository.
+
+```yaml
+  policy.csv: |
+    p, role:maintainer-qa-processing, repositories, get, processing-repo, allow
+    g, sarah@company.example, role:maintainer-qa-processing
+```
+
+2. In the qa Project yaml, add a new role that would look like:
+
+```yaml
+  roles:
+  - name: processing-maintainer
+    description: Can override deployment variables
+    policies:
+    # Allow this group to override this specific Application
+    - p, proj:qa:processing-maintainer, applications, override, qa/processing, allow
+    groups:
+    - maintainer-qa-processing
+```
+
+or via the CLI
+
+```bash
+argocd proj role create qa processing-maintainer
+argocd proj role add-policy qa processing-maintainer -a override -o qa/processing
+argocd proj role add-group qa processing-maintainer maintainer-qa-processing
+```
+
+3. Test that the the changes you want to commit will work  with the `argocd admin
+settings rbac can` command.
+
+```bash
+argocd admin settings rbac can sarah@company.exampmle override 'qa/processing'
+```
 
 ## When To Use Overrides?
 
@@ -46,7 +94,7 @@ would result in the application being redeployed with the new image.
 Since commit access to the repository is unavailable, it is useful to be able to install charts from
 the public repository and customize the deployment with different parameters, without resorting to
 forking the repository to make the changes. For example, to install Redis from the Helm chart
-repository and customize the the database password, you would run:
+repository and customize the database password, you would run:
 
 ```bash
 argocd app create redis --repo https://github.com/helm/charts.git --path stable/redis --dest-server https://kubernetes.default.svc --dest-namespace default -p password=abc123
@@ -54,14 +102,9 @@ argocd app create redis --repo https://github.com/helm/charts.git --path stable/
 
 ## Store Overrides In Git
 
-> The following is available from v1.8 or later
-
 The config management tool specific overrides can be specified in `.argocd-source.yaml` file stored in the source application
 directory in the Git repository.
 
-!!! warn
-    The `.argocd-source` is a beta feature and subject to change.
-
 The `.argocd-source.yaml` file is used during manifest generation and overrides
 application source fields, such as `kustomize`, `helm` etc.
 
@@ -75,12 +118,10 @@ kustomize:
 
 The `.argocd-source` is trying to solve two following main use cases:
 
-- Provide the unifed way to "override" application parameters in Git and enable the "write back" feature
+- Provide the unified way to "override" application parameters in Git and enable the "write back" feature
 for projects like [argocd-image-updater](https://github.com/argoproj-labs/argocd-image-updater).
-- Support "discovering" applications in the Git repository by projects like [applicationset](https://github.com/argoproj-labs/applicationset)
-(see [git files generator](https://github.com/argoproj-labs/applicationset/blob/master/examples/git-files-discovery.yaml))
-
-> The following is available from v1.9 or later
+- Support "discovering" applications in the Git repository by projects like [applicationset](https://github.com/argoproj/applicationset)
+(see [git files generator](https://github.com/argoproj/argo-cd/blob/master/applicationset/examples/git-generator-files-discovery/git-generator-files.yaml))
 
 You can also store parameter overrides in an application specific file, if you
 are sourcing multiple applications from a single path in your repository.
@@ -91,4 +132,4 @@ where `<appname>` is the name of the application the overrides are valid for.
 If there exists an non-application specific `.argocd-source.yaml`, parameters
 included in that file will be merged first, and then the application specific
 parameters are merged, which can also contain overrides to the parameters
-stored in the non-application specific file.
+stored in the non-application specific file.

docs/basics/apps/source.md

@@ -0,0 +1,78 @@
+# Application Source
+
+An *Application Source* tells Argo CD where the manifests for the application
+resources reside, how to generate them and which version or revision of the
+source to use. The application source is defined in `.spec.source` part of the
+*Application* Custom Resource.
+
+Argo CD currently supports two types of sources to track application resources
+from: Git and Helm repositories. Depending on the type of source you are
+configuring for the application, specific configuration has to be performed.
+
+## Source Repository
+
+The `.spec.source.repoURL` field defines the repository where the resource
+manifests are stored. It must be an URL that points to either a Git or a Helm
+repository. For more details about supported URLs, authentication, etc. please
+read the
+[repositories documentation](../repositories/).
+
+### Manifests from a Git repository
+
+If you source manifests from a Git repository, you can use all the generators
+that are supported by Argo CD to render the manifests before they are being
+reconciled into your cluster. For list of available generator tools, please
+have a look at the
+[tools documentation](../../tools/)
+
+#### Path within repository
+
+The `.spec.source.path` defines the path within the repository that contains
+your resources manifests. The path must be specified relative to the repository
+root. If you want to use the top-level directory in your repository, use the
+value `.` as path.
+
+The corresponding parameter for `argocd app create` to specify the path is
+`--path`.
+
+#### Target revision
+
+The `.spec.source.targetRevision` defines the Git target revision to track.
+This can take various formats, please refer to the
+[Tracking strategies documentation](../../syncing/tracking.md)
+for more information.
+
+The corresponding parameter for `argocd app create` to specify the target
+revision is `--targetRevision`.
+
+### Manifests from a Helm repository
+
+If you source your manifests from a Helm repository, only Helm can be used to
+render the manifests, obviously.
+
+#### Specifying the name of the Chart
+
+Instead of using `.spec.source.path`, you need to set `.spec.source.chart` to
+the name of the Helm chart to be used.
+
+#### Specifying the version of the Chart
+
+Also, `.spec.source.targetRevision` specifies the version of the Helm chart to
+use instead of a Git revision.
+
+For more information, refer to the
+[Helm tooling documentation](../../tools/helm.md).
+
+## Source specific configuration
+
+Depending on the tool you use to render the manifests for a given *Application*,
+additional configuration can or must be given. These can be simple options to
+recursively consider all of the manifests found in directories below
+`.spec.source.path`, a directive to use a pinned version of a given tool or more
+complex settings, like
+[parameter overrides](../../tools/)
+
+Please refer to the
+[tool specific documenation](../../tools/)
+for more information about the possible configuration options for each of the
+supported tools.

docs/basics/apps/state.md

@@ -0,0 +1,66 @@
+# Application state & health
+
+## Sync Status
+
+The *Sync Status* represents the current state of reconciliation between the
+*Source* and the *Destination*. The *Sync Status* can take one of the values:
+
+* `SYNCED` - All resources of the *Application* are in the desired state on the
+  destination. There is no deviation between the desired and the actual state.
+
+* `OUT OF SYNC` - Argo CD has determined a deviation between the desired state
+  and the actual state. When an *Application* transitions to this state, the
+  [Automated Sync Policy](../../syncing/policy.md)
+  (if enabled) will trigger a sync for the *Application*.
+
+* `UNKNOWN` - Argo CD currently cannot determine the desired state from the
+  *Application's* source or the actual state on the *Application's* destination.
+  This state usually occurs when a non-transient error occurs while comparing
+  actual and desired states. Argo CD will also let you know about the error.
+
+Argo CD determines the *Sync Status* by performing a *diff* between the
+resources defined by the *Application Source* and the resources that actually
+exist in the *Application Destination*.
+
+In some cases, resources on the target cluster get modified by other actors,
+such as an operator or a controller, after they have been reconciled into the
+target cluster. In such cases, the *Sync Status* would be constantly `OUT OF
+SYNC`.
+
+The diffing behaviour can be changed to ignore such expected deviations, so that
+they won't affect the *Sync Status*. You can read more about this in the
+[Diffing Customization documentation](../../syncing/diffing.md)
+
+## Application Health
+
+The *Application Health* is an aggregate representation of the health of your
+*Application's* resources. Whereas the *Sync Status* determines whether all of
+the *Application's* resource manifests have been successfully reconciled into
+the target Kubernetes cluster, the *Application Health* is an indicator whether
+all of the resources also have been succesfully brought into a usable state by
+Kubernetes.
+
+The *Application Health* can have one of the following states:
+
+* `HEALTHY` - all of the *Application's* resources *Application* are considered
+  healthy
+
+* `PROGRESSING` - at least one of the *Application's* resources is still in the
+  process of being brought to a healthy state
+
+* `DEGRADED` - at least one of the *Application's* resources is marked as being
+  in an erroneous state or is otherwise unhealthy.
+
+* `UNKNOWN` - the health state of the *Application's* resources could not be
+  determined. Argo CD will let you know about the reason for this.
+
+* `MISSING` - the *Application's* resources are missing, and Argo CD cannot
+  reliably determine the health status. This usually happens when *Application*
+  has not been synced, or when there is an error with the cache.
+
+* `SUSPENDED` - to be written
+
+To illustrate this a little, imagine a `Service` resource in your cluster of
+type `LoadBalancer`.
+
+## History

docs/basics/clusters/index.md

@@ -0,0 +1,99 @@
+# Argo CD target clusters
+
+By default an Argo CD instance can deploy applications to the [same cluster](internal/) it is installed on. Additionally, Argo CD has the capability to connect and deploy to [external clusters](external).
+
+This means that there are several topologies for handling multiple clusters with Argo CD
+
+1. Using one Argo CD instance per cluster
+1. Using a centralized Argo CD instance that handles all clusters
+1. A mixture of both strategies. For example you can have different groups of children clusters managed by multiple parent Argo CD instances
+
+Let's see those options in turn:
+
+## Installing Argo CD on each deployment cluster
+
+This is arguably the simplest way to install Argo CD. Each deployment cluster gets its own instance and each Argo CD installation controls the same cluster it is installed on.
+
+![Argo CD per cluster](../../assets/argocd-per-cluster.jpg)
+
+This approach has several advantages when it comes to maintenance and upgrades but also suffers from several issues when you have too many clusters. 
+
+Advantages
+
+ * Straightforward installation
+ * Target clusters do not need network connectivity which each other and can even work fully isolated from each other
+ * Clusters operate independently without reliance on an external instance of Argo CD
+ * Security surface is limited to each individual cluster, (compromising one does not compromise the rest)
+ * [Upgrades](../../operations/upgrading/) can happen in a gradual way by moving Argo CD instances to a new version one-by-one or in waves
+ * Different plugins and configurations/policies can be set on each deployment cluster
+ * Easy to split environments (QA/Staging/Production)
+
+Disadvantages
+
+ * Difficult to manage in a uniform way
+ * Can lead to many instances being out-of-date, introducing a new class of security problems
+ * Poor visibility across organizations
+ * Difficult to implement policy across many instances
+ * More resources used for each cluster in order to run Argo CD itself
+ * Multiple dashboards, users, SSO setups and possible RBAC setups are confusing for end users. 
+
+
+## Using a central Argo CD installation
+
+At the other end of the spectrum we can have a centralized Argo CD installation which controls and manages all deployment clusters. The cluster that hosts Argo CD can be dedicated to Argo CD only or it can also be used for deploying applications as well.
+
+![Centralized Argo CD instance](../../assets/centralized.jpg)
+
+Advantages
+
+* Easy to maintain and upgrade
+* Centralized control (including SSO and RBAC)
+* Better visibility across organization
+* Single dashboard for all clusters
+
+Disadvantages
+
+* Single point of failure
+* Target cluster API’s must be accessible to the central instance
+* Single attack surface
+* RBAC and SSO might not match organizational requirements
+* Impossible to upgrade different clusters in waves
+* No separation between QA/Staging/Prod installations
+* Argo CD performance may degrade with many applications and clusters as they scale - see [High Availability](../../operator-manual/high_availability/) for more information.
+* In theory requires less resources per each deployment cluster (as it only runs apps and not Argo CD itself)
+
+While a single Argo CD instance might be tempting (especially for big organizations) it is important to understand the tradeoffs regarding security and performance if you go down that route. Also note the networking requirements.
+
+## Hybrid approaches
+
+An alternative approach (and most often the recommended one) is a hybrid architecture that either combines Argo CD instances that control other clusters or mixes internal and external clusters in the different Argo CD installations.
+
+!!! information
+    It is important to remember that Argo CD can only manage other [external clusters](external). It is **NOT** possible to manage other Argo CD instances or have a parent-child relationship between different Argo CD installations.
+
+A hybrid approach combines the best of both worlds by allowing you to mitigate the risks of each one according to your own requirements.
+
+Example 1 - Different Argo CD instances per environment
+
+![Hybrid topology 1](../../assets/hybrid1.jpg)
+
+In this example there are 3 management Argo CD instances. This allows the Production instance to have different constraints than the non-production instances while also making upgrades of Argo CD itself more granular (Production instance can be updated at the end after QA and staging).
+
+Example 2 - Mix of Argo CD instances per region and environment
+
+![Hybrid topology 2](../../assets/hybrid2.jpg)
+
+In this example there are different Argo CD instances per region that manage other clusters, while each team also gets its own Argo CD instance. This allows developer teams to have their own config for their Argo CD instance and there is also no fear of affecting other teams during upgrades.
+
+## Which strategy to choose
+
+There is no right or wrong Argo CD topology. Each organization has different needs. It is also possible to start with one topology and change to another as the organization needs are changing.
+
+As a starting point we suggest we have at least 2 Argo CD categories (which might be individual instances or multiple installations)
+
+* Argo CD instance(s) for production systems
+* Argo CD instance(s) for NON production systems
+
+This would help you during [upgrades](../../operations/upgrading/) as you can test a new version of Argo CD itself without affecting production.
+
+

docs/basics/clusters/manage.md

@@ -0,0 +1,117 @@
+# Managing Clusters
+
+## Using the `argocd` CLI
+
+### Listing all clusters
+
+To list all clusters, run `argocd cluster list`. You should see a list of output with details about the clusters.
+
+```bash
+$ argocd cluster list
+SERVER                          NAME        VERSION  STATUS      MESSAGE
+https://kubernetes.default.svc  in-cluster  1.16+    Successful  
+```
+
+### Get details about a cluster
+
+To get more detailed information about a specific cluster, you can use `argocd cluster get <server>`, where `server` is the server URL of the cluster.
+
+```bash
+$ argocd cluster get https://kubernetes.default.svc
+config:
+  tlsClientConfig:
+    insecure: false
+connectionState:
+  attemptedAt: "2021-03-19T16:42:09Z"
+  message: ""
+  status: Successful
+info:
+  applicationsCount: 6
+  cacheInfo:
+    apisCount: 54
+    lastCacheSyncTime: "2021-03-19T16:39:36Z"
+    resourcesCount: 504
+  connectionState:
+    attemptedAt: "2021-03-19T16:42:09Z"
+    message: ""
+    status: Successful
+  serverVersion: 1.16+
+name: in-cluster
+server: https://kubernetes.default.svc
+serverVersion: 1.16+
+```
+
+### Add a cluster
+
+To add a cluster using the CLI:
+
+1. Ensure you have a valid context in your kubeconfig for the cluster. Running `argocd cluster add` will list all available contexts.
+2. Add the cluster with `argocd cluster add <context name>`.
+
+Adding a cluster with `argocd cluster add` installs a ServiceAccount named `argocd-manager` into the `kube-system` namespace of that context and binds the service account to an admin-level ClusterRole. Argo CD uses this service account token to perform its management tasks (i.e. deploy/monitoring).
+
+!!! Tip
+    To register the `in-cluster` cluster as a cluster with its own secret, run
+    `argocd cluster add <cluster name> --in-cluster`
+
+### Removing a cluster
+
+To remove a cluster using the CLI:
+
+1. Identify the server URL for the cluster. Running `argocd cluster list` will show a list of all clusters with their name and server.
+2. Remove the cluster with `argocd cluster rm <server>`
+
+!!! Note
+    Removing a cluster will not remove the Applications associated with that cluster
+
+## Using the web UI
+
+### Get details about a cluster
+
+To view details about a cluster in the web UI, first go to `/settings/clusters/` in your Argo CD instance in your browser, then click on the row for a cluster. You can also click on the "edit" button in the top right corner to edit the cluster name or allowed namespaces.
+
+### Removing a cluster
+
+To remove a cluster using the web UI, first go to `/settings/clusters` in your Argo CD instance in your browser
+Then, find the cluster and click on the three dots on the right hand side of the cluster row, then click "delete".
+
+![Screenshot showing a cluster row in the ArgoCD UI with the "remove" option visible](../../assets/cluster-remove-ui.png)
+
+## Using the kubernetes API
+
+Clusters are stored as kubernetes secrets, so it is possible (but not typically recommended) to manipulate them using the kubernetes API. 
+
+### Listing all clusters
+
+To view all cluster secrets, you can run `kubectl get secret -l argocd.argoproj.io/secret-type="cluster"` in the namespace for your Argo CD instance. The secrets should be in the format `cluster-<server url>-<hash>`, and have keys for `config`, `name`, `server`, and (optionally) `shard`.
+
+```bash
+$ kubectl get secret -l argocd.argoproj.io/secret-type="cluster" -n argocd
+NAME                                        TYPE     DATA   AGE
+cluster-kubernetes.default.svc-3396314289   Opaque   3      3s
+```
+
+```bash
+$ kubectl get secret -n argocd cluster-kubernetes.default.svc-3396314289 -o yaml
+apiVersion: v1
+data:
+  config: ****
+  name: ZG9ja2VyLWRlc2t0b3A=
+  server: aHR0cHM6Ly9rdWJlcm5ldGVzLmRlZmF1bHQuc3Zj
+kind: Secret
+metadata:
+  annotations:
+    managed-by: argocd.argoproj.io
+  creationTimestamp: "2021-03-19T16:59:50Z"
+  labels:
+    argocd.argoproj.io/secret-type: cluster
+  name: cluster-kubernetes.default.svc-3396314289
+  namespace: argocd
+  resourceVersion: "8980461"
+  selfLink: /api/v1/namespaces/argocd/secrets/cluster-kubernetes.default.svc-3396314289
+  uid: 19b453ce-93e7-41f0-b59d-0c4e3b51f3a0
+```
+
+### Removing a cluster
+
+To remove a cluster, identify the name of the cluster secret and run `kubectl delete secret <cluster secret name>`.

docs/basics/projects/index.md

@@ -0,0 +1,35 @@
+# Projects
+
+## Overview
+
+The so-called *Projects* (or, *AppProject* alternatively) play a vital role in
+the multi-tenancy and governance model of Argo CD. It is important to understand
+how *Projects* work and how they impact *Applications* and permissions.
+
+You can think of a *Project* as a way to group specific *Applications* together
+to enforce a common set of governance rules and settings on those Applications,
+with the settings being defined in the *Project*. For example, you can restrict
+the kind of resources allowed in an *Application*, or restrict the *Application*
+to source its manifests only from a certain repository, etc etc. Furthermore,
+projects can issue *access tokens* scoped to applications within the given
+project. These tokens can be used to access the Argo CD API for manipulation
+of *Applications* associated with the project, and their permissions can be
+configured using *Project* specific RBAC configuration.
+
+*Projects* and Applications have a *1:n* relationship, that is, multiple
+*Applications* can belong to the same *Project*, while each *Application* can
+only belong to one *Project*. Furthermore, the association of an *Application*
+to a *Project* is mandatory. It is not possible to have an *Application* that
+is not associated to a *Project*.
+
+An Argo CD *Project* is implemented as a Custom Resource `AppProject` in the
+`argoproj.io/v1alpha1` API. 
+
+All `AppProject` resources must exist in Argo CD's installation namespace
+(`argocd` by default) in the cluster Argo CD is installed to in order to be
+used by Argo CD. They cannot be installed in other clusters or namespaces.
+
+!!! tip "The default project"
+    Argo CD installs a default *Project* which permits everything and restricts
+    nothing. The default *Project* is called, well, `default`.
+

docs/basics/projects/roles.md

@@ -0,0 +1,7 @@
+# Project roles
+
+## Overview
+
+## Access tokens
+
+## Project specific RBAC rules

docs/basics/projects/settings.md

@@ -0,0 +1,135 @@
+# Project level settings
+
+A project can enforce restrictions on the following entities:
+
+## Destinations
+
+A *Project* can define allowed *destinations* for any of the *Applications*
+associated with the *Project*. A *Project's* destination restriction is a
+tuple of a target cluster and a namespace, with wildcard pattern matching
+supported.
+
+|Cluster|Namespace|Outcome|
+|-|-|-|
+|*|*|Allow all namespaces in all clusters|
+|https://kubernetes.default.svc|*|Allow all namespaces in the local cluster (`kubernetes.default.svc`)|
+|https://prod-*|*|Allow all namespaces in target clusters with URL starting with `https://prod-*`|
+|*|dev-apps-*|Allow namespaces starting with `dev-apps-*` in all target clusters|
+
+When an *Application's* destination or one of the *Application's* resources
+with a hardcoded target namespace do not match an allowed destination of the
+*Project*, any sync operation will not be allowed.
+
+## Sources
+
+A *Project* can define allowed *sources* for any of the *Applications*
+associated with the *Project*. A *Project's* allowed sources is a list of one
+or more URL patterns that must match an *Application's* source repository.
+
+The corresponding CLI commands for adding or removing constraints on
+project sources are:
+
+* `argocd proj add-source` - adds a source
+* `argocd proj remove-source` - removes a source
+
+## Cluster resources
+
+A *Project* must define what kind of cluster-scoped resources *Applications* are
+allowed to deploy. If an *Application's* resources contain any cluster-scoped
+resources not allowed by the *Project*, any sync operation will not be allowed.
+
+Allowance of cluster-scoped resources is evaluated from two lists:
+
+* A positive-list to allow specific resources
+* A negative-list to deny specific resources
+
+In order to decide if a resource is allowed, it is first matched against the
+positive list. If it matches the positive-list, and is not found in the
+negative-list, the resource is allowed. If it doesn't match the positive-list,
+or is matched in the negative-list, the resource - and therefore the sync
+operation - is not allowed.
+
+Each list is using tuples of Kubernetes' API `Group` and `Kind` to match the
+resources of the *Application* against. Wildcard patterns are supported. Each
+resource **must** match against the positive-list, and **must not** match
+against the negative-list.
+
+The following table shows matching for a cluster-wide resource of Group/Kind
+`rbac.authorization.k8s.io/ClusterRole` (the dash `-` means, not configured)
+
+|Positive Group| Positive Kind|Negative Group|Negative Kind|Allowed|
+|-|-|-|-|-|
+|`*`|`*`|-|-|Yes|
+|`*`|`*`|`*`|`*`|No|
+|`rbac*`|`*`|-|-|Yes|
+|`*`|`*`|`rbac.authorization.k8s.io`|`ClusterRoleBinding`|Yes|
+
+A newly created *Project* without further configuration will forbid all
+cluster-scoped resources to be managed. The `default` *Project* allows all
+cluster-scoped resources to be managed.
+
+The corresponding CLI commands for adding or removing constraints on
+cluster-scoped resources are:
+
+* `argocd proj allow-cluster-resource` - adds a cluster-scoped resource to the
+  positive-list
+* `argocd proj deny-cluster-resource` - adds a cluster-scoped resource to the
+  negative-list
+
+## Namespaced resources
+
+A *Project* must define what kind of namespace-scoped resources *Applications*
+are allowed to deploy. If an *Application's* resources contain any
+namespace-scoped resources not allowed by the *Project*, any sync operation will
+not be allowed.
+
+The decision tree for whether allowing a namespaced resource for deployment is
+the same as for
+[cluster scoped resources](#cluster-resources).
+
+A newly created *Project* without further configuration will forbid all
+namespaced-scoped resources to be managed. The `default` *Project* allows all
+namespaced-scoped resources to be managed.
+
+The corresponding CLI commands for adding or removing constraints on namespaced
+resources are:
+
+* `argocd proj allow-namespace-resource` - adds a namespace-scoped resource to the
+  positive-list
+* `argocd proj deny-namespace-resource` - adds a namespace-scoped resource to the
+  negative-list
+
+!!! tip "Resources in the core API group"
+    If you need to add resources from the *Core* API group, i.e. *Secret* or
+    *ConfigMap* resources, use the empty string `''` as API group.
+
+## GnuPG keys used for signature verification
+
+An advanced feature of Argo CD is to only allow syncs from Git revisions that
+are signed using GnuPG (e.g. commited using `git commit -S`). You can read more
+about this feature in its
+[documentation](/advanced/gnupg.md).
+
+You can configure the GnuPG key IDs that commits need to be signed by for all
+applications belonging to a certain project. Once at least one key ID is added,
+signature verification will be enforced and any sync operation to a non-signed
+revision, or a revision that is signed with a GnuPG key not in the allow-list
+will be denied.
+
+The corresponding CLI commands for adding and removing GnuPG key IDs are:
+
+* `argocd proj add-signature-key`
+* `argocd proj remove-signature-key`
+
+By default, GnuPG commit verification is disabled.
+
+## Sync windows
+
+A *Project* can define time windows that determine when an *Application* is
+allowed to be synced to a cluster. You can read more about this feature in the
+[Sync Windows documentation](/advanced/sync_windows.md).
+
+By default, a *Project* does not restrict syncing to any time windows and the
+sync is allowed at all times.
+
+To manage sync windows, you can use the `argocd proj windows` command.

docs/basics/repos/auth.md

@@ -0,0 +1,77 @@
+# Repository authentication
+
+## Available authentication methods
+
+If your repository needs authentication to be accessed, the following methods
+are currently supported:
+
+||Basic Auth|TLS client certs|SSH private keys|
+|-|-|-|-|
+|Git via https|X|v1.3+|-|
+|Git via ssh|-|-|X|
+|Helm via https|v1.3+|v1.3+|-|
+
+Other authentication methods, such as AWS IAM or Google ServiceAccounts, are
+not (yet) supported by ArgoCD.
+
+!!! note "Optional vs mandatory authentication"
+    Authentication is optional for Git and Helm repositories connected using the
+    HTTPS protocol. For Git repositories connected using SSH, authentication is
+    mandatory and you need to supply a private key for these connections.
+
+## Personal Access Token (PAT)
+
+Some Git providers require you to use a personal access token (PAT) instead of
+username/password combination when accessing the repositories hosted there
+via HTTPS.
+
+Providers known to enforce the use of PATs are:
+
+* GitHub
+* GitLab
+* BitBucket
+
+You can specify the PAT simply as the password (see below) when connecting
+the custom repository to ArgoCD, using any or the empty string as the username.
+The value for the username (any, empty or your actual username) varies from
+provider to provider.
+
+## Credential templates
+
+Credential templates are a convinient method for accessing multiple repositories
+with the same set of credentials, so you don't have to configure (and possibly
+change regulary) credentials for every repository that you might want to access
+from ArgoCD. Instead, you set up the credentials once using the template and all
+repositories whose URL matches the templated one will re-use these credentials,
+as long as they don't have credentials set up specifically.
+
+For example, you have a bunch of private repositories in the GitHub organisation
+`yourorg`, all accessible using the same SSH key, you can set up a credential
+template for accessing the repositories via SSH like follows:
+
+```bash
+argocd repocreds add git@github.com:yourorg/ --ssh-private-key-path yourorg.key
+```
+
+Since the URL here is a pattern, no validation of the credentials supplied will
+be performed at all during creation of the template.
+
+### Matching templates against repository URLs
+
+Pattern matching will be done on a *best match* basis, so you can have more than
+one matching pattern for any given URL. The pattern that matches best (i.e. is
+the more specific) will win.
+
+Consider you have templates for the following two patterns:
+
+* `https://github.com/yourorg`
+
+* `https://github.com/yourorg/special-`
+
+Now, for the repository `https://github.com/yourorg/yourrepo`, the first pattern
+would match while for the repository `https://github.com/yourorg/special-repo`
+both pattern will match, but the second one will win because it is more specific.
+
+The syntax for the `argocd repocreds` command is similar to that of the
+`argocd repo` command, however it does not support any repository specific
+configuration such as LFS support.

docs/basics/repos/index.md

@@ -0,0 +1,126 @@
+# Repositories
+
+## Introduction
+
+Since ArgoCD is a GitOps centric tool, the repositories containing your
+application manifest(s) play a very vital role in the configuration of
+ArgoCD.
+
+ArgoCD supports pulling the manifests from two distinct types of repositories:
+
+* Git repositories, such as GitHub, GitLab or privately hosted ones
+* Helm repositories, such as Helm's stable charts, Harbor or Chart museum
+
+Git repositories can hold any kind of manifests or sources that ArgoCD
+supports. You can even store Helm charts in your Git repositories. Git
+repositories can be connected using either HTTPS or SSH protocols.
+
+Helm repositories, however, can only hold Helm charts by definition. Helm
+repositories can only be connected using HTTPS.
+
+!!! note
+    Each application defined in ArgoCD is mapped to exactly one repository.
+    It is not possible to map two or more repositories to a single
+    application. If you need resources from more than one repository to define
+    your application, you can look at the advanced repository topics below.
+
+## Unconfigured vs. Configured repositories
+
+ArgoCD differentiates between *unconfigured* and *configured* repositories.
+Unconfigured repositories are those that you can access without any further
+configuration, while a configured repository is required when you need to
+authenticate to the repository (and don't use credential templates as
+described below), or when you need additional custom settings.
+
+Configured repositories were previously known as *private* repositories, but
+have now evolved to be named *configured* repositories - because they don't
+necessarily need to be private.
+
+You don't have to configure a repository in ArgoCD in order to use it as a
+manifest source for your application - you can simply specify the URL of the
+repository when creating an application, as long as the repository is allowed
+as a source in the 
+[project's configuration](projects/#sources) and is publicly accesible or matches one of
+the configured credential templates. Using an unconfigured repository as source
+for your application is as simple as specifying its URL using the `--repo`
+parameter to the `argocd app create` command.
+
+!!! note
+    Only Git repositories accessed using HTTPS are currently supported to be
+    connected without further configuration. Git repositories connected using
+    SSH must always be configured in ArgoCD as a repository or have a matching
+    credential template. Helm repositories must always have an explicit
+    configuration before they can be used.
+
+Using a repository that requires further configuration as the source for an
+Application requires the repository to be configured, or *connected* first.
+For further information on how to connect a repository, please see below.
+
+It is suggested that each repository that you will use as an
+application's source is configured in ArgoCD first.
+
+## Specifying repository URLs
+
+Repository URLs should always be specified in a fully-qualified manner, that
+is they should contain the protocol modifier (i.e. `https://` or `ssh://`) as
+a prefix. Specifying custom ports for the connection to the repository server
+is possible using the `:port` modifier in the `hostname` portion of the URL.
+If a port is not specified, the default ports for the requested protocol
+will be used:
+
+* Port 443 for HTTPS connections
+* Port 22 for SSH connections
+
+Generally, URLs for repositories take the following form
+
+```bash
+protocol://[username@]hostname[:port]/path/to/repo
+```
+
+The `username` URL modifier is only valid (and mandatory!) for connecting Git
+repositories using SSH. Likewise, the `--username` parameter for the appropriate
+CLI commands is only valid for connecting Git or Helm repositories via HTTPS.
+
+!!! note "Usernames for SSH repositories"
+    When using SSH to connect to the repository, you *must* specify the remote
+    username in the URL, i.e. using `ssh://user@example.com/your/repo`. Most
+    Git providers use `git` as remote username, further information should be
+    taken from the provider's documentation.
+
+There is an exception when specifying repository URLs for repositories that
+are to be connected using SSH. These URLs can also be of `scp` style syntax
+in the following form:
+
+```bash
+username@hostname:path/to/repo
+```
+
+!!! warning "Remote port in SSH URLs"
+    Please note that with the `scp` style syntax, it is not possible to specify
+    a custom SSH server port in the URL, because the colon denominates the
+    beginning of the path, and the path will be relative to the SSH server's
+    working directory. If you need to connect via SSH to a non-standard port,
+    you **must** use `ssh://` style URLs to specify the repository to use.
+
+The following are some examples for valid repository URLs
+
+* `https://example.com/yourorg/repo` - specifies repository `/yourorg/repo` on
+  remote server `example.com`, connected via HTTPS on standard port.
+* `https://example.com:9443/yourorg/repo` - specifies repository `/yourorg/repo`
+  on remote server `example.com`, connected via HTTPS on non-standard port
+  `9443`.
+* `ssh://git@example.com/yourorg/repo` - specifies repository `/yourorg/repo`
+  on remote server `example.com`, connected via SSH on standard port and using
+  the remote username `git`.
+* `git@example.com:yourorg/repo` - same as above, but denoted using an `scp`
+  URL.
+* `ssh://git@example.com:2222/yourorg/repo` - specifies repository
+  `/yourorg/repo` on remote server `example.com`, connected via SSH on the
+  non-standard port `2222` and using `git` as the remote username.
+
+A common pitfall is the following `scp` style URL:
+
+* `git@example.com:2222/yourorg/repo` - This would **not** specify a repository
+  `/yourorg/repo` on remote server `example.com` with a non-standard port of
+  `2222`, but rather the repository `2222/yourorg/repo` on the remote server
+  `example.com` with the default SSH port `22`.

docs/basics/repos/manage.md

@@ -0,0 +1,221 @@
+# Managing configured repositories
+
+## Overview
+
+You can manage configured repositories for use with ArgoCD in three ways:
+
+* Using the CLI's `repo` sub-command
+* Using the web UI repository configuration, to be found at the `Repositories`
+  module in the `Settings` sections
+* Using declarative setup. For further information, please refer to the
+  appropriate chapter in the
+  [Operator Manual]().
+
+With each of the methods above, you can add, edit and remove custom repositories
+and their configuration.
+
+## Using the CLI
+
+### Listing all configured repositories
+
+You can list all currently configured repositories using the CLI:
+
+```shell
+argocd repo list
+```
+
+If you prefer to use the web UI, you find the list of configured repositories
+at the `Settings` -> `Repositories` page.
+
+### Adding a repository configuration
+
+Connecting a repository via HTTPS (TLS) is supported for both repository
+types, `git` and `helm`. The URL for a Git repository connected using HTTPS
+must be fully-qualified and prefixed with the protocol, i.e. `https://`. The
+URL may have an optional port modifier if the repository is served from a non
+default port, i.e. `https://example.com:9443`.
+
+!!! note "A few words on HTTP redirects"
+    ArgoCD does not follow HTTP redirects when handling repositories. Some Git
+    providers, notably GitLab and possibly also self-hosted GitLab, will send
+    you a HTTP redirect if your repository URL is not suffixed with `.git`. If
+    you receive a HTTP redirect on connecting the repository, try appending
+    the `.git` suffix to your URL. For example, if you use the URL
+    `https://gitlab.com/you/repo` and GitLab sends you a HTTP 301, try to use
+    `https://gitlab.com/you/repo.git` as the URL to your repository.
+
+To add a configuration for a Git repository to be connected using HTTPS, you
+can use the `argocd repo add` command, specifying a repository URL starting
+with `https://`. 
+
+In its most simple form, the command
+
+```bash
+argocd repo add https://example.com/your/repo
+```
+
+will add the Git repository at `https://example.com/your/repo` to the ArgoCD
+configuration. This simple form however is not different from using an
+unconfigured repository, except it will give you the perks from selecting
+the repository as an application's source in the UI from a dropdown list.
+
+You can add custom configuration for the repository by using the following set
+of command line switches to the `repo add` command:
+
+|Switch|Argument|Description|
+|-|-|-|
+|`--insecure-skip-server-verification`|None|Disables verification of the server's TLS certificate or SSH known host signature, depending on the connection method. You do not want use this switch for production environments.|
+|`--username`|`username`|Use `username` for authenticating at the server (only valid for HTTPS repositories and in combination with `--password`)|
+|`--password`|`password`|Use `password` for authenticating at the server (only valid for HTTPS repositories and in combination with `--username`)|
+|`--ssh-private-key-path`|`path`|Use SSH private key from `path` to authenticate at the remote repository. Only valid and also mandatory for SSH repositories. The private key will be stored in a secret on the cluster ArgoCD runs on.|
+|`--type`|`type`|Specify that repository is of type `repotype`. Current possible values are `helm` and `git` (defaults to `git`)|
+|`--name`|`name`|Specify the name of the repository to be `name`. This is mandatory when adding Helm repositories and optional when adding Git repositories.|
+|`--tls-client-cert-path`|`path`|Specifies to read the TLS client certificate used for authentication from `path` on the local machine. The certificate will be stored in a secret on the cluster ArgoCD is running on.|
+|`--tls-client-cert-key-path`|`path`|Specifies to read the key for TLS client certificate used for authentication from `path` on the local machine. The key will be stored in a secret on the cluster ArgoCD is running on.|
+|`--enable-lfs`|None|Enables the support for Git Large File Storage (LFS) on the repository. Only valid for Git repositories.|
+
+### Examples: Adding repositories via CLI
+
+The following command adds a Git repository from `https://github.com/foo/repo`,
+using `foo` as the username and `bar` as the password for authentication:
+
+```bash
+argocd repo add --username foo --password bar https://github.com/foo/repo
+```
+
+The following command uses a TLS client certificate in addition to the 
+username/password combination to connect the repository. The cert is read
+from `~/mycert.crt`, the corresponding key from `~/mycert.key`:
+
+```bash
+argocd repo add --username foo --password \
+  --tls-client-cert-path ~/mycert.key \
+  --tls-client-cert-key-path ~/mykey.key \
+  https://secure.example.com/repos/myrepo
+```
+
+The following command adds the repository without any authentication, but will
+ignore the TLS certificate presented by the server. Needless to say, this should
+only be used for testing purposes in non-prod environments. Instead of using
+this insecure option, you should consider adding the appropriate TLS certificate
+or CA certificate to ArgoCD so it will be able to correctly verify the server's
+certificate:
+
+```bash
+argocd repo add --insecure-skip-server-verification \
+  https://self-hosted.example.com/repos/myrepo
+```
+
+Finally, the following command adds a repository using the SSH protocol, the
+private SSH key from your local path `~/.ssh/id_rsa` for authentication and
+`git` as the remote username:
+
+```bash
+argocd repo add --ssh-private-key-path ~/.ssh/id_rsa \
+  ssh://git@example.com/yourorg/repo
+```
+
+## Using the web UI
+
+Repositories can also be configured using the web UI. The configuration module
+can be found by clicking on `Settings` and then `Repositories`.
+
+You first need to chose what type of connection your repository should use, and
+then click on the appropriate button:
+
+![Choose repo type](/assets/repo-mgmt-ui-add.png)
+
+The following will walk you through the dialogues for connecting the repository,
+depending on which method you chose:
+
+**SSH:**
+
+![Connect repo using SSH](/assets/repo-mgmt-ui-add-ssh.png)
+
+1. The name of the repository. This is optional for Git repositories.
+
+1. The URL to the repository. This must be either a `ssh://` or `scp` style
+  URL (see discussions about URLs above)
+
+1. Paste the SSH private key to use. This must be a valid SSH private key,
+  including the start and end denominators.
+
+1. If you want to skip the server's SSH host key signature verification, tick
+  this box. You should **not** use this in production environments.
+
+1. If you require Git LFS, tick this box.
+
+1. Click on "Connect" to connect the repository to ArgoCD.
+
+!!! note "Note about SSH private keys"
+    You should make sure that the SSH private key you are pasting does not
+    contain any unintentional line breaks. If using a terminal, you should
+    use `cat ~/yourkey`, mark everything including the
+    `-----BEGIN OPENSSH PRIVATE KEY-----` and
+    `-----END OPENSSH PRIVATE KEY-----` markers, copy the selection to your
+    clipboard and paste it into the UI's field.
+
+**HTTPS:**
+
+![Add repository using HTTPS](/assets/repo-mgmt-ui-add-https.png)
+
+1. The type of the repository. This can either be `git` or `helm`. Please note
+  that when `helm` is selected, another input field for `Repository name` will
+  appear, which you need to fill out as well.
+
+1. The URL to the repository. This must be a `https://` URL.
+
+1. The username to use for authenticating at the repository (optional)
+
+1. The password to use for authenticating at the repository (optional)
+
+1. An optional TLS client certificate to use for authentication. This should
+  be a paste of the full Base64-encoded TLS certificate, including the
+  `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` markers.
+  The certificate will be stored in a secret on the cluster ArgoCD is running
+  on.
+
+1. If you have specified a TLS client certificate, you must provide the
+  corresponding private key as well. This should be a paste of the full
+  Base64-encoded private key, including the
+  `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` markers. The
+  private key will be stored in a secret on the cluster ArgoCD is running on.
+
+1. To skip verification of the repository server's certificate, tick this box.
+  Using this setting in production environments is not recommended.
+
+1. If you require Git LFS support with this repository, tick this box.
+
+1. Click "Connect" to validate configuration and add the repository to ArgoCD
+  configuration.
+
+### Removing a repository configuration
+
+!!! warning
+    If you remove a repository configuration that is in active use by any of
+    your applications, ArgoCD will not prevent you to do so. All applications
+    that use the repository whose configuration has been removed as source,
+    will now access the repository as if it would be unconfigured - this could
+    lead to breakage due to unaccessible manifests.
+
+#### Remove using the CLI
+
+To remove a repository configuration from ArgoCD using the CLI, simply issue
+the following command:
+
+```bash
+argocd repo rm https://example.com/your/repo
+```
+
+#### Using the web UI
+
+Navigate to the repositories configuration at `Settings` -> `Repositories` and
+find the repository you want to unconfigure in the list of configured
+repositories. Then click on the three vertical dots next to the entry and select
+`Disconnect` from the dropdown, as shown on the following screenshot:
+
+![Remove repository](/assets/repo-mgmt-ui-remove.png)
+
+The UI will ask for your final confirmation before removing the repository from
+the configuration.
+

docs/basics/repositories.md

@@ -0,0 +1,433 @@
+# Working with repositories
+
+## Introduction
+
+Since ArgoCD is a GitOps centric tool, the repositories containing your
+application manifest(s) play a very vital role in the configuration of
+ArgoCD.
+
+ArgoCD supports pulling the manifests from two distinct types of repositories:
+
+* Git repositories, such as GitHub, GitLab or privately hostes ones
+* Helm repositories, such as Helm's stable charts, Harbor or Chart museum
+
+Git repositories can hold any kind of manifests or sources that ArgoCD
+supports. You can even store Helm charts in your Git repositories. Git
+repositories can be connected using either HTTPS or SSH protocols.
+
+Helm repositories, however, can only hold Helm charts by definition. Helm
+repositories can only be connected using HTTPS.
+
+!!! note
+    Each application defined in ArgoCD is mapped to exactly one repository.
+    It is not possible to map two or more repositories to a single
+    application. If you need resources from more than one repository to define
+    your application, you can look at the advanced repository topics below.
+
+## Unconfigured vs. Configured repositories
+
+ArgoCD differentiates between *unconfigured* and *configured* repositories.
+Unconfigured repositories are those that you can access without any further
+configuration, while a configured repository is required when you need to
+authenticate to the repository (and don't use credential templates as
+described below), or when you need additional custom settings.
+
+Configured repositories were previously known as *private* repositories, but
+have now evolved to be named *configured* repositories - because they don't
+necessarily need to be private.
+
+You don't have to configure a repository in ArgoCD in order to use it as a
+manifest source for your application - you can simply specify the URL of the
+repository when creating an application, as long as the repository is allowed
+as a source in the 
+[project's configuration](projects/#sources) and is publicly accesible or matches one of
+the configured credential templates. Using an unconfigured repository as source
+for your application is as simple as specifying its URL using the `--repo`
+parameter to the `argocd app create` command.
+
+!!! note
+    Only Git repositories accessed using HTTPS are currently supported to be
+    connected without further configuration. Git repositories connected using
+    SSH must always be configured in ArgoCD as a repository or have a matching
+    credential template. Helm repositories must always have an explicit
+    configuration before they can be used.
+
+Using a repository that requires further configuration as the source for an
+Application requires the repository to be configured, or *connected* first.
+For further information on how to connect a repository, please see below.
+
+It is suggested that you configure each repository that you will use as an
+application's source is configured in ArgoCD first.
+
+## Repository authentication
+
+### Available authentication methods
+
+If your repository needs authentication to be accessed, the following methods
+are currently supported:
+
+||Basic Auth|TLS client certs|SSH private keys|
+|-|-|-|-|
+|Git via https|X|v1.3+|-|
+|Git via ssh|-|-|X|
+|Helm via https|v1.3+|v1.3+|-|
+
+Other authentication methods, such as AWS IAM or Google ServiceAccounts, are
+not (yet) supported by ArgoCD.
+
+!!! note "Optional vs mandatory authentication"
+    Authentication is optional for Git and Helm repositories connected using the
+    HTTPS protocol. For Git repositories connected using SSH, authentication is
+    mandatory and you need to supply a private key for these connections.
+
+### Personal Access Token (PAT)
+
+Some Git providers require you to use a personal access token (PAT) instead of
+username/password combination when accessing the repositories hosted there
+via HTTPS.
+
+Providers known to enforce the use of PATs are:
+
+* GitHub
+* GitLab
+* BitBucket
+
+You can specify the PAT simply as the password (see below) when connecting
+the custom repository to ArgoCD, using any or the empty string as the username.
+The value for the username (any, empty or your actual username) varies from
+provider to provider.
+
+## Specifying repository URLs
+
+Repository URLs should always be specified in a fully-qualified manner, that
+is they should contain the protocol modifier (i.e. `https://` or `ssh://`) as
+a prefix. Specifying custom ports for the connection to the repository server
+is possible using the `:port` modifier in the `hostname` portion of the URL.
+If a port is not specified, the default ports for the requested protocol
+will be used:
+
+* Port 443 for HTTPS connections
+* Port 22 for SSH connections
+
+Generally, URLs for repositories take the following form
+
+```bash
+protocol://[username@]hostname[:port]/path/to/repo
+```
+
+The `username` URL modifier is only valid (and mandatory!) for connecting Git
+repositories using SSH. Likewise, the `--username` parameter for the appropriate
+CLI commands is only valid for connecting Git or Helm repositories via HTTPS.
+
+!!! note "Usernames for SSH repositories"
+    When using SSH to connect to the repository, you *must* specify the remote
+    username in the URL, i.e. using `ssh://user@example.com/your/repo`. Most
+    Git providers use `git` as remote username, further information should be
+    taken from the provider's documentation.
+
+There is an exception when specifying repository URLs for repositories that
+are to be connected using SSH. These URLs can also be of `scp` style syntax
+in the following form:
+
+```bash
+username@hostname:path/to/repo
+```
+
+!!! warning "Remote port in SSH URLs"
+    Please note that with the `scp` style syntax, it is not possible to specify
+    a custom SSH server port in the URL, because the colon denominates the
+    beginning of the path, and the path will be relative to the SSH server's
+    working directory. If you need to connect via SSH to a non-standard port,
+    you **must** use `ssh://` style URLs to specify the repository to use.
+
+The following are some examples for valid repository URLs
+
+* `https://example.com/yourorg/repo` - specifies repository `/yourorg/repo` on
+  remote server `example.com`, connected via HTTPS on standard port.
+* `https://example.com:9443/yourorg/repo` - specifies repository `/yourorg/repo`
+  on remote server `example.com`, connected via HTTPS on non-standard port
+  `9443`.
+* `ssh://git@example.com/yourorg/repo` - specifies repository `/yourorg/repo`
+  on remote server `example.com`, connected via SSH on standard port and using
+  the remote username `git`.
+* `git@example.com:yourorg/repo` - same as above, but denoted using an `scp`
+  URL.
+* `ssh://git@example.com:2222/yourorg/repo` - specifies repository
+  `/yourorg/repo` on remote server `example.com`, connected via SSH on the
+  non-standard port `2222` and using `git` as the remote username.
+
+A common pitfall is the following `scp` style URL:
+
+* `git@example.com:2222/yourorg/repo` - This would **not** specify a repository
+  `/yourorg/repo` on remote server `example.com` with a non-standard port of
+  `2222`, but rather the repository `2222/yourorg/repo` on the remote server
+  `example.com` with the default SSH port `22`.
+
+## Managing configured repositories
+
+You can manage configured repositories for use with ArgoCD in three ways:
+
+* Using the CLI's `repo` sub-command
+* Using the web UI repository configuration, to be found at the `Repositories`
+  module in the `Settings` sections
+* Using declarative setup. For further information, please refer to the
+  appropriate chapter in the
+  [Operator Manual]().
+
+With each of the methods above, you can add, edit and remove custom repositories
+and their configuration.
+
+### Listing all configured repositories
+
+You can list all currently configured repositories using the CLI:
+
+```shell
+argocd repo list
+```
+
+If you prefer to use the web UI, you find the list of configured repositories
+at the `Settings` -> `Repositories` page.
+
+### Adding a repository configuration
+
+Connecting a repository via HTTPS (TLS) is supported for both repository
+types, `git` and `helm`. The URL for a Git repository connected using HTTPS
+must be fully-qualified and prefixed with the protocol, i.e. `https://`. The
+URL may have an optional port modifier if the repository is served from a non
+default port, i.e. `https://example.com:9443`.
+
+!!! note "A few words on HTTP redirects"
+    ArgoCD does not follow HTTP redirects when handling repositories. Some Git
+    providers, notably GitLab and possibly also self-hosted GitLab, will send
+    you a HTTP redirect if your repository URL is not suffixed with `.git`. If
+    you receive a HTTP redirect on connecting the repository, try appending
+    the `.git` suffix to your URL. For example, if you use the URL
+    `https://gitlab.com/you/repo` and GitLab sends you a HTTP 301, try to use
+    `https://gitlab.com/you/repo.git` as the URL to your repository.
+
+#### Configuration using the CLI
+
+To add a configuration for a Git repository to be connected using HTTPS, you
+can use the `argocd repo add` command, specifying a repository URL starting
+with `https://`. 
+
+In its most simple form, the command
+
+```bash
+argocd repo add https://example.com/your/repo
+```
+
+will add the Git repository at `https://example.com/your/repo` to the ArgoCD
+configuration. This simple form however is not different from using an
+unconfigured repository, except it will give you the perks from selecting
+the repository as an application's source in the UI from a dropdown list.
+
+You can add custom configuration for the repository by using the following set
+of command line switches to the `repo add` command:
+
+|Switch|Argument|Description|
+|-|-|-|
+|`--insecure-skip-server-verification`|None|Disables verification of the server's TLS certificate or SSH known host signature, depending on the connection method. You do not want use this switch for production environments.|
+|`--username`|`username`|Use `username` for authenticating at the server (only valid for HTTPS repositories and in combination with `--password`)|
+|`--password`|`password`|Use `password` for authenticating at the server (only valid for HTTPS repositories and in combination with `--username`)|
+|`--ssh-private-key-path`|`path`|Use SSH private key from `path` to authenticate at the remote repository. Only valid and also mandatory for SSH repositories. The private key will be stored in a secret on the cluster ArgoCD runs on.|
+|`--type`|`type`|Specify that repository is of type `repotype`. Current possible values are `helm` and `git` (defaults to `git`)|
+|`--name`|`name`|Specify the name of the repository to be `name`. This is mandatory when adding Helm repositories and optional when adding Git repositories.|
+|`--tls-client-cert-path`|`path`|Specifies to read the TLS client certificate used for authentication from `path` on the local machine. The certificate will be stored in a secret on the cluster ArgoCD is running on.|
+|`--tls-client-cert-key-path`|`path`|Specifies to read the key for TLS client certificate used for authentication from `path` on the local machine. The key will be stored in a secret on the cluster ArgoCD is running on.|
+|`--enable-lfs`|None|Enables the support for Git Large File Storage (LFS) on the repository. Only valid for Git repositories.|
+
+**Some examples:**
+
+The following command adds a Git repository from `https://github.com/foo/repo`,
+using `foo` as the username and `bar` as the password for authentication:
+
+```bash
+argocd repo add --username foo --password bar https://github.com/foo/repo
+```
+
+The following command uses a TLS client certificate in addition to the 
+username/password combination to connect the repository. The cert is read
+from `~/mycert.crt`, the corresponding key from `~/mycert.key`:
+
+```bash
+argocd repo add --username foo --password \
+  --tls-client-cert-path ~/mycert.key \
+  --tls-client-cert-key-path ~/mykey.key \
+  https://secure.example.com/repos/myrepo
+```
+
+The following command adds the repository without any authentication, but will
+ignore the TLS certificate presented by the server. Needless to say, this should
+only be used for testing purposes in non-prod environments. Instead of using
+this insecure option, you should consider adding the appropriate TLS certificate
+or CA certificate to ArgoCD so it will be able to correctly verify the server's
+certificate:
+
+```bash
+argocd repo add --insecure-skip-server-verification \
+  https://self-hosted.example.com/repos/myrepo
+```
+
+Finally, the following command adds a repository using the SSH protocol, the
+private SSH key from your local path `~/.ssh/id_rsa` for authentication and
+`git` as the remote username:
+
+```bash
+argocd repo add --ssh-private-key-path ~/.ssh/id_rsa \
+  ssh://git@example.com/yourorg/repo
+```
+
+#### Configuration using the web UI
+
+Repositories can also be configured using the web UI. The configuration module
+can be found by clicking on `Settings` and then `Repositories`.
+
+You first need to chose what type of connection your repository should use, and
+then click on the appropriate button:
+
+![Choose repo type](/assets/repo-mgmt-ui-add.png)
+
+The following will walk you through the dialogues for connecting the repository,
+depending on which method you chose:
+
+**SSH:**
+
+![Connect repo using SSH](/assets/repo-mgmt-ui-add-ssh.png)
+
+1. The name of the repository. This is optional for Git repositories.
+
+1. The URL to the repository. This must be either a `ssh://` or `scp` style
+  URL (see discussions about URLs above)
+
+1. Paste the SSH private key to use. This must be a valid SSH private key,
+  including the start and end denominators.
+
+1. If you want to skip the server's SSH host key signature verification, tick
+  this box. You should **not** use this in production environments.
+
+1. If you require Git LFS, tick this box.
+
+1. Click on "Connect" to connect the repository to ArgoCD.
+
+!!! note "Note about SSH private keys"
+    You should make sure that the SSH private key you are pasting does not
+    contain any unintentional line breaks. If using a terminal, you should
+    use `cat ~/yourkey`, mark everything including the
+    `-----BEGIN OPENSSH PRIVATE KEY-----` and
+    `-----END OPENSSH PRIVATE KEY-----` markers, copy the selection to your
+    clipboard and paste it into the UI's field.
+
+**HTTPS:**
+
+![Add repository using HTTPS](/assets/repo-mgmt-ui-add-https.png)
+
+1. The type of the repository. This can either be `git` or `helm`. Please note
+  that when `helm` is selected, another input field for `Repository name` will
+  appear, which you need to fill out as well.
+
+1. The URL to the repository. This must be a `https://` URL.
+
+1. The username to use for authenticating at the repository (optional)
+
+1. The password to use for authenticating at the repository (optional)
+
+1. An optional TLS client certificate to use for authentication. This should
+  be a paste of the full Base64-encoded TLS certificate, including the
+  `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` markers.
+  The certificate will be stored in a secret on the cluster ArgoCD is running
+  on.
+
+1. If you have specified a TLS client certificate, you must provide the
+  corresponding private key as well. This should be a paste of the full
+  Base64-encoded private key, including the
+  `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` markers. The
+  private key will be stored in a secret on the cluster ArgoCD is running on.
+
+1. To skip verification of the repository server's certificate, tick this box.
+  Using this setting in production environments is not recommended.
+
+1. If you require Git LFS support with this repository, tick this box.
+
+1. Click "Connect" to validate configuration and add the repository to ArgoCD
+  configuration.
+
+### Removing a repository configuration
+
+!!! warning
+    If you remove a repository configuration that is in active use by any of
+    your applications, ArgoCD will not prevent you to do so. All applications
+    that use the repository whose configuration has been removed as source,
+    will now access the repository as if it would be unconfigured - this could
+    lead to breakage due to unaccessible manifests.
+
+#### Remove using the CLI
+
+To remove a repository configuration from ArgoCD using the CLI, simply issue
+the following command:
+
+```bash
+argocd repo rm https://example.com/your/repo
+```
+
+#### Using the web UI
+
+Navigate to the repositories configuration at `Settings` -> `Repositories` and
+find the repository you want to unconfigure in the list of configured
+repositories. Then click on the three vertical dots next to the entry and select
+`Disconnect` from the dropdown, as shown on the following screenshot:
+
+![Remove repository](/assets/repo-mgmt-ui-remove.png)
+
+The UI will ask for your final confirmation before removing the repository from
+the configuration.
+
+## Managing credential templates
+
+Credential templates are a convinient method for accessing multiple repositories
+with the same set of credentials, so you don't have to configure (and possibly
+change regulary) credentials for every repository that you might want to access
+from ArgoCD. Instead, you set up the credentials once using the template and all
+repositories whose URL matches the templated one will re-use these credentials,
+as long as they don't have credentials set up specifically.
+
+For example, you have a bunch of private repositories in the GitHub organisation
+`yourorg`, all accessible using the same SSH key, you can set up a credential
+template for accessing the repositories via SSH like follows:
+
+```bash
+argocd repocreds add git@github.com:yourorg/ --ssh-private-key-path yourorg.key
+```
+
+Since the URL here is a pattern, no validation of the credentials supplied will
+be performed at all during creation of the template.
+
+### Matching templates against repository URLs
+
+Pattern matching will be done on a *best match* basis, so you can have more than
+one matching pattern for any given URL. The pattern that matches best (i.e. is
+the more specific) will win.
+
+Consider you have templates for the following two patterns:
+
+* `https://github.com/yourorg`
+
+* `https://github.com/yourorg/special-`
+
+Now, for the repository `https://github.com/yourorg/yourrepo`, the first pattern
+would match while for the repository `https://github.com/yourorg/special-repo`
+both pattern will match, but the second one will win because it is more specific.
+
+The syntax for the `argocd repocreds` command is similar to that of the
+`argocd repo` command, however it does not support any repository specific
+configuration such as LFS support.
+
+## Self-signed TLS certificates, custom CAs and SSH Known Hosts
+
+## Advanced repository topics
+
+### Git LFS
+
+### Git submodules
+
+### Separating Helm values and Helm charts

docs/basics/terminology.md

@@ -0,0 +1,111 @@
+Before using Argo CD we assume that you already know about containers, tags and registries. Ideally you should also know how to build containers and publish them to a registry.
+
+In addition, you should also be familiar with basic Kubernetes concepts such as:
+
+ * [manifest](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/)
+ * [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) 
+ * [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
+ * other resources such as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), [services](https://kubernetes.io/docs/concepts/services-networking/service/), [configuration maps](https://kubernetes.io/docs/concepts/configuration/configmap/) etc.
+
+Argo CD is a Continuous Delivery solution specifically created
+for deploying containers to Kubernetes clusters, so a basic understanding
+of both is required in order to use Argo CD effectively.
+
+
+## GitOps
+
+GitOps is a set of best practices for application (and infrastructure) deployments. Argo CD implements these practices, so if you understand the principles of GitOps you can understand the decisions behind Argo CD. The GitOps principles are explained at [opengitops.dev](https://opengitops.dev/). In summary Argo CD works as GitOps controller that pulls automatically updates (principle 3) from manifests stored in Git (principle 2) that describe Kubernetes objects in a declarative manner (principle 1). The syncing process between Git and cluster is happening at regular intervals and works both ways (principle 4).
+
+## Application
+
+The Application is one of the central entities in Argo CD. Kubernetes by itself does not describe what exactly constitutes an application. Argo CD fills this gap by introducing the Application entity that not only groups associated Kubernetes manifests but also defines the source of truth for these manifests in the form of a Git repository. At its simplest form an Argo CD application is an association between a Git repository and a target cluster.
+
+## Project
+
+Project is another entity introduced by Argo CD and is used as a way to group applications. You can use projects in any way you see fit (e.g. per team, per department) but in most cases each project is used to define different security constraints and rules. Projects are the way an operator
+can segment and secure an Argo CD instance for different teams of developers.
+Note that using projects is completely optional. Argo CD comes with a "default" project.
+
+## Cluster
+
+A cluster is any compliant Kubernetes platform that you want to deploy an application to. A single Argo CD instance can manage multiple clusters. By default Argo CD can manage the cluster it was installed on, but you can add extra clusters as deployment targets which themselves do not need to run an Argo CD installation on their own. It is also possible to do the opposite and install multiple Argo CD instances in a single cluster and manage only specific namespaces with each instance.
+
+## Git repository
+
+A Git source is one of the central concepts under GitOps as it holds the source of truth for all your application. The basic Argo CD control loop is to compare each associated Git repository with each cluster deployment and see if there any differences. Argo CD can work with different types of Git providers and protocols and also supports both private and public Git repositories.
+
+## Apps-of-apps pattern
+
+At its most simple form an Application is grouping individual Kubernetes resources (deployments, services etc.). But since the Application itself is a custom Kubernetes object, you can create Argo CD applications that recursively include other Applications. This pattern is called App-of-Apps and is a great way to group micro-services or otherwise related applications. Argo CD supports this pattern in many ways, (for example you can easily drill down in the application hierarchy in the Web UI), but does not enforce it in any way.
+
+## Application set
+
+The [Application Set controller](https://argocd-applicationset.readthedocs.io/en/stable/) is a subproject of Argo CD geared towards multi-cluster and multi-application Argo CD installations. It is a way to automatically create applications/clusters using different generators. For example you can create multiple applications [according to a set of folders in Git](https://argocd-applicationset.readthedocs.io/en/stable/Generators-Git/), or a set of environments according to the [Pull Requests](https://argocd-applicationset.readthedocs.io/en/stable/Generators-Pull-Request/) that you have open. Using Application Sets is optional.
+
+## Command Line Interface (CLI)
+
+Argo CD has a CLI called `argocd` that can be used to manage various aspects of Argo CD, such as applications, clusters and other entities. Using the CLI is great for automation and scripting. It can also be used from a Continuous Integration (CI) pipeline to automate deployments as part of a workflow. The CLI is optional and some people might prefer to use the web UI for the same actions.
+
+## Web User Interface (UI)
+
+Argo CD has a very powerful web interface that can be used to inspect your applications as well as drill down on their individual components. You can also perform common actions from within the UI (including deleting applications). Installing the UI is optional, and you can deploy Argo CD in headless mode without it. You can also lock down the UI using Access Control and User management. 
+
+## Application Programming Interface (API)
+
+Argo CD exposes a RESTful API that allows you to automate all possible actions from your own program or script. Everything that is available from the CLI and the UI is also available through Argo CD's API.  
+
+## Target state
+
+The desired state of an application as described in Git. Typically it consists of Kubernetes manifests either in raw form or templated with Helm/Kustomize or other configuration management tool. 
+
+##  Live state
+
+The state of the application as found in the cluster. It typically includes pods, services, secrets, configmaps and other Kubernetes objects.
+
+## Diff process
+
+The operation when the live state and target state are compared. If they are the same we know that what is in the cluster is also in Git and thus no action needs to be taken. If they are not the same, Argo CD can take an action according to its configuration. A possible action is to apply changes from the Git state to the live state starting the sync process. It is also possible to customize the diff process to ignore specific fields.
+
+## Sync process
+
+The sync process takes places after the diff process and makes all the necessary changes to the live state in order to bring the cluster back to the same state as what is described in Git. There are many settings for the sync process that control if it is automated or not, what objects to ignore, if removing objects is allowed etc.
+
+## Sync status
+
+The sync status for all applications is monitored by Argo CD at all times. "Synced" denotes the case where live state and target state are the same. "Out Of Sync" means that there is a drift between the two of them.
+
+## Refresh status
+
+By default Argo CD will compare live state and target state every 3 minutes. You can change this period with a configuration setting. You can also "refresh" on demand any application from the UI or CLI forcing Argo CD to start the diff process. You can also start the diff process with webhooks from your Git provider.
+
+## Sync waves
+
+Sync waves allow you to customize the order of resource creation when an application is synced. For example you might want a service account object to be created before another Kubernetes resource that needs it.
+
+## Resource Hooks
+
+For each sync operation Argo CD can optionally run other actions before/during/after the sync process. For example you can use the `PostSync` hook
+to run some smoke tests in your new deployments. In the case of Helm, Argo CD also tries to translate [Helm hooks](https://helm.sh/docs/topics/charts_hooks/) to Argo CD hooks.
+
+## Health status
+
+This is an Argo CD specific status that is monitored for all applications. The "healthy" state is different per application type. For example, a Kubernetes ReplicaSet is deemed healthy if the live generation and live replicas match the target generation and desired replicas. Argo CD also has built-in health checks for other common resources such as [Argo Rollout Objects](https://argoproj.github.io/argo-rollouts/) or [Bitnami Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets).
+You can create your own Health checks with the [Lua programming language](https://www.lua.org/).
+
+## Configuration management tool
+
+Argo CD can use any supported templating tool such as Helm, Kustomize, JSonnet. You can add your own third party tool for preparing/templating Kubernetes manifests. Note that in the case of Helm, Argo CD uses it as a pure templating tool. Helm applications installed with Argo CD are not visible to normal Helm commands, and not all of Helm's features and concepts are supported.
+
+## Custom Resource Definitions (CRDs)
+
+Argo CD defines CRDs for all its entities (applications, projects etc). Since CRDs can be stored declaratively in Git on their own, you can fully manage Argo CD configuration with Argo CD itself.
+
+## Role Based Access Control
+
+Argo CD includes a powerful RBAC mechanism on top of applications, projects, clusters and git repositories. With this mechanism Argo CD operators can lock down resources and restrict them only to a specific subset of users. RBAC configuration will also integrate with any of the supported Single Sign On (SSO) providers that might use in your organization.
+
+
+
+
+
+

docs/bug_triage.md

@@ -1,175 +0,0 @@
-# Bug triage proposal for ArgoCD
-
-## Situation
-
-Lots of issues on our issue tracker. Many of them not bugs, but questions,
-or very environment related. It's easy to lose oversight.
-
-Also, it's not obvious which bugs are important. Which bugs should be fixed
-first? Can we make a new release with the current inventory of open bugs?
-Is there still a bug that should make it to the new release?
-
-## Proposal
-
-We should agree upon a common issue triage process. The process must be lean
-and efficient, and should support us and the community looking into the GH
-issue tracker at making the following decisions:
-
-* Is it even a real bug?
-* If it is a real bug, what is the current status of the bug (next to "open" or "closed")?
-* How important is it to fix the bug?
-* How urgent is it to fix the bug?
-* Who will be working to fix the bug?
-
-We need new methods to classify our bugs, at least into these categories:
-
-* validity: Does the issue indeed represent a true bug
-* severity: Denominates what impact the bug has
-* priority: Denominates the urgency of the fix
-
-## Triage process
-
-GH issue tracker provides us with the possibility to label issues. Using these
-labels is not perfect, but should give a good start. Each new issue created in
-our issue tracker should be correctly labeled during its lifecycle, so keeping
-an overview would be simplified by the ability to filter for labels.
-
-The triage process could be as follows:
-
-1. A new bug issue is created by someone on the tracker
-
-1. The first person of the core team to see it will start the triage by classifying
-   the issue (see below). This will indicate the creator that we have noticed the
-   issue, and that it's not "fire & forget" tracker.
-
-1. Initial classification should be possible even when much of the information is
-   missing yet. In this case, the issue would be classified as such (see below).
-   Again, this indicates that someone has noticed the issue, and there is activity
-   in progress to get the required information.
-
-1. Classification of the issue can change over its life-cycle. However, once the
-   issue has been initially classified correctly (that is, with something else than
-   the "placeholder" classification discussed above), changes to the classification
-   should be discussed first with the person who initially classified the issue.
-
-## Classification
-
-We have introduced some new labels in the GH issue tracker for classifying the
-bug issues. These labels are prefixed with the string `bug/`, and should be
-applied to all new issues in our tracker.
-
-### Classification requires more information
-
-If it is not yet possible to classify the bug, i.e. because more information is
-required to correctly classify the bug, you should always set the label
-`bug/in-triage` to make it clear that triage process has started but could not
-yet be completed.
-
-### Issue type
-
-If it's clear that a bug issue is not a bug, but a question or reach for support,
-it should be marked as such:
-
-* Remove any of the labels prefixed `bug/` that might be attached to the issue
-* Remove the label `bug` from the issue
-* Add the label `inquiry` to the issue
-
-If the inquiry turns out to be something that should be covered by the docs, but
-is not, the following actions should be taken:
-
-* The title of the issue should be adapted that it will be clear that the bug
-  affects the docs, not the code
-* The label `documentation` should be attached to the issue
-
-If the issue is too confusing (can happen), another possibility is to close the
-issue and create a new one as described in above (with a meaningful title and
-the label `documentation` attached to it).
-
-### Validity
-
-Some reported bugs may be invalid. It could be a user error, a misconfiguration
-or something along these lines. If it is clear that the bug falls into one of
-these categories:
-
-* Remove any of the labels prefixed `bug/` that might be attached to the issue
-* Add the label `invalid` to the issue
-* Retain the `bug` label to the issue
-* Close the issue
-
-When closing the issue, it is important to let requester know why the issue
-has been closed. The optimum would be to provide a solution to his request
-in the comments of the issue, or at least pointers to possible solutions.
-
-### Regressions
-
-Sometimes it happens that something that worked in a previous release does
-not work now when it should still work. If this is the case, the following
-actions should be done
-
-* Add the label `regression` to the issue
-* Continue with triage
-
-### Severity
-
-It is important to find out how severe the impact of a bug is, and to label
-the bug with this information. For this purpose, the following labels exist
-in our tracker:
-
-* `bug/severity:minor`: Bug has limited impact and maybe affects only an
-  edge-case. Core functionality is not affected, and there is no data loss
-  involved. Something might not work as expected. Example of these kind of
-  bugs could be a CLI command that is not working as expected, a glitch in
-  the UI, wrong documentation, etc.
-
-* `bug/severity:major`: Malfunction in one of the core components, impacting
-  a majority of users or one of the core functionalities in ArgoCD. There is
-  no data loss involved, but for example a sync is not working due to a bug
-  in ArgoCD (and not due to user error), manifests fail to render, etc.
-
-* `bug/severity:critical`: A critical bug in ArgoCD, possibly resulting in
-  data loss, integrity breach or severe degraded overall functionality.
-
-### Priority
-
-The priority of an issue indicates how quickly the issue should be fixed and
-released. This information should help us in deciding the target release for
-the fix, and whether a bug would even justify a dedicated patch release. The
-following labels can be used to classify bugs into their priority:
-
-* `bug/priority:low`: Will be fixed without any specific target release.
-
-* `bug/priority:medium`: Should be fixed in the minor or major release, which
-  ever comes first.
-
-* `bug/priority:high`: Should be fixed with the next patch release.
-
-* `bug/priority:urgent`: Should be fixed immediately and might even justify a
-  dedicated patch release.
-
-The priority should be set according to the value of the fix and the attached
-severity. This means. a bug with a severity of `minor` could still be classified
-with priority `high`, when it is a *low hanging fruit* (i.e. the bug is easy to
-fix with low effort) and contributes to overall user experience of ArgoCD.
-
-Likewise, a bug classified with a severity of `major` could still have a
-priority of `medium`, if there is a workaround available for the bug which
-mitigates the effects of the bug to a bearable extend.
-
-Bugs classified with a severity of `critical` most likely belong to either
-the `urgent` priority, or to the `high` category when there is a workaround
-available.
-
-Bugs that have a `regression`label attached (see Regression above) should
-usually be handled with higher priority, so those kind of issues will most
-likely have a priority of `high` or `urgent` attached to it.
-
-## Summary
-
-Applying a little discipline when working with our issue tracker could greatly
-help us in making informed decision about which bugs to fix when. Also, it
-would help us to get a clear view whether we can do for example a new minor
-release without having forgot any outstanding issues that should make it into
-that release.
-
-If we are able to work with classification of bug issues, we might want to
-extend the triage for enhancement proposals and PRs as well.

docs/cli_installation.md

@@ -1,79 +0,0 @@
-# Installation
-
-You can download the latest Argo CD version from [the latest release page of this repository](https://github.com/argoproj/argo-cd/releases/latest), which will include the `argocd` CLI.
-
-## Linux
-
-You can view the latest version of Argo CD at the link above or run the following command to grab the version:
-
-```bash
-VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
-```
-
-Replace `VERSION` in the command below with the version of Argo CD you would like to download:
-
-```bash
-curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/$VERSION/argocd-linux-amd64
-```
-
-Make the `argocd` CLI executable:
-
-```bash
-chmod +x /usr/local/bin/argocd
-```
-
-You should now be able to run `argocd` commands.
-
-## Mac
-
-### Homebrew
-
-```bash
-brew install argocd
-```
-
-### Download With Curl
-
-You can view the latest version of Argo CD at the link above or run the following command to grab the version:
-
-```bash
-VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
-```
-
-Replace `VERSION` in the command below with the version of Argo CD you would like to download:
-
-```bash
-curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/$VERSION/argocd-darwin-amd64
-```
-
-Make the `argocd` CLI executable:
-
-```bash
-chmod +x /usr/local/bin/argocd
-```
-
-After finishing either of the instructions above, you should now be able to run `argocd` commands.
-
-
-## Windows
-
-### Download With Powershell: Invoke-WebRequest
-
-You can view the latest version of Argo CD at the link above or run the following command to grab the version:
-
-```powershell
-$version = (Invoke-RestMethod https://api.github.com/repos/argoproj/argo-cd/releases/latest).tag_name
-```
-
-Replace `$version` in the command below with the version of Argo CD you would like to download:
-
-```powershell
-$url = "https://github.com/argoproj/argo-cd/releases/download/" + $version + "/argocd-windows-amd64.exe"
-$output = "argocd.exe"
-
-Invoke-WebRequest -Uri $url -OutFile $output
-```
-Also please note you will probably need to move the file into your PATH.
-
-
-After finishing the instructions above, you should now be able to run `argocd` commands.

docs/community.md

@@ -0,0 +1,7 @@
+# Community & Ecosystem
+
+The following is a curated list of community projects related to Argo CD. If
+you have a cool project that benefits the general Argo CD community and want
+to have it listed here, please feel free to
+[submit a PR]()
+with the addition to this document!

docs/core_concepts.md

@@ -1,16 +0,0 @@
-# Core Concepts
-
-Let's assume you're familiar with core Git, Docker, Kubernetes, Continuous Delivery, and GitOps concepts.
-
-* **Application** A group of Kubernetes resources as defined by a manifest. This is a Custom Resource Definition (CRD).
-* **Application source type** Which **Tool** is used to build the application.
-* **Target state** The desired state of an application, as represented by files in a Git repository.
-* **Live state** The live state of that application. What pods etc are deployed.
-* **Sync status** Whether or not the live state matches the target state. Is the deployed application the same as Git says it should be?
-* **Sync** The process of making an application move to its target state. E.g. by applying changes to a Kubernetes cluster.
-* **Sync operation status** Whether or not a sync succeeded.
-* **Refresh** Compare the latest code in Git with the live state. Figure out what is different.
-* **Health** The health of the application, is it running correctly? Can it serve requests?
-* **Tool** A tool to create manifests from a directory of files. E.g. Kustomize or Ksonnet. See **Application Source Type**.
-* **Configuration management tool** See **Tool**.
-* **Configuration management plugin** A custom tool.

docs/developer-guide/api-docs.md

@@ -1,31 +0,0 @@
-# API Docs
-
-You can find the Swagger docs by setting the path to `/swagger-ui` in your Argo CD UI's. E.g. [http://localhost:8080/swagger-ui](http://localhost:8080/swagger-ui).
-
-## Authorization
-
-You'll need to authorize your API using a bearer token. To get a token:
-
-```bash
-$ curl $ARGOCD_SERVER/api/v1/session -d $'{"username":"admin","password":"password"}'
-{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1Njc4MTIzODcsImlzcyI6ImFyZ29jZCIsIm5iZiI6MTU2NzgxMjM4Nywic3ViIjoiYWRtaW4ifQ.ejyTgFxLhuY9mOBtKhcnvobg3QZXJ4_RusN_KIdVwao"} 
-```
-
-> <=v1.2
-
-Then pass using the HTTP `SetCookie` header, prefixing with `argocd.token`:
-
-```bash
-$ curl $ARGOCD_SERVER/api/v1/applications --cookie "argocd.token=$ARGOCD_TOKEN" 
-{"metadata":{"selfLink":"/apis/argoproj.io/v1alpha1/namespaces/argocd/applications","resourceVersion":"37755"},"items":...}
-```
-
-> v1.3
-
-Then pass using the HTTP `Authorization` header, prefixing with `Bearer `:
-
-```bash
-$ curl $ARGOCD_SERVER/api/v1/applications -H "Authorization: Bearer $ARGOCD_TOKEN" 
-{"metadata":{"selfLink":"/apis/argoproj.io/v1alpha1/namespaces/argocd/applications","resourceVersion":"37755"},"items":...}
-```
- 

docs/developer-guide/ci.md

@@ -1,74 +0,0 @@
-# Continuous Integration (CI)
-
-## Troubleshooting CI checks
-
-You can click on the "Details" link next to the failed step to get more information about the failure.
-
-![Failed GitHub Action](ci-pipeline-failed.png)
-
-To read more about The GitHub actions are configured in [`ci-build.yaml`](https://github.com/argoproj/argo-cd/blob/master/.github/workflows/ci-build.yaml).
-
-### Can I retrigger the checks without pushing a new commit?
-
-Since the CI pipeline is triggered on Git commits, there is currently no (known) way on how to retrigger the CI checks without pushing a new commit to your branch.
-
-If you are absolutely sure that the failure was due to a failure in the pipeline, and not an error within the changes you commited, you can push an empty commit to your branch, thus retriggering the pipeline without any code changes. To do so, issue
-
-```bash
-git commit --allow-empty -m "Retrigger CI pipeline"
-git push origin <yourbranch>
-```
-
-### Why does the build step fail?
-
-First, make sure the failing build step succeeds on your machine. Remember the containerized build toolchain is available, too.
-
-If the build is failing at the `Ensuring Gopkg.lock is up-to-date` step, you need to update the dependencies before you push your commits. Run `make dep-ensure` and `make dep` and commit the changes to `Gopkg.lock` to your branch.
-
-### Why does the codegen step fail?
-
-If the codegen step fails with "Check nothing has changed...", chances are high that you did not run `make codegen`, or did not commit the changes it made. You should double check by running `make codegen` followed by `git status` in the local working copy of your branch. Commit any changes and push them to your GH branch to have the CI check it again.
-
-A second common case for this is, when you modified any of the auto generated assets, as these will be overwritten upon `make codegen`.
-
-Generally, this step runs `codegen` and compares the outcome against the Git branch it has checked out. If there are differences, the step will fail.
-
-See [What checked-in code is generated and where does it come from?](faq.md#what-checked-in-code-is-generated-and-how-is-it-generated) for more information.
-
-### Why does the lint step fail?
-
-Your code failed to lint correctly, or modifications were performed by the `golangci-lint` process.
-
-* You should run `make lint`, or `golangci-lint run` on your local branch and fix all the issues.
-
-* If you receive an error like, ```File is not `goimports`-ed (goimports)```, the file is not formatted correctly. Run `gofmt -w $file.go` to resolve this linter error.
-
-### Why does the test or e2e steps fail?
-
-You should check for the cause of the failure in the check's detail page as described above. This will give you the name of the test that has failed, and details about why. If your test are passing locally (using the virtualized toolchain), chances are that the test might be flaky and will pass the next time it is run. Please retrigger the CI pipeline as described above and see if the test step now passes.
-
-## Updating The Builder Image
-
-Login to Docker Hub:
-
-```bash
-docker login
-```
-
-Build image:
-
-```bash
-make builder-image IMAGE_NAMESPACE=argoproj IMAGE_TAG=v1.0.0
-```
-
-## Public CD
-
-Every commit to master is built and published to `docker.pkg.github.com/argoproj/argo-cd/argocd:<version>-<short-sha>`. The list of images is available at
-https://github.com/argoproj/argo-cd/packages.
-
-!!! note
-    Github docker registry [requires](https://github.community/t5/GitHub-Actions/docker-pull-from-public-GitHub-Package-Registry-fail-with-quot/m-p/32888#M1294) authentication to read
-    even publicly available packages. Follow the steps from Kubernetes [documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry)
-    to configure image pull secret if you want to use `docker.pkg.github.com/argoproj/argo-cd/argocd` image.
-
-The image is automatically deployed to the dev Argo CD instance: [https://cd.apps.argoproj.io/](https://cd.apps.argoproj.io/)

docs/developer-guide/contributing.md

@@ -1,293 +0,0 @@
-# Contribution guide
-
-## Preface
-
-We want to make contributing to ArgoCD as simple and smooth as possible.
-
-This guide shall help you in setting up your build & test environment, so that you can start developing and testing bug fixes and feature enhancements without having to make too much effort in setting up a local toolchain.
-
-If you want to submit a PR, please read this document carefully, as it contains important information guiding you through our PR quality gates.
-
-As is the case with the development process, this document is under constant change. If you notice any error, or if you think this document is out-of-date, or if you think it is missing something: Feel free to submit a PR or submit a bug to our GitHub issue tracker.
-
-If you need guidance with submitting a PR, or have any other questions regarding development of ArgoCD, do not hesitate to [join our Slack](https://argoproj.github.io/community/join-slack) and get in touch with us in the `#argo-dev` channel!
-
-## Before you start
-
-You will need at least the following things in your toolchain in order to develop and test ArgoCD locally:
-
-* A Kubernetes cluster. You won't need a fully blown multi-master, multi-node cluster, but you will need something like K3S, Minikube or microk8s. You will also need a working Kubernetes client (`kubectl`) configuration in your development environment. The configuration must reside in `~/.kube/config` and the API server URL must point to the IP address of your local machine (or VM), and **not** to `localhost` or `127.0.0.1` if you are using the virtualized development toolchain (see below)
-
-* You will also need a working Docker runtime environment, to be able to build and run images.
-The Docker version must be fairly recent, and support multi-stage builds. You should not work as root. Make your local user a member of the `docker` group to be able to control the Docker service on your machine.
-
-* Obviously, you will need a `git` client for pulling source code and pushing back your changes.
-
-* Last but not least, you will need a Go SDK and related tools (such as GNU `make`) installed and working on your development environment. The minimum required Go version for building ArgoCD is **v1.14.0**.
-
-* We will assume that your Go workspace is at `~/go`.
-
-!!! note
-    **Attention minikube users**: By default, minikube will create Kubernetes client configuration that uses authentication data from files. This is incompatible with the virtualized toolchain. So if you intend to use the virtualized toolchain, you have to embed this authentication data into the client configuration. To do so, issue `minikube config set embed-certs true` and restart your minikube. Please also note that minikube using the Docker driver is currently not supported with the virtualized toolchain, because the Docker driver exposes the API server on 127.0.0.1 hard-coded. If in doubt, run `make verify-kube-connect` to find out.
-
-## Submitting PRs
-
-When you submit a PR against ArgoCD's GitHub repository, a couple of CI checks will be run automatically to ensure your changes will build fine and meet certain quality standards. Your contribution needs to pass those checks in order to be merged into the repository.
-
-In general, it might be beneficial to only submit a PR for an existing issue. Especially for larger changes, an Enhancement Proposal should exist before.
-
-!!!note
-
-    Please make sure that you always create PRs from a branch that is up-to-date with the latest changes from ArgoCD's master branch. Depending on how long it takes for the maintainers to review and merge your PR, it might be necessary to pull in latest changes into your branch again.
-
-Please understand that we, as an Open Source project, have limited capacities for reviewing and merging PRs to ArgoCD. We will do our best to review your PR and give you feedback as soon as possible, but please bear with us if it takes a little longer as expected.
-
-The following read will help you to submit a PR that meets the standards of our CI tests:
-
-### Title of the PR
-
-Please use a meaningful and concise title for your PR. This will help us to pick PRs for review quickly, and the PR title will also end up in the Changelog.
-
-We use the [Semantic PR title checker](https://github.com/zeke/semantic-pull-requests) to categorize your PR into one of the following categories:
-
-* `fix` - Your PR contains one or more code bug fixes
-* `feat` - Your PR contains a new feature
-* `docs` - Your PR improves the documentation
-* `chore` - Your PR improves any internals of ArgoCD, such as the build process, unit tests, etc
-
-Please prefix the title of your PR with one of the valid categories. For example, if you chose the title your PR `Add documentation for GitHub SSO integration`, please use `docs: Add documentation for GitHub SSO integration` instead.
-
-### Contributor License Agreement
-
-Every contributor to ArgoCD must have signed the current Contributor License Agreement (CLA). You only have to sign the CLA when you are a first time contributor, or when the agreement has changed since your last time signing it. The main purpose of the CLA is to ensure that you hold the required rights for your contribution. The CLA signing is an automated process.
-
-You can read the current version of the CLA [here](https://cla-assistant.io/argoproj/argo-cd).
-
-### PR template checklist
-
-Upon opening a PR, the details will contain a checklist from a template. Please read the checklist, and tick those marks that apply to you.
-
-### Automated builds & tests
-
-After you have submitted your PR, and whenever you push new commits to that branch, GitHub will run a number of Continuous Integration checks against your code. It will execute the following actions, and each of them has to pass:
-
-* Build the Go code (`make build`)
-* Generate API glue code and manifests (`make codegen`)
-* Run a Go linter on the code (`make lint`)
-* Run the unit tests (`make test`)
-* Run the End-to-End tests (`make test-e2e`)
-* Build and lint the UI code (`make lint-ui`)
-* Build the `argocd` CLI (`make cli`)
-
-If any of these tests in the CI pipeline fail, it means that some of your contribution is considered faulty (or a test might be flaky, see below).
-
-### Code test coverage
-
-We use [CodeCov](https://codecov.io) in our CI pipeline to check for test coverage, and once you submit your PR, it will run and report on the coverage difference as a comment within your PR. If the difference is too high in the negative, i.e. your submission introduced a significant drop in code coverage, the CI check will fail.
-
-Whenever you develop a new feature or submit a bug fix, please also write appropriate unit tests for it. If you write a completely new module, please aim for at least 80% of coverage.
-If you want to see how much coverage just a specific module (i.e. your new one) has, you can set the `TEST_MODULE` to the (fully qualified) name of that module with `make test`, i.e.:
-
-```bash
- make test TEST_MODULE=github.com/argoproj/argo-cd/server/cache
-...
-ok      github.com/argoproj/argo-cd/server/cache        0.029s  coverage: 89.3% of statements
-```
-
-## Local vs Virtualized toolchain
-
-ArgoCD provides a fully virtualized development and testing toolchain using Docker images. It is recommended to use those images, as they provide the same runtime environment as the final product and it is much easier to keep up-to-date with changes to the toolchain and dependencies. But as using Docker comes with a slight performance penalty, you might want to setup a local toolchain.
-
-Most relevant targets for the build & test cycles in the `Makefile` provide two variants, one of them suffixed with `-local`. For example, `make test` will run unit tests in the Docker container, `make test-local` will run it natively on your local system.
-
-If you are going to use the virtualized toolchain, please bear in mind the following things:
-
-* Your Kubernetes API server must listen on the interface of your local machine or VM, and not on `127.0.0.1` only.
-* Your Kubernetes client configuration (`~/.kube/config`) must not use an API URL that points to `localhost` or `127.0.0.1`.
-
-You can test whether the virtualized toolchain has access to your Kubernetes cluster by running `make verify-kube-connect` (*after* you have setup your development environment, as described below), which will run `kubectl version` inside the Docker container used for running all tests.
-
-The Docker container for the virtualized toolchain will use the following local mounts from your workstation, and possibly modify its contents:
-
-* `~/go/src` - Your Go workspace's source directory (modifications expected)
-* `~/.cache/go-build` - Your Go build cache (modifications expected)
-* `~/.kube` - Your Kubernetes client configuration (no modifications)
-* `/tmp` - Your system's temp directory (modifications expected)
-
-## Setting up your development environment
-
-The following steps are required no matter whether you chose to use a virtualized or a local toolchain.
-
-### Clone the ArgoCD repository from your personal fork on GitHub
-
-* `mkdir -p ~/go/src/github.com/argoproj`
-* `cd ~/go/src/github.com/argoproj`
-* `git clone https://github.com/yourghuser/argo-cd`
-* `cd argo-cd`
-
-### Optional: Setup an additional Git remote
-
-While everyone has their own Git workflow, the author of this document recommends to create a remote called `upstream` in your local copy pointing to the original ArgoCD repository. This way, you can easily keep your local branches up-to-date by merging in latest changes from the ArgoCD repository, i.e. by doing a `git pull upstream master` in your locally checked out branch. To create the remote, run `git remote add upstream https://github.com/argoproj/argo-cd`
-
-### Install the must-have requirements
-
-Make sure you fulfill the pre-requisites above and run some preliminary tests. Neither of them should report an error.
-
-* Run `kubectl version`
-* Run `docker version`
-* Run `go version`
-
-### Build (or pull) the required Docker image
-
-Build the required Docker image by running `make test-tools-image` or pull the latest version by issuing `docker pull argoproj/argocd-test-tools`.
-
-The `Dockerfile` used to build these images can be found at `test/container/Dockerfile`.
-
-### Test connection from build container to your K8s cluster
-
-Run `make verify-kube-connect`, it should execute without error.
-
-If you receive an error similar to the following:
-
-```
-The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?
-make: *** [Makefile:386: verify-kube-connect] Error 1
-```
-
-you should edit your `~/.kube/config` and modify the `server` option to point to your correct K8s API (as described above).
-
-### Using k3d
-
-[k3d](https://github.com/rancher/k3d) is a lightweight wrapper to run [k3s](https://github.com/rancher/k3s), a minimal Kubernetes distribution, in docker. Because it's running in a docker container, you're dealing with docker's internal networking rules when using k3d. A typical Kubernetes cluster running on your local machine is part of the same network that you're on so you can access it using **kubectl**. However, a Kubernetes cluster running within a docker container (in this case, the one launched by make) cannot access 0.0.0.0 from inside the container itself, when 0.0.0.0 is a network resource outside the container itself (and/or the container's network). This is the cost of a fully self-contained, disposable Kubernetes cluster. The following steps should help with a successful `make verify-kube-connect` execution.
-
-1. Find your host IP by executing `ifconfig` on Mac/Linux and `ipconfig` on Windows. For most users, the following command works to find the IP address.
-
-    * For Mac:
-
-    ```
-    IP=`ifconfig en0 | grep inet | grep -v inet6 | awk '{print $2}'`
-    echo $IP
-    ```
-
-    * For Linux:
-
-    ```
-    IP=`ifconfig eth0 | grep inet | grep -v inet6 | awk '{print $2}'`
-    echo $IP
-    ```
-
-    Keep in mind that this IP is dynamically assigned by the router so if your router restarts for any reason, your IP might change.
-
-2. Edit your ~/.kube/config and replace 0.0.0.0 with the above IP address.
-
-3. Execute a `kubectl version` to make sure you can still connect to the Kubernetes API server via this new IP. Run `make verify-kube-connect` and check if it works.
-
-4. Finally, so that you don't have to keep updating your kube-config whenever you spin up a new k3d cluster, add `--api-port $IP:6550` to your **k3d cluster create** command, where $IP is the value from step 1. An example command is provided here:
-
-```
-k3d cluster create my-cluster --wait --k3s-server-arg '--disable=traefik' --api-port $IP:6550 -p 443:443@loadbalancer
-```
-
-## The development cycle
-
-When you have developed and possibly manually tested the code you want to contribute, you should ensure that everything will build correctly. Commit your changes to the local copy of your Git branch and perform the following steps:
-
-### Pull in all build dependencies
-
-As build dependencies change over time, you have to synchronize your development environment with the current specification. In order to pull in all required dependencies, issue:
-
-* `make dep-ui`
-
-ArgoCD recently migrated to Go modules. Usually, dependencies will be downloaded on build time, but the Makefile provides two targets to download and vendor all dependencies:
-
-* `make mod-download` will download all required Go modules and
-* `make mod-vendor` will vendor those dependencies into the ArgoCD source tree
-
-### Generate API glue code and other assets
-
-ArgoCD relies on Google's [Protocol Buffers](https://developers.google.com/protocol-buffers) for its API, and this makes heavy use of auto-generated glue code and stubs. Whenever you touched parts of the API code, you must re-generate the auto generated code.
-
-* Run `make codegen`, this might take a while
-* Check if something has changed by running `git status` or `git diff`
-* Commit any possible changes to your local Git branch, an appropriate commit message would be `Changes from codegen`, for example.
-
-!!!note
-    There are a few non-obvious assets that are auto-generated. You should not change the autogenerated assets, as they will be overwritten by a subsequent run of `make codegen`. Instead, change their source files. Prominent examples of non-obvious auto-generated code are `swagger.json` or the installation manifest YAMLs.
-
-### Build your code and run unit tests
-
-After the code glue has been generated, your code should build and the unit tests should run without any errors. Execute the following statements:
-
-* `make build`
-* `make test`
-
-These steps are non-modifying, so there's no need to check for changes afterwards.
-
-### Lint your code base
-
-In order to keep a consistent code style in our source tree, your code must be well-formed in accordance to some widely accepted rules, which are applied by a Linter.
-
-The Linter might make some automatic changes to your code, such as indentation fixes. Some other errors reported by the Linter have to be fixed manually.
-
-* Run `make lint` and observe any errors reported by the Linter
-* Fix any of the errors reported and commit to your local branch
-* Finally, after the Linter reports no errors anymore, run `git status` or `git diff` to check for any changes made automatically by Lint
-* If there were automatic changes, commit them to your local branch
-
-If you touched UI code, you should also run the Yarn linter on it:
-
-* Run `make lint-ui`
-* Fix any of the errors reported by it
-
-## Setting up a local toolchain
-
-For development, you can either use the fully virtualized toolchain provided as Docker images, or you can set up the toolchain on your local development machine. Due to the dynamic nature of requirements, you might want to stay with the virtualized environment.
-
-### Install required dependencies and build-tools
-
-!!!note
-    The installations instructions are valid for Linux hosts only. Mac instructions will follow shortly.
-
-For installing the tools required to build and test ArgoCD on your local system, we provide convenient installer scripts. By default, they will install binaries to `/usr/local/bin` on your system, which might require `root` privileges.
-
-You can change the target location by setting the `BIN` environment before running the installer scripts. For example, you can install the binaries into `~/go/bin` (which should then be the first component in your `PATH` environment, i.e. `export PATH=~/go/bin:$PATH`):
-
-```shell
-make BIN=~/go/bin install-tools-local
-```
-
-Additionally, you have to install at least the following tools via your OS's package manager (this list might not be always up-to-date):
-
-* Git LFS plugin
-* GnuPG version 2
-
-### Install Go dependencies
-
-You need to pull in all required Go dependencies. To do so, run
-
-* `make mod-download-local`
-* `make mod-vendor-local`
-
-### Test your build toolchain
-
-The first thing you can do whether your build toolchain is setup correctly is by generating the glue code for the API and after that, run a normal build:
-
-* `make codegen-local`
-* `make build-local`
-
-This should return without any error.
-
-### Run unit-tests
-
-The next thing is to make sure that unit tests are running correctly on your system. These will require that all dependencies, such as Helm, Kustomize, Git, GnuPG, etc are correctly installed and fully functioning:
-
-* `make test-local`
-
-### Run end-to-end tests
-
-The final step is running the End-to-End testsuite, which makes sure that your Kubernetes dependencies are working properly. This will involve starting all of the ArgoCD components locally on your computer. The end-to-end tests consists of two parts: a server component, and a client component.
-
-* First, start the End-to-End server: `make start-e2e-local`. This will spawn a number of processes and services on your system.
-* When all components have started, run `make test-e2e-local` to run the end-to-end tests against your local services.
-
-For more information about End-to-End tests, refer to the [End-to-End test documentation](test-e2e.md).

docs/developer-guide/debugging-remote-environment.md

@@ -1,57 +0,0 @@
-# Debugging a Remote ArgoCD Environment
-
-In this guide, we will describe how to debug a remote ArgoCD environment with [Telepresence](https://telepresence.io/).
-
-Telepresence allows you to connect & debug a service deployed in a remote environment and to "cherry-pick" one service to run locally, staying connected to the remote cluster. This will:
-
-* Reduce resource footprint on the local machine
-* Decrease the feedback loop time
-* Result in more confidence about the delivered code.
-
-To read more about it, refer to the official documentation at [telepresence.io](https://telepresence.io/) or [Medium](https://medium.com/containers-101/development-environment-using-telepresence-634bd7210c26).
-
-## Install ArgoCD
-First of all, install ArgoCD on your cluster
-```shell
-kubectl create ns argocd
-curl -sSfL https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml | kubectl apply -n argocd -f -
-```
-
-## Connect
-Connect to one of the services, for example, to debug the main ArgoCD server run:
-```shell
-telepresence --swap-deployment argocd-server --namespace argocd --env-file .envrc.remote --expose 8080:8080 --expose 8083:8083 --run bash
-```
-* `--swap-deployment` changes the argocd-server deployment
-* `--expose` forwards traffic of remote ports 8080 and 8083 to the same ports locally
-* `--env-file` writes all the environment variables of the remote pod into a local file, the variables are also set on the subprocess of the `--run` command
-* `--run` defines which command to run once a connection is established, use `bash`, `zsh` or others
-
-
-## Debug
-Once a connection is established, use your favorite tools to start the server locally.
-
-### Terminal
-* Compile `make server`
-* Run `./dist/argocd-server`
-
-### VSCode
-In VSCode use the integrated terminal to run the Telepresence command to connect. Then, to run argocd-server service use the following configuration.
-Make sure to run `packr` before starting the debugging session to generate the assets. 
-Update the configuration file to point to kubeconfig file: `KUBECONFIG=` (required)
-```json
-        {
-            "name": "Launch",
-            "type": "go",
-            "request": "launch",
-            "mode": "auto",
-            "program": "${workspaceFolder}/cmd/argocd-server",
-            "envFile": [
-                "${workspaceFolder}/.envrc.remote",
-            ],
-            "env": {
-                "CGO_ENABLED": "0",
-                "KUBECONFIG": "/path/to/kube/config"
-            }
-        }
-```

docs/developer-guide/dependencies.md

@@ -1,54 +0,0 @@
-# Managing Dependencies
-
-## GitOps Engine (`github.com/argoproj/gitops-engine`)
-
-### Repository
-
-https://github.com/argoproj/gitops-engine
-
-### Pulling changes from `gitops-engine` 
-
-After your GitOps Engine PR has been merged, ArgoCD needs to be updated to pull in the version of the GitOps engine that contains your change.  Here are the steps:
-
-* Retrieve the SHA hash for your commit. You will use this in the next step.
-* From the `argo-cd` folder, run the following command
-
-    `go get github.com/argoproj/gitops-engine@<git-commit-sha>`
-
-    If you get an error message `invalid version: unknown revision` then you got the wrong SHA hash
-
-* Run:
-
-    `go mod tidy`
-
-* The following files are changed:
-
-    - `go.mod`
-    - `go.sum`
-
-* Create an ArgoCD PR with a `refactor:` type in its title for the two file changes.
-
-### Tips:
-* See https://github.com/argoproj/argo-cd/pull/4434 as an example
-* The PR might require additional, dependent changes in ArgoCD that are directly impacted by the changes made in the engine.  
-
-## Argo UI Components
-
-### Repository
-
-https://github.com/argoproj/argo-ui
-
-### Pulling changes from Argo UI into Argo CD
-
-If you make changes to the Argo UI component, and your Argo CD changes depend on those changes, follow these steps:
-
-1. Make changes to Argo UI and submit the PR request.
-2. Also, prepare your Argo CD changes, but don't create the PR just yet.
-3. **After** the Argo UI PR has been merged to master, then as part of your Argo CD changes:
-	- Run `yarn add https://github.com/argoproj/argo-ui.git`, and then,
-	- Check in the regenerated yarn.lock file as part of your Argo CD commit
-4. Create the Argo CD PR	 when you are ready. The PR build and test checks should pass.
-
-If your Argo UI change is a 'stand-alone' fix, and you simply want Argo CD to pull in your change, then simply create an Argo CD PR with the yarn.lock file change.
-
-

docs/developer-guide/faq.md

@@ -1,32 +0,0 @@
-# Contribution FAQ
-
-## General
-
-### Can I discuss my contribution ideas somewhere?
-
-Sure thing! You can either open an Enhancement Proposal in our GitHub issue tracker or you can [join us on Slack](https://argoproj.github.io/community/join-slack) in channel #argo-dev to discuss your ideas and get guidance for submitting a PR.
-
-### No one has looked at my PR yet. Why?
-
-As we have limited manpower, it can sometimes take a while for someone to respond to your PR. Especially, when your PR contains complex or non-obvious changes. Please bear with us, we try to look at every PR that we receive.
-
-### Why has my PR been declined? I put much work in it!
-
-We appreciate that you have put your valuable time and know how into a contribution. Alas, some changes do not fit into the overall ArgoCD philosophy, and therefore can't be merged into the official ArgoCD source tree.
-
-To be on the safe side, make sure that you have created an Enhancement Proposal for your change before starting to work on your PR and have gathered enough feedback from the community and the maintainers.
-
-### A check on my PR is failing.
-See [Failing CI Checks](ci.md#troubleshooting-ci-checks).
-
-### What checked-in code is generated, and how is it generated?
-The following files under this repository are generated, and must be kept up-to-date. Also see [Why does the codegen step fail?](ci.md#why-does-the-codegen-step-fail).
-
-See the Makefile for targets that can also run these scripts, and the `codegen` target which runs them all.
-
-| Filename | Purpose | Generated by |
-| -------- | ------- | ------------ |
-| `*.pb.go`, `*.pb.gw.go` | [Protobuf](https://developers.google.com/protocol-buffers/docs/gotutorial) Interfaces | `hack/generate-proto.sh` |
-| `assets/swagger.json` | Swagger 2 API spec | `hack/update-openapi.sh` |
-| `manifests/` | k8s Installation Manifests | `hack/update-manifests.sh` |
-| `docs/user-guide/commands` | CLI Documentation | `tools/cmd-docs/main.go` |

docs/developer-guide/index.md

@@ -1,10 +0,0 @@
-# Overview
-
-!!! warning "You probably don't want to be reading this section of the docs."
-    This part of the manual is aimed at people wanting to develop third-party applications that interact with Argo CD, e.g.
-    
-    * A chat bot
-    * A Slack integration
-    
-!!! note
-    Please make sure you've completed the [getting started guide](../getting_started.md).

docs/developer-guide/releasing.md

@@ -1,236 +0,0 @@
-# Releasing
-
-## Automated release procedure
-
-Starting from `release-1.6` branch, ArgoCD can be released in an automated fashion
-using GitHub actions. The release process takes about 20 minutes, sometimes a
-little less, depending on the performance of GitHub Actions runners.
-
-The target release branch must already exist in the GitHub repository. If you for
-example want to create a release `v1.7.0`, the corresponding release branch
-`release-1.7` needs to exist, otherwise, the release cannot be built. Also,
-the trigger tag should always be created in the release branch, checked out
-in your local repository clone.
-
-Before triggering the release automation, the `CHANGELOG.md` should be updated
-with the latest information, and this change should be committed and pushed to
-the GitHub repository to the release branch. Afterward, the automation can be
-triggered.
-
-**Manual steps before release creation:**
-
-* Update `CHANGELOG.md` with changes for this release
-* Commit & push changes to `CHANGELOG.md`
-* Prepare release notes (save to some file, or copy from Changelog)
-
-**The automation will perform the following steps:**
-
-* Update `VERSION` file in the release branch
-* Update manifests with image tags of the new version in the release branch
-* Build the Docker image and push to Docker Hub
-* Create a release tag in the GitHub repository
-* Create a GitHub release and attach the required assets to it (CLI binaries, ...)
-
-Finally, it will the remove trigger tag from the repository again.
-
-Automation supports both, GA and pre-releases. The automation is triggered by
-pushing a tag to the repository. The tag must be in one of the following formats
-to trigger the GH workflow:
-
-* GA: `release-v<MAJOR>.<MINOR>.<PATCH>`
-* Pre-release: `release-v<MAJOR>.<MINOR>.<PATCH>-rc<RC#>`
-
-The tag must be an annotated tag, and it must contain the release notes in the
-commit message. Please note that Markdown uses `#` character for formatting, but
-Git uses it as comment char. To solve this, temporarily switch Git's comment char
-to something else, the `;` character is recommended.
-
-For example, consider you have configured the Git remote for the repository to
-`github.com/argoproj/argo-cd` to be named `upstream` and are in your locally
-checked out repo:
-
-```shell
-git config core.commentChar ';'
-git tag -a -F /path/to/release-notes.txt release-v1.6.0-rc2
-git push upstream release-v1.6.0-rc2
-git tag -d release-v1.6.0-rc2
-git config core.commentChar '#'
-
-```
-
-For convenience, there is a shell script in the tree that ensures all the
-pre-requisites are met and that the trigger is well-formed before pushing
-it to the GitHub repo.
-
-In summary, the modifications it does are:
-
-* Create annotated trigger tag in your local repository
-* Push the tag to the GitHub repository to trigger the workflow
-* Remove trigger tag from your local repository
-
-The script can be found at `hack/trigger-release.sh` and is used as follows:
-
-```shell
-./hack/trigger-release.sh <version> <remote name> [<release notes path>]
-```
-
-The `<version>` identifier needs to be specified **without** the `release-`
-prefix, so just specify it as `v1.6.0-rc2` for example. The `<remote name>`
-specifies the name of the remote used to push to the GitHub repository. 
-
-If you omit the `<release notes path>`, an editor will pop-up asking you to
-enter the tag's annotation so you can paste the release notes, save, and exit.
-It will also take care of temporarily configuring the `core.commentChar` and
-setting it back to its original state.
-
-:warning:
-    It is strongly recommended to use this script to trigger the workflow
-    instead of manually pushing a tag to the repository.
-
-Once the trigger tag is pushed to the repo, the GitHub workflow will start
-execution. You can follow its progress under the `Actions` tab, the name of the
-action is `Create release`. Don't get confused by the name of the running
-workflow, it will be the commit message of the latest commit to the `master`
-branch, this is a limitation of GH actions.
-
-The workflow performs necessary checks so that the release can be successfully
-built before the build actually starts. It will error when one of the
-prerequisites is not met, or if the release cannot be built (i.e. already
-exists, release notes invalid, etc etc). You can see a summary of what has
-failed in the job's overview page and more detailed errors in the output
-of the step that has failed.
-
-:warning:
-    You cannot perform more than one release on the same release branch at the
-    same time. For example, both `v1.6.0` and `v1.6.1` would operate on the
-    `release-1.6` branch. If you submit `v1.6.1` while `v1.6.0` is still
-    executing, the release automation will not execute. You have to either
-    cancel `v1.6.0` before submitting `v1.6.1` or wait until it has finished.
-    You can execute releases on different release branches simultaneously, for
-    example, `v1.6.0` and `v1.7.0-rc1`, without problems.
-
-### Verifying automated release
-
-After the automatic release creation has finished, you should perform manual
-checks to see if the release came out correctly:
-
-* Check status & output of the GitHub action
-* Check [https://github.com/argoproj/argo-cd/releases](https://github.com/argoproj/argo-cd/releases)
-  to see if the release has been correctly created and if all required assets
-  are attached.
-* Check whether the image has been published on DockerHub correctly
-
-### If something went wrong
-
-If something went wrong, damage should be limited. Depending on the steps that
-have been performed, you will need to manually clean up.
-
-* Delete the release tag (e.g. `v1.6.0-rc2`) created in the GitHub repository. This
-  will immediately set the release (if created) to `draft` status, invisible to the
-  general public.
-* Delete the draft release (if created) from the `Releases` page on GitHub
-* If Docker image has been pushed to DockerHub, delete it
-* If commits have been performed to the release branch, revert them. Paths that could have been committed to are:
-    * `VERSION`
-    * `manifests/*`
-
-### Post-process manual steps
-
-For now, the only manual steps left are to
-
-* update stable tag in the GitHub repository to point to new the release (if appropriate)
-* update the `VERSION` file on `master` if this is a new major release
-
-These may be automated as well in the future.
-
-## Manual releasing
-
-The automatic release process does not interfere with the manual release process, since
-the trigger tag does not match a normal release tag. If you prefer to perform,
-manual release or if automatic release is for some reason broken, these are the
-steps:
-
-Make sure you are logged into Docker Hub:
-
-```bash
-docker login
-```
-
-Export the upstream repository and branch name, e.g.:
-
-```bash
-REPO=upstream ;# or origin 
-BRANCH=release-1.3
-```
-
-Set the `VERSION` environment variable:
-
-```bash 
-# release candidate
-VERSION=v1.3.0-rc1
-# GA release
-VERSION=v1.3.1
-```
-
-Update `VERSION` and manifests with the new version:
-
-```bash
-git checkout $BRANCH
-echo ${VERSION:1} > VERSION
-make dev-tools-image
-make manifests IMAGE_TAG=$VERSION
-git commit -am "Update manifests to $VERSION"
-git tag $VERSION
-```
-
-Build, and push release to Docker Hub
-
-```bash
-git clean -fd
-make release IMAGE_NAMESPACE=argoproj IMAGE_TAG=$VERSION DOCKER_PUSH=true
-git push $REPO $BRANCH
-git push $REPO $VERSION
-```
-
-Update [GitHub releases](https://github.com/argoproj/argo-cd/releases) with:
-
-* Getting started (copy from the previous release)
-* Changelog
-* Binaries (e.g. `dist/argocd-darwin-amd64`).
-
-## Update brew formulae (manual)
-
-If GA, update the Brew formula:
-
-```bash
-brew bump-formula-pr argocd --version ${VERSION:1}
-```
-
-## Update stable tag (manual)
-
-If GA, update `stable` tag:
-
-```bash
-git tag stable --force && git push $REPO stable --force
-```
-
-## Verify release
-
-Locally:
-
-```bash
-kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/$VERSION/manifests/install.yaml
-```
-
-Follow the [Getting Started Guide](../getting_started/).
-
-If GA:
-
-```bash
-brew upgrade argocd
-/usr/local/bin/argocd version
-```
-
-Sync Argo CD in [https://cd.apps.argoproj.io/applications/argo-cd](https://cd.apps.argoproj.io/applications/argo-cd).
-
-Deploy the [site](site.md).

docs/developer-guide/running-locally.md

@@ -1,117 +0,0 @@
-# Running ArgoCD locally
-
-## Run ArgoCD outside of Kubernetes
-
-During development, it might be viable to run ArgoCD outside of a Kubernetes cluster. This will greatly speed up development, as you don't have to constantly build, push and install new ArgoCD Docker images with your latest changes.
-
-You will still need a working Kubernetes cluster, as described in the [Contribution Guide](contributing.md), where ArgoCD will store all of its resources.
-
-If you followed the [Contribution Guide](contributing.md) in setting up your toolchain, you can run ArgoCD locally with these simple steps:
-
-### Install ArgoCD resources to your cluster
-
-First push the installation manifest into argocd namespace:
-
-```shell
-kubectl create namespace argocd
-kubectl apply -n argocd --force -f manifests/install.yaml
-```
-
-### Scale down any ArgoCD instance in your cluster
-
-Make sure that ArgoCD is not running in your development cluster by scaling down the deployments:
-
-```shell
-kubectl -n argocd scale statefulset/argocd-application-controller --replicas 0
-kubectl -n argocd scale deployment/argocd-dex-server --replicas 0
-kubectl -n argocd scale deployment/argocd-repo-server --replicas 0
-kubectl -n argocd scale deployment/argocd-server --replicas 0
-kubectl -n argocd scale deployment/argocd-redis --replicas 0
-```
-
-### Start local services
-
-Before starting local services, make sure you are present in `argocd` namespace. When you use the virtualized toolchain, starting local services is as simple as running
-
-```bash
-make start
-```
-
-This will start all ArgoCD services and the UI in a Docker container and expose the following ports to your host:
-
-* The ArgoCD API server on port 8080
-* The ArgoCD UI server on port 4000
-
-You can now use either the web UI by pointing your browser to `http://localhost:4000` or use the CLI against the API at `http://localhost:8080`. Be sure to use the `--insecure` and `--plaintext` options to the CLI.
-
-As an alternative to using the above command line parameters each time you call `argocd` CLI, you can set the following environment variables:
-
-```bash
-export ARGOCD_SERVER=127.0.0.1:8080
-export ARGOCD_OPTS="--plaintext --insecure"
-```
-
-### Scale up ArgoCD in your cluster
-
-Once you have finished testing your changes locally and want to bring back ArgoCD in your development cluster, simply scale the deployments up again:
-
-```bash
-kubectl -n argocd scale statefulset/argocd-application-controller --replicas 1
-kubectl -n argocd scale deployment/argocd-dex-server --replicas 1
-kubectl -n argocd scale deployment/argocd-repo-server --replicas 1
-kubectl -n argocd scale deployment/argocd-server --replicas 1
-kubectl -n argocd scale deployment/argocd-redis --replicas 1
-```
-
-## Run your own ArgoCD images on your cluster
-
-For your final tests, it might be necessary to build your own images and run them in your development cluster.
-
-### Create Docker account and login
-
-You might need to create a account on [Docker Hub](https://hub.docker.com) if you don't have one already. Once you created your account, login from your development environment:
-
-```bash
-docker login
-```
-
-### Create and push Docker images
-
-You will need to push the built images to your own Docker namespace:
-
-```bash
-export IMAGE_NAMESPACE=youraccount
-```
-
-If you don't set `IMAGE_TAG` in your environment, the default of `:latest` will be used. To change the tag, export the variable in the environment:
-
-```bash
-export IMAGE_TAG=1.5.0-myrc
-```
-
-Then you can build & push the image in one step:
-
-```bash
-DOCKER_PUSH=true make image
-```
-
-### Configure manifests for your image
-
-With `IMAGE_NAMESPACE` and `IMAGE_TAG` still set, run:
-
-```bash
-make manifests
-```
-
-to build a new set of installation manifests which include your specific image reference.
-
-!!!note
-    Do not commit these manifests to your repository. If you want to revert the changes, the easiest way is to unset `IMAGE_NAMESPACE` and `IMAGE_TAG` from your environment and run `make manifests` again. This will re-create the default manifests.
-
-### Configure your cluster with custom manifests
-
-The final step is to push the manifests to your cluster, so it will pull and run your image:
-
-```bash
-kubectl apply -n argocd --force -f manifests/install.yaml
-```

docs/developer-guide/site.md

@@ -1,30 +0,0 @@
-# Site
-
-## Developing And Testing
-
-The web site is build using `mkdocs` and `mkdocs-material`. 
-
-To test:
-
-```bash
-make serve-docs
-```
-
-Check for broken external links:
-
-```bash
-make lint-docs
-```
-
-## Deploying
-
-```bash
-make publish-docs
-```
-
-## Analytics
-
-!!! tip
-    Don't forget to disable your ad-blocker when testing.
-
-We collect [Google Analytics](https://analytics.google.com/analytics/web/#/report-home/a105170809w198079555p192782995).

docs/developer-guide/static-code-analysis.md

@@ -1,10 +0,0 @@
-# Static Code Analysis
-
-We use the following static code analysis tools:
-
-* golangci-lint and tslint for compile time linting
-* [codecov.io](https://codecov.io/gh/argoproj/argo-cd) - for code coverage
-* [snyk.io](https://app.snyk.io/org/argoproj/projects) - for image scanning
-* [sonarcloud.io](https://sonarcloud.io/organizations/argoproj/projects) - for code scans and security alerts
-
-These are at least run daily or on each pull request.

docs/developer-guide/test-e2e.md

@@ -1,62 +0,0 @@
-# E2E Tests
-
-The directory contains E2E tests and test applications. The test assume that Argo CD services are installed into `argocd-e2e` namespace or cluster in current context. One throw-away
-namespace `argocd-e2e***` is created prior to tests execute. The throw-away namespace is used as a target namespace for test applications.
-
-The `test/e2e/testdata` directory contains various Argo CD applications. Before test execution directory is copies into `/tmp/argocd-e2e***` temp directory and used in tests as a
-Git repository via file url: `file:///tmp/argocd-e2e***`.
-
-## Running Tests Locally
-
-1. Start the e2e version `make start-e2e` 
-1. Run the tests: `make test-e2e`
-
-You can observe the tests by using the UI [http://localhost:4000/applications](http://localhost:4000/applications).
-
-## Configuration of E2E Tests execution
-
-The Makefile's `start-e2e` target starts instances of ArgoCD on your local machine, of which the most will require a network listener. If for whatever reason you already have network services on your machine listening on the same ports, the e2e tests will not be able to run. You can derive from the defaults by setting the following environment variables before you run `make start-e2e`:
-
-* `ARGOCD_E2E_APISERVER_PORT`: Listener port for `argocd-server` (default: `8080`)
-* `ARGOCD_E2E_REPOSERVER_PORT`: Listener port for `argocd-reposerver` (default: `8081`)
-* `ARGOCD_E2E_DEX_PORT`: Listener port for `dex` (default: `5556`)
-* `ARGOCD_E2E_REDIS_PORT`: Listener port for `redis` (default: `6379`)
-* `ARGOCD_E2E_YARN_CMD`: Command to use for starting the UI via Yarn (default: `yarn`)
-
-If you have changed the port for `argocd-server`, be sure to also set `ARGOCD_SERVER` environment variable to point to that port, e.g. `export ARGOCD_SERVER=localhost:8888` before running `make test-e2e` so that the test will communicate to the correct server component.
-
-## CI Set-up
-
-The tests are executed by Argo Workflow defined at `.argo-ci/ci.yaml`. CI job The builds an Argo CD image, deploy argo cd components into throw-away kubernetes cluster provisioned
-using k3s and run e2e tests against it.
-
-## Test Isolation
-
-Some effort has been made to balance test isolation with speed. Tests are isolated as follows as each test gets:
-
-* A random 5 character ID.
-* A unique Git repository containing the `testdata` in `/tmp/argocd-e2e/${id}`.
-* A namespace `argocd-e2e-ns-${id}`.
-* An primary name for the app `argocd-e2e-${id}`.
-
-## Troubleshooting
-
-**Tests fails to delete `argocd-e2e-ns-*` namespaces.**
-
-This maybe due to the metrics server, run this:
-
-```bash
-kubectl api-resources
-```
-
-If it exits with status code 1, run:
-
-```bash
-kubectl delete apiservice v1beta1.metrics.k8s.io
-```
-
-Remove `/spec/finalizers` from the namespace
-
-```bash
-kubectl edit ns argocd-e2e-ns-*
-```

docs/faq.md

@@ -1,199 +1 @@
-# FAQ
-
-## I've deleted/corrupted my repo and can't delete my app.
-
-Argo CD can't delete an app if it cannot generate manifests. You need to either:
-
-1. Reinstate/fix your repo.
-1. Delete the app using `--cascade=false` and then manually deleting the resources.
-
-## Why is my application still `OutOfSync` immediately after a successful Sync?
-
-See [Diffing](user-guide/diffing.md) documentation for reasons resources can be OutOfSync, and ways to configure Argo CD
-to ignore fields when differences are expected.
-
-## Why is my application stuck in `Progressing` state?
-
-Argo CD provides health for several standard Kubernetes types. The `Ingress` and `StatefulSet` types have known issues
-which might cause health check to return `Progressing` state instead of `Healthy`.
-
-* `Ingress` is considered healthy if `status.loadBalancer.ingress` list is non-empty, with at least one value
-  for `hostname` or `IP`. Some ingress controllers
-  ([contour](https://github.com/heptio/contour/issues/403)
-  , [traefik](https://github.com/argoproj/argo-cd/issues/968#issuecomment-451082913)) don't update
-  `status.loadBalancer.ingress` field which causes `Ingress` to stuck in `Progressing` state forever.
-
-* `StatefulSet` is considered healthy if value of `status.updatedReplicas` field matches to `spec.replicas` field. Due
-  to Kubernetes bug
-  [kubernetes/kubernetes#68573](https://github.com/kubernetes/kubernetes/issues/68573) the `status.updatedReplicas` is
-  not populated. So unless you run Kubernetes version which include the
-  fix [kubernetes/kubernetes#67570](https://github.com/kubernetes/kubernetes/pull/67570) `StatefulSet` might stay
-  in `Progressing` state.
-* Your `StatefulSet` or `DaemonSet` is using `OnDelete` instead of `RollingUpdate` strategy.
-  See [#1881](https://github.com/argoproj/argo-cd/issues/1881).
-
-As workaround Argo CD allows providing [health check](operator-manual/health.md) customization which overrides default
-behavior.
-
-## I forgot the admin password, how do I reset it?
-
-For Argo CD v1.8 and earlier, the initial password is set to the name of the server pod, as
-per [the getting started guide](getting_started.md). For Argo CD v1.9 and later, the initial password is available from
-a secret named `argocd-initial-admin-secret`.
-
-To change the password, edit the `argocd-secret` secret and update the `admin.password` field with a new bcrypt hash.
-You can use a site like [https://www.browserling.com/tools/bcrypt](https://www.browserling.com/tools/bcrypt) to generate
-a new hash. For example:
-
-```bash
-# bcrypt(password)=$2a$10$rRyBsGSHK6.uc8fntPwVIuLVHgsAhAX7TcdrqW/RADU0uh7CaChLa
-kubectl -n argocd patch secret argocd-secret \
-  -p '{"stringData": {
-    "admin.password": "$2a$10$rRyBsGSHK6.uc8fntPwVIuLVHgsAhAX7TcdrqW/RADU0uh7CaChLa",
-    "admin.passwordMtime": "'$(date +%FT%T%Z)'"
-  }}'
-```
-
-Another option is to delete both the `admin.password` and `admin.passwordMtime` keys and restart argocd-server. This
-will generate a new password as per [the getting started guide](getting_started.md), so either to the name of the pod (
-Argo CD 1.8 and earlier)
-or a randomly generated password stored in a secret (Argo CD 1.9 and later).
-
-## How to disable admin user?
-
-Add `admin.enabled: "false"` to the `argocd-cm` ConfigMap (
-see [user management](operator-manual/user-management/index.md)).
-
-## Argo CD cannot deploy Helm Chart based applications without internet access, how can I solve it?
-
-Argo CD might fail to generate Helm chart manifests if the chart has dependencies located in external repositories. To
-solve the problem you need to make sure that `requirements.yaml`
-uses only internally available Helm repositories. Even if the chart uses only dependencies from internal repos Helm
-might decide to refresh `stable` repo. As workaround override
-`stable` repo URL in `argocd-cm` config map:
-
-```yaml
-data:
-  # v1.2 or earlier use `helm.repositories`
-  helm.repositories: |
-    - url: http://<internal-helm-repo-host>:8080
-      name: stable
-  # v1.3 or later use `repositories` with `type: helm`
-  repositories: |
-    - type: helm
-      url: http://<internal-helm-repo-host>:8080
-      name: stable
-```
-
-## I've configured [cluster secret](./operator-manual/declarative-setup.md#clusters) but it does not show up in CLI/UI, how do I fix it?
-
-Check if cluster secret has `argocd.argoproj.io/secret-type: cluster` label. If secret has the label but the cluster is
-still not visible then make sure it might be a permission issue. Try to list clusters using `admin` user (
-e.g. `argocd login --username admin && argocd cluster list`).
-
-## Argo CD is unable to connect to my cluster, how do I troubleshoot it?
-
-Use the following steps to reconstruct configured cluster config and connect to your cluster manually using kubectl:
-
-```bash
-kubectl exec -it <argocd-pod-name> bash # ssh into any argocd server pod
-argocd-util kubeconfig https://<cluster-url> /tmp/config --namespace argocd # generate your cluster config
-KUBECONFIG=/tmp/config kubectl get pods # test connection manually
-```
-
-Now you can manually verify that cluster is accessible from the Argo CD pod.
-
-## How Can I Terminate A Sync?
-
-To terminate the sync, click on the "synchronisation" then "terminate":
-
-![Synchronization](assets/synchronization-button.png) ![Terminate](assets/terminate-button.png)
-
-## Why Is My App Out Of Sync Even After Syncing?
-
-Is some cases, the tool you use may conflict with Argo CD by adding the `app.kubernetes.io/instance` label. E.g. using
-Kustomize common labels feature.
-
-Argo CD automatically sets the `app.kubernetes.io/instance` label and uses it to determine which resources form the app.
-If the tool does this too, this causes confusion. You can change this label by setting
-the `application.instanceLabelKey` value in the `argocd-cm`. We recommend that you use `argocd.argoproj.io/instance`.
-
-!!! note When you make this change your applications will become out of sync and will need re-syncing.
-
-See [#1482](https://github.com/argoproj/argo-cd/issues/1482).
-
-## Why Are My Resource Limits Out Of Sync?
-
-Kubernetes has normalized your resource limits when they are applied, and then Argo CD has then compared the version in
-your generated manifests to the normalized one is Kubernetes - they won't match.
-
-E.g.
-
-* `'1000m'` normalized to `'1'`
-* `'0.1'` normalized to `'100m'`
-* `'3072Mi'` normalized to `'3Gi'`
-* `3072` normalized to `'3072'` (quotes added)
-
-To fix this use diffing
-customizations [settings](./user-guide/diffing.md#known-kubernetes-types-in-crds-resource-limits-volume-mounts-etc).
-
-## How Do I Fix "invalid cookie, longer than max length 4093"?
-
-Argo CD uses a JWT as the auth token. You likely are part of many groups and have gone over the 4KB limit which is set
-for cookies. You can get the list of groups by opening "developer tools -> network"
-
-* Click log in
-* Find the call to `<argocd_instance>/auth/callback?code=<random_string>`
-
-Decode the token at [https://jwt.io/](https://jwt.io/). That will provide the list of teams that you can remove yourself
-from.
-
-See [#2165](https://github.com/argoproj/argo-cd/issues/2165).
-
-## Why Am I Getting `rpc error: code = Unavailable desc = transport is closing` When Using The CLI?
-
-Maybe you're behind a proxy that does not support HTTP 2? Try the `--grpc-web` flag:
-
-```bash
-argocd ... --grpc-web
-```
-
-## Why Am I Getting `x509: certificate signed by unknown authority` When Using The CLI?
-
-Your not running your server with correct certs.
-
-If you're not running in a production system (e.g. you're testing Argo CD out), try the `--insecure` flag:
-
-```bash
-argocd ... --insecure
-```
-
-!!! warning "Do not use `--insecure` in production"
-
-## I have configured Dex via `dex.config` in `argocd-cm`, it still says Dex is unconfigured. Why?
-
-Most likely you forgot to set the `url` in `argocd-cm` to point to your ArgoCD as well. See also
-[the docs](/operator-manual/user-management/#2-configure-argo-cd-for-sso).
-
-## Why are resources of type `SealedSecret` stuck in the `Progressing` state?
-
-The controller of the `SealedSecret` resource may expose the status condition on resource it provisioned. Since
-version `v1.9.0` ArgoCD picks up that status condition to derive a health status for the `SealedSecret`.
-
-Versions before `v0.15.0` of the `SealedSecret` controller are affected by an issue regarding this status
-conditions updates, which is why this feature is disabled by default in these versions. Status condition updates may be
-enabled by starting the `SealedSecret` controller with the `--update-status` command line parameter or by setting
-the `SEALED_SECRETS_UPDATE_STATUS` environment variable.
-
-To disable ArgoCD from checking the status condition on `SealedSecret` resources, add the following resource
-customization in your `argocd-cm` ConfigMap:
-
-```yaml
-resource.customizations: |
-  bitnami.com/SealedSecret:
-    health.lua: |
-      hs = {}
-      hs.status = "Healthy"
-      hs.message = "Controller doesn't report resource status"
-      return hs
-```
+# Frequently Asked Questions (FAQ)

docs/getting_started.md

@@ -1,232 +0,0 @@
-# Getting Started
-
-!!! tip
-    This guide assumes you have a grounding in the tools that Argo CD is based on. Please read [understanding the basics](understand_the_basics.md) to learn about these tools.
-
-## Requirements
-
-* Installed [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) command-line tool.
-* Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`).
-
-## 1. Install Argo CD
-
-```bash
-kubectl create namespace argocd
-kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
-```
-
-This will create a new namespace, `argocd`, where Argo CD services and application resources will live.
-
-!!! note
-    If you are not interested in UI, SSO, multi-cluster management and just want to pull changes into the cluster then you can disable
-    authentication using `--disable-auth` flag and access Argo CD via CLI using `--port-forward` or `--port-forward-namespace` flags
-    and proceed to step [#6](#6-create-an-application-from-a-git-repository):
-    
-    `kubectl patch deploy argocd-server -n argocd -p '[{"op": "add", "path": "/spec/template/spec/containers/0/command/-", "value": "--disable-auth"}]' --type json`
-
-## 2. Download Argo CD CLI
-
-Download the latest Argo CD version from [https://github.com/argoproj/argo-cd/releases/latest](https://github.com/argoproj/argo-cd/releases/latest). More detailed installation instructions can be found via the [CLI installation documentation](cli_installation.md).
-
-Also available in Mac Homebrew:
-
-```bash
-brew install argocd
-```
-
-## 3. Access The Argo CD API Server
-
-By default, the Argo CD API server is not exposed with an external IP. To access the API server,
-choose one of the following techniques to expose the Argo CD API server:
-
-### Service Type Load Balancer
-Change the argocd-server service type to `LoadBalancer`:
-
-```bash
-kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'
-```
-
-### Ingress
-Follow the [ingress documentation](operator-manual/ingress.md) on how to configure Argo CD with ingress.
-
-### Port Forwarding
-Kubectl port-forwarding can also be used to connect to the API server without exposing the service.
-
-```bash
-kubectl port-forward svc/argocd-server -n argocd 8080:443
-```
-
-The API server can then be accessed using the localhost:8080
-
-
-## 4. Login Using The CLI
-
-!!! warning
-    We strongly advise to change the initially generated administrative password
-    as soon as after your first login to the system.
-
-Depending on the Argo CD version you are installing, the method how to get the
-initial password for the `admin` user is different.
-
-> Argo CD 1.8 and earlier
-
-The initial password is autogenerated to be the pod name of the
-Argo CD API server. This can be retrieved with the command:
-
-```bash
-kubectl get pods -n argocd -l app.kubernetes.io/name=argocd-server -o name | cut -d'/' -f 2
-```
-
-Using the username `admin` and the password from above, login to Argo CD's IP or hostname:
-
-```bash
-argocd login <ARGOCD_SERVER>  # e.g. localhost:8080 or argocd.example.com
-```
-
-Change the password using the command:
-
-```bash
-argocd account update-password
-```
-
-!!! note
-    The initial password is set in a kubernetes secret, named `argocd-secret`, during ArgoCD's initial start up. This means if you edit
-    the deployment in any way which causes a new pod to be deployed, such as disabling TLS on the Argo CD API server. Take note of the initial
-    pod name when you first install Argo CD, or reset the password by following [these instructions](../../faq/#i-forgot-the-admin-password-how-do-i-reset-it)
-
-> Argo CD v1.9 and later
-
-The initial password for the `admin` account is auto-generated and stored as
-clear text in the field `password` in a secret named `argocd-initial-admin-secret`
-in your Argo CD installation namespace. You can simply retrieve this password
-using `kubectl`:
-
-```bash
-kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
-```
-
-For better readability, e.g. if you want to copy & paste the generated password,
-you can simply append `&& echo` to above command, which will add a newline to
-the output.
-
-Using the username `admin` and the password from above, login to Argo CD's IP or hostname:
-
-```bash
-argocd login <ARGOCD_SERVER>
-```
-
-Change the password using the command:
-
-```bash
-argocd account update-password
-```
-
-!!! note
-    You should delete the `argocd-initial-admin-secret` from the Argo CD
-    namespace once you changed the password. The secret serves no other
-    purpose than to store the initially generated password in clear and can
-    safely be deleted at any time. It will be re-created on demand by Argo CD
-    if a new admin password must be re-generated.
-
-## 5. Register A Cluster To Deploy Apps To (Optional)
-
-This step registers a cluster's credentials to Argo CD, and is only necessary when deploying to
-an external cluster. When deploying internally (to the same cluster that Argo CD is running in),
-https://kubernetes.default.svc should be used as the application's K8s API server address.
-
-First list all clusters contexts in your current kubeconfig:
-```bash
-kubectl config get-contexts -o name
-```
-
-Choose a context name from the list and supply it to `argocd cluster add CONTEXTNAME`. For example,
-for docker-desktop context, run:
-```bash
-argocd cluster add docker-desktop
-```
-
-The above command installs a ServiceAccount (`argocd-manager`), into the kube-system namespace of 
-that kubectl context, and binds the service account to an admin-level ClusterRole. Argo CD uses this
-service account token to perform its management tasks (i.e. deploy/monitoring).
-
-!!! note
-    The rules of the `argocd-manager-role` role can be modified such that it only has `create`, `update`, `patch`, `delete` privileges to a limited set of namespaces, groups, kinds. 
-    However `get`, `list`, `watch` privileges are required at the cluster-scope for Argo CD to function.
-
-## 6. Create An Application From A Git Repository
-
-An example repository containing a guestbook application is available at
-[https://github.com/argoproj/argocd-example-apps.git](https://github.com/argoproj/argocd-example-apps.git) to demonstrate how Argo CD works.
-
-### Creating Apps Via CLI
-
-!!! note
-    You can access Argo CD using port forwarding: add `--port-forward-namespace argocd` flag to every CLI command or set `ARGOCD_OPTS` environment variable: `export ARGOCD_OPTS='--port-forward-namespace argocd'`:
-
-    `argocd app create guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path guestbook --dest-server https://kubernetes.default.svc --dest-namespace default`
-
-### Creating Apps Via UI
-
-Open a browser to the Argo CD external UI, and login by visiting the IP/hostname in a browser and use the credentials set in step 4.
-
-After logging in, click the **+ New App** button as shown below:
-
-![+ new app button](assets/new-app.png)
-
-Give your app the name `guestbook`, use the project `default`, and leave the sync policy as `Manual`:
-
-![app information](assets/app-ui-information.png)
-
-Connect the [https://github.com/argoproj/argocd-example-apps.git](https://github.com/argoproj/argocd-example-apps.git) repo to Argo CD by setting repository url to the github repo url, leave revision as `HEAD`, and set the path to `guestbook`:
-
-![connect repo](assets/connect-repo.png)
-
-For **Destination**, set cluster to `in-cluster` and namespace to `default`:
-
-![destination](assets/destination.png)
-
-After filling out the information above, click **Create** at the top of the UI to create the `guestbook` application:
-
-![destination](assets/create-app.png)
-
-
-## 7. Sync (Deploy) The Application
-
-### Syncing via CLI
-
-Once the guestbook application is created, you can now view its status:
-
-```bash
-$ argocd app get guestbook
-Name:               guestbook
-Server:             https://kubernetes.default.svc
-Namespace:          default
-URL:                https://10.97.164.88/applications/guestbook
-Repo:               https://github.com/argoproj/argocd-example-apps.git
-Target:
-Path:               guestbook
-Sync Policy:        <none>
-Sync Status:        OutOfSync from  (1ff8a67)
-Health Status:      Missing
-
-GROUP  KIND        NAMESPACE  NAME          STATUS     HEALTH
-apps   Deployment  default    guestbook-ui  OutOfSync  Missing
-       Service     default    guestbook-ui  OutOfSync  Missing
-```
-
-The application status is initially in `OutOfSync` state since the application has yet to be
-deployed, and no Kubernetes resources have been created. To sync (deploy) the application, run:
-
-```bash
-argocd app sync guestbook
-```
-
-This command retrieves the manifests from the repository and performs a `kubectl apply` of the
-manifests. The guestbook app is now running and you can now view its resource components, logs,
-events, and assessed health status.
-
-### Syncing via UI
-
-![guestbook app](assets/guestbook-app.png)
-![view app](assets/guestbook-tree.png)
-

docs/getting_started/first_steps.md

@@ -0,0 +1,186 @@
+# Accessing Argo CD
+
+After installing the [server component](install.md) and the [Argo CD CLI](install_cli.md) you are now ready to begin deploying applications.
+
+
+## Exposing the API and web UI
+
+To start using either the CLI or the Web interface you need to expose the `argocd-server` service first. By default, after the initial installation
+this service is only available from within the cluster itself (as ClusterIP).
+
+The process of exposing the [service](https://kubernetes.io/docs/concepts/services-networking/service/) is not specific to Argo CD. As Argo CD is a Kubernetes native application you can follow all familiar ways to expose its service to the outside world. If your organization has a well defined policy on how Kubernetes services are exposed, then we advise you to follow that policy first.
+
+### Using an Ingress (Recommended)
+
+For a production-grade Argo CD installation you should use [a Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) to expose the Argo CD service.
+
+See the [Ingress guide](../operations/ingress/index.md) for more details.
+
+After you setup your ingress, you should also commit all associated files into Git and manage them with Argo CD as well (therefore following GitOps for Argo CD itself).
+
+### Using a Load balancer
+
+!!! warning
+    While a Load Balancer is a very easy method to use for exposing Argo CD, we suggest you only employ it for local clusters, product demos and proof-of-concept scenarios. It also opens your Argo CD installation to the whole world. Make sure that you  have a firewall and/or [extra security constraints](../operations/security.md) and know how users will access Argo CD.
+
+A quick way to expose Argo CD to the whole world is to simply convert the existing ClusterIP service to a Loadbalancer one if your Kubernetes cluster supports LoadBalancer services. This is true for most cloud
+platforms, but many bare-metal clusters do not support this out of the box.
+
+If you know that you have access to LoadBalancer services in your cluster you can execute the following:
+
+```bash
+kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'
+```
+
+Then the Argo CD service will get its own separate IP address and optionally a DNS name if you have this option setup.
+
+If you use this method in a permanent manner, beware of the cost impact. A load balancer is usually priced separately on most cloud providers. Make sure you understand the cost implications of this method. An ingress is almost always a cost-effective method if you have multiple services in a single cluster.
+
+### Using Port forwarding
+
+Kubectl port-forwarding can also be used to connect to the API server without exposing the service.
+
+```bash
+kubectl port-forward svc/argocd-server -n argocd 8080:443
+```
+
+The API server can then be accessed using `https://localhost:8080`
+
+This method is expected to be temporary while you debug something or experiment locally. It is **NOT** recommended for production Argo CD installations.
+
+## Find the initial password
+
+On a default installation, Argo CD has one user defined with the following credentials
+
+* username = `admin`
+* password = randomly generated
+
+To find the password execute the following:
+
+```bash
+kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo
+```
+
+!!! warning
+    You should delete the `argocd-initial-admin-secret` from the Argo CD
+    namespace once you changed the password. The secret serves no other
+    purpose than to store the initially generated password in clear and can
+    safely be deleted at any time. It will be re-created on demand by Argo CD
+    if a new admin password must be re-generated.
+
+## Use the CLI to deploy an application
+
+To start deploying resources you need to authenticate with the CLI and then create [Argo CD applications](../basics/apps/index.md).
+
+### CLI Login
+
+Using the username `admin` and the password from above, login to Argo CD's IP or hostname:
+
+```bash
+argocd login <ARGOCD_SERVER>
+```
+
+The value of `ARGOCD_SERVER` depends on the method you used in the previous section. It can be an IP address, a hostname such as `argocd.example.com` or even `localhost` if you use a local cluster.
+
+!!! note
+    The CLI environment must be able to communicate with the Argo CD API server. If it isn't directly accessible as described in the previous section, you can tell the CLI to access it using port forwarding through one of these mechanisms: 1) add `--port-forward-namespace argocd` flag to every CLI command; or 2) set `ARGOCD_OPTS` environment variable: `export ARGOCD_OPTS='--port-forward-namespace argocd'`.
+
+You can change the admin password using the command:
+
+```bash
+argocd account update-password
+```
+
+In order to change the password of the admin user, you will need to know the current password. If you don't know the current password, you will have to use a different method to reset it.
+
+### Create an application
+
+Create the [example guestbook application](https://github.com/argoproj/argocd-example-apps/tree/master/guestbook) with the following command:
+
+```bash
+argocd app create guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path guestbook --dest-server https://kubernetes.default.svc --dest-namespace default
+```
+
+### Sync the application
+
+Once the guestbook application is created, you can now view its status:
+
+```bash
+$ argocd app get guestbook
+Name:               guestbook
+Server:             https://kubernetes.default.svc
+Namespace:          default
+URL:                https://10.97.164.88/applications/guestbook
+Repo:               https://github.com/argoproj/argocd-example-apps.git
+Target:
+Path:               guestbook
+Sync Policy:        <none>
+Sync Status:        OutOfSync from  (1ff8a67)
+Health Status:      Missing
+
+GROUP  KIND        NAMESPACE  NAME          STATUS     HEALTH
+apps   Deployment  default    guestbook-ui  OutOfSync  Missing
+       Service     default    guestbook-ui  OutOfSync  Missing
+```
+
+The application status is initially in `OutOfSync` state since the application has yet to be
+deployed, and no Kubernetes resources have been created. To [sync](../syncing/index.md) (deploy) the application, run:
+
+```bash
+argocd app sync guestbook
+```
+
+This command retrieves the manifests from the [repository](../basics/repos/index.md) and performs a `kubectl apply` on the cluster. The guestbook app is now running and you can now view its resource components, logs,
+events, and assessed health status.
+
+## Use the Web UI to deploy an application
+
+As an alternative method you can also use Argo CD is by the friendly Web interface.
+
+### Web login
+
+Open your browser and  login by visiting the IP/hostname that you exposed
+in the first section. You will see the initial Login screen.
+
+Enter as username `admin` and as password the auto-generated value you found
+by reading the initial Kubernetes secret.
+
+### Create an application
+
+After logging in, click the **+ New App** button as shown below:
+
+![+ new app button](../assets/new-app.png)
+
+Give your app the name `guestbook`, use the [project](../basics/projects/index.md) `default`, and leave the [sync policy](../syncing/index.md) as `Manual`:
+
+![app information](../assets/app-ui-information.png)
+
+Connect the [https://github.com/argoproj/argocd-example-apps.git](https://github.com/argoproj/argocd-example-apps.git) [repository](../basics/repos/index.md) to Argo CD by setting repository url to the github repo url, leave revision as `HEAD`, and set the path to `guestbook`:
+
+![connect repo](../assets/connect-repo.png)
+
+For **Destination**, set cluster URL to `https://kubernetes.default.svc` (or `in-cluster` for cluster name) and namespace to `default`:
+
+![destination](../assets/destination.png)
+
+After filling out the information above, click **Create** at the top of the UI to create the `guestbook` application:
+
+![destination](../assets/create-app.png)
+
+
+### Sync the application
+
+The application status is initially in `OutOfSync` state since the application has yet to be
+deployed, and no Kubernetes resources have been created. To [sync](../syncing/index.md) (deploy) the application, click the Sync button and accept the default values.
+
+After some time the application will be fully deployed (you will see the "Healthy" and "Synced" status).
+
+![guestbook app](../assets/guestbook-app.png)
+
+You can also click on the application entry and get a graphical overview of all the individual Kubernetes resources it contains.
+
+![view app](../assets/guestbook-tree.png)
+
+On the top right corner of the window you can find different controls that allow you to change the visualization method.
+
+

docs/getting_started/install.md

@@ -0,0 +1,252 @@
+# Installing Argo CD server components
+
+!!! tip "Want to upgrade?"
+    If you're looking to upgrade an existing Argo CD installation to a newer
+    version, please have a look at the
+    [upgrade documentation](../../operations/upgrading/).
+
+## Requirements
+
+Argo CD is a Kubernetes-native application, and must be installed into a Kubernetes 
+cluster in order to function properly. Regardless of which
+[installation type](#installation-types) or
+[installation methods](#installation-methods)
+you chose, you will need a target cluster running a supported version of
+Kubernetes, and you will need permissions to create resources in this cluster.
+
+Depending on which
+[installation type](#installation-types) you chose, the required permissions
+will vary.
+
+You need at least one cluster to install Argo CD, but you can later add other deployment targets that themselves do not need an Argo CD instance.
+
+
+
+## Quick installation for trying out Argo CD
+
+!!! warning 
+    This installation method is only useful for demos and prototypes.
+
+If you are impatient and just want to give Argo CD a quick try, make sure that
+your current `kubectl` context is pointing to the cluster you want to install
+Argo CD to, then run
+
+```bash
+kubectl create namespace argocd
+kubectl -n argocd apply -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+```
+
+This will install the current stable version of Argo CD into the `argocd`
+namespace of your Kubernetes cluster. Then continue reading [the first steps](getting_started/first_steps/).
+
+## Production-Grade Installation
+
+When you are ready to use Argo CD in a production environment you have
+several installation options.
+
+For a production setup you should pay attention to extra aspects of your installation such as:
+
+* defining the correct resource limits
+* applying proper security constraints
+* setting up high availability
+* managing Argo CD upgrades
+* monitoring Argo CD itself 
+
+## Installation types
+
+Argo CD provides various installation types, from which you need to pick the
+one that meets your operational requirements.
+
+### Cluster-scoped installation
+
+The cluster-scoped installation type provides the most functionality, and is
+the required installation type if you plan to manage cluster-scoped resources
+with Argo CD. In order to install Argo CD in the cluster scope, you will need
+cluster admin privileges on the cluster you are going to install Argo CD to.
+
+The cluster-scoped installation will install additional `ClusterRoles` and
+`ClusterRoleBindings` in your cluster, with elevated privileges.
+
+This is the generally recommended installation type for most use-cases. It is
+possible to lock-down a cluster-scoped installation later on.
+
+### Namespace-scoped installation
+
+The namespace-scoped installation type will limit the Argo CD installation to
+manage only resources within the namespace on the cluster it is installed to.
+This installation type will not be able to manage cluster-scoped resources on
+the cluster it is installed to, but can be setup to manage cluster-scoped
+resources on other remote clusters.
+
+The namespace-scoped installation will install additional `Roles` and
+`RoleBindings` within the namespace it is installed to.
+
+This installation type cannot be easily upgraded to a cluster-scope later on,
+and should be used if you do not have administrative privileges on the cluster
+you are installing to.
+
+## Installation variants
+
+Both, the cluster-scoped and namespace-scoped installation manifests come in
+two distinct variants:
+
+* Standard
+* High availability
+
+As with the installation type, you should pick the one that meets your
+operational requirements.
+
+### Standard installation
+
+The standard installation is suitable for most use cases in development or
+pre-production environments, and doesn't need much resources on the cluster
+it is installed to.
+
+It will install all Argo CD workloads with a single replica, and also will
+setup a single instance, non-clustered Redis cache.
+
+This flavour can later be easily upgraded to a HA flavour.
+
+### High-availability installation
+
+The HA installation differs from the standard installation in that it will
+start two replicas of `argocd-server` and `argocd-repo-server` each and
+will install a clustered version of the Redis cache, using three replicas
+of `argocd-redis-ha-server` in a `StatefulSet` manager.
+
+The Argo CD workloads will also be setup with anti-affinity rules, so that the
+replicas will be scheduled on different nodes.
+
+Obviously, this flavour requires some more resources on the target cluster.
+You can change the number of replicas later on, except for the Redis cache
+which requires 3 replicas in order to function properly.
+
+This is the recommended flavour for production environments.
+
+## Installation process
+
+### Pre-requisites
+
+No matter what method you chose, you should make sure that you have all the
+required privileges in the target cluster, and that the installation namespace
+is created. So make sure your `kubectl` context points to your target cluster
+and run:
+
+```bash
+kubectl create namespace argocd
+```
+
+### Using plain Kubernetes manifests
+
+Argo CD provides ready-to-use, pre-rendered installation manifests for all
+combinations of installation type and installation variant, as described above.
+
+You can install these manifests using `kubectl apply`, directly from GitHub
+or previously downloaded to your local machine. To install the current *stable*
+version of Argo CD version, you can use one of the below commands:
+
+*Cluster-scope, standard availability:*
+
+```bash
+kubectl -n argocd apply -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+```
+
+*Cluster-scope, high availability:*
+
+```bash
+kubectl -n argocd apply -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml
+```
+
+*Namespace-scope, standard availability:*
+
+```bash
+kubectl -n argocd apply -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/namespace-install.yaml
+```
+
+*Namespace-scope, high availability:*
+
+```bash
+kubectl -n argocd apply -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/namespace-install.yaml
+```
+
+### Using Kustomize
+
+Argo CD provides Kustomize resources which you can use to create an installation
+that is custom-tailored to your environment. You can use Kustomize to render the
+manifests with your own configuration and settings.
+
+If you plan to deviate from the default settings (and you most likely will for
+production environments), using Kustomize is the recommended way of installing
+Argo CD.
+
+The following are minimal examples of `kustomization.yaml` files for each of the
+installation flavours:
+
+*Cluster-scope, standard availability:*
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- https://github.com/argoproj/argo-cd/manifests/cluster-install?ref=stable
+```
+
+*Cluster-scope, high availability:*
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- https://github.com/argoproj/argo-cd/manifests/ha/cluster-install?ref=stable
+```
+
+*Namespace-scope, standard availability:*
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- https://github.com/argoproj/argo-cd/manifests/namespace-install?ref=stable
+```
+
+*Namespace-scope, high availability:*
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- https://github.com/argoproj/argo-cd/manifests/ha/namespace-install?ref=stable
+```
+
+### Using Helm
+
+While Argo CD provides no official Helm charts, there is an awesome, community
+maintained chart for Argo CD available.
+
+You can find this chart, along with installation instructions, at the
+[Argo project's community managed Helm charts](https://github.com/argoproj/argo-helm/tree/master/charts/argo-cd)
+GitHub repository.
+
+Be aware that the Helm chart's maintainers do some things differently, and you
+might not find all of the terminology used here in the Chart.
+
+Also, please note that this is not an officially supported installation method.
+Please direct all questions or problems you face using the Helm chart directly
+to the chart's maintainers.
+
+## Alternative installation methods
+
+You can also use infrastructure tools such as [Terraform](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs), [Pulumi](https://www.pulumi.com/registry/packages/kubernetes/) or [Crossplane](https://github.com/crossplane-contrib/provider-kubernetes) to manage your Argo CD installation.
+
+!!! tip "Use Argo CD to manage itself"
+    It is also possible to install an Argo CD instance and manage it with itself like any other Kubernetes application. You might find interesting the [Argo Autopilot project](https://argocd-autopilot.readthedocs.io/en/stable/) that does exactly that (among other features).
+    It installs Argo CD and sets it up to manage itself.
+
+## Post installation
+
+After installation, you should take some time to
+[lockdown your installation](../../operations/security/).

docs/getting_started/install_cli.md

@@ -0,0 +1,141 @@
+# Installing Argo CD CLI
+
+Argo CD provides a CLI (command line interface) tool for interaction through its
+API. The CLI is currently available for the following platforms:
+
+* Linux on amd64 architecture,
+* Mac (darwin) on amd64 architecture,
+* Windows on amd64 architecture
+
+Ports for other architectures, such as arm32 and arm64, are not yet officially
+available but are planned.
+
+Installing and/or using the CLI is completely optional, but recommended. The
+CLI provides a convenient way to interact with Argo CD through its API.
+
+## Install on Linux
+
+We are not aware of official Argo CD CLI packages for Linux distributions, so
+the easiest way to retrieve and install the CLI on your Linux machine is to
+download the appropriate binary from GitHub using the shell and `curl`:
+
+### Manual download and install Linux CLI
+
+First, retrieve the version of the current release (or set the `ARGOCD_VERSION`
+environment variable manually):
+
+```bash
+ARGOCD_VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
+```
+
+Then, retrieve the binary from GitHub to a temporary location:
+
+```bash
+curl -sSL -o /tmp/argocd-${ARGOCD_VERSION} https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-linux-amd64
+```
+
+Finally, make the binary executable and move it to a location within your
+`$PATH`, in this example `/usr/local/bin`:
+
+```bash
+chmod +x /tmp/argocd-${VERSION}
+sudo mv /tmp/argocd-${VERSION} /usr/local/bin/argocd 
+```
+
+Verify that your CLI is working properly:
+
+```bash
+argocd version --client
+```
+
+This should give an output similar to the following (details may differ across
+versions and platform):
+
+```bash
+argocd: v1.8.1+c2547dc
+  BuildDate: 2020-12-10T02:57:57Z
+  GitCommit: c2547dca95437fdbb4d1e984b0592e6b9110d37f
+  GitTreeState: clean
+  GoVersion: go1.14.12
+  Compiler: gc
+  Platform: linux/amd64
+```
+
+## Install on MacOS (Darwin)
+
+You can install the MacOS CLI either using Homebrew, or manually by downloading
+the CLI from GitHub.
+
+### Installing using Homebrew
+
+This is as simple as running
+
+```bash
+brew install argocd
+```
+
+### Manual download and install MacOS CLI
+
+First, retrieve the version of the current release (or set the `ARGOCD_VERSION`
+environment variable manually):
+
+```bash
+ARGOCD_VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
+```
+
+Then, retrieve the binary from GitHub to a temporary location:
+
+```bash
+curl -sSL -o /tmp/argocd-${ARGOCD_VERSION} https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-darwin-amd64
+```
+
+Finally, make the binary executable and move it to a location within your
+`$PATH`, in this example `/usr/local/bin`:
+
+```bash
+chmod +x /tmp/argocd-${VERSION}
+sudo mv /tmp/argocd-${VERSION} /usr/local/bin/argocd 
+```
+
+Verify that your CLI is working properly:
+
+```bash
+argocd version --client
+```
+
+This should give an output similar to the following (details may differ across
+versions and platform):
+
+```bash
+argocd: v1.8.1+c2547dc
+  BuildDate: 2020-12-10T02:57:57Z
+  GitCommit: c2547dca95437fdbb4d1e984b0592e6b9110d37f
+  GitTreeState: clean
+  GoVersion: go1.14.12
+  Compiler: gc
+  Platform: darwin/amd64
+```
+
+## Install on Windows
+
+You can also use the Argo CD CLI from a Windows machine.
+
+### Installation via WSL
+
+The easiest way to use the CLI from Windows is via the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about).
+
+First you need [to install WSL 1 or 2](https://docs.microsoft.com/en-us/windows/wsl/install) on your Windows machine. Then you can install the Argo CD CLI by following the instructions at the [linux section above](#install-on-linux).
+
+### Manual installation
+
+You can install the native Windows CLI to any folder of your choosing. Open a terminal by typing `cmd` in your start menu and enter the following:
+
+```shell
+cd c:\
+md myapps
+cd myapps
+curl -sSL -o argocd.exe https://github.com/argoproj/argo-cd/releases/latest/download/argocd-windows-amd64.exe
+```
+
+Then type `argocd version --client` to verify your CLI. Finally add the `myapps` folder to your Windows PATH variable.
+

docs/index.md

@@ -1,93 +1,91 @@
-# Overview
-
-<!-- markdownlint-disable MD026 -->
-## What Is Argo CD?
-<!-- markdownlint-enable MD026 -->
 
 Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes.
 
-![Argo CD UI](assets/argocd-ui.gif)
+[![ArgoCD UI example](assets/argocd-ui-example.png)](https://cd.apps.argoproj.io/)
 
-<!-- markdownlint-disable MD026 -->
-## Why Argo CD?
-<!-- markdownlint-enable MD026 -->
-
-Application definitions, configurations, and environments should be declarative and version controlled.
-Application deployment and lifecycle management should be automated, auditable, and easy to understand.
-
-## Getting Started
-
-### Quick Start
-
-```bash
-kubectl create namespace argocd
-kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
-```
-
-Follow our [getting started guide](getting_started.md). Further user oriented [documentation](user-guide/)
-is provided for additional features. If you are looking to upgrade ArgoCD, see the [upgrade guide](./operator-manual/upgrading/overview.md).
-Developer oriented [documentation](developer-guide/) is available for people interested in building third-party integrations.
+Argo CD is one of the core subprojects of the [Argo Family of projects](https://argoproj.github.io/).
 
 ## How it works
 
+Argo CD is a Kubernetes native application. You install it on a Kubernetes cluster as a controller. It then monitors a set of Git repositories and automatically creates/updates the Kubernetes Objects and resources described in Git.
+
+[![how it works](assets/how-it-works.png)](assets/how-it-works.png)
+
 Argo CD follows the **GitOps** pattern of using Git repositories as the source of truth for defining
-the desired application state. Kubernetes manifests can be specified in several ways:
+the desired application state. 
+You can learn more about the GitOps principles at [http://opengitops.dev](http://opengitops.dev).
+
+You can learn more about the major Argo CD concepts by looking at
+the [terminology page](basics/terminology.md).
+
+
+
+## Argo CD Live instance
+
+If you want to see quickly how the Web Interface looks like, The Argo CD team maintains a public instance at [https://cd.apps.argoproj.io/applications](https://cd.apps.argoproj.io/applications).
+
+
+[![ArgoCD public instance](assets/public-instance.png)](https://cd.apps.argoproj.io/)
+
+
+This instance is used to test/deploy Argo CD and other associated Argo projects.
+
+
+## Managing multiple clusters
+
+In the simplest case, Argo CD can manage applications on the same cluster that it is running on. It is also possible to connect additional clusters to a single Argo CD instance and manage them externally without the need of running extra Argo CD instances.
+
+[![multi-cluster](assets/multi-cluster-argocd.png)](assets/multi-cluster-argocd.png)
+
+You can also disable the deployment/management of applications on the cluster Argo CD is running on if you prefer having a "management cluster" that only controls external clusters.
+
+## Types of applications supported
+
+Kubernetes manifests can be specified in [several ways](tools):
 
 * [kustomize](https://kustomize.io) applications
 * [helm](https://helm.sh) charts
-* [ksonnet](https://ksonnet.io) applications
 * [jsonnet](https://jsonnet.org) files
 * Plain directory of YAML/json manifests
-* Any custom config management tool configured as a config management plugin
+* Any custom config management tool configured as a [config management plugin](tools/plugins.md)
 
 Argo CD automates the deployment of the desired application states in the specified target environments.
 Application deployments can track updates to branches, tags, or pinned to a specific version of
-manifests at a Git commit. See [tracking strategies](user-guide/tracking_strategies.md) for additional
+manifests at a Git commit. See [tracking strategies](syncing/tracking.md) for additional
 details about the different tracking strategies available.
 
-For a quick 10 minute overview of Argo CD, check out the demo presented to the Sig Apps community
-meeting:
-
-[![Argo CD Overview Demo](https://img.youtube.com/vi/aWDIQMbp1cc/0.jpg)](https://youtu.be/aWDIQMbp1cc?t=1m4s)
-
-## Architecture
-
-![Argo CD Architecture](assets/argocd_architecture.png)
-
-Argo CD is implemented as a kubernetes controller which continuously monitors running applications
-and compares the current, live state against the desired target state (as specified in the Git repo).
-A deployed application whose live state deviates from the target state is considered `OutOfSync`.
-Argo CD reports & visualizes the differences, while providing facilities to automatically or
-manually sync the live state back to the desired target state. Any modifications made to the desired
-target state in the Git repo can be automatically applied and reflected in the specified target
-environments.
-
-For additional details, see [architecture overview](operator-manual/architecture.md).
-
-## Features
+## Feature highlight
 
 * Automated deployment of applications to specified target environments
-* Support for multiple config management/templating tools (Kustomize, Helm, Ksonnet, Jsonnet, plain-YAML)
-* Ability to manage and deploy to multiple clusters
-* SSO Integration (OIDC, OAuth2, LDAP, SAML 2.0, GitHub, GitLab, Microsoft, LinkedIn)
-* Multi-tenancy and RBAC policies for authorization
+* Support for multiple config management/templating tools (Kustomize, Helm, Jsonnet, plain-YAML)
+* Ability to manage and deploy to [multiple clusters](basics/clusters/external.md)
+* [SSO Integration](operations/sso/overview.md) (OIDC, OAuth2, LDAP, SAML 2.0, GitHub, GitLab, Microsoft, LinkedIn)
+* Multi-tenancy and [RBAC policies](rbac) for authorization
 * Rollback/Roll-anywhere to any application configuration committed in Git repository
-* Health status analysis of application resources
+* [Health status analysis](syncing/health.md) of application resources
 * Automated configuration drift detection and visualization
-* Automated or manual syncing of applications to its desired state
+* Automated or manual [syncing](syncing/index.md) of applications to its desired state
 * Web UI which provides real-time view of application activity
 * CLI for automation and CI integration
-* Webhook integration (GitHub, BitBucket, GitLab)
+* [Webhook integration](syncing/git_webhooks.md) (GitHub, BitBucket, GitLab)
 * Access tokens for automation
-* PreSync, Sync, PostSync hooks to support complex application rollouts (e.g.blue/green & canary upgrades)
+* [PreSync, Sync, PostSync hooks](syncing/waves.md) to support complex application rollouts (e.g.blue/green & canary upgrades)
+* [Sync waves](syncing/waves.md) to control order of resource deployment
 * Audit trails for application events and API calls
-* Prometheus metrics
-* Parameter overrides for overriding ksonnet/helm parameters in Git
+* [Prometheus metrics](operations/metrics.md)
+* [Parameter overrides for overriding Helm parameters in Git](basics/apps/overrides.md)
 
-## Development Status
 
-Argo CD is being actively developed by the community. Our releases can be found [here](https://github.com/argoproj/argo-cd/releases).
+## Argo CD Adoption
 
-## Adoption
+Organizations who have officially adopted Argo CD can be found [at the USERS file](https://github.com/argoproj/argo-cd/blob/master/USERS.md). Feel free to create a Pull Request and add your own organization if you are using Argo CD.  
 
-Organizations who have officially adopted Argo CD can be found [here](https://github.com/argoproj/argo-cd/blob/master/USERS.md).
+## Community 
+
+* Follow the development of the project at [https://github.com/argoproj/argo-cd](https://github.com/argoproj/argo-cd)
+* Visit the [Argo blog](https://blog.argoproj.io/)
+* Join the `#argo-cd` channel at the [CNCF slack](https://argoproj.github.io/community/join-slack/) 
+* Get Twitter updates at [https://twitter.com/argoproj](https://twitter.com/argoproj)
+* Visit the [Argo Subreddit](https://www.reddit.com/r/argoproj/)
+* Connect with us at [https://www.linkedin.com/company/argoproj/](https://www.linkedin.com/company/argoproj/)
+* See more videos and blog posts at the [README file](https://github.com/argoproj/argo-cd/#blogs-and-presentations).

docs/operations/index.md

@@ -0,0 +1,3 @@
+# Operating & maintaining Argo CD
+
+## Architectural overview

docs/operations/ingress/index.md

@@ -0,0 +1,9 @@
+# Configuring Ingress for Argo CD
+
+## HTTP/2 and gRPC
+
+## Configuring the root context
+
+## Configuring the UI base path
+
+## Authenticating through multiple layers of authenticating reverse proxies

docs/operations/scaling.md

@@ -1,111 +1,27 @@
-# High Availability
+## Common Scaling Problems
+
+* Syncs are taking too long to start or complete:
+    * Increase the parallelism limits for the [application controller](#argocd-application-controller) and [repo servers](#argocd-server) to allow more operations to run simultaneously
+    * If you're running many applications with auto-sync enabled, try changing `--app-resync-seconds` in the [application controller](#argocd-application-controller) to reduce the number of operations it's trying to do at once
+* The application controller is using too many resources:
+    * Reduce the parallelism limits for the [application controller](#argocd-application-controller) to improve memory and CPU usage at the expense of sync throughput
+    * For Argo CD installations with multiple clusters and many applications, you can enable [controller sharding](#controller-sharding) to split the load across multiple instances
+* Individual applications with large repositories or large sets of manifests taking too long to sync or refresh:
+    * See [monorepo scaling considerations](#monorepo-scaling-considerations)
+
+[Enabling metrics](./metrics.md) is an important way to ensure you have visibility into the performance of your Argo CD installation as it scales, and will be valuable for troubleshooting many of these issues.
+## High Availability Mode
 
 Argo CD is largely stateless, all data is persisted as Kubernetes objects, which in turn is stored in Kubernetes' etcd. Redis is only used as a throw-away cache and can be lost. When lost, it will be rebuilt without loss of service.
 
-A set HA of manifests are provided for users who wish to run Argo CD in a highly available manner. This runs more containers, and run Redis in HA mode.
+A set of HA manifests are provided for users who wish to run Argo CD in a highly available manner. This runs more containers, and runs Redis in HA mode.
 
 [Manifests ⧉](https://github.com/argoproj/argo-cd/tree/master/manifests) 
 
 !!! note
     The HA installation will require at least three different nodes due to pod anti-affinity roles in the specs.
 
-## Scaling Up
 
-### argocd-repo-server
-
-**settings:**
-
-The `argocd-repo-server` is responsible for cloning Git repository, keeping it up to date and generating manifests using the appropriate tool.
-
-* `argocd-repo-server` fork/exec config management tool to generate manifests. The fork can fail due to lack of memory and limit on the number of OS threads.
-The `--parallelismlimit` flag controls how many manifests generations are running concurrently and allows avoiding OOM kills.
-
-* the `argocd-repo-server` ensures that repository is in the clean state during the manifest generation using config management tools such as Kustomize, Helm
-or custom plugin. As a result Git repositories with multiple applications might be affect repository server performance.
-Read [Monorepo Scaling Considerations](#monorepo-scaling-considerations) for more information.
-
-* `argocd-repo-server` clones repository into `/tmp` ( of path specified in `TMPDIR` env variable ). Pod might run out of disk space if have too many repository
-or repositories has a lot of files. To avoid this problem mount persistent volume.
-
-* `argocd-repo-server` `git ls-remote` to resolve ambiguous revision such as `HEAD`, branch or tag name. This operation is happening pretty frequently
-and might fail. To avoid failed syncs use `ARGOCD_GIT_ATTEMPTS_COUNT` environment variable to retry failed requests.
-
-* `argocd-repo-server` Every 3m (by default) Argo CD checks for changes to the app manifests. Argo CD assumes by default that manifests only change when the repo changes, so it caches generated manifests (for 24h by default). With Kustomize remote bases, or Helm patch releases, the manifests can change even though the repo has not changed. By reducing the cache time, you can get the changes without waiting for 24h. Use `--repo-cache-expiration duration`, and we'd suggest in low volume environments you try '1h'. Bear in mind this will negate the benefit of caching if set too low. 
-
-* `argocd-repo-server` fork exec config management tools such as `helm` or `kustomize` and enforces 90 seconds timeout. The timeout can be increased using `ARGOCD_EXEC_TIMEOUT` env variable.
-
-**metrics:**
-
-* `argocd_git_request_total` - Number of git requests. The metric provides two tags: `repo` - Git repo URL; `request_type` - `ls-remote` or `fetch`.
-
-* `ARGOCD_ENABLE_GRPC_TIME_HISTOGRAM` (v1.8+) - environment variable that enables collecting RPC performance metrics. Enable it if you need to troubleshoot performance issue. Note: metric is expensive to both query and store!
-
-### argocd-application-controller
-
-**settings:**
-
-The `argocd-application-controller` uses `argocd-repo-server` to get generated manifests and Kubernetes API server to get actual cluster state.
-
-* each controller replica uses two separate queues to process application reconciliation (milliseconds) and app syncing (seconds). Number of queue processors for each queue is controlled by
-`--status-processors` (20 by default) and `--operation-processors` (10 by default) flags. Increase number of processors if your Argo CD instance manages too many applications.
-For 1000 application we use 50 for `--status-processors` and 25 for `--operation-processors`
-
-* The manifest generation typically takes the most time during reconciliation. The duration of manifest generation is limited to make sure controller refresh queue does not overflow.
-The app reconciliation fails with `Context deadline exceeded` error if manifest generating taking too much time. As workaround increase value of `--repo-server-timeout-seconds` and
-consider scaling up `argocd-repo-server` deployment.
-
-* The controller uses `kubectl` fork/exec to push changes into the cluster and to convert resource from preferred version into user specified version
-(e.g. Deployment `apps/v1` into `extensions/v1beta1`). Same as config management tool `kubectl` fork/exec might cause pod OOM kill. Use `--kubectl-parallelism-limit` flag to limit
-number of allowed concurrent kubectl fork/execs.
-
-* The controller uses Kubernetes watch APIs to maintain lightweight Kubernetes cluster cache. This allows to avoid querying Kubernetes during app reconciliation and significantly improve
-performance. For performance reasons controller monitors and caches only preferred the version of a resource. During reconciliation, the controller might have to convert cached resource from
-preferred version into a version of the resource stored in Git. If `kubectl convert` fails because conversion is not supported than controller fallback to Kubernetes API query which slows down
-reconciliation. In this case advice user-preferred resource version in Git.
-
-* The controller polls Git every 3m by default. You can increase this duration using `--app-resync seconds` to reduce polling.
-
-* If the controller is managing too many clusters and uses too much memory then you can shard clusters across multiple
-controller replicas. To enable sharding increase the number of replicas in `argocd-application-controller` `StatefulSet`
-and repeat number of replicas in `ARGOCD_CONTROLLER_REPLICAS` environment variable. The strategic merge patch below
-demonstrates changes required to configure two controller replicas.
-
-```yaml
-apiVersion: apps/v1
-kind: StatefulSet
-metadata:
-  name: argocd-application-controller
-spec:
-  replicas: 2
-  template:
-    spec:
-      containers:
-      - name: argocd-application-controller
-        env:
-        - name: ARGOCD_CONTROLLER_REPLICAS
-          value: "2"
-```
-
-* `ARGOCD_ENABLE_GRPC_TIME_HISTOGRAM`  (v1.8+)- environment variable that enables collecting RPC performance metrics. Enable it if you need to troubleshoot performance issue. Note: metric is expensive to both query and store!
-
-**metrics**
-
-* `argocd_app_reconcile` - reports application reconciliation duration. Can be used to build reconciliation duration heat map to get high-level reconciliation performance picture.
-* `argocd_app_k8s_request_total` - number of k8s requests per application. The number of fallback Kubernetes API queries - useful to identify which application has a resource with
-non-preferred version and causes performance issues.
-
-### argocd-server
-
-The `argocd-server` is stateless and probably least likely to cause issues. You might consider increasing number of replicas to 3 or more to ensure there is no downtime during upgrades.
-
-**settings:**
-
-* The `ARGOCD_GRPC_MAX_SIZE_MB` environment variable allows specifying the max size of the server response message in megabytes.
-The default value is 200. You might need to increase for an Argo CD instance that manages 3000+ applications.    
-
-### argocd-dex-server, argocd-redis
-
-The `argocd-dex-server` uses an in-memory database, and two or more instances would have inconsistent data. `argocd-redis` is pre-configured with the understanding of only three total redis servers/sentinels.
 
 ## Monorepo Scaling Considerations
 
@@ -121,13 +37,13 @@ If the manifest generation has no side effects then requests are processed in pa
 
   * **Multiple Custom plugin based applications:** avoid creating temporal files during manifest generation and and create `.argocd-allow-concurrency` file in app directory.
 
-  * **Multiple Kustomize or Ksonnet applications in same repository with [parameter overrides](../user-guide/parameters.md):** sorry, no workaround for now.
+  * **Multiple Kustomize or Ksonnet applications in same repository with parameter overrides:** sorry, no workaround for now.
 
 
 ### Webhook and Manifest Paths Annotation
 
 Argo CD aggressively caches generated manifests and uses repository commit SHA as a cache key. A new commit to the Git repository invalidates cache for all applications configured in the repository
-that again negatively affect mono repositories with multiple applications. You might use [webhooks ⧉](https://github.com/argoproj/argo-cd/tree/master/docs/operator-manual/webhook) and `argocd.argoproj.io/manifest-generate-paths` Application
+that again negatively affect mono repositories with multiple applications. You might use [webhooks ⧉](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/webhook.md) and `argocd.argoproj.io/manifest-generate-paths` Application
 CRD annotation to solve this problem and improve performance.
 
 The `argocd.argoproj.io/manifest-generate-paths` contains a semicolon-separated list of paths within the Git repository that are used during manifest generation. The webhook compares paths specified in the annotation
@@ -194,3 +110,133 @@ spec:
     path: my-application
 # ...
 ```
+
+## Controller Sharding
+
+If the controller is managing too many clusters and uses too much memory then you can shard clusters across multiple
+controller replicas. To enable sharding increase the number of replicas in `argocd-application-controller` `StatefulSet`
+and repeat number of replicas in `ARGOCD_CONTROLLER_REPLICAS` environment variable. The strategic merge patch below
+demonstrates changes required to configure two controller replicas.
+
+```yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: argocd-application-controller
+spec:
+  replicas: 2
+  template:
+    spec:
+      containers:
+      - name: argocd-application-controller
+        env:
+        - name: ARGOCD_CONTROLLER_REPLICAS
+          value: "2"
+```
+
+Each controller shard will manage a set group of clusters. A shard determines if it should reconcile changes for a cluster if the ID of the cluster mod `ARGOCD_CONTROLLER_REPLICAS` is equal to the index number of the controller shard. For example, if there are two controller shards (`argocd-application-controller-0` and `argocd-application-controller-1`) then the cluster with ID 3 will be managed by shard 1 and the cluster with ID 4 will be managed by shard 0.
+
+### "Pinning" Clusters
+
+If you have clusters that with different amounts or kinds of applications, it may be necessary to manually rebalance the number of clusters across shards to ensure you have even amounts of resource usage. If you add a `shard` key to the secret for a cluster, then the cluster will be assigned to that shard instead of the shard it would normally use according to the formula from the previous section. 
+
+!!! Note
+    See the [managing clusters with the kubernetes API section](../../basics/clusters/manage#using-the-kubernetes-api) for more information on working with cluster secrets. 
+
+Once you know the name of the cluster you want to pin, you need to add the `shard` key to the `Secret` resource using `kubectl edit secrets <secret name>`. The value **must be base64 encoded and have no whitespace**. For example, you can find the value that would pin a cluster to shard 9 with `printf "9" | base64`, or `OQ==`. 
+
+#### Using Kustomize
+
+It's also possible to use kustomize to generate pinned cluster secrets using [kustomize secret generators](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kustomize/), which means if you already manage your Argo CD installation via kustomize it's easy to update it to track pinned clusters in git. Just add the following to your `kustomization.yaml` file:
+
+```yaml
+secretGenerator:
+  - name: <cluster secret name>
+    literals:
+      - shard=<pinned shard>
+
+generatorOptions: 
+  disableNameSuffixHash: true
+```
+
+When applied, this will update the cluster secret in place to add the shard key, without changing any of the other secret data.
+
+It's important to add `disableNameSuffix` to the `generatorOptions` block, otherwise the generator will append a random hash to the secret name and the cluster secret cannot be patched correctly.
+
+## Settings Reference For Individual Components
+
+### argocd-application-controller
+
+The `argocd-application-controller` uses `argocd-repo-server` to get generated manifests, fetches cluster state from the Kubernetes API, and applies generated manifests during syncs using `kubectl`.
+
+**settings:**
+
+* For large instances of Argo CD where it's difficult to scale a single controller instance to meet resource demands, see [controller sharding](#controller-sharding)
+
+* each controller replica uses two separate queues to process application reconciliation (milliseconds) and app syncing (seconds). Number of queue processors for each queue is controlled by
+`--status-processors` (20 by default) and `--operation-processors` (10 by default) flags. Increase number of processors if your Argo CD instance manages too many applications.
+For 1000 application we use 50 for `--status-processors` and 25 for `--operation-processors`
+
+* The manifest generation typically takes the most time during reconciliation. The duration of manifest generation is limited to make sure controller refresh queue does not overflow.
+The app reconciliation fails with `Context deadline exceeded` error if manifest generating taking too much time. As workaround increase value of `--repo-server-timeout-seconds` and
+consider scaling up `argocd-repo-server` deployment.
+
+* The controller uses `kubectl` fork/exec to push changes into the cluster and to convert resource from preferred version into user specified version
+(e.g. Deployment `apps/v1` into `extensions/v1beta1`). Same as config management tool `kubectl` fork/exec might cause pod OOM kill. Use `--kubectl-parallelism-limit` flag to limit
+number of allowed concurrent kubectl fork/execs.
+
+* The controller uses Kubernetes watch APIs to maintain lightweight Kubernetes cluster cache. This allows to avoid querying Kubernetes during app reconciliation and significantly improve
+performance. For performance reasons controller monitors and caches only preferred the version of a resource. During reconciliation, the controller might have to convert cached resource from
+preferred version into a version of the resource stored in Git. If `kubectl convert` fails because conversion is not supported than controller fallback to Kubernetes API query which slows down
+reconciliation. In this case advice user-preferred resource version in Git.
+
+* The controller polls Git every 3m by default. You can increase this duration using `--app-resync seconds` to reduce polling.
+
+* `ARGOCD_ENABLE_GRPC_TIME_HISTOGRAM`  (v1.8+)- environment variable that enables collecting RPC performance metrics. Enable it if you need to troubleshoot performance issue. Note: metric is expensive to both query and store!
+
+**metrics**
+
+* `argocd_app_reconcile` - reports application reconciliation duration. Can be used to build reconciliation duration heat map to get high-level reconciliation performance picture.
+* `argocd_app_k8s_request_total` - number of k8s requests per application. The number of fallback Kubernetes API queries - useful to identify which application has a resource with
+non-preferred version and causes performance issues.
+### argocd-repo-server
+
+The `argocd-repo-server` is responsible for cloning Git repositories, keeping them up to date and generating manifests using the appropriate tool.
+
+**settings:**
+
+* `argocd-repo-server` fork/exec config management tool to generate manifests. The fork can fail due to lack of memory and limit on the number of OS threads.
+The `--parallelismlimit` flag controls how many manifests generations are running concurrently and allows avoiding OOM kills.
+
+* the `argocd-repo-server` ensures that repository is in the clean state during the manifest generation using config management tools such as Kustomize, Helm
+or custom plugin. As a result Git repositories with multiple applications might be affect repository server performance.
+Read [Monorepo Scaling Considerations](#monorepo-scaling-considerations) for more information.
+
+* `argocd-repo-server` clones repository into `/tmp` ( of path specified in `TMPDIR` env variable ). Pod might run out of disk space if have too many repository
+or repositories has a lot of files. To avoid this problem mount persistent volume.
+
+* `argocd-repo-server` `git ls-remote` to resolve ambiguous revision such as `HEAD`, branch or tag name. This operation is happening pretty frequently
+and might fail. To avoid failed syncs use `ARGOCD_GIT_ATTEMPTS_COUNT` environment variable to retry failed requests.
+
+* `argocd-repo-server` Every 3m (by default) Argo CD checks for changes to the app manifests. Argo CD assumes by default that manifests only change when the repo changes, so it caches generated manifests (for 24h by default). With Kustomize remote bases, or Helm patch releases, the manifests can change even though the repo has not changed. By reducing the cache time, you can get the changes without waiting for 24h. Use `--repo-cache-expiration duration`, and we'd suggest in low volume environments you try '1h'. Bear in mind this will negate the benefit of caching if set too low. 
+
+* `argocd-repo-server` fork exec config management tools such as `helm` or `kustomize` and enforces 90 seconds timeout. The timeout can be increased using `ARGOCD_EXEC_TIMEOUT` env variable.
+
+**metrics:**
+
+* `argocd_git_request_total` - Number of git requests. The metric provides two tags: `repo` - Git repo URL; `request_type` - `ls-remote` or `fetch`.
+
+* `ARGOCD_ENABLE_GRPC_TIME_HISTOGRAM` (v1.8+) - environment variable that enables collecting RPC performance metrics. Enable it if you need to troubleshoot performance issue. Note: metric is expensive to both query and store!
+
+### argocd-server
+
+The `argocd-server` is stateless and probably least likely to cause issues. You might consider increasing number of replicas to 3 or more to ensure there is no downtime during upgrades.
+
+**settings:**
+
+* The `ARGOCD_GRPC_MAX_SIZE_MB` environment variable allows specifying the max size of the server response message in megabytes.
+The default value is 200. You might need to increase for an Argo CD instance that manages 3000+ applications.    
+
+### argocd-dex-server, argocd-redis
+
+The `argocd-dex-server` uses an in-memory database, and two or more instances would have inconsistent data. `argocd-redis` is pre-configured with the understanding of only three total redis servers/sentinels.

docs/operations/security.md

@@ -0,0 +1,19 @@
+# Securing your Argo CD installation
+
+The following is a compilation of best practises to lock-down your installation
+in order to make it more secure, both in terms of operational stability and
+access control.
+
+While these steps are completely optional, we highly recommend to implement them.
+
+## Setup Single Sign On (SSO) or local users
+
+## Setup Role Based Access Control (RBAC)
+
+## Disable the default admin user
+
+## Setup resource limits for Argo CD workloads
+
+## Restrict network access
+
+## Backup configuration

docs/operations/upgrading.md

@@ -0,0 +1 @@
+# Upgrading Argo CD

docs/operator-manual/application.yaml

@@ -1,121 +0,0 @@
-apiVersion: argoproj.io/v1alpha1
-kind: Application
-metadata:
-  name: guestbook
-  # You'll usually want to add your resources to the argocd namespace.
-  namespace: argocd
-  # Add a this finalizer ONLY if you want these to cascade delete.
-  finalizers:
-    - resources-finalizer.argocd.argoproj.io
-spec:
-  # The project the application belongs to.
-  project: default
-
-  # Source of the application manifests
-  source:
-    repoURL: https://github.com/argoproj/argocd-example-apps.git
-    targetRevision: HEAD
-    path: guestbook
-
-    # helm specific config
-    helm:
-      # Extra parameters to set (same as setting through values.yaml, but these take precedence)
-      parameters:
-      - name: "nginx-ingress.controller.service.annotations.external-dns\\.alpha\\.kubernetes\\.io/hostname"
-        value: mydomain.example.com
-      - name: "ingress.annotations.kubernetes\\.io/tls-acme"
-        value: "true"
-        forceString: true # ensures that value is treated as a string
-
-      # Release name override (defaults to application name)
-      releaseName: guestbook
-
-      # Helm values files for overriding values in the helm chart
-      # The path is relative to the spec.source.path directory defined above
-      valueFiles:
-      - values-prod.yaml
-
-      # Values file as block file
-      values: |
-        ingress:
-          enabled: true
-          path: /
-          hosts:
-            - mydomain.example.com
-          annotations:
-            kubernetes.io/ingress.class: nginx
-            kubernetes.io/tls-acme: "true"
-          labels: {}
-          tls:
-            - secretName: mydomain-tls
-              hosts:
-                - mydomain.example.com
-
-      # Optional Helm version to template with. If omitted it will fallback to look at the 'apiVersion' in Chart.yaml
-      # and decide which Helm binary to use automatically. This field can be either 'v2' or 'v3'.
-      version: v2
-
-    # kustomize specific config
-    kustomize:
-      # Optional kustomize version. Note: version must be configured in argocd-cm ConfigMap
-      version: v3.5.4
-      # Optional image name prefix
-      namePrefix: prod-
-      # Optional images passed to "kustomize edit set image".
-      images:
-      - gcr.io/heptio-images/ks-guestbook-demo:0.2
-
-    # directory
-    directory:
-      recurse: true
-      jsonnet:
-        # A list of Jsonnet External Variables
-        extVars:
-        - name: foo
-          value: bar
-          # You can use "code to determine if the value is either string (false, the default) or Jsonnet code (if code is true).
-        - code: true
-          name: baz
-          value: "true"
-        # A list of Jsonnet Top-level Arguments
-        tlas:
-        - code: false
-          name: foo
-          value: bar
-
-    # plugin specific config
-    plugin:
-      name: mypluginname
-      # environment variables passed to the plugin
-      env:
-        - name: FOO
-          value: bar
-
-  # Destination cluster and namespace to deploy the application
-  destination:
-    server: https://kubernetes.default.svc
-    namespace: guestbook
-
-  # Sync policy
-  syncPolicy:
-    automated: # automated sync by default retries failed attempts 5 times with following delays between attempts ( 5s, 10s, 20s, 40s, 80s ); retry controlled using `retry` field.
-      prune: true # Specifies if resources should be pruned during auto-syncing ( false by default ).
-      selfHeal: true # Specifies if partial app sync should be executed when resources are changed only in target Kubernetes cluster and no git change detected ( false by default ).
-      allowEmpty: false # Allows deleting all application resources during automatic syncing ( false by default ).
-    syncOptions:     # Sync options which modifies sync behavior
-    - Validate=false # disables resource validation (equivalent to 'kubectl apply --validate=false') ( true by default ).
-    - CreateNamespace=true # Namespace Auto-Creation ensures that namespace specified as the application destination exists in the destination cluster.
-    # The retry feature is available since v1.7
-    retry:
-      limit: 5 # number of failed sync attempt retries; unlimited number of attempts if less than 0
-      backoff:
-        duration: 5s # the amount to back off. Default unit is seconds, but could also be a duration (e.g. "2m", "1h")
-        factor: 2 # a factor to multiply the base duration after each failed retry
-        maxDuration: 3m # the maximum amount of time allowed for the backoff strategy
-
-  # Ignore differences at the specified json pointers
-  ignoreDifferences:
-  - group: apps
-    kind: Deployment
-    jsonPointers:
-    - /spec/replicas

docs/operator-manual/architecture.md

@@ -1,34 +0,0 @@
-
-# Architectural Overview
-
-![Argo CD Architecture](../assets/argocd_architecture.png)
-
-## Components
-
-### API Server
-The API server is a gRPC/REST server which exposes the API consumed by the Web UI, CLI, and CI/CD 
-systems. It has the following responsibilities:
-
-* application management and status reporting
-* invoking of application operations (e.g. sync, rollback, user-defined actions)
-* repository and cluster credential management (stored as K8s secrets)
-* authentication and auth delegation to external identity providers
-* RBAC enforcement
-* listener/forwarder for Git webhook events
-
-### Repository Server
-The repository server is an internal service which maintains a local cache of the Git repository
-holding the application manifests. It is responsible for generating and returning the Kubernetes
-manifests when provided the following inputs:
-
-* repository URL
-* revision (commit, tag, branch)
-* application path
-* template specific settings: parameters, ksonnet environments, helm values.yaml
-
-### Application Controller
-The application controller is a Kubernetes controller which continuously monitors running
-applications and compares the current, live state against the desired target state (as specified in
-the repo). It detects `OutOfSync` application state and optionally takes corrective action. It
-is responsible for invoking any user-defined hooks for lifecycle events (PreSync, Sync, PostSync)
-

docs/operator-manual/argocd-cm.yaml

@@ -1,260 +0,0 @@
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: argocd-cm
-  namespace: argocd
-  labels:
-    app.kubernetes.io/name: argocd-cm
-    app.kubernetes.io/part-of: argocd
-data:
-  # Argo CD's externally facing base URL (optional). Required when configuring SSO
-  url: https://argo-cd-demo.argoproj.io
-
-  # Enables application status badge feature
-  statusbadge.enabled: "true"
-
-  # Enables anonymous user access. The anonymous users get default role permissions specified argocd-rbac-cm.yaml.
-  users.anonymous.enabled: "true"
-  # Specifies token expiration duration
-  users.session.duration: "24h"
-
-  # Enables google analytics tracking is specified
-  ga.trackingid: "UA-12345-1"
-  # Unless set to 'false' then user ids are hashed before sending to google analytics
-  ga.anonymizeusers: "false"
-
-  # the URL for getting chat help, this will typically be your Slack channel for support
-  help.chatUrl: "https://mycorp.slack.com/argo-cd"
-  # the text for getting chat help, defaults to "Chat now!"
-  help.chatText: "Chat now!"
-
-  # A dex connector configuration (optional). See SSO configuration documentation:
-  # https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/sso
-  # https://github.com/dexidp/dex/tree/master/Documentation/connectors
-  dex.config: |
-    connectors:
-      # GitHub example
-      - type: github
-        id: github
-        name: GitHub
-        config:
-          clientID: aabbccddeeff00112233
-          clientSecret: $dex.github.clientSecret
-          orgs:
-          - name: your-github-org
-            teams:
-            - red-team
-    # It is possible to provide custom static client for dex if you want to reuse it
-    # with other services
-    # staticClients:
-    # - id: argo-workflow
-    #   name: Argo Workflow
-    #   redirectURIs:
-    #     - https://argo/oauth2/callback
-    #   secret: $secretReference
-
-  # OIDC configuration as an alternative to dex (optional).
-  oidc.config: |
-    name: Okta
-    issuer: https://dev-123456.oktapreview.com
-    clientID: aaaabbbbccccddddeee
-    clientSecret: $oidc.okta.clientSecret
-    # Optional set of OIDC scopes to request. If omitted, defaults to: ["openid", "profile", "email", "groups"]
-    requestedScopes: ["openid", "profile", "email"]
-    # Optional set of OIDC claims to request on the ID token.
-    requestedIDTokenClaims: {"groups": {"essential": true}}
-
-  # Git repositories configure Argo CD with (optional).
-  # This list is updated when configuring/removing repos from the UI/CLI
-  # Note: 'type: helm' field is supported in v1.3+. Use 'helm.repositories' for older versions.
-  repositories: |
-    - url: https://github.com/argoproj/my-private-repository
-      passwordSecret:
-        name: my-secret
-        key: password
-      usernameSecret:
-        name: my-secret
-        key: username
-      sshPrivateKeySecret:
-        name: my-secret
-        key: sshPrivateKey
-    - type: helm
-      url: https://storage.googleapis.com/istio-prerelease/daily-build/master-latest-daily/charts
-      name: istio.io
-    - type: helm
-      url: https://my-private-chart-repo.internal
-      name: private-repo
-      usernameSecret:
-        name: my-secret
-        key: username
-      passwordSecret:
-        name: my-secret
-        key: password
-
-  # Non-standard and private Helm repositories (deprecated in 1.3).
-  helm.repositories: |
-    - url: https://storage.googleapis.com/istio-prerelease/daily-build/master-latest-daily/charts
-      name: istio.io
-    - url: https://my-private-chart-repo.internal
-      name: private-repo
-      usernameSecret:
-        name: my-secret
-        key: username
-      passwordSecret:
-        name: my-secret
-        key: password
-
-  # Configuration to customize resource behavior (optional). Keys are in the form: group/Kind.
-  resource.customizations: |
-    admissionregistration.k8s.io/MutatingWebhookConfiguration:
-      # List of json pointers in the object to ignore differences
-      ignoreDifferences: |
-        jsonPointers:
-        - /webhooks/0/clientConfig/caBundle
-    certmanager.k8s.io/Certificate:
-      # Lua script for customizing the health status assessment
-      health.lua: |
-        hs = {}
-        if obj.status ~= nil then
-          if obj.status.conditions ~= nil then
-            for i, condition in ipairs(obj.status.conditions) do
-              if condition.type == "Ready" and condition.status == "False" then
-                hs.status = "Degraded"
-                hs.message = condition.message
-                return hs
-              end
-              if condition.type == "Ready" and condition.status == "True" then
-                hs.status = "Healthy"
-                hs.message = condition.message
-                return hs
-              end
-            end
-          end
-        end
-        hs.status = "Progressing"
-        hs.message = "Waiting for certificate"
-        return hs
-    cert-manager.io/Certificate:
-      # Lua script for customizing the health status assessment
-      health.lua: |
-        hs = {}
-        if obj.status ~= nil then
-          if obj.status.conditions ~= nil then
-            for i, condition in ipairs(obj.status.conditions) do
-              if condition.type == "Ready" and condition.status == "False" then
-                hs.status = "Degraded"
-                hs.message = condition.message
-                return hs
-              end
-              if condition.type == "Ready" and condition.status == "True" then
-                hs.status = "Healthy"
-                hs.message = condition.message
-                return hs
-              end
-            end
-          end
-        end
-        hs.status = "Progressing"
-        hs.message = "Waiting for certificate"
-        return hs
-    apps/Deployment:
-      # List of Lua Scripts to introduce custom actions
-      actions: |
-        # Lua Script to indicate which custom actions are available on the resource
-        discovery.lua: |
-          actions = {}
-          actions["restart"] = {}
-          return actions
-        definitions:
-          - name: restart
-            # Lua Script to modify the obj
-            action.lua: |
-              local os = require("os")
-              if obj.spec.template.metadata == nil then
-                  obj.spec.template.metadata = {}
-              end
-              if obj.spec.template.metadata.annotations == nil then
-                  obj.spec.template.metadata.annotations = {}
-              end
-              obj.spec.template.metadata.annotations["kubectl.kubernetes.io/restartedAt"] = os.date("!%Y-%m-%dT%XZ")
-              return obj
-
-  # Configuration to completely ignore entire classes of resource group/kinds (optional).
-  # Excluding high-volume resources improves performance and memory usage, and reduces load and
-  # bandwidth to the Kubernetes API server.
-  # These are globs, so a "*" will match all values.
-  # If you omit groups/kinds/clusters then they will match all groups/kind/clusters.
-  # NOTE: events.k8s.io and metrics.k8s.io are excluded by default
-  resource.exclusions: |
-    - apiGroups:
-      - repositories.stash.appscode.com
-      kinds:
-      - Snapshot
-      clusters:
-      - "*.local"
-
-  # By default all resource group/kinds are included. The resource.inclusions setting allows customizing
-  # list of included group/kinds.
-  resource.inclusions: |
-    - apiGroups:
-      - repositories.stash.appscode.com
-      kinds:
-      - Snapshot
-      clusters:
-      - "*.local"
-
-  resource.compareoptions: |
-    # if ignoreAggregatedRoles set to true then differences caused by aggregated roles in RBAC resources are ignored.
-    ignoreAggregatedRoles: true
-
-    # disables status field diffing in specified resource types
-    # 'crd' - CustomResourceDefinitions (default)
-    # 'all' - all resources
-    # 'none' - disabled
-    ignoreResourceStatusField: crd
-
-  # Configuration to add a config management plugin.
-  configManagementPlugins: |
-    - name: kasane
-      init:
-        command: [kasane, update]
-      generate:
-        command: [kasane, show]
-
-  # Build options/parameters to use with `kustomize build` (optional)
-  kustomize.buildOptions: --load_restrictor none
-
-  # Additional Kustomize versions and corresponding binary paths
-  kustomize.version.v3.5.1: /custom-tools/kustomize_3_5_1
-  kustomize.version.v3.5.4: /custom-tools/kustomize_3_5_4
-
-  # The metadata.label key name where Argo CD injects the app name as a tracking label (optional).
-  # Tracking labels are used to determine which resources need to be deleted when pruning.
-  # If omitted, Argo CD injects the app name into the label: 'app.kubernetes.io/instance'
-  application.instanceLabelKey: mycompany.com/appname
-
-  # disables admin user. Admin is enabled by default
-  admin.enabled: "false"
-  # add an additional local user with apiKey and login capabilities
-  #   apiKey - allows generating API keys
-  #   login - allows to login using UI
-  accounts.alice: apiKey, login
-  # disables user. User is enabled by default
-  accounts.alice.enabled: "false"
-
-  # The location of optional user-defined CSS that is loaded at runtime.
-  # Local CSS Files:
-  # - If the supplied path is to a file mounted on the argocd-server container, that file should be mounted
-  #   within a subdirectory of the existing "/shared/app" directory (e.g. "/shared/app/custom").  Otherwise,
-  #   the file will likely fail to be imported by the browser with an "incorrect MIME type" error.
-  # - The path should be specified relative to the "/shared/app" directory; not as an absolute path.
-  # Remote CSS Files:
-  # - Files may also be loaded from remote locations via fully qualified URLs.
-  ui.cssurl: "./custom/my-styles.css"
-
-  # An optional user-defined banner message that's displayed at the top of every UI page.
-  # Every time this is updated, it will clear a user's localStorage telling the UI to hide the banner forever.
-  ui.bannercontent: "Hello there!"
-  # Optional link for banner. If set, the entire banner text will become a link.
-  # You can have bannercontent without a bannerurl, but not the other way around.
-  ui.bannerurl: "https://argoproj.github.io"

docs/operator-manual/argocd-rbac-cm.yaml

@@ -1,30 +0,0 @@
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: argocd-rbac-cm
-  namespace: argocd
-  labels:
-    app.kubernetes.io/name: argocd-rbac-cm
-    app.kubernetes.io/part-of: argocd
-data:
-  # policy.csv is an file containing user-defined RBAC policies and role definitions (optional).
-  # Policy rules are in the form:
-  #   p, subject, resource, action, object, effect
-  # Role definitions and bindings are in the form:
-  #   g, subject, inherited-subject
-  # See https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/rbac.md for additional information.
-  policy.csv: |
-    # Grant all members of the group 'my-org:team-alpha; the ability to sync apps in 'my-project'
-    p, my-org:team-alpha, applications, sync, my-project/*, allow
-    # Grant all members of 'my-org:team-beta' admins
-    g, my-org:team-beta, role:admin
-
-  # policy.default is the name of the default role which Argo CD will falls back to, when
-  # authorizing API requests (optional). If omitted or empty, users may be still be able to login,
-  # but will see no apps, projects, etc...
-  policy.default: role:readonly
-
-  # scopes controls which OIDC scopes to examine during rbac enforcement (in addition to `sub` scope).
-  # If omitted, defaults to: '[groups]'. The scope value can be a string, or a list of strings.
-  scopes: '[cognito:groups, email]'
-

docs/operator-manual/argocd-secret.yaml

@@ -1,43 +0,0 @@
-apiVersion: v1
-kind: Secret
-metadata:
-  name: argocd-secret
-  namespace: argocd
-  labels:
-    app.kubernetes.io/name: argocd-secret
-    app.kubernetes.io/part-of: argocd
-type: Opaque
-data:
-  # TLS certificate and private key for API server (required).
-  # Autogenerated with a self-signed certificate when keys are missing or invalid.
-  tls.crt:
-  tls.key:
-
-  # bcrypt hash of the admin password and its last modified time (required).
-  # Autogenerated to be the name of the argocd-server pod when missing.
-  admin.password:
-  admin.passwordMtime:
-
-  # random server signature key for session validation (required).
-  # Autogenerated when missing.
-  server.secretkey:
-
-  # Shared secrets for authenticating GitHub, GitLab, BitBucket webhook events (optional).
-  # See https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/webhook.md for additional details.
-  # github webhook secret
-  webhook.github.secret: shhhh! it's a github secret
-  # gitlab webhook secret
-  webhook.gitlab.secret: shhhh! it's a gitlab secret
-  # bitbucket webhook secret
-  webhook.bitbucket.uuid: your-bitbucket-uuid
-  # bitbucket server webhook secret
-  webhook.bitbucketserver.secret: shhhh! it's a bitbucket server secret
-  # gogs server webhook secret
-  webhook.gogs.secret: shhhh! it's a gogs server secret
-
-  # an additional user password and its last modified time (see user definition in argocd-cm.yaml)
-  accounts.alice.password:
-  accounts.alice.passwordMtime:
-  # list of generated account tokens/api keys
-  accounts.alice.tokens: |
-    [{"id":"123","iat":1583789194,"exp":1583789194}]