PipeCD – Welcome to PipeCD

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

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

Component Architecture

The control plane is a centralized part of PipeCD. It contains several services as below to manage the application, deployment data and handle all requests from pipeds and web clients:

Server

server handles all incoming gRPC requests from pipeds, web clients, incoming HTTP requests such as auth callback from third party services. It also serves all web assets including HTML, JS, CSS… This service can be easily scaled by updating the pod number.

Cache

cache is a single pod service for caching internal data used by server service. Currently, this cache service is powered by redis. You can configure the control plane to use a fully-managed redis cache service instead of launching a cache pod in your cluster.

Ops

ops is a single pod service for operating PipeCD owner’s tasks. For example, it provides an internal web page for adding and managing projects; it periodically removes the old data; it collects and saves the deployment insights.

Data Store

Data store is a storage for storing model data such as applications and deployments. This can be a fully-managed service such as GCP Firestore, GCP Cloud SQL or AWS RDS (currently we choose MySQL v8 as supported relational data store). You can also configure the control plane to use a self-managed MySQL server. When installing the control plane, you have to choose one of the provided data store services.

File Store

File store is a storage for storing stage logs, application live states. This can be a fully-managed service such as GCP GCS, AWS S3, or a self-managed service such as Minio. When installing the control plane, you have to choose one of the provided file store services.

Docs-V0.56.x: Canary deployment for Kubernetes app with Istio

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

Canary release is a technique to reduce the risk of introducing a new software version in production by slowly rolling out the change to a small subset of users before rolling it out to the entire infrastructure and making it available to everybody. – martinfowler.com/canaryrelease

With Istio, we can accomplish this goal by configuring a sequence of rules that route a percentage of traffic to each variant of the application. And with PipeCD, you can enable and automate the canary strategy for your Kubernetes application even easier.

In this guide, we will show you how to configure the application configuration file to send 10% of traffic to the new version and keep 90% to the primary variant. Then after waiting for manual approval, you will complete the migration by sending 100% of traffic to the new version.

Complete source code for this example is hosted in pipe-cd/examples repository.

Before you begin

Add a new Kubernetes application by following the instructions in this guide
Ensure having pipecd.dev/variant: primary label and selector in the workload template
Ensure having at least one Istio’s DestinationRule and defining the needed subsets (primary and canary) with pipecd.dev/variant label

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: mesh-istio-canary
spec:
  host: mesh-istio-canary.default.svc.cluster.local
  subsets:
  - name: primary
    labels:
      pipecd.dev/variant: primary
  - name: canary
    labels:
      pipecd.dev/variant: canary

Ensure having at least one Istio’s VirtualService manifest and all traffic is routed to the primary

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: mesh-istio-canary
spec:
  hosts:
    - mesh-istio-canary.pipecd.dev
  gateways:
    - mesh-istio-canary
  http:
    - route:
      - destination:
          host: mesh-istio-canary.default.svc.cluster.local
          subset: primary
        weight: 100

Enabling canary strategy

Add the following application configuration file into the application directory in Git.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 50%
      - name: K8S_TRAFFIC_ROUTING
        with:
          canary: 10
          primary: 90
      - name: WAIT_APPROVAL
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_TRAFFIC_ROUTING
        with:
          primary: 100
      - name: K8S_CANARY_CLEAN
  trafficRouting:
    method: istio
    istio:
      host: mesh-istio-canary.default.svc.cluster.local

Send a PR to update the container image version in the Deployment manifest and merge it to trigger a new deployment. PipeCD will plan the deployment with the specified canary strategy.

Deployment Details Page

Now you have an automated canary deployment for your application. 🎉

Understanding what happened

In this example, you configured the application configuration file to migrate traffic from an old to a new version of the application using Istio’s weighted routing feature.

Stage 1: K8S_CANARY_ROLLOUT ensures that the workloads of canary variant (new version) should be deployed. But at this time, they still handle nothing, all traffic are handled by workloads of primary variant. The number of workloads (e.g. pod) for canary variant is configured to be 50% of the replicas number of primary varant.

Stage 2: K8S_TRAFFIC_ROUTING ensures that 10% of traffic should be routed to canary variant and 90% to primary variant. Because the trafficRouting is configured to use Istio, PipeCD will find Istio’s VirtualService resource of this application to control the traffic percentage.

Stage 3: WAIT_APPROVAL waits for a manual approval from someone in your team.
Stage 4: K8S_PRIMARY_ROLLOUT ensures that all resources of primary variant will be updated to the new version.

Stage 5: K8S_TRAFFIC_ROUTING ensures that all traffic should be routed to primary variant. Now primary variant is running the new version so it means all traffic is handled by the new version.

Stage 6: K8S_CANARY_CLEAN ensures all created resources for canary variant should be destroyed.

Docs-V0.56.x: Contribute to PipeCD

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

PipeCD is an open source project that anyone in the community can use, improve, and enjoy. We’d love you to join us!

Code of Conduct

PipeCD follows the CNCF Code of Conduct. Please read it to understand which actions are acceptable and which are not.

Ways to Contribute

There are many ways to contribute, and many don’t involve writing code:

Use PipeCD — Follow the Quickstart and report issues you encounter
Triage issues — Browse open issues, provide workarounds, ask for clarification, or suggest labels
Fix bugs — Issues labeled good first issue are great starting points
Improve docs — See Contribute to PipeCD Documentation
Participate in discussions — Share ideas in GitHub Discussions

Development Setup

Project Structure

PipeCD consists of several components:

Component	Description
cmd/pipecd	Control Plane — manages deployment data and provides gRPC API
cmd/piped	Piped agent — runs in your cluster
cmd/pipectl	Command-line tool
cmd/launcher	Command executor for remote upgrade
web	Web UI
docs	Documentation

Prerequisites

Go (check go.mod for version)
Node.js and Yarn (for web development)
Docker
kubectl
kind (Kubernetes in Docker)

Starting a Local Environment

1. Update Dependencies

make update/go-deps
make update/web-deps

Starting a local environment may fail if dependencies are not up to date.

2. Start Local Cluster and Registry

make up/local-cluster

This creates the pipecd Kubernetes namespace and starts a local registry.

To clean up later:

make down/local-cluster

3. Run Control Plane

make run/pipecd

To stop:

make stop/pipecd

4. Port Forward

In a separate terminal:

kubectl port-forward -n pipecd svc/pipecd 8080

5. Access the UI

Open http://localhost:8080?project=quickstart

Username: hello-pipecd
Password: hello-pipecd

Running Piped Agent

Ensure Control Plane is running and accessible.
Register a new Piped:
- Go to Settings → Piped (or http://localhost:8080/settings/piped?project=quickstart)
- Add a new piped and copy the generated Piped ID and base64 key

Create piped-config.yaml in the repository root:

Tip: Create a .dev folder (gitignored) for multiple config files.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: quickstart
  pipedID: <YOUR_PIPED_ID>
  pipedKeyData: <YOUR_PIPED_BASE64_KEY>
  apiAddress: localhost:8080
  repositories:
    - repoId: example
      remote: git@github.com:pipe-cd/examples.git
      branch: master
  syncInterval: 1m
  platformProviders:
    - name: example-kubernetes
      type: KUBERNETES
      config:
        kubeConfigPath: /path/to/.kube/config

Start the Piped agent:

make run/piped CONFIG_FILE=path/to/piped-config.yaml INSECURE=true

Useful Commands

Check the Makefile for available commands. Common ones:

make check          # Run all checks (lint, test, etc.)
make test/go        # Run Go tests
make test/web       # Run web tests
make build/go       # Build Go binaries

Pull Request Process

Before You Start

Find or create an issue — Check if an issue exists, or open one for new features/bugs
Claim the issue — Comment “I’d like to work on this” to get assigned (expected to submit PR within 7 days)
Investigate first — Discuss your approach in the issue before coding to reduce back-and-forth on the PR
Focus on one issue — Especially for newcomers, work on one issue at a time

Submitting a Pull Request

Keep PRs small — Aim for ~300 lines of diff. Split larger changes into multiple PRs.
Use descriptive titles — Follow commit message style: present tense, capitalize first letter
```
Add imports to Terraform plan result
```
Sign off commits — Required for DCO compliance:
```
git commit -s -m "Your commit message"
```
Run checks before submitting:
```
make check
```
Target the master branch — All PRs should be opened against master

User-Facing Changes

If your change affects users, update the PR description:

**Does this PR introduce a user-facing change?**:
- **How are users affected by this change**:
- **Is this breaking change**:
- **How to migrate (if breaking change)**:

Licensing

By contributing, you agree to license your contributions under the Apache License Version 2.0. Add this header to new files:

// Copyright 2025 The PipeCD Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

Reporting Issues

Bugs

File bugs at GitHub Issues:

One issue, one bug
Provide reproduction steps — List all steps to reproduce the issue

Security Issues

Report security vulnerabilities privately via Slack or Twitter DM to maintainers listed in MAINTAINERS.md.

Feature Requests

Enhancement request — Improvements to existing features
Feature request — Entirely new features

Join the Community

Slack

We have a #pipecd channel on CNCF Slack for discussions and help. You can also assist other users in the channel.

Community Meetings

We host PipeCD Development and Community Meetings every 2 weeks where we share project news, demos, answer questions, and triage issues. View the Meeting Notes and Agenda.

Become a Member

If you’d like to join the pipe-cd GitHub organization:

Have at least 5 PRs merged to repositories in the pipe-cd organization
Attend a PipeCD public community meeting

Membership isn’t required to contribute—it’s for those who want to contribute long-term or take ownership of features.

What Happens Next?

The maintainers will review your PR. We’ll help with obvious issues and work with you to get it merged. Thank you for contributing!

Docs-V0.56.x: Installing Control Plane on Kubernetes

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

Prerequisites

Having a running Kubernetes cluster
Installed Helm (3.8.0 or later)

Installation

1. Preparing an encryption key

PipeCD requires a key for encrypting sensitive data or signing JWT token while authenticating. You can use one of the following commands to generate an encryption key.

openssl rand 64 | base64 > encryption-key

# or
cat /dev/urandom | head -c64 | base64 > encryption-key

2. Preparing Control Plane configuration file and installing

Control Plane Architecture

The Control Plane of PipeCD is constructed by several components, as shown in the above graph (for more in detail please read Control Plane architecture overview docs). As mentioned in the graph, the PipeCD’s data can be stored in one of the provided fully-managed or self-managed services. So you have to decide which kind of data store and file store you want to use and prepare a Control Plane configuration file suitable for that choice.

Using Firestore and GCS

PipeCD requires a GCS bucket and service account files to access Firestore and GCS service. Here is an example of configuration file:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  stateKey: {RANDOM_STRING}
  datastore:
    type: FIRESTORE
    config:
      namespace: pipecd
      environment: dev
      project: {YOUR_GCP_PROJECT_NAME}
      # Must be a service account with "Cloud Datastore User" and "Cloud Datastore Index Admin" roles
      # since PipeCD needs them to creates the needed Firestore composite indexes in the background.
      credentialsFile: /etc/pipecd-secret/firestore-service-account
  filestore:
    type: GCS
    config:
      bucket: {YOUR_BUCKET_NAME}
      # Must be a service account with "Storage Object Admin (roles/storage.objectAdmin)" role on the given bucket
      # since PipeCD need to write file object such as deployment log file to that bucket.
      credentialsFile: /etc/pipecd-secret/gcs-service-account

See ConfigurationReference for the full configuration.

After all, install the Control Plane as bellow:

helm upgrade -i pipecd oci://ghcr.io/pipe-cd/chart/pipecd --version v0.56.0 --namespace={NAMESPACE} \
  --set-file config.data=path-to-control-plane-configuration-file \
  --set-file secret.encryptionKey.data=path-to-encryption-key-file \
  --set-file secret.firestoreServiceAccount.data=path-to-service-account-file \
  --set-file secret.gcsServiceAccount.data=path-to-service-account-file

Currently, besides Firestore PipeCD supports other databases as its datastore such as MySQL. Also as for filestore, PipeCD supports AWS S3 and MINIO either.

For example, in case of using MySQL as datastore and MINIO as filestore, the ControlPlane configuration will be as follow:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  stateKey: {RANDOM_STRING}
  datastore:
    type: MYSQL
    config:
      url: {YOUR_MYSQL_ADDRESS}
      database: {YOUR_DATABASE_NAME}
  filestore:
    type: MINIO
    config:
      endpoint: {YOUR_MINIO_ADDRESS}
      bucket: {YOUR_BUCKET_NAME}
      accessKeyFile: /etc/pipecd-secret/minio-access-key
      secretKeyFile: /etc/pipecd-secret/minio-secret-key
      autoCreateBucket: true

You can find required configurations to use other datastores and filestores from ConfigurationReference.

Caution: In case of using MySQL as Control Plane’s datastore, please note that the implementation of PipeCD requires some features that only available on MySQL v8, make sure your MySQL service is satisfied the requirement.

3. Accessing the PipeCD web

If your installation was including an ingress, the PipeCD web can be accessed by the ingress’s IP address or domain. Otherwise, private PipeCD web can be accessed by using kubectl port-forward to expose the installed Control Plane on your localhost:

kubectl port-forward svc/pipecd 8080 --namespace={NAMESPACE}

Now go to http://localhost:8080 on your browser, you will see a page to login to your project.

Up to here, you have an installed PipeCD’s Control Plane. To log in, you need to initialize a new project.

4. Initialize a new project

To create a new project, you need to access to the ops pod in your installed PipeCD control plane, using kubectl port-forward command:

kubectl port-forward service/pipecd-ops 9082 --namespace={NAMESPACE}

Then, access to http://localhost:9082.

On that page, you will see the list of registered projects and a link to register new projects. Registering a new project requires only a unique ID string and an optional description text.

Once a new project has been registered, a static admin (username, password) will be automatically generated for the project admin, you can use that to login via the login form in the above section.

For more about adding a new project in detail, please read the following docs.

5. Upgrade Control Plane version

To upgrade the PipeCD Control Plane, preparations and commands remain as you do when installing PipeCD Control Plane. Only need to change the version flag in command to the specified version you want to upgrade your PipeCD Control Plane to.

helm upgrade -i pipecd oci://ghcr.io/pipe-cd/chart/pipecd --version {NEW_VERSION} --namespace={NAMESPACE} \
  --set-file config.data=path-to-control-plane-configuration-file \
  --set-file secret.encryptionKey.data=path-to-encryption-key-file \
  --set-file secret.firestoreServiceAccount.data=path-to-service-account-file \
  --set-file secret.gcsServiceAccount.data=path-to-service-account-file

Production Hardening

This part provides guidance for a production hardened deployment of the control plane.

Publishing the control plane

You can allow external access to the control plane by enabling the ingress configuration.
End-to-End TLS

After switching to HTTPs, do not forget to set the api.args.secureCookie parameter to be true to disallow using cookie on unsecured HTTP connection.

Alternatively in the case of GKE Ingress, PipeCD also requires a TLS certificate for internal use. This can be a self-signed one and generated by this command:
```
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN={YOUR_DOMAIN}"
```
Those key and cert can be configured via secret.internalTLSKey.data and secret.internalTLSCert.data.

To enable internal tls connection, please set the gateway.internalTLS.enabled parameter to be true.

Otherwise, the cloud.google.com/app-protocols annotation is also should be configured as the following:
```
service:
  port: 443
  annotations:
    cloud.google.com/app-protocols: '{"service":"HTTP2"}'
```

Docs-V0.56.x: Installing on Kubernetes cluster

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

Prerequisites

Having piped’s ID and Key strings

Ensure that the piped has been registered and you are having its PIPED_ID and PIPED_KEY strings.
If you are not having them, this page guides you how to register a new one.

Preparing SSH key

If your Git repositories are private, piped requires a private SSH key to access those repositories.
Please checkout this documentation for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository’s Settings page.)

In the cluster-wide mode

This way requires installing cluster-level resources. Piped installed with this way can perform deployment workloads against any other namespaces than the where Piped runs on.

Preparing a piped configuration file as the following

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: {PROJECT_ID}
  pipedID: {PIPED_ID}
  pipedKeyFile: /etc/piped-secret/piped-key
  # Write in a format like "host:443" because the communication is done via gRPC.
  apiAddress: {CONTROL_PLANE_API_ADDRESS}
  git:
    sshKeyFile: /etc/piped-secret/ssh-key
  repositories:
    - repoId: {REPO_ID_OR_NAME}
      remote: git@github.com:{GIT_ORG}/{GIT_REPO}.git
      branch: {GIT_BRANCH}
  syncInterval: 1m

See ConfigurationReference for the full configuration.

Installing by using Helm (3.8.0 or later)

# This command just installs a Piped with the specified version.
# Whenever you want to upgrade that Piped to a new version or update its config data
# you have to restart it by re-running this command.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set-file config.data={PATH_TO_PIPED_CONFIG_FILE} \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE}

# Enable remote-upgrade feature of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-upgrade
# This allows upgrading Piped to a new version from the web console.
# But we still need to restart Piped when we want to update its config data.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set launcher.enabled=true \
  --set-file config.data={PATH_TO_PIPED_CONFIG_FILE} \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE}

