Docs-V1 (UserGuide): Add /managing-application root files

docs/content/en/docs-v1.0.x/user-guide/managing-application/adding-an-application.md

@@ -0,0 +1,94 @@
+---
+title: "Adding an application"
+linkTitle: "Adding an application"
+weight: 1
+description: >
+  This page describes how to add a new application.
+---
+
+An application is a collection of resources and configurations that are managed together.
+It represents the service which you are going to deploy. With PipeCD, all the application manifests and its application configuration (`app.pipecd.yaml`) must be committed into a directory of a Git repository. That directory is called as application directory.
+
+Each application is managed by exactly one `piped` instance. However, a single `piped` can manage multiple applications.
+
+Starting PipeCD V1, you can deploy virtually any application on your desired platform using plugins. See more about plugins. Currently, the PipeCD maintainers team maintains plugins for Kubernetes and Terraform.
+
+## Preparing the application configuration file
+
+You have to **prepare a configuration file** which contains your application configuration and store that file in the Git repository which your Piped is watching first to enable adding a new application this way.
+
+The application configuration file name must be suffixed by `.pipecd.yaml` because Piped periodically checks for files with this suffix.
+
+> Note: Make sure that your Application Repository is listed in your `piped` configuration file. See the [`piped` configuration reference](../managing-piped/configuration-reference/#gitrepository:~:text=No-,repositories,-%5B%5DRepository) for more details.
+
+{{< tabpane >}}
+{{< tab lang="yaml" header="Kubernetes Application" >}}
+# For application's configuration in detail for a Kubernetes Application, please visit
+# https://pipecd.dev/docs/user-guide/managing-application/defining-app-configuration/kubernetes/
+
+apiVersion: pipecd.dev/v1beta1
+kind: Application
+spec:
+  name: foo
+  labels:
+    team: bar
+{{< /tab >}}
+{{< tab lang="yaml" header="Terraform Application" >}}
+
+# For application's configuration in detail for Terraform Application, please visit
+# https://pipecd.dev/docs/user-guide/managing-application/defining-app-configuration/terraform/
+
+apiVersion: pipecd.dev/v1beta1
+kind: Application
+spec:
+  name: foo
+  labels:
+    team: bar
+{{< /tab >}}
+{{< /tabpane >}}
+
+## Registering your application
+
+Before deploying an application, it must be registered to help PipeCD know:
+
+- where the application configuration is placed
+- which `piped` should handle it and which platform the application should be deployed to.
+
+You can register a new application from the web console (aka the Control Plane) by picking from a list of unused apps suggested by `pipeds` while scanning the git repositories connected to it.
+
+You can also use the `pipectl` command-line tool to confiure your application in the Control Plane. See adding a new application using [`pipectl`](../../command-line-tool/#adding-a-new-application).
+
+>**NOTE:**
+>Manually configuring the application on the Control Plane is not supported for PipeCD v1 deployments (deployment using plugins) as of now. We are working on this feature.
+
+<!-- To define your application deployment pipeline which contains the guideline to show Piped how to deploy your application, please visit [Defining app configuration](../defining-app-configuration/). -->
+
+Go to the PipeCD web console on application list page, click the `+ADD` button at the top left corner of the application list page and then switch to the `PIPED V1 ADD FROM SUGGESTIONS` tab.
+
+Select the Piped that you want to use and the deploy target that you want to deploy to. If you have configured your `piped` configuration file and the Application Repository correctly, all the applications in the target repository will be listed in the 'Select application to add' tab. Select the unregistered Applicatiom you want to deploy and click on 'SAVE'. Your application should now be successfully registered.
+
+![Registering an Application from Suggestions: PipeCD v1](/images/add-from-suggestions-v1.png)
+<p style="text-align: center;">
+Registering an Application from Suggestions
+</p>
+
+## Updating an application
+
+The web console supports only enable, disable, and delete operations for your deployment. You cannot modify the application details from the web console (aka Control Plane).
+
+To update your application, edit the `app.pipecd.yaml` file in your Git repository:
+
+```yaml
+apiVersion: pipecd.dev/v1beta1
+kind: Application
+metadata:
+  name: my-app
+spec:
+  name: new-name
+  labels:
+    team: new-team
+```
+
+Commit and push the changes. `Piped` will detect the updates and apply them automatically, according to the configured deployment pipeline.
+
+For all available configuration options, see the [configuration reference](../configuration-reference/).

docs/content/en/docs-v1.0.x/user-guide/managing-application/application-live-state.md

@@ -0,0 +1,19 @@
+---
+title: "Application live state"
+linkTitle: "Application live state"
+weight: 7
+description: >
+  The live states of application components as well as their health status.
+---
+
+By default, `piped` continuously monitors the running resources/components of all deployed applications to determine the state of them and then send those results to the control plane. The application state will be visualized and rendered at the application details page in realtime. That helps developers can see what is running in the cluster as well as their health status. The application state includes:
+
+- visual graph of application resources/components. Each resource/component node includes its metadata and health status.
+- health status of the whole application. Application health status is `HEALTHY` if and only if the health statuses of all of its resources/components are `HEALTHY`.
+
+![A screenshot of the Application Details page on the Control Plane](/images/application-details.png)
+<p style="text-align: center;">
+Application Details Page
+</p>
+
+By clicking on the resource/component node, a popup will be revealed from the right side to show more details about that resource/component.

docs/content/en/docs-v1.0.x/user-guide/managing-application/cancelling-a-deployment.md

@@ -0,0 +1,17 @@
+---
+title: "Cancelling a deployment"
+linkTitle: "Cancelling a deployment"
+weight: 5
+description: >
+  This page describes how to cancel a running deployment.
+---
+
+A running deployment can be cancelled from web UI at the deployment details page.
+
+If the application rollback is enabled in the application configuration, the rollback process will be executed after the cancelling. You can also explicitly specify to rollback after the cancelling or not from the web UI by clicking on `▼` mark on the right side of the `CANCEL` button to select your option.
+
+![A screenshot demonstrating how to cancel a deployment](/images/cancel-deployment.png)
+<p style="text-align: center;">
+Cancel a Deployment from web UI
+</p>
+

docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-drift-detection.md

@@ -0,0 +1,104 @@
+---
+title: "Configuration drift detection"
+linkTitle: "Configuration drift detection"
+weight: 8
+description: >
+  Automatically detecting the configuration drift.
+---
+
+Configuration Drift is a phenomenon where running resources of service become more and more different from the definitions in Git as time goes on, due to manual ad-hoc changes and updates.
+As PipeCD is using Git as a single source of truth, all application resources and infrastructure changes should be done by making a pull request to Git. Whenever a configuration drift occurs it should be notified to the developers and be fixed.
+
+PipeCD includes `Configuration Drift Detection` feature, which periodically compares running resources/configurations with the definitions in Git to detect the configuration drift and shows the comparing result in the application details web page and sends a notifications to the developers as well.
+
+### Detection Result
+
+There are three statuses for the drift detection result: `SYNCED`, `OUT_OF_SYNC`, `DEPLOYING`.
+
+#### SYNCED
+
+This status means no configuration drift was detected. All resources/configurations are synced from the definitions in Git. From the application details page, this status is shown by a green "Synced" mark.
+
+![A screenshot of displaying a 'SNYCED' state](/images/application-synced.png)
+<p style="text-align: center;">
+Application is in SYNCED state
+</p>
+
+#### OUT_OF_SYNC
+
+This status means a configuration drift was detected. An application is in this status when at least one of the following conditions is satisfied:
+
+- at least one resource is defined in Git but NOT running in the cluster
+- at least one resource is NOT defined in Git but running in the cluster
+- at least one resource that is both defined in Git and running in the cluster but NOT in the same configuration
+
+This status is shown by a red "Out of Sync" mark on the application details page.
+
+![Screenshot showing "OUT OF SYNC' resources configuration state](/images/application-out-of-sync.png)
+<p style="text-align: center;">
+Application is in OUT_OF_SYNC state
+</p>
+
+Click on the "SHOW DETAILS" button to see more details about why the application is in the `OUT_OF_SYNC` status. In the below example, the replicas number of a Deployment was not matching, it was `300` in Git but `3` in the cluster.
+
+![](/images/application-out-of-sync-details.png)
+<p style="text-align: center;">
+The details shows why the application is in OUT_OF_SYNC state
+</p>
+
+#### DEPLOYING
+
+This status means the application is deploying and the configuration drift detection is not running a white. Whenever a new deployment of the application was started, the detection process will temporarily be stopped until that deployment finishes and will be continued after that.
+
+### How to enable Configuration Drift Detection?
+
+This feature is automatically enabled for all applications by deafult. 
+
+You can change the checking interval as well as [configure the notification](../../managing-piped/configuring-notifications/) for these events in `piped` configuration.
+
+Note: If you want to trigger deployment automatically when `OUT_OF_SYNC` occurs, see [Trigger configuration](./triggering-a-deployment/#trigger-configuration).
+
+### Ignore drift detection for specific fields
+
+> **Note:** This feature is currently supported only for Kubernetes Applications.
+
+You can also ignore drift detection for specified fields in your application manifests. In other words, even if the selected fields have different values between live state and Git, the application status will not be set to `Out of Sync`.
+
+For example, suppose you have the application's manifest as below:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: simple
+spec:
+  replicas: 2
+  template:
+    spec:
+      containers:
+        - args:
+            - hi
+            - hello
+          image: gcr.io/pipecd/helloworld:v1.0.0
+          name: helloworld
+```
+
+If you want to ignore the drift detection for the two sceans
+
+- pod's replicas
+- `helloworld` container's args
+
+Add the following statements to `app.pipecd.yaml` to ignore diff on those fields.
+
+```yaml
+spec:
+  ...
+  driftDetection:
+    ignoreFields:
+      - apps/v1:Deployment:default:simple#spec.replicas
+      - apps/v1:Deployment:default:simple#spec.template.spec.containers.0.args
+```
+
+Note: The `ignoreFields` is in format `apiVersion:kind:namespace:name#yamlFieldPath`
+
+For more information, see the [configuration reference](./configuration-reference/#driftdetection).

docs/content/en/docs-v1.0.x/user-guide/managing-application/deployment-chain.md

@@ -0,0 +1,62 @@
+---
+title: "Deployment chain"
+linkTitle: "Deployment chain"
+weight: 11
+description: >
+  Specific guide for configuring chain of deployments.
+---
+
+For users who want to use PipeCD to build a complex deployment flow, which contains multiple applications across multiple application kinds and roll them out to multiple clusters gradually or promoting across environments, this page will show you how to use PipeCD to achieve that requirement.
+
+## Configuration
+
+The idea of this feature is to trigger the whole deployment chain when a specified deployment is triggered. To trigger the deployment chain, we need to add a configuration section named `postSync` which contains all configurations that be used when the deployment is triggered. For this `Deployment Chain` feature, configuration for it is under `postSync.chain` section.
+
+A canonical configuration looks as below:
+
+```yaml
+apiVersion: pipecd.dev/v1beta1
+kind: Application
+spec:
+  input:
+    ...
+  pipeline:
+    ...
+  postSync:
+    chain:
+      applications:
+        # Find all applications with name `application-2` and trigger them.
+        - name: application-2
+        # Fill all applications with name `application-3` and trigger them.
+        - name: application-3
+```
+
+As a result, the above configuration will be used to create a deployment chain like the below figure
+
+![Screenshot of deployment chain feature](/images/deployment-chain-figure.png)
+
+In the context of the deployment chain in PipeCD, a chain is made up of many `blocks`, and each block contains multiple `nodes` which is the reference to a deployment. The first block in the chain always contains only one node, which is the deployment that triggers the whole chain. Other blocks of the chain are built using filters which are configurable via `postSync.chain.applications` section. As for the above example, the second block `Block 2` contains 2 different nodes, which are 2 different PipeCD applications with the same name `application-2`.
+
+__Tip__:
+
+1. If you followed all the configuration references and built your deployment chain configuration, but some deployments in your defined chain are not triggered as you want, please re-check those deployments [`trigger configuration`](../triggering-a-deployment/#trigger-configuration). The `onChain` trigger is __disabled by default__; you need to enable that configuration to enable your deployment to be triggered as a node in the deployment chain.
+2. Values configured under `postSync.chain.applications` - we call it __Application matcher__'s values are merged using `AND` operator. Currently, only `name` and `kind` are supported, but `labels` will also be supported soon.
+
+<!-- See [Examples](../../examples/#deployment-chain) for more specific. -->
+
+## Deployment chain characteristic
+
+Something you need to care about while creating your deployment chain with PipeCD
+
+1. The deployment chain blocks are run in sequence, one by one. But all nodes in the same block are run in parallel, you should ensure that all nodes(deployments) in the same block do not depend on each other.
+2. Once a node in a block has finished with `FAILURE` or `CANCELLED` status, the containing block will be set to fail, and all other nodes which have not yet finished will be set to `CANCELLED` status (those nodes will be rolled back if they're in the middle of its deploying process). Consequently, all blocks after that failed block will be set to `CANCELLED` status and be stopped.
+
+## Console view
+
+![Deployment chain console](/images/deployment-chain-console.png)
+
+The UI for this deployment chain feature currently is under development, we can only __view deployments in chain one by one__ on the deployments page and deployment detail page as usual.
+
+## Reference
+
+See [Configuration Reference](../configuration-reference/#postsync) for the full configuration.

docs/content/en/docs-v1.0.x/user-guide/managing-application/manifest-attachment.md

@@ -0,0 +1,63 @@
+---
+title: "Manifest attachment"
+linkTitle: "Manifest attachment"
+weight: 10
+description: >
+  Attach configuration cross manifest files while deployment.
+---
+
+For insensitive data which needs to be attached/mounted as a configuration of other resources, Kubernetes ConfigMaps is a simple and bright idea. How about the other application kinds, which need something as simple as k8s ConfigMaps? PipeCD has attachment feature for your usecase.
+
+## Configuration
+
+Suppose you have `config.yaml` file which contains
+
+```yaml
+mysql:
+  rootPassword: "test"
+  database: "pipecd"
+```
+
+Then your application configuration will be configured like this
+
+```yaml
+apiVersion: pipecd.dev/v1beta1
+kind: Application
+spec:
+  name: secret-management
+  labels:
+    env: example
+    team: xyz
+  attachment:
+    sources:
+      config: config.yaml
+    targets:
+      - taskdef.yaml
+```
+
+The configuration says that: The file `config.yaml` will be used as an attachment for others, its content will be referred as `config`. The target files, that can use the `config.yaml` file as an attachment, are currently configured to `taskdef.yaml` file.
+
+And in the "target" file, which uses `config.yaml` file content
+
+```yaml
+...
+containerDefinitions:
+  - command: "echo {{ .attachment.config }}"
+    image: nginx:1
+    cpu: 100
+    memory: 100
+    name: web
+...
+```
+
+In all cases, `Piped` will perform attaching the attachment file content at last, right before using it to handle any deployment tasks.
+
+__Tip__:
+
+This feature can be used in combo with PipeCD [SecretManagement feature](../secret-management). You can encrypt your secret data using PipeCD secret encryption function, it will be decrypted and placed in your configuration files; then the PipeCD attachment feature will attach that decrypted configuration to the manifest of resource, which requires that configuration.
+
+See examples for detail.
+
+<!-- ## Examples
+
+- [examples/ecs/attachment](https://github.com/pipe-cd/examples/tree/master/ecs/attachment) -->

docs/content/en/docs-v1.0.x/user-guide/managing-application/rolling-back-a-deployment.md

@@ -0,0 +1,22 @@
+---
+title: "Rolling back a deployment"
+linkTitle: "Rolling back a deployment"
+weight: 6
+description: >
+  This page describes when a deployment is rolled back automatically and how to manually rollback a deployment.
+---
+
+Rolling back a deployment can be automated by enabling the `autoRollback` field in the application configuration of the application. When `autoRollback` is enabled, the deployment will be rolled back if any of the following conditions are met:
+
+- a stage of the deployment pipeline was failed
+- an analysis stage determined that the deployment had a negative impact
+- any error occurs while deploying
+
+When the rolling back process is triggered, a new `ROLLBACK` stage will be added to the deployment pipeline and it reverts all the applied changes.
+
+![Screenshot of rolling back a deployment](/images/rolled-back-deployment.png)
+<p style="text-align: center;">
+Deployment Rollback
+</p>
+
+Alternatively, you can manually roll back a deployment from the web UI by clicking on `Cancel with Rollback` button.