+Registering an Application from Suggestions +
+ +## 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/). diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/application-live-state.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/application-live-state.md new file mode 100644 index 0000000000..5277a86b80 --- /dev/null +++ b/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`. + + ++Application Details Page +
+ +By clicking on the resource/component node, a popup will be revealed from the right side to show more details about that resource/component. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/cancelling-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/cancelling-a-deployment.md new file mode 100644 index 0000000000..1112f1be52 --- /dev/null +++ b/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. + + ++Cancel a Deployment from web UI +
+ diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-drift-detection.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-drift-detection.md new file mode 100644 index 0000000000..db7a34b998 --- /dev/null +++ b/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. + + ++Application is in SYNCED state +
+ +#### 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. + + ++Application is in OUT_OF_SYNC state +
+ +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. + + ++The details shows why the application is in OUT_OF_SYNC state +
+ +#### 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). diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/deployment-chain.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/deployment-chain.md new file mode 100644 index 0000000000..58ba2c0418 --- /dev/null +++ b/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 + + + +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. + + + +## 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 + + + +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. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/manifest-attachment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/manifest-attachment.md new file mode 100644 index 0000000000..ea823384d3 --- /dev/null +++ b/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. + + diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/rolling-back-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/rolling-back-a-deployment.md new file mode 100644 index 0000000000..c284592e8b --- /dev/null +++ b/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. + + ++Deployment Rollback +
+ +Alternatively, you can manually roll back a deployment from the web UI by clicking on `Cancel with Rollback` button. diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/secret-management.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/secret-management.md new file mode 100755 index 0000000000..724fdef99e --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/secret-management.md @@ -0,0 +1,123 @@ +--- +title: "Secret management" +linkTitle: "Secret management" +weight: 9 +description: > + Storing secrets safely in the Git repository. +--- + +When doing GitOps, user wants to use Git as a single source of truth. But storing credentials like Kubernetes Secret or Terraform's credentials directly in Git is not safe. + +This feature helps you keep that sensitive information safely in Git, right next to your application manifests. + +The basic flow will look like this: + +- user encrypts their secret data via the PipeCD's Web UI and stores the encrypted data in Git +- `Piped` decrypts them before doing deployment tasks + +## Prerequisites + +Before using this feature, `Piped` needs to be started with a key pair for secret encryption. + +You can use the following command to generate a key pair: + +``` console +openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key +openssl pkey -in private-key -pubout -out public-key +``` + +Then specify them while [installing](../../../installation/install-piped/installing-on-kubernetes) the `Piped` with these options: + +``` console +--set-file secret.data.secret-public-key=PATH_TO_PUBLIC_KEY_FILE \ +--set-file secret.data.secret-private-key=PATH_TO_PRIVATE_KEY_FILE +``` + +Finally, enable this feature in Piped configuration file with `secretManagement` field as below: + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + pipedID: your-piped-id + ... + secretManagement: + type: KEY_PAIR + config: + privateKeyFile: /etc/piped-secret/secret-private-key + publicKeyFile: /etc/piped-secret/secret-public-key +``` + +## Encrypting secret data + +In order to encrypt the secret data, navigate to the Applications page and click the “Encrypt Secret“ button located in the top-left corner. Then, select a piped from the dropdown list, after that enter your secret data, and click the “ENCRYPT“ button. +The encrypted data should be shown for you. Copy it to store in Git. + + ++Applications page +
+ ++The form for encrypting secret data +
+ +## Storing encrypted secrets in Git + +To make encrypted secrets available to an application, they must be specified in the application configuration file of that application. + +- `encryptedSecrets` contains a list of the encrypted secrets. +- `decryptionTargets` contains a list of files that are using one of the encrypted secrets and should be decrypted by `Piped`. + +``` yaml +apiVersion: pipecd.dev/v1beta1 +# One of Piped defined app, for example: using the Kubernetes plugin +kind: Application +spec: + encryption: + encryptedSecrets: + password: encrypted-data + decryptionTargets: + - secret.yaml +``` + +## Accessing encrypted secrets + +Any file in the application directory can use `.encryptedSecrets` context to access secrets you have encrypted and stored in the application configuration. + +For example, + +- Accessing by a Kubernets Secret manfiest + +``` yaml +apiVersion: v1 +kind: Secret +metadata: + name: simple-sealed-secret +data: + password: "{{ .encryptedSecrets.password }}" +``` + +- Configuring ENV variable of a Lambda function to use a encrypted secret + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: LambdaFunction +spec: + name: HelloFunction + environments: + KEY: "{{ .encryptedSecrets.key }}" +``` + +In all cases, `Piped` will decrypt the encrypted secrets and render the decryption target files before using to handle any deployment tasks. + + diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md new file mode 100644 index 0000000000..783e07965f --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md @@ -0,0 +1,51 @@ +--- +title: "Triggering a deployment" +linkTitle: "Triggering a deployment" +weight: 4 +description: > + This page describes when a deployment is triggered automatically and how to manually trigger a deployment. +--- + +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. + +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`](#trigger-configuration) to enable the ability to attempt to resolve `OUT_OF_SYNC` state whenever a configuration drift has been detected. + +### Trigger configuration + +Configuration for the trigger used to determine whether we trigger a new deployment. There are several configurable types: + +- `onCommit`: Controls triggering new deployment when new Git commits touched the application. +- `onCommand`: Controls triggering new deployment when received a new `SYNC` command. +- `onOutOfSync`: Controls triggering new deployment when application is at `OUT_OF_SYNC` state. +- `onChain`: Controls triggering new deployment when the application is counted as a node of some chains. + +See [Configuration Reference](../../configuration-reference/#deploymenttrigger) for the full configuration. + +After a new deployment was triggered, it will be queued to be handled 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 queueing one to plan the deploying pipeline. +`piped` plans the deploying pipeline based on the application 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](../../../concepts/#sync-strategy) or the specified pipeline based on the commit message by configuring [CommitMatcher](../../configuration-reference/#commitmatcher) in the application 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. + + ++A Running Deployment at the Deployment Details Page +
+ +As explained above, by default all deployments will be triggered automatically by checking the merged commits but you also can manually trigger a new deployment from web UI. + +By clicking on `SYNC` button at the application details page, a new deployment for that application will be triggered to sync the application to be the state specified at the newest commit of the master branch (default branch). + + ++Application Details Page +
diff --git a/docs/static/images/add-from-suggestions-v1.png b/docs/static/images/add-from-suggestions-v1.png new file mode 100644 index 0000000000..48e5d785da Binary files /dev/null and b/docs/static/images/add-from-suggestions-v1.png differ