# Enable both remote-upgrade and remote-config features of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-config
# Beside of the ability to upgrade Piped to a new version from the web console,
# remote-config allows loading the Piped config stored in a remote location such as a Git repository.
# Whenever the config data is changed, it loads the new config and restarts Piped to use that new config.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set launcher.enabled=true \
  --set launcher.configFromGitRepo.enabled=true \
  --set launcher.configFromGitRepo.repoUrl=git@github.com:{GIT_ORG}/{GIT_REPO}.git \
  --set launcher.configFromGitRepo.branch={GIT_BRANCH} \
  --set launcher.configFromGitRepo.configFile={RELATIVE_PATH_TO_PIPED_CONFIG_FILE_IN_GIT_REPO} \
  --set launcher.configFromGitRepo.sshKeyFile=/etc/piped-secret/ssh-key \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE}

Note: Be sure to set --set args.insecure=true if your Control Plane has not TLS-enabled yet.

See values.yaml for the full values.

In the namespaced mode

The previous way requires installing cluster-level resources. If you want to restrict Piped’s permission within the namespace where Piped runs on, this way is for you. Most parts are identical to the previous way, but some are slightly different.

Adding a new cloud provider like below to the previous piped configuration file

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: {PROJECT_ID}
  pipedID: {PIPED_ID}
  pipedKeyFile: /etc/piped-secret/piped-key
  # Write in a format like "host:443" because the communication is done via gRPC.
  apiAddress: {CONTROL_PLANE_API_ADDRESS}
  git:
    sshKeyFile: /etc/piped-secret/ssh-key
  repositories:
    - repoId: REPO_ID_OR_NAME
      remote: git@github.com:{GIT_ORG}/{GIT_REPO}.git
      branch: {GIT_BRANCH}
  syncInterval: 1m
  # This is needed to restrict to limit the access range to within a namespace.
  platformProviders:
    - name: my-kubernetes
      type: KUBERNETES
      config:
        appStateInformer:
          namespace: {NAMESPACE}

Installing by using Helm (3.8.0 or later)

# This command just installs a Piped with the specified version.
# Whenever you want to upgrade that Piped to a new version or update its config data
# you have to restart it by re-running this command.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set-file config.data={PATH_TO_PIPED_CONFIG_FILE} \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE} \
  --set args.enableDefaultKubernetesCloudProvider=false \
  --set rbac.scope=namespace

# Enable remote-upgrade feature of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-upgrade
# This allows upgrading Piped to a new version from the web console.
# But we still need to restart Piped when we want to update its config data.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set launcher.enabled=true \
  --set-file config.data={PATH_TO_PIPED_CONFIG_FILE} \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE} \
  --set args.enableDefaultKubernetesCloudProvider=false \
  --set rbac.scope=namespace

# Enable both remote-upgrade and remote-config features of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-config
# Beside of the ability to upgrade Piped to a new version from the web console,
# remote-config allows loading the Piped config stored in a remote location such as a Git repository.
# Whenever the config data is changed, it loads the new config and restarts Piped to use that new config.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set launcher.enabled=true \
  --set launcher.configFromGitRepo.enabled=true \
  --set launcher.configFromGitRepo.repoUrl=git@github.com:{GIT_ORG}/{GIT_REPO}.git \
  --set launcher.configFromGitRepo.branch={GIT_BRANCH} \
  --set launcher.configFromGitRepo.configFile={RELATIVE_PATH_TO_PIPED_CONFIG_FILE_IN_GIT_REPO} \
  --set launcher.configFromGitRepo.sshKeyFile=/etc/piped-secret/ssh-key \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE} \
  --set args.enableDefaultKubernetesCloudProvider=false \
  --set rbac.scope=namespace

In case on OpenShift less than 4.2

OpenShift uses an arbitrarily assigned user ID when it starts a container. Starting from OpenShift 4.2, it also inserts that user into /etc/passwd for using by the application inside the container, but before that version, the assigned user is missing in that file. That blocks workloads of ghcr.io/pipe-cd/piped image. Therefore if you are running on OpenShift with a version before 4.2, please use ghcr.io/pipe-cd/piped-okd image with the following command:

Installing by using Helm (3.8.0 or later)

# This command just installs a Piped with the specified version.
# Whenever you want to upgrade that Piped to a new version or update its config data
# you have to restart it by re-running this command.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set-file config.data={PATH_TO_PIPED_CONFIG_FILE} \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE} \
  --set args.enableDefaultKubernetesCloudProvider=false \
  --set rbac.scope=namespace
  --set args.addLoginUserToPasswd=true \
  --set securityContext.runAsNonRoot=true \
  --set securityContext.runAsUser={UID} \
  --set securityContext.fsGroup={FS_GROUP} \
  --set securityContext.runAsGroup=0 \
  --set image.repository="ghcr.io/pipe-cd/piped-okd"

# Enable remote-upgrade feature of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-upgrade
# This allows upgrading Piped to a new version from the web console.
# But we still need to restart Piped when we want to update its config data.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set launcher.enabled=true \
  --set-file config.data={PATH_TO_PIPED_CONFIG_FILE} \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE} \
  --set args.enableDefaultKubernetesCloudProvider=false \
  --set rbac.scope=namespace
  --set args.addLoginUserToPasswd=true \
  --set securityContext.runAsNonRoot=true \
  --set securityContext.runAsUser={UID} \
  --set securityContext.fsGroup={FS_GROUP} \
  --set securityContext.runAsGroup=0 \
  --set launcher.image.repository="ghcr.io/pipe-cd/launcher-okd"

# Enable both remote-upgrade and remote-config features of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-config
# Beside of the ability to upgrade Piped to a new version from the web console,
# remote-config allows loading the Piped config stored in a remote location such as a Git repository.
# Whenever the config data is changed, it loads the new config and restarts Piped to use that new config.

helm upgrade -i dev-piped oci://ghcr.io/pipe-cd/chart/piped --version=v0.56.0 --namespace={NAMESPACE} \
  --set launcher.enabled=true \
  --set launcher.configFromGitRepo.enabled=true \
  --set launcher.configFromGitRepo.repoUrl=git@github.com:{GIT_ORG}/{GIT_REPO}.git \
  --set launcher.configFromGitRepo.branch={GIT_BRANCH} \
  --set launcher.configFromGitRepo.configFile={RELATIVE_PATH_TO_PIPED_CONFIG_FILE_IN_GIT_REPO} \
  --set launcher.configFromGitRepo.sshKeyFile=/etc/piped-secret/ssh-key \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE} \
  --set args.enableDefaultKubernetesCloudProvider=false \
  --set rbac.scope=namespace
  --set args.addLoginUserToPasswd=true \
  --set securityContext.runAsNonRoot=true \
  --set securityContext.runAsUser={UID} \
  --set securityContext.fsGroup={FS_GROUP} \
  --set securityContext.runAsGroup=0 \
  --set launcher.image.repository="ghcr.io/pipe-cd/launcher-okd"

Docs-V0.56.x: Configuring Kubernetes application

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

Based on the application configuration and the pull request changes, PipeCD plans how to execute the deployment: doing quick sync or doing progressive sync with the specified pipeline.

Note:

You can generate an application config file easily and interactively by pipectl init.

Quick sync

Quick sync is a fast way to sync application to the state specified in the target Git commit without any progressive strategy. It just applies all the defined manifests to sync the application. The quick sync will be planned in one of the following cases:

no pipeline was specified in the application configuration file
pipeline was specified but the PR did not make any changes on workload (e.g. Deployment’s pod template) or config (e.g. ConfigMap, Secret)

For example, the application configuration as below is missing the pipeline field. This means any pull request touches the application will trigger a quick sync deployment.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  input:
    helmChart:
      repository: pipecd
      name: helloworld
      version: v0.3.0

In another case, even when the pipeline was specified, a PR that just changes the Deployment’s replicas number for scaling will also trigger a quick sync deployment.

Sync with the specified pipeline

The pipeline field in the application configuration is used to customize the way to do deployment by specifying and configuring the execution stages. You may want to configure those stages to enable a progressive deployment with a strategy like canary, blue-green, a manual approval, an analysis stage.

To enable customization, PipeCD defines three variants for each Kubernetes application: primary (aka stable), baseline and canary.

primary runs the current version of code and configuration.
baseline runs the same version of code and configuration as the primary variant. (Creating a brand-new baseline workload ensures that the metrics produced are free of any effects caused by long-running processes.)
canary runs the proposed change of code or configuration.

Depending on the configured pipeline, any variants can exist and receive the traffic during the deployment process but once the deployment is completed, only the primary variant should be remained.

These are the provided stages for Kubernetes application you can use to build your pipeline:

K8S_PRIMARY_ROLLOUT
- update the primary resources to the state defined in the target commit
K8S_CANARY_ROLLOUT
- generate canary resources based on the definition of the primary resource in the target commit and apply them
K8S_CANARY_CLEAN
- remove all canary resources
K8S_BASELINE_ROLLOUT
- generate baseline resources based on the definition of the primary resource in the target commit and apply them
K8S_BASELINE_CLEAN
- remove all baseline resources
K8S_TRAFFIC_ROUTING
- split traffic between variants

and other common stages:

WAIT
WAIT_APPROVAL
ANALYSIS

See the description of each stage at Customize application deployment.

Manifest Templating

In addition to plain-YAML, PipeCD also supports Helm and Kustomize for templating application manifests.

A helm chart can be loaded from:

the same git repository with the application directory, we call as a local chart

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  input:
    helmChart:
      path: ../../local/helm-charts/helloworld

a different git repository, we call as a remote git chart

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  input:
    helmChart:
      gitRemote: git@github.com:pipe-cd/manifests.git
      ref: v0.5.0
      path: manifests/helloworld

a Helm chart repository, we call as a remote chart

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  input:
    helmChart:
      repository: pipecd
      name: helloworld
      version: v0.5.0

A kustomize base can be loaded from:

the same git repository with the application directory, we call as a local base
a different git repository, we call as a remote base

See Examples for more specific.

Reference

See Configuration Reference for the full configuration.

Docs-V0.56.x: Remote upgrade and remote config

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

Remote upgrade

The remote upgrade is the ability to restart the currently running Piped with another version from the web console. This reduces the effort involved in updating Piped to newer versions. All Pipeds that are running by the provided Piped container image can be enabled to use this feature. It means Pipeds running on a Kubernetes cluster, a virtual machine, a serverless service can be upgraded remotely from the web console.

Basically, in order to use this feature you must run Piped with /launcher command instead of /piped command as usual. Please check the installation guide on each environment to see the details.

After starting Piped with the remote-upgrade feature, you can go to the Settings page then click on UPGRADE button on the top-right corner. A dialog will be shown for selecting which Pipeds you want to upgrade and what version they should run.

Select a list of Pipeds to upgrade from Settings page

Remote config

Although the remote-upgrade allows you remotely restart your Pipeds to run any new version you want, if your Piped is loading its config locally where Piped is running, you still need to manually restart Piped after adding any change on that config data. Remote-config is for you to remove that kind of manual operation.

Remote-config is the ability to load Piped config data from a remote location such as a Git repository. Not only that, but it also watches the config periodically to detect any changes on that config and restarts Piped to reflect the new configuration automatically.

This feature requires the remote-upgrade feature to be enabled simultaneously. Please check Runtime Options and the installation guide on each environment to know how to configure Piped to load a remote config file.

Summary

By remote-upgrade you can upgrade your Piped to a newer version by clicking on the web console
By remote-config you can enforce your Piped to use the latest config data just by updating its config file stored in a Git repository

Docs-V0.56.x: Adding a wait stage

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

In addition to waiting for approvals from someone, the deployment pipeline can be configured to wait an amount of time before continuing. This can be done by adding the WAIT stage into the pipeline. This stage has one configurable field, duration, to configure how long it should wait.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
      - name: WAIT
        with:
          duration: 5m
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_CANARY_CLEAN

Deployment with a WAIT stage

Docs-V0.56.x: Adding a project

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

The control plane ops can add a new project for a team. Project adding can be simply done from an internal web page prepared for the ops. Because that web service is running in an ops pod, in order to access it, use the kubectl port-forward command to forward a local port to a port on the ops pod as follows:

kubectl port-forward service/pipecd-ops 9082 --namespace={NAMESPACE}

Then, access to http://localhost:9082.

On that page, you will see the list of registered projects and a link to register new projects. Registering a new project requires only a unique ID string and an optional description text.

Once a new project has been registered, a static admin (username, password) will be automatically generated for the project admin. You can send that information to the project admin. The project admin first uses the provided static admin information to log in to PipeCD. After that, they can change the static admin information, configure the SSO, RBAC or disable static admin user.

Caution: The Role-Based Access Control (RBAC) setting is required to enable your team to log in using SSO. Please make sure you have that set up before disabling the static admin user.

Docs-V0.56.x: Adding a git repository

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

In the piped configuration file, we specify the list of Git repositories that should be handled by the piped. A Git repository contains one or more deployable applications where each application is put inside a directory called the application directory. That directory contains an application configuration file as well as application manifests. The piped periodically checks for new commits and fetches the needed manifests from those repositories for executing the deployment.

A single piped can be configured to handle one or more Git repositories. In order to enable a new Git repository, let’s add a new GitRepository block to the repositories field in the piped configuration file.

For example, with the following snippet, piped will take the master branch of pipe-cd/examples repository as a target Git repository for doing deployments.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  ...
  repositories:
    - repoId: examples
      remote: git@github.com:pipe-cd/examples.git
      branch: master

In most of the cases, we want to deal with private Git repositories. For accessing those private repositories, piped needs a private SSH key, which can be configured while installing with secret.sshKey in the Helm chart.

helm install dev-piped pipecd/piped --version={VERSION} \
  --set-file config.data={PATH_TO_PIPED_CONFIG_FILE} \
  --set-file secret.data.piped-key={PATH_TO_PIPED_KEY_FILE} \
  --set-file secret.data.ssh-key={PATH_TO_PRIVATE_SSH_KEY_FILE}

You can see this configuration reference for more configurable fields about Git commands.

Currently, piped allows configuring only one private SSH key for all specified Git repositories. So you can configure the same SSH key for all of those private repositories, or break them into separate pipeds. In the near future, we also want to update piped to support loading multiple SSH keys.

Docs-V0.56.x: BlueGreen deployment for Kubernetes app with Istio

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

Similar to canary deployment, PipeCD allows you to enable and automate the blue-green deployment strategy for your application based on Istio’s weighted routing feature.

In both canary and blue-green strategies, the old version and the new version of the application get deployed at the same time. But while the canary strategy slowly routes the traffic to the new version, the blue-green strategy quickly routes all traffic to one of the versions.

In this guide, we will show you how to configure the application configuration file to apply the blue-green strategy.

Complete source code for this example is hosted in pipe-cd/examples repository.

Before you begin

Add a new Kubernetes application by following the instructions in this guide
Ensure having pipecd.dev/variant: primary label and selector in the workload template
Ensure having at least one Istio’s DestinationRule and defining the needed subsets (primary and canary) with pipecd.dev/variant label

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: mesh-istio-bluegreen
spec:
  host: mesh-istio-bluegreen
  subsets:
  - name: primary
    labels:
      pipecd.dev/variant: primary
  - name: canary
    labels:
      pipecd.dev/variant: canary
  trafficPolicy:
    tls:
      mode: ISTIO_MUTUAL

Ensure having at least one Istio’s VirtualService manifest and all traffic is routed to the primary

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: mesh-istio-bluegreen
spec:
  hosts:
    - mesh-istio-bluegreen.pipecd.dev
  gateways:
    - mesh-istio-bluegreen
  http:
    - route:
      - destination:
          host: mesh-istio-bluegreen
          subset: primary
        weight: 100

Enabling blue-green strategy

Add the following application configuration file into the application directory in the Git repository.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 100%
      - name: K8S_TRAFFIC_ROUTING
        with:
          all: canary
      - name: WAIT_APPROVAL
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_TRAFFIC_ROUTING
        with:
          all: primary
      - name: K8S_CANARY_CLEAN
  trafficRouting:
    method: istio
    istio:
      host: mesh-istio-bluegreen

Send a PR to update the container image version in the Deployment manifest and merge it to trigger a new deployment. PipeCD will plan the deployment with the specified blue-green strategy.

Deployment Details Page

Now you have an automated blue-green deployment for your application. 🎉

Understanding what happened

In this example, you configured the application configuration file to switch all traffic from an old to a new version of the application using Istio’s weighted routing feature.

Stage 1: K8S_CANARY_ROLLOUT ensures that the workloads of canary variant (new version) should be deployed. But at this time, they still handle nothing, all traffic is handled by workloads of primary variant. The number of workloads (e.g. pod) for canary variant is configured to be 100% of the replicas number of primary varant.

Stage 2: K8S_TRAFFIC_ROUTING ensures that all traffic should be routed to canary variant. Because the trafficRouting is configured to use Istio, PipeCD will find Istio’s VirtualService resource of this application to control the traffic percentage. (You can add an ANALYSIS stage after this to validate the new version. When any negative impacts are detected, an auto-rollback stage will be executed to switch all traffic back to the primary variant.)

Stage 3: WAIT_APPROVAL waits for a manual approval from someone in your team.
Stage 4: K8S_PRIMARY_ROLLOUT ensures that all resources of primary variant will be updated to the new version.

Stage 5: K8S_TRAFFIC_ROUTING ensures that all traffic should be routed to primary variant. Now primary variant is running the new version so it means all traffic is handled by the new version.

Stage 6: K8S_CANARY_CLEAN ensures all created resources for canary variant should be destroyed.

Docs-V0.56.x: Installing Control Plane on ECS

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

Currently, we provide the example of deploying Control Plane to ECS using terraform.

