PipeCD – Managing application

Docs-V0.56.x: Adding an application

Mon, 01 Jan 0001 00:00:00 +0000

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 application’s 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 can be handled by one and only one piped. Currently, PipeCD is supporting 5 kinds of application: Kubernetes, Terraform, CloudRun, Lambda, ECS.

Note: Be sure your application manifests repository is listed in Piped managing repositories configuration.

Before deploying an application, it must be registered to help PipeCD knows

where the application configuration is placed
which piped should handle it and which platform the application should be deployed to

Through the web console, you can register a new application in one of the following ways:

Picking from a list of unused apps suggested by Pipeds while scanning Git repositories (Recommended)
Manually configuring application information

(If you prefer to use pipectl command-line tool, see its usage for the details.)

Picking from a list of unused apps suggested by Pipeds

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.

# For application's configuration in detail for KubernetesApp, please visit
# https://pipecd.dev/docs/user-guide/managing-application/defining-app-configuration/kubernetes/

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: foo
  labels:
    team: bar

# For application's configuration in detail for TerraformApp, please visit
# https://pipecd.dev/docs/user-guide/managing-application/defining-app-configuration/terraform/

apiVersion: pipecd.dev/v1beta1
kind: TerraformApp
spec:
  name: foo
  labels:
    team: bar

# For application's configuration in detail for LambdaApp, please visit
# https://pipecd.dev/docs/user-guide/managing-application/defining-app-configuration/lambda/

apiVersion: pipecd.dev/v1beta1
kind: LambdaApp
spec:
  name: foo
  labels:
    team: bar

# For application's configuration in detail for CloudRunApp, please visit
# https://pipecd.dev/docs/user-guide/managing-application/defining-app-configuration/cloudrun/

apiVersion: pipecd.dev/v1beta1
kind: CloudRunApp
spec:
  name: foo
  labels:
    team: bar

# For application's configuration in detail for ECSApp, please visit
# https://pipecd.dev/docs/user-guide/managing-application/defining-app-configuration/ecs/

apiVersion: pipecd.dev/v1beta1
kind: ECSApp
spec:
  name: foo
  labels:
    team: bar

To define your application deployment pipeline which contains the guideline to show Piped how to deploy your application, please visit 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 go to the ADD FROM GIT tab.

Select the Piped and Platform Provider that you deploy to, once the Piped that’s watching your Git repository catches the new unregistered application configuration file, it will be listed up in this panel. Click ADD to complete the registration.

Manually configuring application information

This way, you can postpone the preparation for your application’s configuration after submitting all the necessary information about your app on the web console.

By clicking on +ADD button at the application list page, a popup will be revealed from the right side as below:

After filling all the required fields, click Save button to complete the application registering.

Here are the list of fields in the register form:

Field	Description	Required
Name	The application name	Yes
Kind	The application kind. Select one of these values: `Kubernetes`, `Terraform`, `CloudRun`, `Lambda` and `ECS`.	Yes
Piped	The piped that handles this application. Select one of the registered `piped`s at `Settings/Piped` page.	Yes
Repository	The Git repository contains application configuration and application configuration. Select one of the registered repositories in `piped` configuration.	Yes
Path	The relative path from the root of the Git repository to the directory containing application configuration and application configuration. Use `./` means repository root.	Yes
Config Filename	The name of application configuration file. Default is `app.pipecd.yaml`.	No
Platform Provider	Where the application will be deployed to. Select one of the registered cloud/platform providers in `piped` configuration. This field name previously was `Cloud Provider`.	Yes

Note: Labels couldn’t be set via this form. If you want, try the way to register via the application configuration defined in the Git repository.

After submitting the form, one more step left is adding the application configuration file for that application into the application directory in Git repository same as we prepared in the above method.

Please refer Define your app’s configuration or pipecd/examples for the examples of being supported application kind.

Updating an application

Regardless of which method you used to register the application, the web console can only be used to disable/enable/delete the application, besides the adding operation. All updates on application information must be done via the application configuration file stored in Git as a single source of truth.

apiVersion: pipecd.dev/v1beta1
kind: AppKind
spec:
  name: new-name
  labels:
    team: new-team

Refer to configuration reference to see the full list of configurable fields.

