diff --git a/docs/content/en/docs-dev/user-guide/configuration-reference.md b/docs/content/en/docs-dev/user-guide/configuration-reference.md index c0ac6f9103..e8e9184848 100644 --- a/docs/content/en/docs-dev/user-guide/configuration-reference.md +++ b/docs/content/en/docs-dev/user-guide/configuration-reference.md @@ -20,8 +20,8 @@ spec: | Field | Type | Description | Required | |-|-|-|-| | input | [KubernetesDeploymentInput](#kubernetesdeploymentinput) | Input for Kubernetes deployment such as kubectl version, helm version, manifests filter... | No | -| planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | | trigger | [DeploymentTrigger](#deploymenttrigger) | Configuration for trigger used to determine should we trigger a new deployment or not. | No | +| planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | | commitMatcher | [CommitMatcher](#commitmatcher) | Forcibly use QuickSync or Pipeline when commit message matched the specified pattern. | No | | quickSync | [KubernetesQuickSync](#kubernetesquicksync) | Configuration for quick sync. | No | | pipeline | [Pipeline](#pipeline) | Pipeline for deploying progressively. | No | @@ -47,8 +47,8 @@ spec: | Field | Type | Description | Required | |-|-|-|-| | input | [TerraformDeploymentInput](#terraformdeploymentinput) | Input for Terraform deployment such as terraform version, workspace... | No | -| planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | | trigger | [DeploymentTrigger](#deploymenttrigger) | Configuration for trigger used to determine should we trigger a new deployment or not. | No | +| planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | | quickSync | [TerraformQuickSync](#terraformquicksync) | Configuration for quick sync. | No | | pipeline | [Pipeline](#pipeline) | Pipeline for deploying progressively. | No | | triggerPaths | []string | List of directories or files where their changes will trigger the deployment. Regular expression can be used. This field is `deprecated`, please use [`spec.trigger.onCommit.paths`](#deploymenttrigger) instead. | No | @@ -70,8 +70,8 @@ spec: | Field | Type | Description | Required | |-|-|-|-| | input | [CloudRunDeploymentInput](#cloudrundeploymentinput) | Input for CloudRun deployment such as docker image... | No | -| planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | | trigger | [DeploymentTrigger](#deploymenttrigger) | Configuration for trigger used to determine should we trigger a new deployment or not. | No | +| planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | | quickSync | [CloudRunQuickSync](#cloudrunquicksync) | Configuration for quick sync. | No | | pipeline | [Pipeline](#pipeline) | Pipeline for deploying progressively. | No | | triggerPaths | []string | List of directories or files where their changes will trigger the deployment. Regular expression can be used. This field is `deprecated`, please use [`spec.trigger.onCommit.paths`](#deploymenttrigger) instead. | No | @@ -91,8 +91,8 @@ spec: | Field | Type | Description | Required | |-|-|-|-| -| planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | | trigger | [DeploymentTrigger](#deploymenttrigger) | Configuration for trigger used to determine should we trigger a new deployment or not. | No | +| planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | | quickSync | [LambdaQuickSync](#lambdaquicksync) | Configuration for quick sync. | No | | pipeline | [Pipeline](#pipeline) | Pipeline for deploying progressively. | No | | triggerPaths | []string | List of directories or files where their changes will trigger the deployment. Regular expression can be used. This field is `deprecated`, please use [`spec.trigger.onCommit.paths`](#deploymenttrigger) instead. | No | @@ -113,9 +113,9 @@ spec: | Field | Type | Description | Required | |-|-|-|-| +| trigger | [DeploymentTrigger](#deploymenttrigger) | Configuration for trigger used to determine should we trigger a new deployment or not. | No | | input | [ECSDeploymentInput](#ecsdeploymentinput) | Input for ECS deployment such as TaskDefinition, Service... | Yes | | planner | [DeploymentPlanner](#deploymentplanner) | Configuration for planner used while planning deployment. | No | -| trigger | [DeploymentTrigger](#deploymenttrigger) | Configuration for trigger used to determine should we trigger a new deployment or not. | No | | quickSync | [ECSQuickSync](#ecsquicksync) | Configuration for quick sync. | No | | pipeline | [Pipeline](#pipeline) | Pipeline for deploying progressively. | No | | triggerPaths | []string | List of directories or files where their changes will trigger the deployment. Regular expression can be used. This field is `deprecated`, please use [`spec.trigger.onCommit.paths`](#deploymenttrigger) instead. | No | @@ -194,14 +194,29 @@ One of `yamlField` or `regex` is required. | Field | Type | Description | Required | |-|-|-|-| -| onCommit | [OnCommitConfiguration](#oncommitconfiguration) | Configuration controls how trigger handles deployment in case of some changes found in Git source. | No | +| onCommit | [OnCommit](#oncommit) | Controls triggering new deployment when new Git commits touched the application. | No | +| onCommand | [OnCommand](#oncommand) | Controls triggering new deployment when received a new `SYNC` command. | No | +| onOutOfSync | [OnOutOfSync](#onoutofsync) | Controls triggering new deployment when application is at `OUT_OF_SYNC` state. | No | + +## OnCommit + +| Field | Type | Description | Required | +|-|-|-|-| +| disabled | bool | Whether to exclude application from triggering target when new Git commits touched it. Default is `false`. | No | +| paths | []string | List of directories or files where any changes of them will be considered as touching the application. Regular expression can be used. Empty means watching all changes under the application directory. | No | + +## OnCommand + +| Field | Type | Description | Required | +|-|-|-|-| +| disabled | bool | Whether to exclude application from triggering target when received a new `SYNC` command. Default is `false`. | No | -## OnCommitConfiguration +## OnOutOfSync | Field | Type | Description | Required | |-|-|-|-| -| disabled | bool | Disable trigger a new deployment in case of some changes found in Git source or not. Default is `false`. | No | -| paths | []string | List of directories or files where their changes will trigger the deployment. Regular expression can be used. No value provided means watch all changes under the application directory. | No | +| disabled | bool | Whether to exclude application from triggering target when application is at `OUT_OF_SYNC` state. Default is `true`. | No | +| minWindow | duration | Minimum amount of time must be elapsed since the last deployment. This can be used to avoid triggering unnecessary continuous deployments based on `OUT_OF_SYNC` status. Default is `5m`. | No | ## Pipeline diff --git a/docs/content/en/docs-dev/user-guide/triggering-a-deployment.md b/docs/content/en/docs-dev/user-guide/triggering-a-deployment.md index 3e3932b307..01da6c66a6 100644 --- a/docs/content/en/docs-dev/user-guide/triggering-a-deployment.md +++ b/docs/content/en/docs-dev/user-guide/triggering-a-deployment.md @@ -6,24 +6,22 @@ description: > This page describes when a deployment is triggered automatically and how to manually trigger a deployment. --- -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. -The mission of the deployments is syncing all running resources/components of applications in the cluster to the state specified in the newest commit. -So by default, when a new merged pull request touches an application, a new deployment for that application will be triggered to sync the application to the state specified in the newest merged commit. +PipeCD uses Git as a single source of truth; all application resources are defined declaratively and immutably in Git. Whenever a developer wants to update the application or infrastructure, they will send a pull request to that Git repository to propose the change. The state defined in Git is the desired state for the application and infrastructure running in the cluster. -A pull request (commit) is considered as touching an application whenever its changes include: -- one or more files inside the application directory -- one or more files inside one of the [dependencies](/docs/user-guide/configuration-reference/#kubernetesdeploymentinput) of the application +PipeCD applies the proposed changes to running resources in the cluster by triggering needed deployments for applications. The deployment mission is syncing all running resources of the application in the cluster to the state specified in the newest commit in Git. + +By default, when a new merged pull request touches an application, a new deployment for that application will be triggered to execute the sync process. But users can configure the application to control when a new deployment should be triggered or not. For example, using [`onOutOfSync`](/docs/user-guide/configuration-reference/#deploymenttrigger) to enable the ability to attempt to resolve `OUT_OF_SYNC` state whenever a configuration drift has been detected. After a new deployment was triggered, it will be queued to handle by the appropriate `piped`. And at this time the deployment pipeline was not decided yet. `piped` schedules all deployments of applications to ensure that for each application only one deployment will be executed at the same time. -When no deployment of an application is running, `piped` picks one queueing deployment for that application to plan the deploying pipeline. +When no deployment of an application is running, `piped` picks queueing one to plan the deploying pipeline. `piped` plans the deploying pipeline based on the deployment configuration and the diff between the running state and the specified state in the newest commit. For example: - when the merged pull request updated a Deployment's container image or updated a mounting ConfigMap or Secret, `piped` planner will decide that the deployment should use the specified pipeline to do a progressive deployment. - when the merged pull request just updated the `replicas` number, `piped` planner will decide to use a quick sync to scale the resources. -You can force `piped` planner to decide to use the [QuickSync](docs/concepts/#quick-sync) or the specified pipeline based on the commit message by configuring [CommitMatcher](/docs/user-guide/configuration-reference/#commitmatcher) in the deployment configuration. +You can force `piped` planner to decide to use the [QuickSync](/docs/concepts/#quick-sync) or the specified pipeline based on the commit message by configuring [CommitMatcher](/docs/user-guide/configuration-reference/#commitmatcher) in the deployment configuration. After being planned, the deployment will be executed as the decided pipeline. The deployment execution including the state of each stage as well as their logs can be viewed in realtime at the deployment details page.