Please refer to the blog post :) PipeCD best practice 02 - control plane on ECS.

Docs-V0.56.x: Installing on Google Cloud VM

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

Prerequisites

Having piped’s ID and Key strings

Ensure that the piped has been registered and you are having its PIPED_ID and PIPED_KEY strings.
If you are not having them, this page guides you how to register a new one.

Preparing SSH key

If your Git repositories are private, piped requires a private SSH key to access those repositories.
Please checkout this documentation for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository’s Settings page.)

Installation

Preparing a piped configuration file as the following:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: {PROJECT_ID}
  pipedID: {PIPED_ID}
  pipedKeyData: {BASE64_ENCODED_PIPED_KEY}
  # Write in a format like "host:443" because the communication is done via gRPC.
  apiAddress: {CONTROL_PLANE_API_ADDRESS}

  git:
    sshKeyData: {BASE64_ENCODED_PRIVATE_SSH_KEY}

  repositories:
    - repoId: {REPO_ID_OR_NAME}
      remote: git@github.com:{GIT_ORG}/{GIT_REPO}.git
      branch: {GIT_BRANCH}

  # Optional
  # Uncomment this if you want to enable this Piped to handle Cloud Run application.
  # platformProviders:
  #  - name: cloudrun-in-project
  #    type: CLOUDRUN
  #    config:
  #      project: {GCP_PROJECT_ID}
  #      region: {GCP_PROJECT_REGION}

  # Optional
  # Uncomment this if you want to enable this Piped to handle Terraform application.
  #  - name: terraform-gcp
  #    type: TERRAFORM

  # Optional
  # Uncomment this if you want to enable SecretManagement feature.
  # https://pipecd.dev//docs/user-guide/managing-application/secret-management/
  # secretManagement:
  #   type: KEY_PAIR
  #   config:
  #     privateKeyData: {BASE64_ENCODED_PRIVATE_KEY}
  #     publicKeyData: {BASE64_ENCODED_PUBLIC_KEY}

See ConfigurationReference for the full configuration.

Creating a new secret in SecretManager to store above configuration data securely
```
gcloud secrets create vm-piped-config --data-file={PATH_TO_CONFIG_FILE}
```

Creating a new Service Account for Piped and giving it needed roles

gcloud iam service-accounts create vm-piped \
  --description="Using by Piped running on Google Cloud VM" \
  --display-name="vm-piped"

# Allow Piped to access the created secret.
gcloud secrets add-iam-policy-binding vm-piped-config \
  --member="serviceAccount:vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

# Allow Piped to write its log messages to Google Cloud Logging service.
gcloud projects add-iam-policy-binding {GCP_PROJECT_ID} \
  --member="serviceAccount:vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/logging.logWriter"

# Optional
# If you want to use this Piped to handle Cloud Run application
# run the following command to give it the needed roles.
# https://cloud.google.com/run/docs/reference/iam/roles#additional-configuration
#
# gcloud projects add-iam-policy-binding {GCP_PROJECT_ID} \
#   --member="serviceAccount:vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com" \
#   --role="roles/run.developer"
#
# gcloud iam service-accounts add-iam-policy-binding {GCP_PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
#   --member="serviceAccount:vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com" \
#   --role="roles/iam.serviceAccountUser"

Running Piped on a Google Cloud VM

# Enable remote-upgrade feature of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-upgrade
# This allows upgrading Piped to a new version from the web console.

  gcloud compute instances create-with-container vm-piped \
    --container-image="ghcr.io/pipe-cd/launcher:v0.56.0" \
    --container-arg="launcher" \
    --container-arg="--config-from-gcp-secret=true" \
    --container-arg="--gcp-secret-id=projects/{GCP_PROJECT_ID}/secrets/vm-piped-config/versions/{SECRET_VERSION}" \
    --network="{VPC_NETWORK}" \
    --subnet="{VPC_SUBNET}" \
    --scopes="cloud-platform" \
    --service-account="vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com"

# This just installs a Piped with the specified version.
# Whenever you want to upgrade that Piped to a new version or update its config data you have to restart it.

  gcloud compute instances create-with-container vm-piped \
    --container-image="ghcr.io/pipe-cd/piped:v0.56.0" \
    --container-arg="piped" \
    --container-arg="--config-gcp-secret=projects/{GCP_PROJECT_ID}/secrets/vm-piped-config/versions/{SECRET_VERSION}" \
    --network="{VPC_NETWORK}" \
    --subnet="{VPC_SUBNET}" \
    --scopes="cloud-platform" \
    --service-account="vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com"

After that, you can see on PipeCD web at Settings page that Piped is connecting to the Control Plane. You can also view Piped log as described here.

Docs-V0.56.x: Adding a manual approval stage

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

While deploying an application to production environments, some teams require manual approvals before continuing. The manual approval stage enables you to control when the deployment is allowed to continue by requiring a specific person or team to approve. This stage is named WAIT_APPROVAL and you can add it to your pipeline before some stages that should be approved before they can be executed.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
      - name: WAIT_APPROVAL
        with:
          timeout: 6h
          approvers:
            - user-abc
      - name: K8S_PRIMARY_ROLLOUT

As above example, the deployment requires an approval from user-abc before K8S_PRIMARY_ROLLOUT stage can be executed.

The value of user ID in the approvers list depends on your SSO configuration, it must be GitHub’s user ID if your SSO was configured to use GitHub provider, it must be Gmail account if your SSO was configured to use Google provider.

In case the approvers field was not configured, anyone in the project who has Editor or Admin role can approve the deployment pipeline.

Also, it will end with failure when the time specified in timeout has elapsed. Default is 6h.

Deployment with a WAIT_APPROVAL stage

Docs-V0.56.x: Configuring Terraform application

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

Quick Sync

By default, when the pipeline was not specified, PipeCD triggers a quick sync deployment for the merged pull request. Quick sync for a Terraform deployment does terraform plan and if there are any changes detected it applies those changes automatically.

Sync with the specified pipeline

The pipeline field in the application configuration is used to customize the way to do the deployment. You can add a manual approval before doing terraform apply or add an analysis stage after applying the changes to determine the impact of those changes.

These are the provided stages for Terraform application you can use to build your pipeline:

TERRAFORM_PLAN
- do the terraform plan and show the changes will be applied
TERRAFORM_APPLY
- apply all the infrastructure changes

and other common stages:

WAIT
WAIT_APPROVAL
ANALYSIS

See the description of each stage at Customize application deployment.

Module location

Terraform module can be loaded from:

the same git repository with the application directory, we call as a local module
a different git repository, we call as a remote module

Reference

See Configuration Reference for the full configuration.

Docs-V0.56.x: Architectural overview

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

Component Architecture

Piped

A single binary component runs in your cluster, your local network to handle the deployment tasks. It can be run inside a Kubernetes cluster by simply starting a Pod or a Deployment. This component is designed to be stateless, so it can also be run in a single VM or even your local machine.

Control Plane

A centralized component manages deployment data and provides gRPC API for connecting pipeds as well as all web-functionalities of PipeCD such as authentication, showing deployment list/details, application list/details, delivery insights…

Control Plane contains the following components:

server: a service to provide api for piped, web and serve static assets for web.
ops: a service to provide administrative features for Control Plane owner like adding/managing projects.
cache: a redis cache service for caching internal data.
datastore: data storage for storing deployment, application data
- this can be a fully-managed service such as Firestore, Cloud SQL…
- or a self-managed such as MySQL
filestore: file storage for storing logs, application states
- this can a fully-managed service such as GCS, S3…
- or a self-managed service such as Minio

For more information, see Architecture overview of Control Plane.

Docs-V0.56.x: Authentication and authorization

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

Static Admin

When the PipeCD owner adds a new project, an admin account will be automatically generated for the project. After that, PipeCD owner sends that static admin information including username, password strings to the project admin, who can use that information to log in to PipeCD web with the admin role.

After logging, the project admin should change the provided username and password. Or disable the static admin account after configuring the single sign-on for the project.

Single Sign-On (SSO)

Single sign-on (SSO) allows users to log in to PipeCD by relying on a trusted third-party service.

The project can be configured to use a shared SSO configuration (shared OAuth application) instead of needing a new one. In that case, while creating the project, the PipeCD owner specifies the name of the shared SSO configuration should be used, and then the project admin can skip configuring SSO at the settings page.

Supported service

GitHub
Generic OIDC

Note: In the future, we want to support such as Google Gmail, Bitbucket…

Github

Before configuring the SSO, you need an OAuth application of the using service. For example, GitHub SSO requires creating a GitHub OAuth application as described in this page:

https://docs.github.com/en/developers/apps/creating-an-oauth-app

The authorization callback URL should be https://YOUR_PIPECD_ADDRESS/auth/callback.

Generic OIDC

PipeCD supports any OIDC provider, with tested providers including Keycloak, Auth0, and AWS Cognito. The only supported authentication flow currently is the Authorization Code Grant.

Requirements and Troubleshooting:

The OIDC provider must provide claims for user’s roles and username.
Roles claim value must use the same values as pre-configured project RBAC Roles.
Claims can be retrieved from the IdToken or UserInfo endpoint. The UserInfo endpoint will be used if the issuer supports it.
You can use set a custom claim key name for roles and username in the OIDC provider. Using usernameClaimKey and rolesClaimKey in the configuration. If not set, the default value will be chosen in the following order:
- Supported Claims Key for Username (in order of priority): username, preferred_username,name, cognito:username
- Supported Claims Key for Role (in order of priority): groups, roles, cognito:groups, custom:roles, custom:groups
If no usable claims are found, Unable to find user error will be shown.
If no roles are found, user can not access any resources. (If allowStrayAsViewer is set to true, user can access as a viewer)

Provider Configuration Examples:

Keycloak

Client authentication: On
Valid redirect URIs: https://YOUR_PIPECD_ADDRESS/auth/callback
Client scopes: Add a new mapper to the <client-id>-dedicated scope. For instance, map Group Membership information to the groups claim (Full group path should be off).

Control Plane configuration:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<KEYCLOAK_ADDRESS>/realms/<REALM>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile

Okta

Allowed Callback URLs: https://YOUR_PIPECD_ADDRESS/auth/callback

Control Plane configuration:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<OKTA_ID>.okta.com
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile
          - groups

Auth0

Allowed Callback URLs: https://YOUR_PIPECD_ADDRESS/auth/callback

Control Plane configuration:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<AUTH0_ADDRESS>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile

Roles/Groups Claims For Role or Groups information mapping using Auth0 Actions, here is an example for setting custom:roles:

exports.onExecutePostLogin = async (event, api) => {
  let namespace = "custom";
  if (namespace && !namespace.endsWith("/")) {
    namespace += ":";
  }
  api.idToken.setCustomClaim(namespace + "roles", event.authorization.roles);
};

AWS Cognito

Allowed Callback URLs: https://YOUR_PIPECD_ADDRESS/auth/callback

Control Plane configuration:

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://cognito-idp.<AWS_REGION>.amazonaws.com/<USER_POOL_ID>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile

Custom Claims Key

In some cases, the OIDC provider may not provide the claims with the default key names like groups. You can set the custom claim key name for roles and username in the control plane configuration to map the claims from the OIDC provider. To be cautious, OIDC providers can not be used if issuer discovery is not supported.

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<OIDC_ADDRESS>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile
        usernameClaimKey: username # change to your custom claim key
        rolesClaimKey: roles # change to your custom claim key
        avatarUrlClaimKey: picture # change to your custom claim key

(Optional) You can choose to use the avatar URL from the OIDC provider. Using avatarUrlClaimKey in the configuration. If not set, the default value will be chosen in the following order: picture, avatar_url

Custom OIDC Configuration

If you want to set your custom endpoint without using the endpoint from the issuer, you can set the authorization_endpoint, token_endpoint, userinfo_endpoint in the control plane configuration.

apiVersion: "pipecd.dev/v1beta1"
kind: ControlPlane
spec:
  sharedSSOConfigs:
    - name: oidc
      provider: OIDC
      oidc:
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        issuer: https://<OIDC_ADDRESS>
        redirectUri: https://<PIPECD_ADDRESS>/auth/callback
        scopes:
          - openid
          - profile
        authorization_endpoint: https://<OIDC_ADDRESS>/authorize # change to your custom endpoint
        token_endpoint: https://<OIDC_ADDRESS>/token # change to your custom endpoint
        userinfo_endpoint: https://<OIDC_ADDRESS>/userinfo # change to your custom endpoint

Role-Based Access Control (RBAC)

Role-based access control (RBAC) allows restricting access on the PipeCD web-based on the roles of user groups within the project. Before using this feature, the SSO must be configured.

PipeCD provides three built-in roles:

Viewer: has only permissions to view existing resources or data.
Editor: has all viewer permissions, plus permissions for actions that modify state, such as manually syncing application, canceling deployment…
Admin: has all editor permissions, plus permissions for updating project configurations.

Configuring the PipeCD’s roles

The below table represents PipeCD’s resources with actions on those resources.

resource	get	list	create	update	delete
application	○	○	○	○	○
deployment	○	○		○
event		○
piped	○	○	○	○
project	○			○
apiKey		○	○	○
insight	○

Each role is defined as a combination of multiple policies under this format.

resources=RESOURCE_NAMES;actions=ACTION_NAMES

The * represents all resources and all actions for a resource.

resources=*;actions=ACTION_NAMES
resources=RESOURCE_NAMES;actions=*
resources=*;actions=*

Configuring the PipeCD’s user groups

User Group represents a relation with a specific team (GitHub)/group (Google) and an arbitrary role. All users belong to a team/group will have all permissions of that team/group.

In case of using the GitHub team as a PipeCD user group, the PipeCD user group must be set in lowercase. For example, if your GitHub team is named ORG/ABC-TEAM, the PipeCD user group would be set as ORG/abc-team. (It’s follow the GitHub team URL as github.com/orgs/{organization-name}/teams/{TEAM-NAME})

Note: You CANNOT assign multiple roles to a team/group, should create a new role with suitable permissions instead.

Docs-V0.56.x: Adding an automated deployment analysis stage

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

Automated Deployment Analysis (ADA) evaluates the impact of the deployment you are in the middle of by analyzing the metrics data, log entries, and the responses of the configured HTTP requests. The analysis of the newly deployed application is often carried out in a manual, ad-hoc or statistically incorrect manner. ADA automates that and helps to build a robust deployment process. ADA is available as a stage in the pipeline specified in the application configuration file.

ADA does the analysis by periodically performing queries against the Analysis Provider and evaluating the results to know the impact of the deployment. Then based on these evaluating results, the deployment can be rolled back immediately to minimize any negative impacts.

The canonical use case for this stage is to determine if your canary deployment should proceed.

Automatic rollback based on the analysis result

Prerequisites

Before enabling ADA inside the pipeline, all required Analysis Providers must be configured in the Piped Configuration according to this guide.

Analysis by metrics

Strategies

You can choose one of the four strategies to fit your use case.

THRESHOLD: A simple method to compare against a statically defined threshold (same as the typical analysis method up to v0.18.0).
PREVIOUS: A method to compare metrics with the last successful deployment.
CANARY_BASELINE: A method to compare the metrics between the Canary and Baseline variants.
CANARY_PRIMARY(not recommended): A method to compare the metrics between the Canary and Primary variants.

THRESHOLD is the simplest strategy, so it’s for you if you attempt to evaluate this feature.

THRESHOLD only checks if the query result falls within the statically specified range, whereas others evaluate by checking the deviation of two time-series data. Therefore, those configuration fields are slightly different from each other. The next section covers how to configure the ADA stage for each strategy.

Configuration

Here is an example for the THRESHOLD strategy.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: ANALYSIS
        with:
          duration: 30m
          metrics:
            - strategy: THRESHOLD
              provider: my-prometheus
              interval: 5m
              expected:
                max: 0.01
              query: |
                sum (rate(http_requests_total{status=~"5.*"}[5m]))
                /
                sum (rate(http_requests_total[5m]))

In the provider field, put the name of the provider in Piped configuration prepared in the Prerequisites section.

The ANALYSIS stage will continue to run for the period specified in the duration field. In the meantime, Piped sends the given query to the Analysis Provider at each specified interval.

For each query, it checks if the result is within the expected range. If it’s not expected, this ANALYSIS stage will fail (typically the rollback stage will be started). You can change the acceptable number of failures by setting the failureLimit field.

The other strategies are basically the same, but there are slight differences. Let’s take a look at them.

PREVIOUS strategy

In the PREVIOUS strategy, Piped queries the analysis provider with the time range when the deployment was previously successful, and compares that metrics with the current metrics.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: ANALYSIS
        with:
          duration: 30m
          metrics:
            - strategy: PREVIOUS
              provider: my-prometheus
              deviation: HIGH
              interval: 5m
              query: |
                sum (rate(http_requests_total{status=~"5.*"}[5m]))
                /
                sum (rate(http_requests_total[5m]))

In the THRESHOLD strategy, we used expected to evaluate the deployment, but here we use deviation instead. The stage fails on deviation in the specified direction. In the above example, it fails if the current metrics is higher than the previous.

CANARY strategy

With baseline:

In the CANARY_BASELINE strategy, Piped checks if there is a significant difference between the metrics of the two running variants, Canary and Baseline.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: ANALYSIS
        with:
          duration: 30m
          metrics:
            - strategy: CANARY_BASELINE
              provider: my-prometheus
              deviation: HIGH
              interval: 5m
              query: |
                sum (rate(http_requests_total{job="foo-{{ .Variant.Name }}", status=~"5.*"}[5m]))
                /
                sum (rate(http_requests_total{job="foo-{{ .Variant.Name }}"}[5m]))