Docs-V0.56.x: Defining application's configuration

Mon, 01 Jan 0001 00:00:00 +0000

In the previous section, we knew that each PipeCD application requires a configuration file (we call it the application configuration file) that contains the application’s information (such as name, label, etc) and also defines how should Piped deploy that application. In this section, we will show you how to define a deployment pipeline like that for each kind of PipeCD supporting application.

Docs-V0.56.x: Customizing application's deployment pipeline

Mon, 01 Jan 0001 00:00:00 +0000

In the previous section, we knew how to use PipeCD supporting application kind’s stages to build up a pipeline that defines how Piped should deploy your application. In this section, aside from the application kind specified stages, we will talk about some commonly defined pipeline stages, which can be used to build up a more fashionable deployment pipeline for your application.

Example deployment with a WAIT stage

Docs-V0.56.x: Triggering a deployment

Mon, 01 Jan 0001 00:00:00 +0000

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 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 for the full configuration.

After a new deployment is triggered, it will be queued to be handled by the appropriate piped. At this time, the deployment pipeline has not been 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 a queued 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 or the specified pipeline based on the commit message by configuring 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 real time on 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

Docs-V0.56.x: Cancelling a deployment

Mon, 01 Jan 0001 00:00:00 +0000

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 cancellation. You can also explicitly specify whether to rollback after the cancellation 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

Docs-V0.56.x: Rolling back a deployment

Mon, 01 Jan 0001 00:00:00 +0000

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 has 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.

A deployment was rolled back

Alternatively, manually rolling back a running deployment can be done from web UI by clicking on Cancel with rollback button.

Docs-V0.56.x: Application live state

Mon, 01 Jan 0001 00:00:00 +0000

By default, piped continuously monitors the running resources/components of all deployed applications to determine their state and then sends those results to the control plane. The application state will be visualized and rendered on the application details page in real time. This helps developers 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.

Docs-V0.56.x: Configuration drift detection

Mon, 01 Jan 0001 00:00:00 +0000

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 as well as sends the notifications to the developers.

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 for a while. Whenever a new deployment of the application is started, the detection process will temporarily be stopped until that deployment finishes and will be continued after that.

How to enable

This feature is automatically enabled for all applications.

You can change the checking interval as well as configure the notification for these events in piped configuration.

Note: If you want to trigger deployment automatically when OUT_OF_SYNC occurs, see Trigger configuration.

Ignore drift detection for specific fields

Note: This feature is currently supported for only Kubernetes application.

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

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.

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.

Docs-V0.56.x: Secret management

Mon, 01 Jan 0001 00:00:00 +0000

When doing GitOps, users want 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.

Basically, the 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:

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 the Piped with these options:

--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:

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.

apiVersion: pipecd.dev/v1beta1
# One of Piped defined app kind such as: KubernetesApp
kind: {APPLICATION_KIND}
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 Kubernetes Secret manifest

apiVersion: v1
kind: Secret
metadata:
  name: simple-sealed-secret
data:
  password: "{{ .encryptedSecrets.password }}"

Configuring ENV variable of a Lambda function to use an encrypted secret

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 them to handle any deployment tasks.

Examples

Docs-V0.56.x: Manifest attachment

Mon, 01 Jan 0001 00:00:00 +0000

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

mysql:
  rootPassword: "test"
  database: "pipecd"

Then your application configuration will be configured like this

apiVersion: pipecd.dev/v1beta1
kind: ECSApp
spec:
  name: secret-management
  labels:
    env: example
    team: xyz
  input:
    ...
  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

...
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. 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

Docs-V0.56.x: Deployment chain

Mon, 01 Jan 0001 00:00:00 +0000

For users who want to use PipeCD to build a complex deployment flow, which contains multiple applications across multiple application kinds and roll out them to multiple clusters gradually or promoting across environments, this guideline 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 enable 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:

apiVersion: pipecd.dev/v1beta1
kind: TerraformApp
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` of kind `KUBERNETES`
        # and trigger them.
        - name: application-3
          kind: KUBERNETES

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:

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. 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.
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 for more specific.

Deployment chain characteristic

Something you need to be aware of while creating your deployment chain with PipeCD:

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.
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 their 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 for the full configuration.