Add description to the examples

docs/content/en/blog/news/pipecd-best-practice-01.md

@@ -29,7 +29,7 @@ At a glance, PipeCD is composed of 2 components, the Control Plane and the Piped
 
 2. Developers from the product team may need to self-install piped into their applications running cluster if the platform team does not manage those credentials.\
 \
-Once the Piped - the runner is installed successfully, developers only need to care about [application configuration](/docs/user-guide/adding-an-application/) - which defines the pipeline so that piped(s) can use them to deploy your applications. Interaction with the applications is mainly done via the PipeCD web console and the configuration files stored on Git.
+Once the Piped - the runner is installed successfully, developers only need to care about [app configuration](/docs/user-guide/adding-an-application/) - which defines the pipeline so that piped(s) can use them to deploy your applications. Interaction with the applications is mainly done via the PipeCD web console and the configuration files stored on Git.
 
 > As an __operator__, PipeCD [control-plane](/docs/operator-manual/control-plane/) and [piped](/docs/operator-manual/piped/)(s) are what you should care about. As a __developer__, you should care about [piped](/docs/operator-manual/piped/) which installed in your applications running cluster and your [applications' PipeCD configurations](/docs/user-guide/adding-an-application/).
 

examples/cloudrun/analysis/app.pipecd.yaml

@@ -27,3 +27,7 @@ spec:
       - name: CLOUDRUN_PROMOTE
         with:
           percent: 100
+  description: |
+    This app demonstrates how to use ANALYSIS stage to analyze the deployment.\
+    After new version has been deployed to receive 10% of traffic, Piped periodically sends http requests to the endpoint of the new version to verify its responses.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/cloudrun/canary/app.pipecd.yaml

@@ -1,4 +1,3 @@
-# Deployment pipeline with canary strategy.
 apiVersion: pipecd.dev/v1beta1
 kind: CloudRunApp
 spec:
@@ -26,3 +25,6 @@ spec:
       - name: CLOUDRUN_PROMOTE
         with:
           percent: 100
+  description: |
+    This app demonstrates how to deploy a Cloud Run application with Canary strategy.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/cloudrun/secret-management/app.pipecd.yaml

@@ -10,3 +10,6 @@ spec:
       key: {ENCRYPTED_DATA_GENERATED_FROM_WEB}
     decryptionTargets:
       - service.yaml
+  description: |
+    This app demonstrates how to use [Secret Management](https://pipecd.dev/docs/user-guide/secret-management/) feature to store an encrypted credential in Git for use by Cloud Run service.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/cloudrun/simple/app.pipecd.yaml

@@ -6,6 +6,6 @@ spec:
     env: example
     team: abc
   description: |
-    An example application that demonstrate how to deploy a Cloud Run application with [Quick Sync](https://pipecd.dev/docs/concepts/#quick-sync) strategy.\
+    This app demonstrates how to deploy a Cloud Run application with [Quick Sync](https://pipecd.dev/docs/concepts/#quick-sync) strategy.\
     No pipeline is specified then in each deployment PipeCD will roll out the new version and switch all traffic to it immediately.\
-    References: [adding an application](https://pipecd.dev/docs/user-guide/adding-an-application/), [application configuration](https://pipecd.dev/docs/user-guide/configuring-deployment/cloudrun/)
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/cloudrun/wait-approval/app.pipecd.yaml

@@ -1,4 +1,3 @@
-# Deployment pipeline that contains a manual approval stage.
 apiVersion: pipecd.dev/v1beta1
 kind: CloudRunApp
 spec:
@@ -27,3 +26,7 @@ spec:
       - event: "*"
         slack:
           - slack-user-id-3  # slack-user-name-3
+  description: |
+    This app demonstrates how to configure a Cloud Run app with a WAIT_APPROVAL stage.\
+    This ensures that all deployments of this app must be approved manually on the web console.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/ecs/simple/app.pipecd.yaml

@@ -13,3 +13,7 @@ spec:
         targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-lb/YYYY
         containerName: web
         containerPort: 80
+  description: |
+    This app demonstrates how to deploy an ECS application with [Quick Sync](https://pipecd.dev/docs/concepts/#quick-sync) strategy.\
+    No pipeline is specified then in each deployment PipeCD will roll out the new version and switch all traffic to it immediately.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/analysis-by-http/app.pipecd.yaml

@@ -21,3 +21,7 @@ spec:
               interval: 1m
       - name: K8S_PRIMARY_ROLLOUT
       - name: K8S_CANARY_CLEAN
+  description: |
+    This app demonstrates how to use ANALYSIS stage to analyze the deployment.\
+    After new version has been deployed to receive 10% of traffic, Piped periodically sends http requests to the endpoint of the new version to verify its responses.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/analysis-by-metrics/app.pipecd.yaml

@@ -14,7 +14,6 @@ spec:
         with:
           duration: 30m
           metrics:
-            # The simplest way to analyze.
             - strategy: THRESHOLD
               provider: my-prometheus
               interval: 5m
@@ -24,11 +23,9 @@ spec:
                 sum by (job) (rate(http_requests_total{status=~"5.*", job="analysis"}[5m]))
                 /
                 sum by (job) (rate(http_requests_total{job="analysis"}[5m]))
-
-            # In case of using AnalysisTemplate
-            - template:
-                name: http_request_duration_99th_quantile
-                appArgs:
-                  job: foo
       - name: K8S_PRIMARY_ROLLOUT
       - name: K8S_CANARY_CLEAN
+  description: |
+    This app demonstrates how to use ANALYSIS stage to analyze the deployment based on its metrics.\
+    After new version has been deployed to receive 20% of traffic, Piped periodically requests the specified query to analyze its metrics data.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/bluegreen/app.pipecd.yaml

@@ -1,4 +1,3 @@
-# Deploy progressively with bluegreen strategy.
 apiVersion: pipecd.dev/v1beta1
 kind: KubernetesApp
 spec:
@@ -28,3 +27,6 @@ spec:
           primary: 100
       # Destroy all workloads of CANARY variant.
       - name: K8S_CANARY_CLEAN
+  description: |
+    This app demonstrates how to deploy a Kubernetes app by BlueGreen strategy without requiring any mesh.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/canary/app.pipecd.yaml

@@ -1,4 +1,3 @@
-# Deploy progressively with canary strategy.
 apiVersion: pipecd.dev/v1beta1
 kind: KubernetesApp
 spec:
@@ -21,3 +20,6 @@ spec:
       - name: K8S_PRIMARY_ROLLOUT
       # Destroy all workloads of CANARY variant.
       - name: K8S_CANARY_CLEAN
+  description: |
+    This app demonstrates how to deploy a Kubernetes app by Canary strategy without requering any mesh.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/helm-local-chart/app.pipecd.yaml

@@ -20,3 +20,6 @@ spec:
       valueFiles:
         - values.yaml
     helmVersion: 3.1.1
+  description: |
+    This app demonstrates how to deploy a Kubernetes app that uses a Helm chart sourced from the same Git repository.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/helm-remote-chart/app.pipecd.yaml

@@ -17,3 +17,6 @@ spec:
         - values.yaml
       releaseName: helm-remote-chart
     helmVersion: 3.1.1
+  description: |
+    This app demonstrates how to deploy a Kubernetes app that uses a Helm chart sourced from a remote HTTP Chart server.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/helm-remote-git-chart/app.pipecd.yaml

@@ -1,5 +1,3 @@
-# Deploy a helm chart sourced from another Git repository
-# without using pipeline.
 apiVersion: pipecd.dev/v1beta1
 kind: KubernetesApp
 spec:
@@ -18,3 +16,6 @@ spec:
         - values.yaml
       releaseName: helm-remote-git-chart
     helmVersion: 3.1.1
+  description: |
+    This app demonstrates how to deploy a Kubernetes app that uses a Helm chart sourced from the same Git repository.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/kustomize-local-base/app.pipecd.yaml

@@ -1,5 +1,3 @@
-# Deploy a kustomize package that just uses the local bases from the same Git repository
-# without using pipeline.
 apiVersion: pipecd.dev/v1beta1
 kind: KubernetesApp
 spec:
@@ -13,3 +11,6 @@ spec:
         - local-modules/kustomize-bases/helloworld/*
   input:
     kustomizeVersion: 3.5.5
+  description: |
+    This app demonstrates how to deploy a Kubernetes app that uses a Kustomize package sourced from the same Git repository.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/kustomize-remote-base/app.pipecd.yaml

@@ -1,5 +1,3 @@
-# Deploy a kustomize package that uses remote bases from other Git repositories
-# without using pipeline.
 apiVersion: pipecd.dev/v1beta1
 kind: KubernetesApp
 spec:
@@ -9,3 +7,6 @@ spec:
     team: product
   input:
     kustomizeVersion: 3.5.5
+  description: |
+    This app demonstrates how to deploy a Kubernetes app that uses a Kustomize package sourced from another Git repository.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/mesh-istio-bluegreen/app.pipecd.yaml

@@ -31,3 +31,6 @@ spec:
     method: istio
     istio:
       host: mesh-istio-bluegreen
+  description: |
+    This app demonstrates how to deploy a Kubernetes app with BlueGreen strategy by using Istio mesh.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/mesh-istio-canary/app.pipecd.yaml

@@ -33,3 +33,6 @@ spec:
     method: istio
     istio:
       host: mesh-istio-canary.default.svc.cluster.local
+  description: |
+    This app demonstrates how to deploy a Kubernetes app with Canary strategy by using Istio mesh.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/secret-management/app.pipecd.yaml

@@ -14,3 +14,6 @@ spec:
       password: {ENCRYPTED_DATA_GENERATED_FROM_WEB}
     decryptionTargets:
       - secret.yaml
+  description: |
+    This app demonstrates how to use [Secret Management](https://pipecd.dev/docs/user-guide/secret-management/) feature to store an encrypted credential in Git for embed in a Kubernetes manifest.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/simple/app.pipecd.yaml

@@ -11,6 +11,6 @@ spec:
       - service.yaml
     kubectlVersion: 1.18.5
   description: |
-    An example application that demonstrate how to deploy a Kubernetes application with [Quick Sync](https://pipecd.dev/docs/concepts/#quick-sync) strategy.\
+    This app demonstrates how to deploy a Kubernetes application with [Quick Sync](https://pipecd.dev/docs/concepts/#quick-sync) strategy.\
     No pipeline is specified then in each deployment PipeCD will roll out the new version and switch all traffic to it immediately.\
-    References: [adding an application](https://pipecd.dev/docs/user-guide/adding-an-application/), [application configuration](https://pipecd.dev/docs/user-guide/configuring-deployment/kubernetes/)
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/kubernetes/wait-approval/app.pipecd.yaml

@@ -1,5 +1,3 @@
-# This deployment has an Approval stage to wait until got
-# an approval from one of the specified approvers.
 apiVersion: pipecd.dev/v1beta1
 kind: KubernetesApp
 spec:
@@ -28,3 +26,7 @@ spec:
       - event: "*"
         slack:
           - slack-user-id-3  # slack-user-name-3
+  description: |
+    This app demonstrates how to configure a Kubernetes app with a WAIT_APPROVAL stage.\
+    This ensures that all deployments of this app must be approved manually on the web console.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/lambda/simple/app.pipecd.yaml

@@ -1,9 +1,11 @@
-# Quick sync by rolling out the new version and switching all traffic to it.
-# https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html
 apiVersion: pipecd.dev/v1beta1
 kind: LambdaApp
 spec:
   name: simple
   labels:
     env: example
     team: abc
+  description: |
+    This app demonstrates how to deploy a Lambda application with [Quick Sync](https://pipecd.dev/docs/concepts/#quick-sync) strategy.\
+    No pipeline is specified then in each deployment PipeCD will roll out the new version and switch all traffic to it immediately.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/terraform/autorollback/app.pipecd.yaml

@@ -1,4 +1,3 @@
-# Automatically applies when any changes were detected.
 apiVersion: pipecd.dev/v1beta1
 kind: TerraformApp
 spec:
@@ -13,3 +12,7 @@ spec:
       serviceAccount: {ENCRYPTED_DATA_GENERATED_FROM_WEB}
     decryptionTargets:
       - .credentials/service-account.json
+  description: |
+    This app demonstrates how to enable auto-rollback feature for a Terraform application.\
+    Once `spec.input.autoRollback` is enabled application will be rolled back to previous version if any error occurs.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/terraform/local-module/app.pipecd.yaml

@@ -6,3 +6,6 @@ spec:
   labels:
     env: example
     team: infra
+  description: |
+    This app demonstrates how to use a local terraform module which is placed in the same Git repository.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/terraform/remote-module/app.pipecd.yaml

@@ -1,8 +1,10 @@
-# Deploy application that using remote terraform modules from other Git repositories.
 apiVersion: pipecd.dev/v1beta1
 kind: TerraformApp
 spec:
   name: remote-module
   labels:
     env: example
     team: infra
+  description: |
+    This app demonstrates how to use a remote terraform module which can be fetched from another Git repository.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/terraform/secret-management/app.pipecd.yaml

@@ -10,3 +10,6 @@ spec:
       serviceAccount: {ENCRYPTED_DATA_GENERATED_FROM_WEB}
     decryptionTargets:
       - .credentials/service-account.json
+  description: |
+    This app demonstrates how to use [Secret Management](https://pipecd.dev/docs/user-guide/secret-management/) feature to store an encrypted credential in Git for use by Terraform code.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/terraform/simple/app.pipecd.yaml

@@ -1,4 +1,3 @@
-# Automatically applies when any changes were detected.
 apiVersion: pipecd.dev/v1beta1
 kind: TerraformApp
 spec:
@@ -7,9 +6,13 @@ spec:
     env: example
     team: infra
   input:
-    terraformVersion: 1.0.10
+    terraformVersion: 1.1.6
   encryption:
     encryptedSecrets:
       serviceAccount: {ENCRYPTED_DATA_GENERATED_FROM_WEB}
     decryptionTargets:
       - .credentials/service-account.json
+  description: |
+    This app demonstrates how to deploy a Terraform application with [Quick Sync](https://pipecd.dev/docs/concepts/#quick-sync) strategy.\
+    No pipeline is specified then in each deployment PipeCD does terraform plan and if there are any changes detected it applies those changes automatically.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)

examples/terraform/wait-approval/app.pipecd.yaml

@@ -1,4 +1,3 @@
-# Deployment pipeline that contains a manual approval stage.
 apiVersion: pipecd.dev/v1beta1
 kind: TerraformApp
 spec:
@@ -8,7 +7,7 @@ spec:
     team: infra
   input:
     workspace: dev
-    terraformVersion: 1.0.10
+    terraformVersion: 1.1.6
   pipeline:
     stages:
       - name: TERRAFORM_PLAN
@@ -29,3 +28,6 @@ spec:
       - event: "*"
         slack:
           - slack-user-id-3  # slack-user-name-3
+  description: |
+    This app demonstrates how to add use WAIT_APPROVAL stage to require a manual approval before applying.\
+    References: [adding a new app](https://pipecd.dev/docs/user-guide/adding-an-application/), [app configuration](https://pipecd.dev/docs/user-guide/configuration-reference/)