Like PREVIOUS, you specify the conditions for failure with deviation.

It generates different queries for Canary and Baseline to compare the metrics. You can use the Variant args to template the queries. Analysis Template uses the Go templating engine which only replaces values. This allows variant-specific data to be embedded in the query.

The available built-in args currently are:

Property	Type	Description
Variant.Name	string	“canary”, “baseline”, or “primary” will be populated

Also, you can define the custom args using baselineArgs and canaryArgs, and refer them like {{ .VariantCustom.Args.job }}.

          metrics:
            - strategy: CANARY_BASELINE
              provider: my-prometheus
              deviation: HIGH
              baselineArgs:
                job: bar
              canaryArgs:
                job: baz
              interval: 5m
              query: cpu_usage{job="{{ .VariantCustomArgs.job }}", status=~"5.*"}

With primary (not recommended):

If for some reason you cannot provide the Baseline variant, you can also compare Canary and Primary. However, we recommend that you compare it with Baseline that is a variant launched at the same time as Canary as much as possible.

Comparison algorithm

The metric comparison algorithm in PipeCD uses a nonparametric statistical test called Mann-Whitney U test to check for a significant difference between two metrics collection (like Canary and Baseline, or the previous deployment and the current metrics).

Example pipelines

Analyze the canary variant using the THRESHOLD strategy:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 20%
      - name: ANALYSIS
        with:
          duration: 30m
          metrics:
            - provider: my-prometheus
              interval: 10m
              expected:
                max: 0.1
              query: rate(cpu_usage_total{app="foo"}[10m])
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_CANARY_CLEAN

Analyze the primary variant using the PREVIOUS strategy:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_PRIMARY_ROLLOUT
      - name: ANALYSIS
        with:
          duration: 30m
          metrics:
            - strategy: PREVIOUS
              provider: my-prometheus
              interval: 5m
              deviation: HIGH
              query: rate(cpu_usage_total{app="foo"}[5m])

Analyze the canary variant using the CANARY_BASELINE strategy:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 20%
      - name: K8S_BASELINE_ROLLOUT
        with:
          replicas: 20%
      - name: ANALYSIS
        with:
          duration: 30m
          metrics:
            - strategy: CANARY_BASELINE
              provider: my-prometheus
              interval: 10m
              deviation: HIGH
              query: rate(cpu_usage_total{app="foo", variant="{{ .Variant.Name }}"}[10m])
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_CANARY_CLEAN
      - name: K8S_BASELINE_CLEAN

The full list of configurable ANALYSIS stage fields are here.

See more the example.

Analysis by logs

TBA

Analysis by http

TBA

[Optional] Analysis Template

Analysis Templating is a feature that allows you to define some shared analysis configurations to be used by multiple applications. These templates must be placed at the .pipe directory at the root of the Git repository. Any application in that Git repository can use to the defined template by specifying the name of the template in the application configuration file.

apiVersion: pipecd.dev/v1beta1
kind: AnalysisTemplate
spec:
  metrics:
    http_error_rate:
      interval: 30m
      provider: my-prometheus
      expected:
        max: 0
      query: |
        sum without(status) (rate(http_requests_total{status=~"5.*", job="{{ .App.Name }}"}[1m]))
        /
        sum without(status) (rate(http_requests_total{job="{{ .App.Name }}"}[1m]))

Once the AnalysisTemplate is defined, you can reference from the application configuration using the template field.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: ANALYSIS
        with:
          duration: 30m
          metrics:
            - template:
                name: http_error_rate

Analysis Template uses the Go templating engine which only replaces values. This allows deployment-specific data to be embedded in the analysis template.

The available built-in args are:

Property	Type	Description
App.Name	string	Application Name.
K8s.Namespace	string	The Kubernetes namespace where manifests will be applied.

Also, custom args is supported. Custom args placeholders can be defined as {{ .AppCustomArgs.<name> }}.

Of course, it can be used in conjunction with Variant args.

See here for more examples. And the full list of configurable AnalysisTemplate fields are here.

Docs-V0.56.x: Canary deployment for Kubernetes app with PodSelector

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

Using service mesh like Istio helps you doing canary deployment easier with many powerful features, but not all teams are ready to use service mesh in their environment. This page will walk you through using PipeCD to enable canary deployment for Kubernetes application running in a non-mesh environment.

Basically, the idea behind is described as this Kubernetes document; the Service resource uses the common label set to route the traffic to both canary and primary workloads, and percentage of traffic for each variant is based on their replicas number.

Enabling canary strategy

Assume your application has the following Service and Deployment manifests:

service.yaml

apiVersion: v1
kind: Service
metadata:
  name: helloworld
spec:
  selector:
    app: helloworld
  ports:
    - protocol: TCP
      port: 9085

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: helloworld
  labels:
    app: helloworld
    pipecd.dev/variant: primary
spec:
  replicas: 30
  revisionHistoryLimit: 2
  selector:
    matchLabels:
      app: helloworld
      pipecd.dev/variant: primary
  template:
    metadata:
      labels:
        app: helloworld
        pipecd.dev/variant: primary
    spec:
      containers:
      - name: helloworld
        image: gcr.io/pipecd/helloworld:v0.1.0
        args:
          - server
        ports:
          - containerPort: 9085

In PipeCD context, manifests defined in Git are the manifests for primary variant, so please note to ensure that your deployment manifest contains pipecd.dev/variant: primary label and selector in the spec.

To enable canary strategy for this Kubernetes application, you will update your application configuration file to be as below:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      # Deploy the workloads of CANARY variant. In this case, the number of
      # workload replicas of CANARY variant is 50% of the replicas number of PRIMARY variant.
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 50%
      - name: WAIT_APPROVAL
        with:
          duration: 10s
      # Update the workload of PRIMARY variant to the new version.
      - name: K8S_PRIMARY_ROLLOUT
      # Destroy all workloads of CANARY variant.
      - name: K8S_CANARY_CLEAN

That is all, now let try to send a PR to update the container image version in the Deployment manifest and merge it to trigger a new deployment. Then, PipeCD will plan the deployment with the specified canary strategy.

Deployment Details Page

Complete source code for this example is hosted in pipe-cd/examples repository.

Understanding what happened

In this example, you configured your application to be deployed with a canary strategy using a native feature of Kubernetes: pod selector. The traffic will be routed to both canary and primary workloads because they are sharing the same label: app: helloworld. The percentage of traffic for each variant is based on the respective number of pods.

Here are what happened in details:

Before deploying, all traffic gets routed to primary workloads.

Stage 1: K8S_CANARY_ROLLOUT ensures that the workloads of canary variant (new version) should be deployed. The number of workloads (e.g. pod) for canary variant is configured to be 50% of the replicas number of primary variant. It means 15 canary pods will be started, and they receive 33.3% traffic while primary workloads receive the remaining 66.7% traffic.

Stage 2: WAIT_APPROVAL waits for a manual approval from someone in your team.
Stage 3: K8S_PRIMARY_ROLLOUT ensures that all resources of primary variant will be updated to the new version.

Stage 4: K8S_CANARY_CLEAN ensures all created resources for canary variant should be destroyed. After that, the primary workloads running in with the new version will receive all traffic.

Docs-V0.56.x: Configuring Cloud Run application

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

Note: Cloud Run job has not been supported yet.

Deploying a Cloud Run application requires a service.yaml file placed inside the application directory. That file contains the service specification used by Cloud Run as follows:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE_NAME
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/maxScale: '5'
    spec:
      containerConcurrency: 80
      containers:
      - args:
        - server
        image: gcr.io/pipecd/helloworld:v0.5
        ports:
        - containerPort: 9085
        resources:
          limits:
            cpu: 1000m
            memory: 128Mi

Quick sync

By default, when the pipeline was not specified, PipeCD triggers a quick sync deployment for the merged pull request. Quick sync for a Cloud Run deployment will roll out the new version and switch all traffic to it.

Sync with the specified pipeline

The pipeline field in the application configuration is used to customize the way to do the deployment. You can add a manual approval before routing traffic to the new version or add an analysis stage to do some smoke tests against the new version before allowing them to receive the real traffic.

These are the provided stages for Cloud Run application you can use to build your pipeline:

CLOUDRUN_PROMOTE
- promote the new version to receive an amount of traffic

and other common stages:

WAIT
WAIT_APPROVAL
ANALYSIS

See the description of each stage at Customize application deployment.

Here is an example that rolls out the new version gradually:

apiVersion: pipecd.dev/v1beta1
kind: CloudRunApp
spec:
  pipeline:
    stages:
      # Promote new version to receive 10% of traffic.
      - name: CLOUDRUN_PROMOTE
        with:
          percent: 10
      - name: WAIT
        with:
          duration: 10m
      # Promote new version to receive 50% of traffic.
      - name: CLOUDRUN_PROMOTE
        with:
          percent: 50
      - name: WAIT
        with:
          duration: 10m
      # Promote new version to receive all traffic.
      - name: CLOUDRUN_PROMOTE
        with:
          percent: 100

Reference

See Configuration Reference for the full configuration.

Docs-V0.56.x: Contribute to PipeCD Blogs

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

We welcome blog contributions from the community! Blog posts are a great way to share your experiences, tutorials, and insights about PipeCD with other users.

What makes a good blog post?

Blog posts can cover a variety of topics, including:

Announcements: New features, releases, or project updates
Tutorials: Step-by-step guides on using PipeCD features
Use cases: How you or your organization uses PipeCD
Best practices: Tips and tricks for getting the most out of PipeCD
Integrations: How to integrate PipeCD with other tools

Where blog posts live

Blog posts are located in the /docs/content/en/blog/ directory within the pipe-cd/pipecd repository.

Blog post format

Each blog post is a Markdown file with YAML front matter. Here’s the structure:

