Refresh docs

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.