---
date: 2025-01-03
title: "Your Blog Post Title"
linkTitle: "Short Title for Navigation"
weight: 980
description: "A brief description of your post"
author: Your Name ([@your-github-handle](https://github.com/your-github-handle))
categories: ["Announcement"]
tags: ["Tag1", "Tag2"]
---

Your content here...

Front matter fields

Field	Required	Description
`date`	Yes	Publication date in `YYYY-MM-DD` format
`title`	Yes	Full title of your blog post
`linkTitle`	Yes	Shorter title used in navigation menus
`weight`	Yes	Controls ordering (lower = newer, typically use ~980-990)
`description`	No	Brief summary for SEO and previews
`author`	Yes	Your name with GitHub profile link
`categories`	Yes	One of: `Announcement`, `Tutorial`, `Release`
`tags`	No	Relevant keywords for your post

Content guidelines

Use clear, concise language
Include code examples where appropriate (use fenced code blocks with language identifiers)
Add images to /docs/static/images/ and reference them as ![alt text](/images/your-image.png)
Structure your post with headings (##, ###) for readability
Include a conclusion or summary section

How to submit your blog post

Fork and clone the pipecd repository
Create a branch for your blog post:
```
git checkout -b blog/your-post-title
```
Create your blog post file in /docs/content/en/blog/:
```
touch docs/content/en/blog/your-post-title.md
```
Add any images to /docs/static/images/
Preview locally by running:
```
make run/site
```
Then visit http://localhost:1313/blog/ to see your post.

Commit and push your changes:

git add .
git commit -s -m "blog: add post about your-topic"
git push origin blog/your-post-title

Open a Pull Request against the master branch

Review process

A maintainer will review your blog post for:

Technical accuracy
Clarity and readability
Adherence to the format guidelines
Appropriate use of images and code examples

Feel free to reach out on the #pipecd Slack channel if you have questions or want feedback on your draft before submitting.

Thank you for contributing to the PipeCD blog!

Docs-V0.56.x: Installing on Cloud Run

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

Prerequisites

Having piped’s ID and Key strings

Ensure that the piped has been registered and you are having its PIPED_ID and PIPED_KEY strings.
If you are not having them, this page guides you how to register a new one.

Preparing SSH key

If your Git repositories are private, piped requires a private SSH key to access those repositories.
Please checkout this documentation for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository’s Settings page.)

Installation

Preparing a piped configuration file as the following:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: {PROJECT_ID}
  pipedID: {PIPED_ID}
  pipedKeyData: {BASE64_ENCODED_PIPED_KEY}
  # Write in a format like "host:443" because the communication is done via gRPC.
  apiAddress: {CONTROL_PLANE_API_ADDRESS}

  git:
    sshKeyData: {BASE64_ENCODED_PRIVATE_SSH_KEY}

  repositories:
    - repoId: {REPO_ID_OR_NAME}
      remote: git@github.com:{GIT_ORG}/{GIT_REPO}.git
      branch: {GIT_BRANCH}

  # Optional
  # Enable this Piped to handle Cloud Run application.
  platformProviders:
    - name: cloudrun-in-project
      type: CLOUDRUN
      config:
        project: {GCP_PROJECT_ID}
        region: {GCP_PROJECT_REGION}

  # Optional
  # Uncomment this if you want to enable this Piped to handle Terraform application.
  #  - name: terraform-gcp
  #    type: TERRAFORM

  # Optional
  # Uncomment this if you want to enable SecretManagement feature.
  # https://pipecd.dev//docs/user-guide/managing-application/secret-management/
  # secretManagement:
  #   type: KEY_PAIR
  #   config:
  #     privateKeyData: {BASE64_ENCODED_PRIVATE_KEY}
  #     publicKeyData: {BASE64_ENCODED_PUBLIC_KEY}

See ConfigurationReference for the full configuration.

Creating a new secret in SecretManager to store above configuration data securely
```
gcloud secrets create cloudrun-piped-config --data-file={PATH_TO_CONFIG_FILE}
```
then make sure that Cloud Run has the ability to access that secret as this guide.

Running Piped in Cloud Run

Prepare a Cloud Run service manifest file as below.

# Enable remote-upgrade feature of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-upgrade
# This allows upgrading Piped to a new version from the web console.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: piped
  annotaions:
    run.googleapis.com/ingress: internal
    run.googleapis.com/ingress-status: internal
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/maxScale: '1'           # This must be 1.
        autoscaling.knative.dev/minScale: '1'           # This must be 1.
        run.googleapis.com/cpu-throttling: "false"      # This is required.
    spec:
      containerConcurrency: 1                           # This must be 1 to ensure Piped work correctly.
      containers:
        - image: gcr.io/pipecd/launcher:v0.56.0
          args:
            - launcher
            - --launcher-admin-port=9086
            - --config-file=/etc/piped-config/config.yaml
          ports:
            - containerPort: 9086
          volumeMounts:
            - mountPath: /etc/piped-config
              name: piped-config
          resources:
            limits:
              cpu: 1000m
              memory: 2Gi
      volumes:
        - name: piped-config
          secret:
            secretName: cloudrun-piped-config
            items:
              - path: config.yaml
                key: latest

# This just installs a Piped with the specified version.
# Whenever you want to upgrade that Piped to a new version or update its config data you have to restart it.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: piped
  annotaions:
    run.googleapis.com/ingress: internal
    run.googleapis.com/ingress-status: internal
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/maxScale: '1'           # This must be 1.
        autoscaling.knative.dev/minScale: '1'           # This must be 1.
        run.googleapis.com/cpu-throttling: "false"      # This is required.
    spec:
      containerConcurrency: 1                           # This must be 1.
      containers:
        - image: gcr.io/pipecd/piped:v0.56.0
          args:
            - piped
            - --config-file=/etc/piped-config/config.yaml
          ports:
            - containerPort: 9085
          volumeMounts:
            - mountPath: /etc/piped-config
              name: piped-config
          resources:
            limits:
              cpu: 1000m
              memory: 2Gi
      volumes:
        - name: piped-config
          secret:
            secretName: cloudrun-piped-config
            items:
              - path: config.yaml
                key: latest

Run Piped service on Cloud Run with the following command:

gcloud beta run services replace cloudrun-piped-service.yaml

Note: Make sure that the created secret is accessible from this Piped service. See more here.

Docs-V0.56.x: Adding a platform provider

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

PipeCD supports multiple platforms and multiple application kinds which run on those platforms. Platform provider defines which platform and where the application should be deployed to. So while registering a new application, the name of a configured platform provider is required.

Currently, PipeCD is supporting these five kinds of platform providers: KUBERNETES, ECS, TERRAFORM, CLOUDRUN, LAMBDA. A new platform provider can be enabled by adding a PlatformProvider struct to the piped configuration file. A piped can have one or multiple platform provider instances from the same or different platform provider kind.

The next sections show the specific configuration for each kind of platform provider.

Configuring Kubernetes platform provider

By default, piped deploys Kubernetes application to the cluster where the piped is running in. An external cluster can be connected by specifying the masterURL and kubeConfigPath in the configuration.

And, the default resources (defined at here) from all namespaces of the Kubernetes cluster will be watched for rendering the application state in realtime and detecting the configuration drift. In case you want to restrict piped to watch only a single namespace, let specify the namespace in the KubernetesAppStateInformer field. You can also add other resources or exclude resources to/from the watching targets by that field.

Below configuration snippet just specifies a name and type of platform provider. It means the platform provider kubernetes-dev will connect to the Kubernetes cluster where the piped is running in, and this platform provider watches all of the predefined resources from all namespaces inside that cluster.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  ...
  platformProviders:
    - name: kubernetes-dev
      type: KUBERNETES

See ConfigurationReference for the full configuration.

Configuring Terraform platform provider

A terraform platform provider contains a list of shared terraform variables that will be applied while running the deployment of its applications.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  ...
  platformProviders:
    - name: terraform-dev
      type: TERRAFORM
      config:
        vars:
          - "project=pipecd"

See ConfigurationReference for the full configuration.

Configuring Cloud Run platform provider

Adding a Cloud Run provider requires the name of the Google Cloud project and the region name where Cloud Run service is running. A service account file for accessing to Cloud Run is also required if the machine running the piped does not have enough permissions to access.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  ...
  platformProviders:
    - name: cloudrun-dev
      type: CLOUDRUN
      config:
        project: {GCP_PROJECT}
        region: {CLOUDRUN_REGION}
        credentialsFile: {PATH_TO_THE_SERVICE_ACCOUNT_FILE}

See ConfigurationReference for the full configuration.

Configuring Lambda platform provider

Adding a Lambda provider requires the region name where Lambda service is running.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  ...
  platformProviders:
    - name: lambda-dev
      type: LAMBDA
      config:
        region: {LAMBDA_REGION}
        profile: default
        credentialsFile: {PATH_TO_THE_CREDENTIAL_FILE}

You will generally need your AWS credentials to authenticate with Lambda. Piped provides multiple methods of loading these credentials. It attempts to retrieve credentials in the following order:

From the environment variables. Available environment variables are AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY and AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY.
From the given credentials file. (the credentialsFile field in above sample)
From the pod running in EKS cluster via STS (SecurityTokenService).
From the EC2 Instance Role.

Therefore, you don’t have to set credentialsFile if you use the environment variables or the EC2 Instance Role. Keep in mind the IAM role/user that you use with your Piped must possess the IAM policy permission for at least Lambda.Function and Lambda.Alias resources controll (list/read/write).

See ConfigurationReference for the full configuration.

Configuring ECS platform provider

Adding a ECS provider requires the region name where ECS cluster is running.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  ...
  platformProviders:
    - name: ecs-dev
      type: ECS
      config:
        region: {ECS_CLUSTER_REGION}
        profile: default
        credentialsFile: {PATH_TO_THE_CREDENTIAL_FILE}

Just same as Lambda platform provider, there are several ways to authorize Piped agent to enable it performs deployment jobs. It attempts to retrieve credentials in the following order:

From the environment variables. Available environment variables are AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY and AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY.
From the given credentials file. (the credentialsFile field in above sample)
From the pod running in EKS cluster via STS (SecurityTokenService).
From the EC2 Instance Role.

See ConfigurationReference for the full configuration.

Docs-V0.56.x: BlueGreen deployment for Kubernetes app with PodSelector

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

TBA

For applications that are not deployed on a service mesh, PipeCD can enable blue-green deployment with Kubernetes L4 networking.

Docs-V0.56.x: Custom Sync

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

CUSTOM_SYNC is one stage in the pipeline and you can define scripts to deploy run in this stage.

Note: This feature is marked as a deprecated feature and will be removed later.

How to configure Custom Sync

Add a CUSTOM_SYNC to your pipeline and write commands to deploy your infrastructure. The commands run in the directory where this application configuration file exists.

apiVersion: pipecd.dev/v1beta1
kind: LambdaApp
spec:
  name: sam-simple
  labels:
    env: example
    team: abc
  planner:
    # Must add this configuration to force use CUSTOM_SYNC stage.
    alwaysUsePipeline: true
  pipeline:
    stages:
      - name: CUSTOM_SYNC
        with:
          envs:
            AWS_PROFILE: "sample"
          run: |
            cd sam-app
            sam build
            echo y | sam deploy --profile $AWS_PROFILE

Note:

You can use CUSTOM_SYNC with any current supporting application kind, but keep alwaysUsePipeline true to not run the application kind’s default QUICK_SYNC.
Only one CUSTOM_SYNC stage should be used in an application pipeline.
The commands run with the environment variable PATH that refers ~/.piped/tools at first.

The public piped image available in PipeCD main repo (ref: Dockerfile) is based on alpine and only has a few UNIX command available (ref: piped-base Dockerfile). If you want to use your commands (sam in the above example), you can:

Prepare your own environment container image then add piped binary to it.
Build your own container image based on ghcr.io/pipe-cd/piped image.
Manually update your running piped container (not recommended).

Auto Rollback

When autoRollback is enabled, the deployment will be rolled back in the same way as Rolling Back.

When the rolling back process is triggered in the pipeline including CUSTOM_SYNC, CUSTOM_SYNC_ROLLBACK stage will be added to the deployment pipeline. CUSTOM_SYNC_ROLLBACK is different from ROLLBACK that applications set defaultly, it runs the same commands as CUSTOM_SYNC in the runnning commit to reverts all the applied changes.

Docs-V0.56.x: Installing on ECS Fargate

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

Prerequisites

Having piped’s ID and Key strings

Ensure that the piped has been registered and you are having its PIPED_ID and PIPED_KEY strings.
If you are not having them, this page guides you how to register a new one.

Preparing SSH key

If your Git repositories are private, piped requires a private SSH key to access those repositories.
Please checkout this documentation for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository’s Settings page.)

Installation

Preparing a piped configuration file as follows:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: {PROJECT_ID}
  pipedID: {PIPED_ID}
  pipedKeyData: {BASE64_ENCODED_PIPED_KEY}
  # Write in a format like "host:443" because the communication is done via gRPC.
  apiAddress: {CONTROL_PLANE_API_ADDRESS}

  git:
    sshKeyData: {BASE64_ENCODED_PRIVATE_SSH_KEY}

  repositories:
    - repoId: {REPO_ID_OR_NAME}
      remote: git@github.com:{GIT_ORG}/{GIT_REPO}.git
      branch: {GIT_BRANCH}

  # Optional
  # Enable this Piped to handle ECS application.
  platformProviders:
    - name: ecs-dev
      type: ECS
      config:
        region: {ECS_RUNNING_REGION}

  # Optional
  # Uncomment this if you want to enable this Piped to handle Terraform application.
  #  - name: terraform-dev
  #    type: TERRAFORM

  # Optional
  # Uncomment this if you want to enable SecretManagement feature.
  # https://pipecd.dev//docs/user-guide/managing-application/secret-management/
  # secretManagement:
  #   type: KEY_PAIR
  #   config:
  #     privateKeyData: {BASE64_ENCODED_PRIVATE_KEY}
  #     publicKeyData: {BASE64_ENCODED_PUBLIC_KEY}

See ConfigurationReference for the full configuration.

Store the above configuration data to AWS to enable using it while creating piped task. Both AWS Secrets Manager and AWS Systems Manager Parameter Store are available to address this task.

  aws secretsmanager create-secret --name PipedConfig \
    --description "Configuration of piped running as ECS Fargate task" \
    --secret-string `base64 piped-config.yaml`

  aws ssm put-parameter \
    --name PipedConfig \
    --value `base64 piped-config.yaml` \
    --type SecureString

Prepare task definition for your piped task. Basically, you can just define your piped TaskDefinition as normal TaskDefinition, the only thing that needs to be beware is, in case you used AWS Secrets Manager to store piped configuration, to enable your piped accesses it’s configuration we created as a secret on above, you need to add secretsmanager:GetSecretValue policy to your piped task executionRole. Read more in Required IAM permissions for Amazon ECS secrets.

A sample TaskDefinition for Piped as follows

# Enable remote-upgrade feature of Piped.
# https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-upgrade
# This allows upgrading Piped to a new version from the web console.

{
  "family": "piped",
  "executionRoleArn": "{PIPED_TASK_EXECUTION_ROLE_ARN}",
  "containerDefinitions": [
    {
      "name": "piped",
      "essential": true,
      "image": "ghcr.io/pipe-cd/launcher:v0.56.0",
      "entryPoint": [
        "sh",
        "-c"
      ],
      "command": [
        "/bin/sh -c \"launcher launcher --config-data=$(echo $CONFIG_DATA)\""
      ],
      "secrets": [
        {
          "valueFrom": "{PIPED_SECRET_MANAGER_ARN}",
          "name": "CONFIG_DATA"
        }
      ],
    }
  ],
  "requiresCompatibilities": [
    "FARGATE"
  ],
  "networkMode": "awsvpc",
  "memory": "512",
  "cpu": "256"
}

# This just installs a Piped with the specified version.
# Whenever you want to upgrade that Piped to a new version or update its config data you have to restart it.

{
  "family": "piped",
  "executionRoleArn": "{PIPED_TASK_EXECUTION_ROLE_ARN}",
  "containerDefinitions": [
    {
      "name": "piped",
      "essential": true,
      "image": "ghcr.io/pipe-cd/piped:v0.56.0",
      "entryPoint": [
        "sh",
        "-c"
      ],
      "command": [
        "/bin/sh -c \"piped piped --config-data=$(echo $CONFIG_DATA)\""
      ],
      "secrets": [
        {
          "valueFrom": "{PIPED_SECRET_MANAGER_ARN}",
          "name": "CONFIG_DATA"
        }
      ],
    }
  ],
  "requiresCompatibilities": [
    "FARGATE"
  ],
  "networkMode": "awsvpc",
  "memory": "512",
  "cpu": "256"
}

aws ecs register-task-definition --cli-input-json file://taskdef.json
aws ecs run-task --cluster {ECS_CLUSTER} --task-definition piped

Once the task is created, it will run continuously because of the piped execution. Since this task is run without startedBy setting, in case the piped is stopped, it will not automatically be restarted. To do so, you must define an ECS service to control piped task deployment.

A sample Service definition to control piped task deployment.

{
  "cluster": "{ECS_CLUSTER}",
  "serviceName": "piped",
  "desiredCount": 1, # This must be 1.
  "taskDefinition": "{PIPED_TASK_DEFINITION_ARN}",
  "deploymentConfiguration": {
    "minimumHealthyPercent": 0,
    "maximumPercent": 100
  },
  "schedulingStrategy": "REPLICA",
  "launchType": "FARGATE",
  "networkConfiguration": {
    "awsvpcConfiguration": {
      "assignPublicIp": "ENABLED", # This is need to enable ECS deployment to pull piped container images.
      ...
    }
  }
}

Then start your piped task controller service.

aws ecs create-service \
  --cluster {ECS_CLUSTER} \
  --service-name piped \
  --cli-input-json file://service.json

Docs-V0.56.x: Configuring Lambda application

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

Deploying a Lambda application requires a function.yaml file placed inside the application directory. That file contains values to be used to deploy Lambda function on your AWS cluster. Currently, Piped supports deploying all types of Lambda deployment packages:

container images (called container image as Lambda function)
.zip file archives (which stored in AWS S3)

Besides, Piped also supports deploying your Lambda function directly from the function source code which is stored in a remote git repository.

Deploy container image as Lambda function

A sample function.yaml file for container image as Lambda function used deployment as follows:

apiVersion: pipecd.dev/v1beta1
kind: LambdaFunction
spec:
  name: SimpleFunction
  image: ecr.ap-northeast-1.amazonaws.com/lambda-test:v0.0.1
  role: arn:aws:iam::76xxxxxxx:role/lambda-role
  # The amount of memory available to the Lambda application 
  # at runtime. The value can be any multiple of 1 MB.
  memory: 512
  # Timeout of the Lambda application, the value must
  # in between 1 to 900 seconds.
  timeout: 30
  tags:
    app: simple
  environments:
    FOO: bar
  # ephemeralStorage is optional value. If you define a ephemeral storage to lambda, you can
  # use this field. The value must be in between 512 to 10240 MB.
  ephemeralStorage:
    size: 512
  # vpcConfig is optional value. If you define a vpc configuration to lambda, you can
  # use this field.
  vpcConfig:
    securityGroupIds:
      - sg-01234
      - sg-56789
    subnetIds:
      - subnet-01234
      - subnet-56789

Except the tags and the environments field, all others are required fields for the deployment to run.

The role value represents the service role (for your Lambda function to run), not for Piped agent to deploy your Lambda application. To be able to pull container images from AWS ECR, besides policies to run as usual, you need to add Lambda.ElasticContainerRegistry read permission to your Lambda function service role.

The environments field represents environment variables that can be accessed by your Lambda application at runtime. In case of no value set for this field, all environment variables for the deploying Lambda application will be revoked, so make sure you set all currently required environment variables of your running Lambda application on function.yaml if you migrate your app to PipeCD deployment.

Deploy .zip file archives as Lambda function

It’s recommended to use container image as Lambda function due to its simplicity, but as mentioned above, below is a sample function.yaml file for Lambda which uses zip packing source code stored in AWS S3.

apiVersion: pipecd.dev/v1beta1
kind: LambdaFunction
spec:
  name: SimpleZipPackingS3Function
  role: arn:aws:iam::76xxxxxxx:role/lambda-role
  # --- 3 next lines allow Piped to determine your Lambda function code stored in AWS S3.
  s3Bucket: pipecd-sample-lambda
  s3Key: pipecd-sample-src
  s3ObjectVersion: 1pTK9_v0Kd7I8Sk4n6abzCL
  # ---
  handler: app.lambdaHandler
  runtime: nodejs14.x
  memory: 512
  timeout: 30
  environments:
    FOO: bar
  tags:
    app: simple-zip-s3

Value for the runtime field should be listed in AWS Lambda runtimes official docs. All other fields setting are remained as in the case of using container image as Lambda function pattern.

Deploy source code directly as Lambda function

In case you don’t have a separated CI pipeline that provides artifacts (such as container image, built zip files) as its outputs and want to set up a simple pipeline to deploy the Lambda function directly from your source code, this deployment package is for you.

apiVersion: pipecd.dev/v1beta1
kind: LambdaFunction
spec:
  name: SimpleCanaryZipFunction
  role: arn:aws:iam::76xxxxxxx:role/lambda-role
  # source configuration use to determine the source code of your Lambda function.
  source:
    # git remote address where the source code is placing.
    git: git@github.com:username/lambda-function-code.git
    # the commit SHA or tag for remote git. Use branch name means you will always use
    # the latest code of that branch as Lambda function code which is NOT recommended.
    ref: dede7cdea5bbd3fdbcc4674bfcd2b2f9e0579603
    # relative path from the repository root directory to the function code directory.
    path: hello-world
  handler: app.lambdaHandler
  runtime: nodejs14.x
  memory: 128
  timeout: 5
  tags:
    app: canary-zip

All other fields setting are remained as in the case of using .zip archives as Lambda function pattern.

Quick sync

By default, when the pipeline was not specified, PipeCD triggers a quick sync deployment for the merged pull request. Quick sync for a Lambda deployment will roll out the new version and switch all traffic to it.

Sync with the specified pipeline

These are the provided stages for Lambda application you can use to build your pipeline:

LAMBDA_CANARY_ROLLOUT
- deploy workloads of the new version, but it is still receiving no traffic.
LAMBDA_PROMOTE
- promote the new version to receive an amount of traffic.

and other common stages:

WAIT
WAIT_APPROVAL
ANALYSIS

See the description of each stage at Customize application deployment.

Here is an example that rolls out the new version gradually:

apiVersion: pipecd.dev/v1beta1
kind: LambdaApp
spec:
  pipeline:
    stages:
      # Deploy workloads of the new version.
      # But this is still receiving no traffic.
      - name: LAMBDA_CANARY_ROLLOUT
      # Promote new version to receive 10% of traffic.
      - name: LAMBDA_PROMOTE
        with:
          percent: 10
      - name: WAIT
        with:
          duration: 10m
      # Promote new version to receive 50% of traffic.
      - name: LAMBDA_PROMOTE
        with:
          percent: 50
      - name: WAIT
        with:
          duration: 10m
      # Promote new version to receive all traffic.
      - name: LAMBDA_PROMOTE
        with:
          percent: 100

Reference

See Configuration Reference for the full configuration.

Docs-V0.56.x: Registering a piped

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

The list of pipeds is shown on the Settings page. Anyone who has the project admin role can register a new piped by clicking on the +ADD button.

Registering a new piped

Docs-V0.56.x: Script Run stage

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

SCRIPT_RUN stage is one stage in the pipeline and you can execute any commands.

Note: This feature is at the alpha status. Currently you can use it on all application kinds, but the rollback feature is only for the application kind of KubernetesApp.

How to configure SCRIPT_RUN stage

Add a SCRIPT_RUN to your pipeline and write commands.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: canary-with-script-run
  labels:
    env: example
    team: product
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 10%
      - name: WAIT
        with:
          duration: 10s
      - name: SCRIPT_RUN
        with:
          env:
            MSG: "execute script1"
          run: |
            echo $MSG
            sleep 10
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_CANARY_CLEAN
      - name: SCRIPT_RUN
        with:
          env:
            MSG: "execute script2"
          run: |
            echo $MSG
            sleep 10

You can define the command as run. Also, if you want to use some values as variables, you can define them as env.

The commands run in the directory where this application configuration file exists.

Execute the script file

If your script is so long, you can separate the script as a file. You can put the file with the app.pipecd.yaml in the same dir and then you can execute the script like this.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: script-run
  pipeline:
    stages:
      - name: SCRIPT_RUN
        with:
          run: |
            sh script.sh

.
├── app.pipecd.yaml
└── script.sh

Builtin commands

Currently, you can use the commands which are installed in the environment for the piped.

For example, If you are using the container platform and the offcial piped container image, you can use the command below.

git
ssh
jq
curl
commands installed by piped in $PIPED_TOOL_DIR (check at runtime)
built-in commands installed in the base image

The public piped image available in PipeCD main repo (ref: Dockerfile) is based on alpine and only has a few UNIX commands available (ref: piped-base Dockerfile).

If you want to use your commands, you can realize it with either step below.

Prepare your own environment container image then add piped binary to it.
Build your own container image based on ghcr.io/pipe-cd/piped image.

Default environment values

You can use the envrionment values related to the deployment.

Name	Description	Example
SR_DEPLOYMENT_ID	The deployment id	877625fc-196a-40f9-b6a9-99decd5494a0
SR_APPLICATION_ID	The application id	8d7609e0-9ff6-4dc7-a5ac-39660768606a
SR_APPLICATION_NAME	The application name	example
SR_TRIGGERED_AT	The timestamp when the deployment is triggered	1719571113
SR_TRIGGERED_COMMIT_HASH	The commit hash that triggered the deployment	2bf969a3dad043aaf8ae6419943255e49377da0d
SR_TRIGGERED_COMMANDER	The ID of user who triggered the deployment via UI. This is APIKey’s ID if it was triggered via `pipectl sync`. This is empty if it was triggered by your piped.	userid
SR_REPOSITORY_URL	The repository url configured in the piped config	git@github.com:org/repo.git, https://github.com/org/repo
SR_SUMMARY	The summary of the deployment	Sync with the specified pipeline because piped received a command from user via web console or pipectl
SR_CONTEXT_RAW	The json encoded string of above values	{“deploymentID”:“877625fc-196a-40f9-b6a9-99decd5494a0”,“applicationID”:“8d7609e0-9ff6-4dc7-a5ac-39660768606a”,“applicationName”:“example”,“triggeredAt”:1719571113,“triggeredCommitHash”:“2bf969a3dad043aaf8ae6419943255e49377da0d”,“repositoryURL”:“git@github.com:org/repo.git”,“labels”:{“env”:“example”,“team”:“product”}}
SR_LABELS_XXX	The label attached to the deployment. The env name depends on the label name. For example, if a deployment has the labels `env:prd` and `team:server`, `SR_LABELS_ENV` and `SR_LABELS_TEAM` are registered.	prd, server
SR_IS_ROLLBACK	This is `true` if the deployment is rollbacking. Otherwise, this is `false`.	false

Use `SR_CONTEXT_RAW` with jq

You can use jq command to refer to the values from SR_CONTEXT_RAW.

      - name: SCRIPT_RUN
        with:
          run: |
            echo "Get deploymentID from SR_CONTEXT_RAW"
            echo $SR_CONTEXT_RAW | jq -r '.deploymentID'
            sleep 10
          onRollback: |
            echo "rollback script-run"

Rollback

Note: Currently, this feature is only for the application kind of KubernetesApp.

You can define the command as onRollback to execute when to rollback similar to run. Execute the command to rollback SCRIPT_RUN to the point where the deployment was canceled or failed.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: canary-with-script-run
  labels:
    env: example
    team: product
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 10%
      - name: WAIT
        with:
          duration: 10s
      - name: SCRIPT_RUN
        with:
          env:
            MSG: "execute script1"
            R_MSG: "rollback script1"
          run: |
            echo $MSG
            sleep 10
          onRollback: |
            echo $R_MSG
            sleep 10
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_CANARY_CLEAN

The command defined as onRollback is executed as SCRIPT_RUN_ROLLBACK stage after each ROLLBACK stage.

When there are multiple SCRIPT_RUN stages, they are executed in the same order as SCRIPT_RUN on the pipeline. Also, only for the executed SCRIPT_RUNs are rollbacked.

For example, consider when deployment proceeds in the following order from 1 to 7.

1. K8S_CANARY_ROLLOUT
2. WAIT
3. SCRIPT_RUN
4. K8S_PRIMARY_ROLLOUT
5. SCRIPT_RUN
6. K8S_CANARY_CLEAN
7. SCRIPT_RUN

Then

If 3 is canceled or fails while running, only SCRIPT_RUN of 3 will be rollbacked.
If 4 is canceled or fails while running, only SCRIPT_RUN of 3 will be rollbacked.
If 6 is canceled or fails while running, only SCRIPT_RUNs 3 and 5 will be rollbacked. The order of executing is 3 -> 5.

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: Adding a Helm chart repository or registry

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

PipeCD supports Kubernetes applications that are using Helm for templating and packaging. In addition to being able to deploy a Helm chart that is sourced from the same Git repository (local chart) or from a different Git repository (remote git chart), an application can use a chart sourced from a Helm chart repository.

Adding Helm chart repository

A Helm chart repository is a location backed by an HTTP server where packaged charts can be stored and shared. Before an application can be configured to use a chart from a Helm chart repository, that chart repository must be enabled in the related piped by adding the ChartRepository struct to the piped configuration file.

# piped configuration file
apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  ...
  chartRepositories:
    - name: pipecd
      address: https://charts.pipecd.dev

For example, the above snippet enables the official chart repository of PipeCD project. After that, you can configure the Kubernetes application to load a chart from that chart repository for executing the deployment.

# Application configuration file.
apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  input:
    # Helm chart sourced from a Helm Chart Repository.
    helmChart:
      repository: pipecd
      name: helloworld
      version: v0.5.0

In case the chart repository is backed by HTTP basic authentication, the username and password strings are required in configuration.

Adding Helm chart registry

A Helm chart registry is a mechanism enabled by default in Helm 3.8.0 and later that allows the OCI registry to be used for storage and distribution of Helm charts.

Before an application can be configured to use a chart from a registry, that registry must be enabled in the related piped by adding the ChartRegistry struct to the piped configuration file if authentication is enabled at the registry.

# piped configuration file
apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  ...
  chartRegistries:
    - type: OCI
      address: registry.example.com
      username: sample-username
      password: sample-password

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: Configuring ECS application

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

There are two main ways to deploy an Amazon ECS application.

Your application is a one-time or periodic batch job.
- it’s a standalone task.
- you need to prepare TaskDefinition
Your application is deployed to run continuously or behind a load balancer.
- you need to prepare TaskDefinition and Service

To deploy an Amazon ECS application, the TaskDefinition configuration file must be located in the application directory. This file contains all configuration for ECS TaskDefinition object and will be used by Piped agent while deploying your application/service to the ECS cluster.

To deploy your application to run continuously or to place it behind a load balancer, You need to create ECS Service. The Service configuration file also must be located in the application directory. This file contains all configurations for ECS Service object.

If you’re not familiar with ECS, you can get examples for those files from here.

Note:

You can generate an application config file easily and interactively by pipectl init.

Quick sync

By default, when the pipeline was not specified, PipeCD triggers a quick sync deployment for the merged pull request. Quick sync for an ECS deployment will roll out the new version and switch all traffic to it immediately.

In case of standalone task, only Quick sync is supported.

Here is an example for Quick sync.

apiVersion: pipecd.dev/v1beta1
kind: ECSApp
spec:
  name: simple
  labels:
    env: example
    team: xyz
  input:
    # Path to Service configuration file in Yaml/JSON format.
    serviceDefinitionFile: servicedef.yaml
    # Path to TaskDefinition configuration file in Yaml/JSON format.
    # Default is `taskdef.json`
    taskDefinitionFile: taskdef.yaml
    targetGroups:
      primary:
        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-lb/YYYY
        containerName: web
        containerPort: 80

apiVersion: pipecd.dev/v1beta1
kind: ECSApp
spec:
  name: standalonetask-fargate
  labels:
    env: example
    team: xyz
  input:
    # Path to TaskDefinition configuration file in Yaml/JSON format.
    # Default is `taskdef.json`
    taskDefinitionFile: taskdef.yaml
    clusterArn: arn:aws:ecs:ap-northeast-1:XXXX:cluster/test-cluster
    awsvpcConfiguration:
      assignPublicIp: ENABLED
      subnets:
        - subnet-YYYY
        - subnet-YYYY
      securityGroups:
          - sg-YYYY

Sync with the specified pipeline

These are the provided stages for ECS application you can use to build your pipeline:

ECS_CANARY_ROLLOUT
- deploy workloads of the new version as CANARY variant, but it is still receiving no traffic.
ECS_PRIMARY_ROLLOUT
- deploy workloads of the new version as PRIMARY variant, but it is still receiving no traffic.
ECS_TRAFFIC_ROUTING
- routing traffic to the specified variants.
ECS_CANARY_CLEAN
- destroy all workloads of CANARY variant.

and other common stages:

WAIT
WAIT_APPROVAL
ANALYSIS

See the description of each stage at Customize application deployment.

Here is an example that rolls out the new version gradually:

apiVersion: pipecd.dev/v1beta1
kind: ECSApp
spec:
  input:
    # Path to Service configuration file in Yaml/JSON format.
    serviceDefinitionFile: servicedef.yaml
    # Path to TaskDefinition configuration file in Yaml/JSON format.
    # Default is `taskdef.json`
    taskDefinitionFile: taskdef.yaml
    targetGroups:
      primary:
        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-canary-blue/YYYY
        containerName: web
        containerPort: 80
      canary:
        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-canary-green/YYYY
        containerName: web
        containerPort: 80
  pipeline:
    stages:
      # Deploy the workloads of CANARY variant, the number of workload
      # for CANARY variant is equal to 30% of PRIMARY's workload.
      # But this is still receiving no traffic.
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 30
      # Change the traffic routing state where
      # the CANARY workloads will receive the specified percentage of traffic.
      # This is known as multi-phase canary strategy.
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 20
      # Optional: We can also add an ANALYSIS stage to verify the new version.
      # If this stage finds any not good metrics of the new version,
      # a rollback process to the previous version will be executed.
      - name: ANALYSIS
      # Update the workload of PRIMARY variant to the new version.
      - name: ECS_PRIMARY_ROLLOUT
      # Change the traffic routing state where
      # the PRIMARY workloads will receive 100% of the traffic.
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100
      # Destroy all workloads of CANARY variant.
      - name: ECS_CANARY_CLEAN

NOTE

When you use an ELB for deployments, all listener rules that have the same target groups as configured in app.pipecd.yaml will be controlled.
- That means you need to link target groups to your listener rules before deployments.
- For more information and diagrams, see Issue#4733 [ECS] Modify ELB listener rules other than defaults without adding config.
When you use Service Connect, you cannot use Canary or Blue/Green deployment yet because Service Connect does not support the external deployment yet.
When you use AutoScaling for a service, you can disable reconciling desiredCount by following steps.
1. Create a service without defining desiredCount in the service definition file. See Restrictions of Service Definition.
2. Configure AutoScaling by yourself.

Reference

See Configuration Reference for the full configuration.

Docs-V0.56.x: Installing on a single machine

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

Prerequisites

Having piped’s ID and Key strings

Ensure that the piped has been registered and you are having its PIPED_ID and PIPED_KEY strings.
If you are not having them, this page guides you how to register a new one.

Preparing SSH key

If your Git repositories are private, piped requires a private SSH key to access those repositories.
Please checkout this documentation for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository’s Settings page.)

Installation

Downloading the latest piped binary for your machine

https://github.com/pipe-cd/pipecd/releases

Preparing a piped configuration file as the following:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: {PROJECT_ID}
  pipedID: {PIPED_ID}
  pipedKeyFile: {PATH_TO_PIPED_KEY_FILE}
  # Write in a format like "host:443" because the communication is done via gRPC.
  apiAddress: {CONTROL_PLANE_API_ADDRESS}
  git:
    sshKeyFile: {PATH_TO_SSH_KEY_FILE}
  repositories:
    - repoId: {REPO_ID_OR_NAME}
      remote: git@github.com:{GIT_ORG}/{GIT_REPO}.git
      branch: {GIT_BRANCH}
  syncInterval: 1m

See ConfigurationReference for the full configuration.

Start running the piped

./piped piped --config-file={PATH_TO_PIPED_CONFIG_FILE}

Docs-V0.56.x: Adding an analysis provider

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

To enable Automated deployment analysis feature, you have to set the needed information for Piped to connect to the Analysis Provider.

Currently, PipeCD supports the following providers:

Prometheus

Piped queries the range query endpoint to obtain metrics used to evaluate the deployment.

You need to define the Prometheus server address accessible to Piped.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  analysisProviders:
    - name: prometheus-dev
      type: PROMETHEUS
      config:
        address: https://your-prometheus.dev

The full list of configurable fields are here.

Datadog

Piped queries the MetricsApi.QueryMetrics endpoint to obtain metrics used to evaluate the deployment.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  analysisProviders:
    - name: datadog-dev
      type: DATADOG
      config:
        apiKeyFile: /etc/piped-secret/datadog-api-key
        applicationKeyFile: /etc/piped-secret/datadog-application-key

The full list of configurable fields are here.

If you choose Helm as the installation method, we recommend using --set-file to mount the key files while performing the upgrading process.

--set-file secret.data.datadog-api-key={PATH_TO_API_KEY_FILE} \
--set-file secret.data.datadog-application-key={PATH_TO_APPLICATION_KEY_FILE}

Docs-V0.56.x: Configuration reference

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

apiVersion: pipecd.dev/v1beta1
kind: ControlPlane
spec:
  address: https://your-pipecd-address
  ...

Control Plane Configuration

Field	Type	Description	Required
stateKey	string	A randomly generated string used to sign oauth state.	Yes
datastore	DataStore	Storage for storing application, deployment data.	Yes
filestore	FileStore	File storage for storing deployment logs and application states.	Yes
cache	Cache	Internal cache configuration.	No
address	string	The address to the control plane. This is required if SSO is enabled.	No
insightCollector	InsightCollector	Option to run collector of Insights feature.	No
sharedSSOConfigs	[]SharedSSOConfig	List of shared SSO configurations that can be used by any projects.	No
projects	[]Project	List of debugging/quickstart projects. Please note that do not use this to configure the projects running in the production.	No

DataStore

Field	Type	Description	Required
type	string	Which type of data store should be used. Can be one of the following values `FIRESTORE`, `MYSQL`.	Yes
config	DataStoreConfig	Specific configuration for the datastore type. This must be one of these DataStoreConfig.	Yes

DataStoreConfig

Must be one of the following objects:

DataStoreFireStoreConfig

Field	Type	Description	Required
namespace	string	The root path element considered as a logical namespace, e.g. `pipecd`.	Yes
environment	string	The second path element considered as a logical environment, e.g. `dev`. All pipecd collections will have path formatted according to `{namespace}/{environment}/{collection-name}`.	Yes
collectionNamePrefix	string	The prefix for collection name. This can be used to avoid conflicts with existing collections in your Firestore database.	No
project	string	The name of GCP project hosting the Firestore.	Yes
credentialsFile	string	The path to the service account file for accessing Firestores.	No

DataStoreMySQLConfig

Field	Type	Description	Required
url	string	The address to MySQL server. Should attach with the database port info as `127.0.0.1:3307` in case you want to use another port than the default value.	Yes
database	string	The name of database.	No (If you set it via URL)
usernameFile	string	Path to the file containing the username.	No
passwordFile	string	Path to the file containing the password.	No

FileStore

Field	Type	Description	Required
type	string	Which type of file store should be used. Can be one of the following values `GCS`, `S3`, `MINIO`	Yes
config	FileStoreConfig	Specific configuration for the filestore type. This must be one of these FileStoreConfig.	Yes

FileStoreConfig

Must be one of the following objects:

FileStoreGCSConfig

Field	Type	Description	Required
bucket	string	The bucket name.	Yes
credentialsFile	string	The path to the service account file for accessing GCS.	No

FileStoreS3Config

Field	Type	Description	Required
bucket	string	The AWS S3 bucket name.	Yes
region	string	The AWS region name.	Yes
profile	string	The AWS profile name. Default value is `default`.	No
credentialsFile	string	The path to AWS credential file. Requires only if you want to auth by specified credential file, by default PipeCD will use `$HOME/.aws/credentials` file.	No
roleARN	string	The IAM role arn to use when assuming an role. Requires only if you want to auth by `WebIdentity` pattern.	No
tokenFile	string	The path to the WebIdentity token PipeCD should use to assume a role with. Requires only if you want to auth by `WebIdentity` pattern.	No

FileStoreMinioConfig

Field	Type	Description	Required
endpoint	string	The address of Minio.	Yes
bucket	string	The bucket name.	Yes
accessKeyFile	string	The path to the access key file.	No
secretKeyFile	string	The path to the secret key file.	No
autoCreateBucket	bool	Whether the given bucket should be made automatically if not exists.	No

Cache

Field	Type	Description	Required
ttl	duration	The time that in-memory cache items are stored before they are considered as stale.	Yes

Project

Field	Type	Description	Required
id	string	The unique identifier of the project.	Yes
desc	string	The description about the project.	No
staticAdmin	ProjectStaticUser	Static admin account of the project.	Yes

ProjectStaticUser

Field	Type	Description	Required
username	string	The username string.	Yes
passwordHash	string	The bcrypt hashed value of the password string.	Yes

InsightCollector

Field	Type	Description	Required
application	InsightCollectorApplication	Application metrics collector.	No
deployment	InsightCollectorDeployment	Deployment metrics collector.	No

InsightCollectorApplication

Field	Type	Description	Required
enabled	bool	Whether to enable. Default is `true`	No
schedule	string	When collector will be executed. Default is `0 * * * *`	No

InsightCollectorDeployment

Field	Type	Description	Required
enabled	bool	Whether to enable. Default is `true`	No
schedule	string	When collector will be executed. Default is `30 * * * *`	No
chunkMaxCount	int	The maximum number of deployment items could be stored in a chunk. Default is `1000`	No

SharedSSOConfig

Field	Type	Description	Required
name	string	The unique name of the configuration.	Yes
provider	string	The SSO service provider. Currently, only `GITHUB` and `OIDC` is supported.	Yes
sessionTtl	int	The time to live of session for SSO login. Unit is `hour`. Default is 7 * 24 hours.	No
github	SSOConfigGitHub	GitHub sso configuration.	No
oidc	SSOConfigOIDC	OIDC sso configuration.	No

SSOConfigGitHub

Field	Type	Description	Required
clientId	string	The client id string of GitHub oauth app.	Yes
clientSecret	string	The client secret string of GitHub oauth app.	Yes
baseUrl	string	The address of GitHub service. Required if enterprise.	No
uploadUrl	string	The upload url of GitHub service.	No
proxyUrl	string	The address of the proxy used while communicating with the GitHub service.	No

SSOConfigOIDC

Field	Type	Description	Required
clientId	string	The client id string of OpenID Connect oauth app.	Yes
clientSecret	string	The client secret string of OpenID Connect oauth app.	Yes
issuer	string	The address of OpenID Connect service.	Yes
redirectUri	string	The address of the redirect URI.	Yes
authorizationEndpoint	string	The address of the authorization endpoint. Only set if you want to use custom authorization endpoint (still need issuer discovery).	No
tokenEndpoint	string	The address of the token endpoint. Only set if you want to use custom token endpoint (still need issuer discovery).	No
userInfoEndpoint	string	The address of the user info endpoint. Only set if you want to use custom user info endpoint (still need issuer discovery).	No
proxyUrl	string	The address of the proxy used while communicating with the OpenID Connect service.	No
scopes	[]string	Scopes to request from the OpenID Connect service. Default is `openid`. Some providers may require other scopes.	No
usernameClaimKey	string	The key name of the claim that contains the username. If not set, the default value will be chosen in the following order: `username`, `preferred_username`, `name`, `cognito:username`.	No
rolesClaimKey	string	The key name of the claim that contains the roles. If not set, the default value will be chosen in the following order: `groups`, `roles`, `custom:roles`, `custom:groups`.	No
avatarUrlClaimKey	string	The key name of the claim that contains the avatar url. If not set, the default value will be chosen in the following order: `picture`, `avatar_url`.	No

Docs-V0.56.x: Required Permissions

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

A Piped requires some permissions to deploy applications, depending on the platform.

Note: If you run a piped as an ECS task, you need to attach the permissions on the piped task’s task role, not task execution role.

For ECSApp

You need IAM actions like the following example. You can restrict Resource.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:CreateService",
                "ecs:CreateTaskSet",
                "ecs:DeleteTaskSet",
                "ecs:DeregisterTaskDefinition",
                "ecs:DescribeServices",
                "ecs:DescribeTaskDefinition",
                "ecs:DescribeTaskSets",
                "ecs:DescribeTasks",
                "ecs:ListClusters",
                "ecs:ListServices",
                "ecs:ListTasks",
                "ecs:ListTagsForResource",
                "ecs:RegisterTaskDefinition",
                "ecs:RunTask",
                "ecs:TagResource",
                "ecs:UntagResource",
                "ecs:UpdateService",
                "ecs:UpdateServicePrimaryTaskSet",
                "elasticloadbalancing:DescribeListeners",
                "elasticloadbalancing:DescribeRules",
                "elasticloadbalancing:DescribeTargetGroups",
                "elasticloadbalancing:ModifyListener",
                "elasticloadbalancing:ModifyRule"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": [
                "arn:aws:iam::<account-id>:role/<task-execution-role>",
                "arn:aws:iam::<account-id>:role/<task-role>"
            ]
        }
    ]
}

For LambdaApp

You need IAM actions like the following example. You can restrict Resource.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "lambda:CreateAlias",
                "lambda:CreateFunction",
                "lambda:GetAlias",
                "lambda:GetFunction",
                "lambda:ListFunctions",
                "lambda:PublishVersion",
                "lambda:TagResource",
                "lambda:UntagResource",
                "lambda:UpdateAlias",
                "lambda:UpdateFunctionCode",
                "lambda:UpdateFunctionConfiguration"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": [
                "arn:aws:iam::<account-id>:role/<function-role>"
            ]
        }
    ]
}

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: Configuring event watcher

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

To enable EventWatcher, you have to configure your piped at first.

Grant write permission

The SSH key used by Piped must be a key with write-access because piped needs to commit and push to your git repository when any incoming event matches.

Specify Git repositories to be observed

Piped watches events only for the Git repositories specified in the gitRepos list. You need to add all repositories you want to enable EventWatcher.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  eventWatcher:
    gitRepos:
      - repoId: repo-1
      - repoId: repo-2
      - repoId: repo-3

[optional] Specify EventWatcher files Piped will use

NOTE: This way is valid only for defining events using .pipe/.

If multiple Pipeds handle a single repository, you can prevent conflicts by splitting into the multiple EventWatcher files and setting includes/excludes to specify the files that should be monitored by this Piped.

Say for instance, if you only want the Piped to use the EventWatcher files under .pipe/dev/:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  eventWatcher:
    gitRepos:
      - repoId: repo-1
        commitMessage: Update values by Event watcher
        includes:
          - dev/*.yaml

excludes is prioritized if both includes and excludes are given.

The full list of configurable fields are here.

[optional] Settings for git user

By default, every git commit uses piped as a username and pipecd.dev@gmail.com as an email. You can change it with the git field.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  git:
    username: foo
    email: foo@example.com

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

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

PipeCD events (deployment triggered, planned, completed, analysis result, piped started…) can be sent to external services like Slack or a Webhook service. While forwarding those events to a chat service helps developers have a quick and convenient way to know the deployment’s current status, forwarding to a Webhook service may be useful for triggering other related tasks like CI jobs.

PipeCD events are emitted and sent by the piped component. So all the needed configurations can be specified in the piped configuration file. Notification configuration including:

a list of Routes which used to match events and decide where the event should be sent to
a list of Receivers which used to know how to send events to the external service

Notification Route matches events based on their metadata like name, group, app, labels. Below is the list of supporting event names and their groups.

Event	Group	Description
DEPLOYMENT_TRIGGERED	DEPLOYMENT
DEPLOYMENT_PLANNED	DEPLOYMENT
DEPLOYMENT_STARTED	DEPLOYMENT
DEPLOYMENT_APPROVED	DEPLOYMENT
DEPLOYMENT_WAIT_APPROVAL	DEPLOYMENT
DEPLOYMENT_ROLLING_BACK	DEPLOYMENT	PipeCD sends a notification when a deployment is completed, while it does not send a notification when a deployment status changes to DEPLOYMENT_ROLLING_BACK because it is not a completion status. See #4547
DEPLOYMENT_SUCCEEDED	DEPLOYMENT
DEPLOYMENT_FAILED	DEPLOYMENT
DEPLOYMENT_CANCELLED	DEPLOYMENT
DEPLOYMENT_TRIGGER_FAILED	DEPLOYMENT
APPLICATION_SYNCED	APPLICATION_SYNC
APPLICATION_OUT_OF_SYNC	APPLICATION_SYNC
APPLICATION_HEALTHY	APPLICATION_HEALTH
APPLICATION_UNHEALTHY	APPLICATION_HEALTH
PIPED_STARTED	PIPED
PIPED_STOPPED	PIPED

Sending notifications to Slack

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  notifications:
    routes:
      # Sending all event which contains labels `env: dev` to dev-slack-channel.
      - name: dev-slack
        labels:
          env: dev
        receiver: dev-slack-channel
      # Only sending deployment started and completed events which contains
      # labels `env: prod` and `team: pipecd` to prod-slack-channel.
      - name: prod-slack
        events:
          - DEPLOYMENT_TRIGGERED
          - DEPLOYMENT_SUCCEEDED
        labels:
          env: prod
          team: pipecd
        receiver: prod-slack-channel
      - name: integration-slack
        receiver: integration-slack-api
    receivers:
      - name: dev-slack-channel
        slack:
          hookURL: https://slack.com/dev
      - name: prod-slack-channel
        slack:
          hookURL: https://slack.com/prod
      - name: integration-slack-api
        slack:
          oauthTokenData: "token"
          channelID: "testid"
      - name: hookurl-with-mentioned-accounts
        slack:
          hookURL: https://slack.com/dev,
          mentionedAccounts:
            - '@user1'
            - 'user2'
      - name: integration-slack-api-with-mentioned-accounts
        slack:
          oauthTokenData: token
          channelID: testid
          mentionedAccounts:
            - '@user1'
            - 'user2'
      - name: integration-slack-api-with-oauthTokenData-and-mentioned-groups
        slack:
          oauthTokenData: token
          channelID: testid
          mentionedGroups:
            - 'group1'
            - '<!subteam^group2>'
      - name: integration-slack-api-with-oauthTokenData-and-mentioned-both-accounts-and-groups
        slack:
          oauthTokenData: token
          channelID: testid
          mentionedAccounts:
            - 'user1'
            - '@user2'
          mentionedGroups:
            - 'groupID1'
            - '<!subteam^groupID2>'

Deployment was triggered, planned and completed successfully

A piped has been started

For detailed configuration, please check the configuration reference for Notifications section.

Sending notifications to external services via webhook

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  notifications:
    routes:
      # Sending all events an external service.
      - name: all-events-to-a-external-service
        receiver: a-webhook-service
    receivers:
      - name: a-webhook-service
        webhook:
          url: {WEBHOOK_SERVICE_URL}
          signatureValue: {RANDOM_SIGNATURE_STRING}

For detailed configuration, please check the configuration reference for NotificationReceiverWebhook section.

Docs-V0.56.x: Configuration reference

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

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: ...
  pipedID: ...
  ...

Piped Configuration

Field	Type	Description	Required
projectID	string	The identifier of the PipeCD project where this piped belongs to.	Yes
pipedID	string	The generated ID for this piped.	Yes
pipedKeyFile	string	The path to the file containing the generated key string for this piped.	Yes
pipedKeyData	string	Base64 encoded string of Piped key. Either pipedKeyFile or pipedKeyData must be set.	Yes
apiAddress	string	The address used to connect to the Control Plane’s API in format `host:port`.	Yes
syncInterval	duration	How often to check whether an application should be synced. Default is `1m`.	No
appConfigSyncInterval	duration	How often to check whether application configuration files should be synced. Default is `1m`.	No
git	Git	Git configuration needed for Git commands.	No
repositories	[]Repository	List of Git repositories this piped will handle.	No
chartRepositories	[]ChartRepository	List of Helm chart repositories that should be added while starting up.	No
chartRegistries	[]ChartRegistry	List of helm chart registries that should be logged in while starting up.	No
platformProviders	[]PlatformProvider	List of platform providers can be used by this piped.	No
analysisProviders	[]AnalysisProvider	List of analysis providers can be used by this piped.	No
eventWatcher	EventWatcher	Optional Event watcher settings.	No
secretManagement	SecretManagement	The using secret management method.	No
notifications	Notifications	Sending notifications to Slack, Webhook…	No
appSelector	map[string]string	List of labels to filter all applications this piped will handle. Currently, it is only be used to filter the applications suggested for adding from the control plane.	No

Git

Field	Type	Description	Required
username	string	The username that will be configured for `git` user. Default is `piped`.	No
email	string	The email that will be configured for `git` user. Default is `pipecd.dev@gmail.com`.	No
sshConfigFilePath	string	Where to write ssh config file. Default is `$HOME/.ssh/config`.	No
host	string	The host name. Default is `github.com`.	No
hostName	string	The hostname or IP address of the remote git server. Default is the same value with Host.	No
sshKeyFile	string	The path to the private ssh key file. This will be used to clone the source code of the specified git repositories.	No
sshKeyData	string	Base64 encoded string of SSH key.	No
password	string	The base64 encoded password for git used while cloning above Git repository.	No

GitRepository

Field	Type	Description	Required
repoID	string	Unique identifier to the repository. This must be unique in the piped scope.	Yes
remote	string	Remote address of the repository used to clone the source code. e.g. `git@github.com:org/repo.git`	Yes
branch	string	The branch will be handled.	Yes

ChartRepository

Field	Type	Description	Required
type	string	The repository type. Currently, HTTP and GIT are supported. Default is HTTP.	No
name	string	The name of the Helm chart repository. Note that is not a Git repository but a Helm chart repository.	Yes if type is HTTP
address	string	The address to the Helm chart repository.	Yes if type is HTTP
username	string	Username used for the repository backed by HTTP basic authentication.	No
password	string	Password used for the repository backed by HTTP basic authentication.	No
insecure	bool	Whether to skip TLS certificate checks for the repository or not.	No
gitRemote	string	Remote address of the Git repository used to clone Helm charts.	Yes if type is GIT
sshKeyFile	string	The path to the private ssh key file used while cloning Helm charts from above Git repository.	No

ChartRegistry

Field	Type	Description	Required
type	string	The registry type. Currently, only OCI is supported. Default is OCI.	No
address	string	The address to the registry.	Yes
username	string	Username used for the registry authentication.	No
password	string	Password used for the registry authentication.	No

PlatformProvider

Field	Type	Description	Required
name	string	The name of the platform provider.	Yes
type	string	The platform provider type. Must be one of the following values: `KUBERNETES`, `TERRAFORM`, `ECS`, `CLOUDRUN`, `LAMBDA`.	Yes
config	PlatformProviderConfig	Specific configuration for the specified type of platform provider.	No

PlatformProviderConfig

Must be one of the following structs:

PlatformProviderKubernetesConfig

Field	Type	Description	Required
masterURL	string	The master URL of the kubernetes cluster. Empty means in-cluster.	No
kubectlVersion	string	Version of kubectl which will be used to connect to your cluster. Empty means the version set on piped config or default version will be used.	No
kubeConfigPath	string	The path to the kubeconfig file. Empty means in-cluster.	No
appStateInformer	KubernetesAppStateInformer	Configuration for application resource informer.	No

PlatformProviderTerraformConfig

Field	Type	Description	Required
vars	[]string	List of variables that will be set directly on terraform commands with `-var` flag. The variable must be formatted by `key=value`.	No
driftDetectionEnabled	bool	Enable drift detection. This is a temporary option and will be possibly removed in the future release. Default is `true`	No

PlatformProviderCloudRunConfig

Field	Type	Description	Required
project	string	The GCP project hosting the Cloud Run service.	Yes
region	string	The region of running Cloud Run service.	Yes
credentialsFile	string	The path to the service account file for accessing Cloud Run service.	No

PlatformProviderLambdaConfig

Field	Type	Description	Required
region	string	The region of running Lambda service.	Yes
credentialsFile	string	The path to the credential file for logging into AWS cluster. If this value is not provided, piped will read credential info from environment variables. It expects the format ~/.aws/credentials.	No
roleARN	string	The IAM role arn to use when assuming an role. Required if you want to use the AWS SecurityTokenService.	No
tokenFile	string	The path to the WebIdentity token the SDK should use to assume a role with. Required if you want to use the AWS SecurityTokenService.	No
profile	string	The profile to use for logging into AWS cluster. The default value is `default`.	No
awsAPIPollingInterval	duration	The interval of periodical calls of AWS APIs. Currently, this is an interval of refreshing the live state of Lambda functions. Default is 15s.	No

PlatformProviderECSConfig

Field	Type	Description	Required
region	string	The region of running ECS cluster.	Yes
credentialsFile	string	The path to the credential file for logging into AWS cluster. If this value is not provided, piped will read credential info from environment variables. It expects the format ~/.aws/credentials	No
roleARN	string	The IAM role arn to use when assuming an role. Required if you want to use the AWS SecurityTokenService.	No
tokenFile	string	The path to the WebIdentity token the SDK should use to assume a role with. Required if you want to use the AWS SecurityTokenService.	No
profile	string	The profile to use for logging into AWS cluster. The default value is `default`.	No

KubernetesAppStateInformer

Field	Type	Description	Required
namespace	string	Only watches the specified namespace. Empty means watching all namespaces.	No
includeResources	[]KubernetesResourcematcher	List of resources that should be added to the watching targets.	No
excludeResources	[]KubernetesResourcematcher	List of resources that should be ignored from the watching targets.	No

KubernetesResourceMatcher

Field	Type	Description	Required
apiVersion	string	The APIVersion of the kubernetes resource.	Yes
kind	string	The kind name of the kubernetes resource. Empty means all kinds are matching.	No

AnalysisProvider

Field	Type	Description	Required
name	string	The unique name of the analysis provider.	Yes
type	string	The provider type. Currently, only PROMETHEUS, DATADOG are available.	Yes
config	AnalysisProviderConfig	Specific configuration for the specified type of analysis provider.	Yes

AnalysisProviderConfig

Must be one of the following structs:

AnalysisProviderPrometheusConfig

Field	Type	Description	Required
address	string	The Prometheus server address.	Yes
usernameFile	string	The path to the username file.	No
passwordFile	string	The path to the password file.	No

AnalysisProviderDatadogConfig

Field	Type	Description	Required
address	string	The address of Datadog API server. Only “datadoghq.com”, “us3.datadoghq.com”, “datadoghq.eu”, “ddog-gov.com” are available. Defaults to “datadoghq.com”	No
apiKeyFile	string	The path to the api key file.	Yes
applicationKeyFile	string	The path to the application key file.	Yes
apiKeyData	string	Base64 API Key for Datadog API server. Either apiKeyData or apiKeyFile must be set	No
applicationKeyData	string	Base64 Application Key for Datadog API server. Either applicationKeyFile or applicationKeyData must be set	No

EventWatcher

Field	Type	Description	Required
checkInterval	duration	Interval to fetch the latest event and compare it with one defined in EventWatcher config files. Defaults to `1m`.	No
gitRepos	[]EventWatcherGitRepo	The configuration list of git repositories to be observed. Only the repositories in this list will be observed by Piped.	No

EventWatcherGitRepo

Field	Type	Description	Required
repoId	string	Id of the git repository. This must be unique within the repos’ elements.	Yes
commitMessage	string	The commit message used to push after replacing values. Default message is used if not given.	No
includes	[]string	The paths to EventWatcher files to be included. Patterns can be used like `foo/*.yaml`.	No
excludes	[]string	The paths to EventWatcher files to be excluded. Patterns can be used like `foo/*.yaml`. This is prioritized if both includes and this are given.	No

SecretManagement

Field	Type	Description	Required
type	string	Which management method should be used. Default is `KEY_PAIR`.	Yes
config	SecretManagementConfig	Configuration for using secret management method.	Yes

SecretManagementConfig

Must be one of the following structs:

SecretManagementKeyPair

Field	Type	Description	Required
privateKeyFile	string	Path to the private RSA key file.	Yes
privateKeyData	string	Base64 encoded string of private RSA key. Either privateKeyFile or privateKeyData must be set.	No
publicKeyFile	string	Path to the public RSA key file.	Yes
publicKeyData	string	Base64 encoded string of public RSA key. Either publicKeyFile or publicKeyData must be set.	No

SecretManagementGCPKMS

WIP

Notifications

Field	Type	Description	Required
routes	[]NotificationRoute	List of notification routes.	No
receivers	[]NotificationReceiver	List of notification receivers.	No

NotificationRoute

Field	Type	Description	Required
name	string	The name of the route.	Yes
receiver	string	The name of receiver who will receive all matched events.	Yes
events	[]string	List of events that should be routed to the receiver.	No
ignoreEvents	[]string	List of events that should be ignored.	No
groups	[]string	List of event groups should be routed to the receiver.	No
ignoreGroups	[]string	List of event groups should be ignored.	No
apps	[]string	List of applications where their events should be routed to the receiver.	No
ignoreApps	[]string	List of applications where their events should be ignored.	No
labels	map[string]string	List of labels where their events should be routed to the receiver.	No
ignoreLabels	map[string]string	List of labels where their events should be ignored.	No

NotificationReceiver

Field	Type	Description	Required
name	string	The name of the receiver.	Yes
slack	NotificationReceiverSlack	Configuration for slack receiver.	No
webhook	NotificationReceiverWebhook	Configuration for webhook receiver.	No

NotificationReceiverSlack

Field	Type	Description	Required
hookURL	string	The hookURL of a slack channel.	Yes
oauthToken	string	The token for Slack API use. (deprecated)	No
oauthTokenData	string	Base64 encoded string of The token for Slack API use.	No
oauthTokenFile	string	The path to the oauthToken file	No
channelID	string	The channel id which slack api send to.	No
mentionedAccounts	[]string	The accounts to which slack api refers. This field supports both `@username` and `username` writing styles.	No
mentionedGroups	[]string	The groups to which slack api refers. This field supports both `<!subteam^groupname>` and `groupname` writing styles.	No

NotificationReceiverWebhook

Field	Type	Description	Required
url	string	The URL where notification event will be sent to.	Yes
signatureKey	string	The HTTP header key used to store the configured signature in each event. Default is “PipeCD-Signature”.	No
signatureValue	string	The value of signature included in header of each event request. It can be used to verify the received events.	No
signatureValueFile	string	The path to the signature value file.	No

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: Using Pprof in Piped

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

Piped provides built-in support for pprof, a tool for visualization and analysis of profiling data. It’s a part of the standard Go library.

In Piped, several routes are registered to serve the profiling data in a format understood by the pprof tool. Here are the routes:

/debug/pprof/: This route serves an index page that lists the available profiling data.
/debug/pprof/profile: This route serves CPU profiling data.
/debug/pprof/trace: This route serves execution trace data.

You can access these routes to get the profiling data. For example, to get the CPU profiling data, you can access the /debug/pprof/profile route.

Note that using these features in a production environment may impact performance.

This document explains the basic usage of pprof in Piped. For more detailed information or specific use cases, please refer to the official Go documentation.

How to use pprof

Access the pprof index page
```
curl http://localhost:9085/debug/pprof/
```
This will return an HTML page that lists the available profiling data.
Get the CPU Profile
```
curl http://localhost:9085/debug/pprof/profile > cpu.pprof
```
This will save the CPU profiling data to a file named cpu.pprof. You can then analyze this data using the pprof tool:
```
go tool pprof cpu.pprof
```
Get the Execution Trace
```
curl http://localhost:9085/debug/pprof/trace > trace.out
```
This will save the execution trace data to a file named trace.out. You can then view this trace using the go tool trace command:
```
go tool trace trace.out
```
Please replace localhost:9085 with the actual address and port of your Piped’s admin server.

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.

Docs-V0.56.x: Runtime Options

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

You can configure some options when running Piped and launcher.

Options for Piped

Usage:
  piped piped [flags]

Flags:
      --add-login-user-to-passwd                   Whether to add login user to $HOME/passwd. This is typically for applications running as a random user ID.
      --admin-port int                             The port number used to run a HTTP server for admin tasks such as metrics, healthz. (default 9085)
      --app-manifest-cache-count int               The number of app manifests to cache. The cache-key contains the commit hash. The default is 150. (default 150)     
      --cert-file string                           The path to the TLS certificate file.
      --config-aws-secret string                   The ARN of secret that contains Piped config and be stored in AWS Secrets Manager.
      --config-aws-ssm-parameter string            The name of parameter of Piped config stored in AWS Systems Manager Parameter Store. SecureString is also supported.
      --config-data string                         The base64 encoded string of the configuration data.
      --config-file string                         The path to the configuration file.
      --config-gcp-secret string                   The resource ID of secret that contains Piped config and be stored in GCP SecretManager.
      --enable-default-kubernetes-cloud-provider   Whether the default kubernetes provider is enabled or not. This feature is deprecated.
      --grace-period duration                      How long to wait for graceful shutdown. (default 30s)
  -h, --help                                       help for piped
      --insecure                                   Whether disabling transport security while connecting to control-plane.
      --launcher-version string                    The version of launcher which initialized this Piped.
      --tools-dir string                           The path to directory where to install needed tools such as kubectl, helm, kustomize. (default "~/.piped/tools")

Global Flags:
      --log-encoding string                The encoding type for logger [json|console|humanize]. (default "humanize")
      --log-level string                   The minimum enabled logging level. (default "info")
      --metrics                            Whether metrics is enabled or not. (default true)
      --profile                            If true enables uploading the profiles to Stackdriver.
      --profile-debug-logging              If true enables logging debug information of profiler.
      --profiler-credentials-file string   The path to the credentials file using while sending profiles to Stackdriver.

Options for launcher

Usage:
  launcher launcher [flags]

Flags:
      --aws-secret-id string                  The ARN of secret that contains Piped config in AWS Secrets Manager service.
      --aws-ssm-parameter string              The name of parameter of Piped config stored in AWS Systems Manager Parameter Store. SecureString is also supported.
      --cert-file string                      The path to the TLS certificate file.
      --check-interval duration               Interval to periodically check desired config/version to restart Piped. Default is 1m. (default 1m0s)
      --config-data string                    The base64 encoded string of the configuration data.
      --config-file string                    The path to the configuration file.
      --config-from-aws-secret                Whether to load Piped config that is being stored in AWS Secrets Manager service.
      --config-from-aws-ssm-parameter-store   Whether to load Piped config that is being stored in AWS Systems Manager Parameter Store.
      --config-from-gcp-secret                Whether to load Piped config that is being stored in GCP SecretManager service.
      --config-from-git-repo                  Whether to load Piped config that is being stored in a git repository.
      --default-version string                The version should be run when no desired version was specified. Empty means using the same version with Launcher.
      --gcp-secret-id string                  The resource ID of secret that contains Piped config in GCP SecretManager service.
      --git-branch string                     Branch of git repository to for Piped config.
      --git-piped-config-file string          Relative path within git repository to locate Piped config file.
      --git-repo-url string                   The remote URL of git repository to fetch Piped config.
      --git-ssh-key-data string               Base64 encoded value of SSH private key to fetch Piped config from the private git repository.
      --git-ssh-key-file string               The path to SSH private key to fetch Piped config from private git repository.
      --grace-period duration                 How long to wait for graceful shutdown. (default 30s)
  -h, --help                                  help for launcher
      --home-dir string                       The working directory of Launcher.
      --insecure                              Whether disabling transport security while connecting to control-plane.
      --launcher-admin-port int               The port number used to run a HTTP server for admin tasks such as metrics, healthz.

Global Flags:
      --log-encoding string                The encoding type for logger [json|console|humanize]. (default "humanize")
      --log-level string                   The minimum enabled logging level. (default "info")
      --metrics                            Whether metrics is enabled or not. (default true)
      --profile                            If true enables uploading the profiles to Stackdriver.
      --profile-debug-logging              If true enables logging debug information of profiler.
      --profiler-credentials-file string   The path to the credentials file using while sending profiles to Stackdriver.

Docs-V0.56.x: Connect between CI and CD with event watcher

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

The only way to upgrade your application with PipeCD is modifying configuration files managed by the Git repositories. It brings benefits quite a bit, but it can be painful to manually update them every time in some cases (e.g. continuous deployment to your development environment for debugging, the latest prerelease to the staging environment).

If you’re experiencing any of the above pains, Event watcher is for you. Event watcher works as a helper facility to seamlessly link CI and CD. This feature lets you automatically update files managed by your Piped when an arbitrary event has occurred. While it empowers you to build pretty versatile workflows, the canonical use case is that you trigger a new deployment by image updates, package releases, etc.

This guide walks you through configuring Event watcher and how to push an Event.

Prerequisites

Before we get into configuring EventWatcher, be sure to configure Piped. See here for more details.

Usage

File updating can be done by registering the latest value corresponding to the Event in the Control Plane and comparing it with the current value.

Therefore, you mainly need to:

define which values in which files should be updated when a new Event found.
integrate a step to push an Event to the Control Plane using pipectl into your CI workflow.

1. Defining Events

Use the `.pipe/` directory

NOTE: This way is deprecated and will be removed in the future, so please use the application configuration.

Prepare EventWatcher configuration files under the .pipe/ directory at the root of your Git repository. In that files, you define which values in which files should be updated when the Piped found out a new Event.

For instance, suppose you want to update the Kubernetes manifest defined in helloworld/deployment.yaml when an Event with the name helloworld-image-update occurs:

apiVersion: pipecd.dev/v1beta1
kind: EventWatcher
spec:
  events:
    - name: helloworld-image-update
      replacements:
        - file: helloworld/deployment.yaml
          yamlField: $.spec.template.spec.containers[0].image

The full list of configurable EventWatcher fields are here.

Use the application configuration

Define what to do for which event in the application configuration file of the target application.

matcher: Which event should be handled.
handler: What to do for the event which is specified by matcher.

For instance, suppose you want to update the Kubernetes manifest defined in helloworld/deployment.yaml when an Event with the name helloworld-image-update occurs:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: helloworld
  eventWatcher:
    - matcher:
        name: helloworld-image-update
      handler:
        type: GIT_UPDATE
        config:
          replacements:
            - file: deployment.yaml
              yamlField: $.spec.template.spec.containers[0].image

The full list of configurable eventWatcher fields are here.

2. Pushing an Event with `pipectl`

To register a new value corresponding to Event such as the above in the Control Plane, you need to perform pipectl. And we highly recommend integrating a step for that into your CI workflow.

You first need to set-up the pipectl:

Install it on your CI system or where you want to run according to this guide.
Grab the API key to which the READ_WRITE role is attached according to this guide.

Once you’re all set up, pushing a new Event to the Control Plane by the following command:

pipectl event register \
    --address={CONTROL_PLANE_API_ADDRESS} \
    --api-key={API_KEY} \
    --name=helloworld-image-update \
    --data=gcr.io/pipecd/helloworld:v0.2.0

You can see the status on the event list page.

After a while, Piped will create a commit as shown below:

     spec:
       containers:
       - name: helloworld
-        image: gcr.io/pipecd/helloworld:v0.1.0
+        image: gcr.io/pipecd/helloworld:v0.2.0

NOTE: Keep in mind that it may take a little while because Piped periodically fetches the new events from the Control Plane. You can change its interval according to here.

[optional] Using labels

Event watcher is a project-wide feature, hence an event name is unique inside a project. That is, you can update multiple repositories at the same time if you use the same event name for different events.

On the contrary, if you want to explicitly distinguish those, we recommend using labels. You can make an event definition unique by using any number of labels with arbitrary keys and values. Suppose you define an event with the labels env: dev and appName: helloworld:

When you use the .pipe/ directory, you can configure like below.

apiVersion: pipecd.dev/v1beta1
kind: EventWatcher
spec:
  events:
    - name: image-update
      labels:
        env: dev
        appName: helloworld
      replacements:
        - file: helloworld/deployment.yaml
          yamlField: $.spec.template.spec.containers[0].image

The other example is like below.

apiVersion: pipecd.dev/v1beta1
kind: ApplicationKind
spec:
  name: helloworld
  eventWatcher:
    - matcher:
        name: image-update
        labels:
          env: dev
          appName: helloworld
      handler:
        type: GIT_UPDATE
        config:
          replacements:
            - file: deployment.yaml
              yamlField: $.spec.template.spec.containers[0].image

The file update will be executed only when the labels are explicitly specified with the --labels flag.

pipectl event register \
    --address=CONTROL_PLANE_API_ADDRESS \
    --api-key=API_KEY \
    --name=image-update \
    --labels env=dev,appName=helloworld \
    --data=gcr.io/pipecd/helloworld:v0.2.0

Note that it is considered a match only when labels are an exact match.

[optional] Using contexts

You can also attach additional metadata to the event. This information can be added as a trailer to the git commit when Event Watcher using the GIT_UPDATE handler. This can be useful when attaching information from the source code repository to the manifest repository.

For example, you can attach the source code commit link to the manifest repository.

pipectl event register \
    --address=CONTROL_PLANE_API_ADDRESS \
    --api-key=API_KEY \
    --name=sample \
    --data=gcr.io/pipecd/helloworld:v0.48.0 \
    --contexts Source-Commit-Hash=xxxxxxx,Source-Commit-URL=https://github.com/pipe-cd/pipecd/commit/xxxxxxx

# In manifest repository
$ git show                                                                        
commit ff46cdc9a3ce87a9a66436269251a4870ac55183 (HEAD -> main, origin/main, origin/HEAD)
Author: ffjlabo <pipecd.dev@gmail.com>
Date:   Wed Oct 30 16:56:36 2024 +0900

    Replace values with "gcr.io/pipecd/helloworld:v0.48.0" set by Event "simple"

    Source-Commit-Hash: xxxxxxx
    Source-Commit-URL: https://github.com/pipe-cd/pipecd/commit/xxxxxxx

[optional] Using commit-hash and commit-url for Deployment Trace

You can attach commit-hash and commit-url of the commit that trigger the event as metadata to the event. Once you added these data to your event on registering, you would have a better way to understand what deployments are triggered by your application commit via PipeCD Deployment Trace feature.

To attach these values

pipectl event register \
    --address=CONTROL_PLANE_API_ADDRESS \
    --api-key=API_KEY \
    --name=sample \
    --data=gcr.io/pipecd/helloworld:v0.48.0 \
    --commit-hash=20c98a503062021720b2fcf2058276b3245xxxxx
    --commit-url=https://github.com/pipe-cd/pipecd/commit/20c98a503062021720b2fcf2058276b3245xxxxx

NOTE: There are few more information of the triggered commit you can attach as event metadata, find more in DeploymentTrace docs.

Examples

Suppose you want to update your configuration file after releasing a new Helm chart.

You define the configuration for event watcher in helloworld/app.pipecd.yaml file like:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  input:
    helmChart:
      name: helloworld
      version: 0.1.0
  eventWatcher:
    - matcher:
        name: image-update
        labels:
          env: dev
          appName: helloworld
      handler:
        type: GIT_UPDATE
        config:
          replacements:
            - file: app.pipecd.yaml
              yamlField: $.spec.input.helmChart.version

Push a new version 0.2.0 as data when the Helm release is completed.

pipectl event register \
    --address=CONTROL_PLANE_API_ADDRESS \
    --api-key=API_KEY \
    --name=helm-release \
    --labels env=dev,appName=helloworld \
    --data=0.2.0

Then you’ll see that Piped updates as:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  input:
    helmChart:
      name: helloworld
-     version: 0.1.0
+     version: 0.2.0
  eventWatcher:
    - matcher:
        name: image-update
        labels:
          env: dev
          appName: helloworld
      handler:
        type: GIT_UPDATE
        config:
          replacements:
            - file: app.pipecd.yaml
              yamlField: $.spec.input.helmChart.version

Github Actions

If you’re using Github Actions in your CI workflow, actions-event-register is for you! With it, you can easily register events without any installation.