PipeCD – Official Plugins

Docs-V1.0.x: Kubernetes plugin

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

The kubernetes plugin deploys an application to a single Kubernetes cluster. It supports quick sync and pipeline-based rollouts with canary, baseline, and primary variants, and can shift traffic between variants using the PodSelector or Istio method.

By default, piped deploys the application to the cluster it runs in. To deploy to an external cluster, set masterURL and kubeConfigPath in the plugin’s deployTargets.

Prerequisites

Register the plugin in the piped configuration. Add a kubernetes plugin block with a deployTargets entry for the cluster:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  # ...
  plugins:
    - name: kubernetes
      port: 7001
      url: file:///path/to/plugin/binary  # or an https:// release URL
      deployTargets:
        - name: local
          config:
            # Empty masterURL/kubeConfigPath means the cluster piped runs in.
            kubectlVersion: 1.32.2

The plugin downloads kubectl automatically. piped fetches kubectl (and kustomize/helm when used) via the tool registry, so the binary does not need to be pre-installed on the piped host. Pin a version with kubectlVersion if you need a specific one.
When registering the application in the control plane, select the deploy target the application should deploy to.

Quick sync

With no pipeline defined, the plugin performs a quick sync (K8S_SYNC): it applies all manifests to the cluster. This minimal app.pipecd.yaml deploys the manifests in the application directory:

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-app
  plugins:
    kubernetes:
      input:
        manifests:
          - deployment.yaml
          - service.yaml
        kubectlVersion: 1.32.2

Sync with the specified pipeline

Define a pipeline to control the rollout. The stages run in order:

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-app
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 1
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_CANARY_CLEAN
  plugins:
    kubernetes:
      input:
        manifests:
          - deployment.yaml
        kubectlVersion: 1.32.2

See Pipeline stages for every available stage and its options.

Pipeline stages

Stages are listed under spec.pipeline.stages, with options under with.

K8S_SYNC

Applies all manifests to the cluster. This is the stage that runs during a quick sync when no pipeline block is defined in your app.pipecd.yaml.

Option	Type	Description	Default
addVariantLabelToSelector	bool	Add the PRIMARY variant label to workload selectors if missing.	false
prune	bool	Remove resources that are no longer defined in Git.	false

K8S_PRIMARY_ROLLOUT

Rolls out the PRIMARY (stable) variant using the manifests defined in Git. You can optionally create a dedicated Service for the PRIMARY variant and enable pruning so that any resources removed from Git are also deleted from the cluster.

Option	Type	Description	Default
suffix	string	Suffix for the PRIMARY variant’s resource names.	primary
createService	bool	Create a Service for the PRIMARY variant.	false
addVariantLabelToSelector	bool	Add the PRIMARY variant label to workload selectors if missing.	false
prune	bool	Remove resources no longer defined in Git.	false

K8S_CANARY_ROLLOUT

Creates CANARY variant workloads alongside the currently running version. This lets you send a portion of traffic to the new version and compare its behaviour against the stable version before deciding to promote or roll back. You can optionally create a dedicated Service for the canary and apply manifest patches to customise the variant before it is deployed.

Option	Type	Description	Default
replicas	int or string	Number of CANARY pods. An integer, or a percentage of PRIMARY (e.g. `"50%"`).	1
suffix	string	Suffix for the CANARY variant’s resource names.	canary
createService	bool	Create a Service for the CANARY variant.	false
patches	[]K8sResourcePatch	Patches applied to manifests before generating the CANARY variant.	-

K8S_CANARY_CLEAN

Removes the CANARY variant resources that were created by K8S_CANARY_ROLLOUT. This stage is typically placed at the end of a canary pipeline to clean up after promotion or after a rollback decision. It takes no options.

K8S_BASELINE_ROLLOUT

Creates BASELINE variant workloads from the running (currently live) manifests, not the target manifests. This means the baseline is an exact copy of what is already in production, giving you a stable reference point to compare against the canary during analysis.

Option	Type	Description	Default
replicas	int or string	Number of BASELINE pods. An integer, or a percentage of PRIMARY.	1
suffix	string	Suffix for the BASELINE variant’s resource names.	baseline
createService	bool	Create a Service for the BASELINE variant.	false

K8S_BASELINE_CLEAN

Removes the BASELINE variant resources that were created by K8S_BASELINE_ROLLOUT. Place this stage at the end of a canary/baseline pipeline to clean up after the analysis is complete, whether you promoted or rolled back. It takes no options.

K8S_TRAFFIC_ROUTING

Shifts traffic between the PRIMARY, CANARY, and BASELINE variants. The routing method is set by the application-level trafficRouting config and determines how the split is applied.

PodSelector (default) works by updating the Service’s spec.selector to point entirely at one variant. This means one variant must receive 100% of traffic at a time, and baseline is not supported with this method.

Istio works by updating the VirtualService route weights, which allows traffic to be split by percentage across all three variants simultaneously.

Option	Type	Description	Default
all	string	Send all traffic to one variant: `primary`, `canary`, or `baseline`.	-
primary	int	Percentage of traffic to the PRIMARY variant.	0
canary	int	Percentage of traffic to the CANARY variant.	0
baseline	int	Percentage of traffic to the BASELINE variant.	0

PodSelector: switch all traffic to the canary variant:

- name: K8S_TRAFFIC_ROUTING
  with:
    all: canary

Istio: split traffic 80/20 between primary and canary (requires trafficRouting.method: istio on the app):

- name: K8S_TRAFFIC_ROUTING
  with:
    primary: 80
    canary: 20

K8S_ROLLBACK

Restores the application to the previously running manifests. This stage is triggered automatically when a deployment fails or is cancelled with rollback. You do not add it to your pipeline; PipeCD inserts it automatically.

Livestate and drift detection

The plugin reports the live state of the application, and detects drift by comparing the live cluster state against the manifests in Git. Two controls scope what counts as drift:

Ignore annotation: annotate a resource with pipecd.dev/ignore-drift-detection: "true" and changes to it no longer flip the application to OUT_OF_SYNC.

Include/exclude filtering: narrow which resource kinds the informer watches via appStateInformer in the deploy target config. For example, to stop Secret changes from being reported as drift:

deployTargets:
  - name: local
    config:
      appStateInformer:
        excludeResources:
          - apiVersion: v1
            kind: Secret

Plan preview

Before a pipeline runs, plan preview shows the manifest diff that the deployment will apply. Secret values are masked as *** in the preview.

Helm authentication for private repositories and registries

Credentials for private Helm chart repositories and OCI registries are configured in the piped configuration under the plugin’s config block, never in app.pipecd.yaml. When the plugin starts, it runs helm repo add / helm repo update for each configured repository and helm registry login for each OCI registry, once, before any deployment. Passwords are passed to helm via stdin so they do not appear in the process list.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  plugins:
    - name: kubernetes
      # port / url / deployTargets ...
      config:
        chartRepositories:
          - type: HTTP
            name: my-private-repo
            address: https://charts.example.com
            username: my-user
            password: my-password
            insecure: false
        chartRegistries:
          - type: OCI
            address: ghcr.io
            username: my-github-user
            password: my-pat-token

chartRepositories fields: type (only HTTP), name, address, username, password, insecure. chartRegistries fields: type (only OCI), address, username, password.

Configuration reference

KubernetesApplicationSpec

The spec of a Kubernetes Application shares the common application fields (name, labels, pipeline, …) and adds the following under plugins.kubernetes:

Field	Type	Description	Required
input	KubernetesDeploymentInput	Input for the deployment such as manifests and tool versions.	Yes
quickSync	K8S_SYNC options	Options applied when the application is deployed via quick sync (no pipeline).	No
workloads	[]K8sResourceReference	Which resources are treated as the application’s workloads. Empty means all `Deployment`s.	No
service	K8sResourceReference	Which resource is treated as the application’s Service. Empty means the first `Service`.	No
variantLabel	KubernetesVariantLabel	The label used to distinguish variant (primary/canary/baseline) manifests.	No
trafficRouting	KubernetesTrafficRouting	Traffic routing configuration. Defaults to the PodSelector method.	No

KubernetesDeploymentInput

Field	Type	Description	Required
manifests	[]string	List of manifest files in the application directory used to deploy. Empty means all manifest files in the directory.	No
kubectlVersion	string	Version of `kubectl` to use.	No
kustomizeVersion	string	Version of `kustomize` to use.	No
kustomizeOptions	map[string]string	Options passed to `kustomize` commands (e.g. `load-restrictor: LoadRestrictionsNone`).	No
helmVersion	string	Version of `helm` to use.	No
helmChart	InputHelmChart	Where to fetch the Helm chart.	No
helmOptions	InputHelmOptions	Configurable parameters for `helm` commands.	No
namespace	string	The namespace where manifests are applied.	No
autoCreateNamespace	bool	Automatically create the namespace if it does not exist. Default is `false`.	No

KubernetesDeployTargetConfig

Configured under plugins[].deployTargets[].config in the piped configuration.

Field	Type	Description	Required
masterURL	string	Master URL of the cluster. Empty means the cluster `piped` runs in.	No
kubeConfigPath	string	Path to the kubeconfig file. Empty means the cluster `piped` runs in.	No
kubectlVersion	string	Default `kubectl` version for this deploy target.	No
appStateInformer	KubernetesAppStateInformer	Scopes which resources the livestate informer watches.	No

KubernetesAppStateInformer

Field	Type	Description	Required
namespace	string	Only watch this namespace. Empty means all namespaces.	No
includeResources	[]KubernetesResourceMatcher	Resources to add to the watch targets.	No
excludeResources	[]KubernetesResourceMatcher	Resources to ignore from the watch targets.	No

KubernetesResourceMatcher

Field	Type	Description	Required
apiVersion	string	API version of the resource.	Yes
kind	string	Kind of the resource. Empty means all kinds match.	No

KubernetesVariantLabel

Field	Type	Description	Required
key	string	The label key. Default `pipecd.dev/variant`.	No
primaryValue	string	Label value for the PRIMARY variant. Default `primary`.	No
canaryValue	string	Label value for the CANARY variant. Default `canary`.	No
baselineValue	string	Label value for the BASELINE variant. Default `baseline`.	No

InputHelmChart

Field	Type	Description	Required
path	string	Relative path from the repository root to the chart directory (for a local chart).	No
repository	string	Name of an added Helm chart repository.	No
name	string	Chart name.	No
version	string	Chart version.	No

InputHelmOptions

Field	Type	Description	Required
releaseName	string	Release name of the Helm deployment. Defaults to the application name.	No
setValues	map[string]string	Values passed via `--set`.	No
valueFiles	[]string	Value files to load (must be within the application directory).	No
setFiles	map[string]string	File paths whose contents are passed via `--set-file`.	No
apiVersions	[]string	Supported Kubernetes API versions passed via `--api-versions`.	No
kubeVersion	string	Kubernetes version for `Capabilities.KubeVersion`.	No

K8sResourceReference

Field	Type	Description	Required
kind	string	Kind of the referenced resource.	Yes
name	string	Name of the referenced resource.	Yes

KubernetesTrafficRouting

Field	Type	Description	Required
method	string	Routing method: `podselector` or `istio`. Default `podselector`.	No
istio	IstioTrafficRouting	Istio-specific configuration (used when `method: istio`).	No

IstioTrafficRouting

Field	Type	Description	Required
editableRoutes	[]string	Routes in the VirtualService that may be updated. Empty means all routes.	No
host	string	The service host.	No
virtualService	K8sResourceReference	Reference to the VirtualService manifest. Empty means the first one.	No

K8sResourcePatch

Used by K8S_CANARY_ROLLOUT.patches to customize manifests before generating the CANARY variant.

Field	Type	Description	Required
target.kind	string	Kind of the manifest to patch.	Yes
target.name	string	Name of the manifest to patch.	Yes
target.documentRoot	string	Path to a field whose string value is patched, e.g. `$.data.values\.yaml`. Empty means the whole manifest.	No
ops	[]K8sResourcePatchOp	List of patch operations to apply.	Yes

K8sResourcePatchOp

Field	Type	Description	Required
op	string	Operation type. Only `yaml-replace` is supported. Default is `yaml-replace`.	No
path	string	JSONPath expression pointing to the field to replace, e.g. `$.spec.replicas`.	Yes
value	string	New value to set at `path`.	Yes

Docs-V1.0.x: Kubernetes multi-cluster plugin

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

Note: The kubernetes_multicluster plugin is in Alpha. Its configuration schema may change in future releases.

The kubernetes_multicluster plugin deploys one application to multiple Kubernetes clusters from a single app.pipecd.yaml. Every pipeline stage runs against all of the application’s deploy targets in parallel, unless a stage is restricted to a subset of targets. It supports the same deployment strategies as the single-cluster Kubernetes plugin (quick sync, canary, baseline, primary rollout, and traffic routing) and extends them with per-cluster manifests, per-cluster tool versions, and per-stage target filtering.

Prerequisites

Register each cluster as a deploy target in the piped configuration. Add a kubernetes_multicluster plugin block with one deployTargets entry per cluster:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  # ...
  plugins:
    - name: kubernetes_multicluster
      port: 7002
      url: file:///path/to/plugin/binary  # or an https:// release URL
      deployTargets:
        - name: cluster-eu
          config:
            kubeConfigPath: /etc/piped/kube/cluster-eu
        - name: cluster-us
          config:
            kubeConfigPath: /etc/piped/kube/cluster-us

The plugin downloads kubectl automatically. Piped fetches kubectl (and kustomize/helm when used) via the tool registry so the binary does not need to be pre-installed on the piped host. Pin a version with kubectlVersion if you need a specific one.
When registering the application in the control plane, select every cluster the app should deploy to as its deploy targets.

Quick sync

With no pipeline defined, the plugin performs a quick sync (K8S_MULTI_SYNC): it applies all manifests to every selected cluster. This minimal app.pipecd.yaml deploys the same manifests to two clusters simultaneously:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: my-app
  plugins:
    kubernetes_multicluster:
      input:
        manifests:
          - deployment.yaml
          - service.yaml
        kubectlVersion: 1.32.2

Sync with the specified pipeline

Define a pipeline to control the rollout. The stages run in order, and each stage executes on all deploy targets in parallel:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: my-app
  pipeline:
    stages:
      - name: K8S_MULTI_CANARY_ROLLOUT
        with:
          replicas: 1
      - name: K8S_MULTI_PRIMARY_ROLLOUT
      - name: K8S_MULTI_CANARY_CLEAN
  plugins:
    kubernetes_multicluster:
      input:
        manifests:
          - deployment.yaml
        kubectlVersion: 1.32.2

See Pipeline stages for every available stage and its options.

Pipeline stages

Stages are listed under spec.pipeline.stages, with options under with. By default a stage runs on all of the application’s deploy targets; add multiTargets to restrict it to named clusters (see Per-stage target filtering).

K8S_MULTI_SYNC

Applies all manifests to every selected deploy target. This is the stage that runs during a quick sync when no pipeline block is defined in your app.pipecd.yaml. The available options are the same as those in the quickSync block of the application config.

Option	Type	Description	Default
addVariantLabelToSelector	bool	Add the PRIMARY variant label to workload selectors if missing.	false
prune	bool	Remove resources that are no longer defined in Git.	false
multiTargets	[]string	Restrict the stage to these deploy targets.	all

K8S_MULTI_PRIMARY_ROLLOUT

Rolls out the PRIMARY (stable) variant to all selected targets using the manifests defined in Git. You can optionally create a dedicated Service for the PRIMARY variant and enable pruning so that any resources removed from Git are also deleted from the cluster.

Option	Type	Description	Default
suffix	string	Suffix for the PRIMARY variant’s resource names.	primary
createService	bool	Create a Service for the PRIMARY variant.	false
addVariantLabelToSelector	bool	Add the PRIMARY variant label to workload selectors if missing.	false
prune	bool	Remove resources no longer defined in Git.	false
multiTargets	[]string	Restrict the stage to these deploy targets.	all

K8S_MULTI_CANARY_ROLLOUT

Option	Type	Description	Default
replicas	int or string	Number of CANARY pods. An integer, or a percentage of PRIMARY (e.g. `"50%"`).	1
suffix	string	Suffix for the CANARY variant’s resource names.	canary
createService	bool	Create a Service for the CANARY variant.	false
patches	[]K8sResourcePatch	Patches applied to manifests before generating the CANARY variant.	-
multiTargets	[]string	Restrict the stage to these deploy targets.	all

K8S_MULTI_CANARY_CLEAN

Removes the CANARY variant resources that were created by K8S_MULTI_CANARY_ROLLOUT. This stage is typically placed at the end of a canary pipeline to clean up after promotion or after a rollback decision.

Option	Type	Description	Default
multiTargets	[]string	Restrict the stage to these deploy targets.	all

K8S_MULTI_BASELINE_ROLLOUT

Option	Type	Description	Default
replicas	int or string	Number of BASELINE pods. An integer, or a percentage of PRIMARY.	1
suffix	string	Suffix for the BASELINE variant’s resource names.	baseline
createService	bool	Create a Service for the BASELINE variant.	false
multiTargets	[]string	Restrict the stage to these deploy targets.	all

K8S_MULTI_BASELINE_CLEAN

Removes the BASELINE variant resources that were created by K8S_MULTI_BASELINE_ROLLOUT. Place this stage at the end of a canary/baseline pipeline to clean up after the analysis is complete, whether you promoted or rolled back.

Option	Type	Description	Default
multiTargets	[]string	Restrict the stage to these deploy targets.	all

K8S_MULTI_TRAFFIC_ROUTING

Shifts traffic between the PRIMARY, CANARY, and BASELINE variants. The routing method is set by the application-level trafficRouting config and determines how the split is applied.

PodSelector (default) works by updating the Service’s spec.selector to point entirely at one variant. This means one variant must receive 100% of traffic at a time and baseline is not supported with this method.

Istio works by updating the VirtualService route weights, which allows traffic to be split by percentage across all three variants simultaneously.

Option	Type	Description	Default
all	string	Send all traffic to one variant: `primary`, `canary`, or `baseline`.	-
primary	int	Percentage of traffic to the PRIMARY variant.	0
canary	int	Percentage of traffic to the CANARY variant.	0
baseline	int	Percentage of traffic to the BASELINE variant.	0
multiTargets	[]string	Restrict the stage to these deploy targets.	all

PodSelector: switch all traffic to the canary variant:

- name: K8S_MULTI_TRAFFIC_ROUTING
  with:
    all: canary

Istio: split traffic 80/20 between primary and canary (requires trafficRouting.method: istio on the app)

- name: K8S_MULTI_TRAFFIC_ROUTING
  with:
    primary: 80
    canary: 20

K8S_MULTI_ROLLBACK

Restores the application to the previously running manifests on every target. It prunes resources no longer defined in those manifests and cleans up any leftover CANARY or BASELINE variant resources. This stage is triggered automatically when a deployment fails or is cancelled with rollback. You do not add it to your pipeline; PipeCD inserts it automatically.

Multi-cluster features

One application, many clusters

A single app.pipecd.yaml deploys to every cluster selected as a deploy target. Every stage runs against all targets in parallel, and the deployment result reports the outcome per cluster, so one cluster failing does not hide the status of the others.

By default all targets share the same input.manifests. To give each cluster its own manifests or tool versions, declare multiTargets.

Per-cluster manifests with multiTargets

Each multiTargets entry binds a deploy target name to its own manifest paths (and optional tool overrides). Use this when clusters need different manifests - for example region-specific config:

spec:
  plugins:
    kubernetes_multicluster:
      input:
        multiTargets:
          - target:
              name: cluster-eu
            manifests:
              - ./cluster-eu/deployment.yaml
          - target:
              name: cluster-us
            manifests:
              - ./cluster-us/deployment.yaml
        kubectlVersion: 1.32.2

Per-target overrides available on each entry:

kubectlVersion : use a different kubectl version for this cluster (takes precedence over input.kubectlVersion).
kustomizeDir: point this cluster at its own kustomize overlay directory.
kustomizeVersion / kustomizeOptions : per-cluster kustomize control.

multiTargets:
  - target:
      name: cluster-eu
    kustomizeDir: ./overlays/eu
  - target:
      name: cluster-us
    kustomizeDir: ./overlays/us
    kubectlVersion: 1.31.0

Per-stage target filtering

Any stage can be limited to a subset of clusters with the multiTargets option, which takes a list of deploy target names. When multiTargets is empty (the default) the stage runs on all targets. When it contains names, the stage runs only on those clusters. Any name that does not match a configured deploy target is silently ignored.

This lets you roll out cautiously. For example, canary on cluster-eu only, then promote to primary everywhere:

pipeline:
  stages:
    - name: K8S_MULTI_CANARY_ROLLOUT
      with:
        replicas: 1
        multiTargets: [cluster-eu]
    - name: K8S_MULTI_PRIMARY_ROLLOUT          # all targets
    - name: K8S_MULTI_CANARY_CLEAN
      with:
        multiTargets: [cluster-eu]

Livestate and drift detection

The plugin reports the live state of the application per cluster. Each deploy target gets its own sync status (SYNCED, OUT_OF_SYNC, or UNKNOWN) and resource tree, aggregated under a single application entry in the UI.

Drift is detected by comparing the live cluster state against the manifests in Git. Two controls scope what counts as drift:

Ignore annotation : annotate a resource with pipecd.dev/ignore-drift-detection: "true" and changes to it no longer flip the application to OUT_OF_SYNC.

Include/exclude filtering : narrow which resource kinds the informer watches via appStateInformer in the deploy target config. For example, to stop Secret changes from being reported as drift:

deployTargets:
  - name: cluster-us
    config:
      kubeConfigPath: /etc/piped/kube/cluster-us
      appStateInformer:
        excludeResources:
          - apiVersion: v1
            kind: Secret

Plan preview

Before a pipeline runs, plan preview shows the manifest diff that the deployment will apply. For multi-cluster applications, the diff is rendered per deploy target so you can see exactly what will change on each cluster (including “No changes were detected” for clusters that are unaffected). Secret values are masked as *** in the preview.

Helm authentication for private repositories and registries

Credentials for private Helm chart repositories and OCI registries are configured in the piped configuration under the plugin’s config block and never in app.pipecd.yaml. When the plugin starts, it runs helm repo add / helm repo update for each configured repository and helm registry login for each OCI registry, once, before any deployment. Passwords are passed to helm via stdin so they do not appear in the process list.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  plugins:
    - name: kubernetes_multicluster
      # port / url / deployTargets ...
      config:
        chartRepositories:
          - type: HTTP                       # ChartMuseum, Nexus, Artifactory, ...
            name: my-private-repo
            address: https://charts.example.com
            username: my-user
            password: my-password
            insecure: false
        chartRegistries:
          - type: OCI                        # GHCR, ECR, Google Artifact Registry, ...
            address: ghcr.io
            username: my-github-user
            password: my-pat-token

chartRepositories fields: type (only HTTP), name, address, username, password, insecure. chartRegistries fields: type (only OCI), address, username, password.

Configuration reference

KubernetesApplicationSpec

The spec of a KubernetesApp shares the common application fields (name, labels, pipeline, …) and adds the following under plugins.kubernetes_multicluster:

Field	Type	Description	Required
input	KubernetesDeploymentInput	Input for the deployment such as manifests, tool versions, and per-cluster targets.	Yes
quickSync	K8S_MULTI_SYNC options	Options applied when the application is deployed via quick sync (no pipeline).	No
workloads	[]K8sResourceReference	Which resources are treated as the application’s workloads. Empty means all `Deployment`s.	No
service	K8sResourceReference	Which resource is treated as the application’s Service. Empty means the first `Service`.	No
variantLabel	KubernetesVariantLabel	The label used to distinguish variant (primary/canary/baseline) manifests.	No
trafficRouting	KubernetesTrafficRouting	Traffic routing configuration. Defaults to the PodSelector method.	No

KubernetesDeploymentInput

Field	Type	Description	Required
manifests	[]string	List of manifest files in the application directory used to deploy. Empty means all manifest files in the directory.	No
kubectlVersion	string	Version of `kubectl` to use.	No
kustomizeVersion	string	Version of `kustomize` to use.	No
kustomizeOptions	map[string]string	Options passed to `kustomize` commands (e.g. `load-restrictor: LoadRestrictionsNone`). Mutually exclusive with `helmChart`.	No
helmVersion	string	Version of `helm` to use.	No
helmChart	InputHelmChart	Where to fetch the Helm chart.	No
helmOptions	InputHelmOptions	Configurable parameters for `helm` commands.	No
namespace	string	The namespace where manifests are applied.	No
autoCreateNamespace	bool	Automatically create the namespace if it does not exist. Default is `false`.	No
multiTargets	[]KubernetesMultiTarget	Per-cluster manifest paths and tool overrides. See Multi-cluster features.	No

KubernetesMultiTarget

Declares per-cluster input. Each entry targets one deploy target by name and may override manifests and tool settings for that cluster.

Field	Type	Description	Required
target.name	string	Name of the deploy target this entry applies to.	Yes
target.labels	map[string]string	Labels for the target.	No
manifests	[]string	Manifest files for this target. Overrides the top-level `input.manifests` for this cluster.	No
kubectlVersion	string	`kubectl` version for this target. Takes precedence over `input.kubectlVersion`.	No
kustomizeDir	string	Path to a kustomize overlay directory for this target.	No
kustomizeVersion	string	`kustomize` version for this target.	No
kustomizeOptions	map[string]string	`kustomize` options for this target.	No

KubernetesDeployTargetConfig

Configured under plugins[].deployTargets[].config in the piped configuration, one per cluster.

Field	Type	Description	Required
masterURL	string	Master URL of the cluster. Empty means in-cluster.	No
kubeConfigPath	string	Path to the kubeconfig file. Empty means in-cluster.	No
kubectlVersion	string	Default `kubectl` version for this cluster.	No
appStateInformer	KubernetesAppStateInformer	Scopes which resources the livestate informer watches.	No

KubernetesAppStateInformer

Field	Type	Description	Required
namespace	string	Only watch this namespace. Empty means all namespaces.	No
includeResources	[]KubernetesResourceMatcher	Resources to add to the watch targets.	No
excludeResources	[]KubernetesResourceMatcher	Resources to ignore from the watch targets.	No

KubernetesResourceMatcher

Field	Type	Description	Required
apiVersion	string	API version of the resource.	Yes
kind	string	Kind of the resource. Empty means all kinds match.	No

KubernetesVariantLabel

Field	Type	Description	Required
key	string	The label key. Default `pipecd.dev/variant`.	No
primaryValue	string	Label value for the PRIMARY variant. Default `primary`.	No
canaryValue	string	Label value for the CANARY variant. Default `canary`.	No
baselineValue	string	Label value for the BASELINE variant. Default `baseline`.	No

InputHelmChart

Field	Type	Description	Required
gitRemote	string	Git remote address where the chart is located. Empty means the same repository.	No
ref	string	Commit SHA or tag for the remote git.	No
path	string	Relative path to the chart directory (for a local chart).	No
repository	string	Name of an added Helm chart repository.	No
name	string	Chart name.	No
version	string	Chart version.	No

InputHelmOptions

Field	Type	Description	Required
releaseName	string	Release name of the Helm deployment. Defaults to the application name.	No
setValues	map[string]string	Values passed via `--set`.	No
valueFiles	[]string	Value files to load (must be within the application directory).	No
setFiles	map[string]string	File paths whose contents are passed via `--set-file`.	No
apiVersions	[]string	Supported Kubernetes API versions passed via `--api-versions`.	No
kubeVersion	string	Kubernetes version for `Capabilities.KubeVersion`.	No

K8sResourceReference

Field	Type	Description	Required
kind	string	Kind of the referenced resource.	Yes
name	string	Name of the referenced resource.	Yes

KubernetesTrafficRouting

Field	Type	Description	Required
method	string	Routing method: `podselector` or `istio`. Default `podselector`.	No
istio	IstioTrafficRouting	Istio-specific configuration (used when `method: istio`).	No

IstioTrafficRouting

Field	Type	Description	Required
editableRoutes	[]string	Routes in the VirtualService that may be updated. Empty means all routes.	No
host	string	The service host.	No
virtualService	K8sResourceReference	Reference to the VirtualService manifest. Empty means the first one.	No

K8sResourcePatch

Used by K8S_MULTI_CANARY_ROLLOUT.patches to customize manifests before generating the CANARY variant.

Field	Type	Description	Required
target.kind	string	Kind of the manifest to patch.	Yes
target.name	string	Name of the manifest to patch.	Yes
target.documentRoot	string	Path to a field whose string value is patched, e.g. `$.data.values\.yaml`. Empty means the whole manifest.	No
ops	[]K8sResourcePatchOp	List of patch operations to apply.	Yes

K8sResourcePatchOp

Field	Type	Description	Required
op	string	Operation type. Only `yaml-replace` is supported. Default is `yaml-replace`.	No
path	string	JSONPath expression pointing to the field to replace, e.g. `$.spec.replicas`.	Yes
value	string	New value to set at `path`.	Yes

Docs-V1.0.x: Terraform plugin

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

The terraform plugin runs Terraform-based deployments. It reads the Terraform files in the application directory and applies them through a pipeline, running terraform plan and terraform apply as pipeline stages. A deploy target represents a Terraform execution environment: its variables and drift-detection setting.

Prerequisites

Register the plugin in the piped configuration. Add a terraform plugin block with one or more deployTargets:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  # ...
  plugins:
    - name: terraform
      port: 7002
      url: file:///path/to/plugin/binary  # or an https:// release URL
      deployTargets:
        - name: dev
          config:
            vars:
              - "project=pipecd"
            driftDetectionEnabled: true

The plugin downloads terraform automatically. piped fetches the terraform binary via the tool registry, so it does not need to be pre-installed on the piped host. The version defaults to 0.13.0; pin a different one with terraformVersion in the application configuration.
Put the application’s Terraform files (*.tf) in the application directory alongside app.pipecd.yaml.

Quick sync

With no pipeline defined, the plugin performs a quick sync (TERRAFORM_APPLY): it applies any detected changes to reach the state described by the Terraform files. This minimal app.pipecd.yaml deploys the Terraform files in the application directory:

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-infra
  plugins:
    terraform:
      workspace: dev
      vars:
        - "project=pipecd"

Sync with the specified pipeline

Define a pipeline to run terraform plan before applying. A common pattern is to plan, pause for a manual approval, then apply:

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-infra
  pipeline:
    stages:
      - name: TERRAFORM_PLAN
      - name: WAIT_APPROVAL
        with:
          approvers:
            - user-a
      - name: TERRAFORM_APPLY
  plugins:
    terraform:
      workspace: dev

See Pipeline stages for every available stage and its options.

Pipeline stages

Stages are listed under spec.pipeline.stages, with options under with.

TERRAFORM_PLAN

Runs terraform plan and shows the changes the deployment would apply. Use it before TERRAFORM_APPLY to review the plan (optionally behind a WAIT_APPROVAL stage).

Option	Type	Description	Default
exitOnNoChanges	bool	Exit the pipeline with a success status when the plan detects no changes.	false

TERRAFORM_APPLY

Runs terraform apply to apply the changes described by the Terraform files. This is also the stage that runs during a quick sync when no pipeline block is defined. It takes no options.

TERRAFORM_ROLLBACK

Restores the infrastructure to the previous commit’s Terraform files by running terraform apply against them. This stage is triggered automatically when a deployment fails or is cancelled with rollback. You do not add it to your pipeline; PipeCD inserts it automatically.

Livestate and drift detection

The plugin detects drift by running terraform plan and comparing the actual infrastructure against the Terraform files in Git. If the plan reports changes, the application is marked OUT_OF_SYNC; otherwise it is SYNCED. Drift detection is controlled per deploy target by driftDetectionEnabled, which is enabled by default. It is an evolving feature and its behaviour may change in future releases.

Plan preview

Before a pipeline runs, plan preview runs terraform plan and shows the changes the deployment would apply, so you can review them on the pull request.

Configuration reference

TerraformApplicationSpec

The spec of a Terraform Application shares the common application fields (name, labels, pipeline, …) and adds the following under plugins.terraform:

Field	Type	Description	Required
workspace	string	The Terraform workspace name. Empty means the `default` workspace.	No
terraformVersion	string	Version of `terraform` to use. Empty means the default version (`0.13.0`).	No
vars	[]string	Variables passed to `terraform` commands with `-var`. Each entry is `key=value` (e.g. `image_id=ami-abc123`).	No
varFiles	[]string	Variable files passed to `terraform` commands with `-var-file`.	No
commandFlags	TerraformCommandFlags	Additional flags passed to `terraform` commands.	No
commandEnvs	TerraformCommandEnvs	Additional environment variables set while running `terraform` commands.	No

TerraformCommandFlags

Extra flags appended to the underlying terraform commands.

Field	Type	Description	Required
shared	[]string	Flags applied to every `terraform` command.	No
init	[]string	Flags applied to `terraform init`.	No
plan	[]string	Flags applied to `terraform plan`.	No
apply	[]string	Flags applied to `terraform apply`.	No

TerraformCommandEnvs

Extra environment variables set when running the underlying terraform commands.

Field	Type	Description	Required
shared	[]string	Environment variables applied to every `terraform` command.	No
init	[]string	Environment variables applied to `terraform init`.	No
plan	[]string	Environment variables applied to `terraform plan`.	No
apply	[]string	Environment variables applied to `terraform apply`.	No

DeployTargetConfig

Configured under plugins[].deployTargets[].config in the piped configuration, one per Terraform execution environment.

Field	Type	Description	Required
vars	[]string	Variables passed to `terraform` commands with `-var` for this target. Each entry is `key=value` (e.g. `image_id=ami-abc123`).	No
driftDetectionEnabled	bool	Enable drift detection for this target. Default is `true`.	No

Docs-V1.0.x: ECS Plugin

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

Note: The ECS plugin is currently in alpha status.

The ECS plugin enables PipeCD to deploy applications to Amazon ECS. It manages deployments via ECS task sets using the EXTERNAL deployment controller, which allows PipeCD to control traffic routing and progressive delivery directly.

There are two main deployment modes:

Service: An application that runs continuously, optionally placed behind a load balancer. Requires a TaskDefinition file and a Service definition file.
Standalone task: A one-time or periodic batch job. Requires only a TaskDefinition file.

Prerequisites

`piped` configuration

Add the ECS plugin to your piped configuration:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  plugins:
    - name: ecs
      port: 7003
      url: file:///path/to/.piped/plugins/ecs
      deployTargets:
        - name: my-ecs-target
          config:
            region: us-east-1

See ECSDeployTargetConfig for all available options including cross-account role assumption and OIDC-based authentication.

IAM permissions

ECS deployments involve three distinct IAM roles. Confusing them is a common source of permission errors.

Deployment role: the role assumed by piped when calling AWS APIs to deploy your application. Configured via roleARN in the deploy target config, or resolved from the default credential chain. This role needs:

{
  "Effect": "Allow",
  "Action": [
    "ecs:CreateService",
    "ecs:UpdateService",
    "ecs:DescribeServices",
    "ecs:RegisterTaskDefinition",
    "ecs:DescribeTaskDefinition",
    "ecs:CreateTaskSet",
    "ecs:UpdateServicePrimaryTaskSet",
    "ecs:DeleteTaskSet",
    "ecs:DescribeTaskSets",
    "ecs:ListTasks",
    "ecs:DescribeTasks",
    "ecs:RunTasks",
    "ecs:ListTagsForResource",
    "ecs:TagResource",
    "ecs:UntagResource",
    "elasticloadbalancing:DescribeListeners",
    "elasticloadbalancing:DescribeRules",
    "elasticloadbalancing:ModifyRule",
    "iam:PassRole"
  ],
  "Resource": "*"
}

iam:PassRole is required because AWS enforces it whenever a caller passes a role ARN to ECS APIs. Specifically, it is triggered by RegisterTaskDefinition (which receives executionRoleArn and taskRoleArn from the task definition file) and CreateService (which receives the service role ARN). In practice, scope this permission to the specific role ARNs used in your task and service definitions rather than "Resource": "*".

Task execution role: assumed by the ECS agent on your behalf to prepare the task environment before the container starts. It is not used by piped or your application. Typical uses:

Pull container images from Amazon ECR
Publish container logs to CloudWatch Logs
Retrieve secrets from Secrets Manager or SSM Parameter Store

This role is specified as executionRoleArn in your task definition file.

Task role: assumed by the application running inside the container. It is not used by piped or the ECS agent. Grant only the permissions your application needs at runtime, for example reading from S3 or writing to DynamoDB.

This role is specified as taskRoleArn in your task definition file.

Definition files

The ECS plugin reads two YAML or JSON files from your application directory to determine what to deploy.

Task definition file

Specifies the container(s) to run: image, CPU, memory, ports, environment variables, and IAM roles. The file is parsed into the AWS SDK types.TaskDefinition struct (the response type), then the plugin forwards a subset of those fields to RegisterTaskDefinition. Field names must match the Go struct field names (case-insensitive), which correspond to the AWS API JSON field names in camelCase. Fields present in RegisterTaskDefinitionInput but absent from types.TaskDefinition cannot be set through this file.

# taskdef.yaml
family: my-service
executionRoleArn: arn:aws:iam::XXXX:role/ECSTaskExecutionRole
taskRoleArn: arn:aws:iam::XXXX:role/ECSTaskRole # optional: grants your app AWS permissions
requiresCompatibilities:
  - FARGATE
networkMode: awsvpc
cpu: "256"
memory: "512"
containerDefinitions:
  - name: web
    image: public.ecr.aws/nginx/nginx:1.27
    portMappings:
      - containerPort: 80
    cpu: 100
    memory: 100

The default filename is taskdef.json. Override it with taskDefinitionFile in the application config.

Note: The tags field in the task definition file is not currently forwarded to RegisterTaskDefinition. Support is planned for a future version.

Service definition file

Specifies how the ECS service runs: cluster, desired task count, network configuration, and load balancer settings. The file is parsed into the AWS SDK types.Service struct (the response type), then the plugin forwards a subset of those fields to CreateService or UpdateService. Field names must match the Go struct field names (case-insensitive), which correspond to the AWS API JSON field names in camelCase. Fields present in CreateServiceInput/UpdateServiceInput but absent from types.Service cannot be set through this file.

# servicedef.yaml
serviceName: my-service
clusterArn: arn:aws:ecs:ap-northeast-1:XXXX:cluster/my-cluster
desiredCount: 2
deploymentController:
  type: EXTERNAL # required by the ECS plugin
launchType: FARGATE
networkConfiguration:
  awsvpcConfiguration:
    assignPublicIp: ENABLED
    subnets:
      - subnet-YYYY
    securityGroups:
      - sg-YYYY
schedulingStrategy: REPLICA

Note: Due to current parsing limitations, not all fields are forwarded to CreateService and UpdateService. The fields listed below are not yet supported:

CreateService: capacityProviderStrategy, serviceConnectConfiguration

UpdateService: deploymentConfiguration, healthCheckGracePeriodSeconds, placementConstraints, platformVersion, capacityProviderStrategy, serviceConnectConfiguration, serviceRegistries, volumeConfigurations

Full field support is planned alongside support for the ECS deployment controller in a future version.

Fields you should not include:

loadBalancers: PipeCD injects the target group configuration from targetGroups in the app config at deploy time.
desiredCount: omit this when using Auto Scaling, otherwise PipeCD will reconcile it back to the value in the file on every deployment.
Tags managed by PipeCD (pipecd/managed-by, pipecd/commit-hash, etc.): these are stamped automatically and will be overwritten.

The service definition file is not needed for standalone tasks.

Service definition requirements

The ECS plugin manages deployments via task sets. Your service definition file must specify the EXTERNAL deployment controller:

deploymentController:
  type: EXTERNAL

Without this, the plugin cannot create or manage task sets for your service.

Note: Support for the ECS deployment controller (type: ECS) is planned for a future version.

Choosing a deployment strategy

When a pipeline is configured, the ECS plugin compares the container images in the target task definition against those in the currently running deployment to decide whether to execute the pipeline or skip it with a quick sync:

Condition	Strategy
No running deployment source available	Pipeline sync
Running task definition cannot be loaded	Pipeline sync (fallback)
One or more container images added, removed, or changed	Pipeline sync
No container image changes	Quick sync

The comparison checks each container by name. If the image name differs, the full change is reported; if only the tag or digest differs, the version change is reported. All detected changes appear in the deployment summary in the UI.

Note: Non-image changes (environment variables, CPU/memory, etc.) do not affect strategy selection. If you update only those fields, the plugin will choose quick sync even when a pipeline is configured.

Use quick sync when:

You want a simple, immediate rollout with no traffic splitting.
The environment is non-critical (e.g. dev, staging) where gradual rollout adds no value.

Use pipeline sync when:

You want to gradually shift traffic using canary or blue-green strategies.
You need manual approval gates before full rollout.
You want automated analysis (metrics, logs) to validate the new version before promoting it.

Quick sync

By default, when no pipeline is specified in the application configuration, PipeCD triggers a quick sync for any merged pull request. Quick sync registers the new task definition, creates/updates the ECS service, promotes a new primary task set, waits for stability, and removes old task sets. All traffic is switched to the new version immediately.

Note: Standalone tasks always use quick sync. Pipeline sync is not supported for standalone tasks.

Service with load balancer

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-service
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        targetGroups:
          primary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-lb/YYYY
            containerName: web
            containerPort: 80

Standalone task (batch job)

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-batch-job
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        taskDefinitionFile: taskdef.yaml
        runStandaloneTask: true
        clusterArn: arn:aws:ecs:ap-northeast-1:XXXX:cluster/my-cluster
        launchType: FARGATE
        awsvpcConfiguration:
          assignPublicIp: ENABLED
          subnets:
            - subnet-YYYY
          securityGroups:
            - sg-YYYY

Service discovery (no load balancer)

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-internal-service
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        accessType: SERVICE_DISCOVERY

Pipeline sync (progressive delivery)

Add a pipeline field to the application configuration to define a custom deployment strategy using the following ECS stages:

Stage	Description
`ECS_PRIMARY_ROLLOUT`	Roll out the new task set as the PRIMARY variant
`ECS_CANARY_ROLLOUT`	Roll out the new task set as the CANARY variant (receives no traffic initially)
`ECS_TRAFFIC_ROUTING`	Route traffic between PRIMARY and CANARY task sets via ALB listener weights. Requires `accessType: ELB` and both `primary` and `canary` target groups to be configured.
`ECS_CANARY_CLEAN`	Clean up all task sets belonging to the CANARY variant

Common stages also available:

Stage	Description
`WAIT`	Wait for a specified duration
`WAIT_APPROVAL`	Wait for a manual approval
`ANALYSIS`	Run analysis to validate metrics before proceeding

ECS_ROLLBACK is automatically added when autoRollback: true is set (the default).

Note: ECS_SYNC is the stage used internally by quick sync. It is not intended for use in a custom pipeline.

Canary deployment

Gradually shifts a small fraction of traffic to the new version first, observes it, then promotes to primary. Requires two ALB target groups (primary and canary) both attached to the same listener.

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-service
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        targetGroups:
          primary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-primary/YYYY
            containerName: web
            containerPort: 80
          canary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-canary/ZZZZ
            containerName: web
            containerPort: 80
  pipeline:
    stages:
      # 1. Deploy the canary task set at 30% of the primary workload capacity.
      #    At this point canary is running but receives no traffic yet.
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 30

      # 2. Route 10% of traffic to canary, 90% stays on primary.
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 10

      # 3. (Optional) Run automated analysis while canary is receiving 10% traffic.
      #    Piped queries the analysis provider every 5 minutes for 10 minutes total.
      #    If the HTTP error rate exceeds 1%, the stage fails and ECS_ROLLBACK triggers.
      #    Remove this stage if you do not have an analysis provider configured.
      - name: ANALYSIS
        with:
          duration: 10m
          metrics:
            - strategy: THRESHOLD
              provider: my-prometheus # name of the analysis provider in piped config
              interval: 5m
              expected:
                max: 0.01 # fail if error rate exceeds 1%
              query: |
                sum(rate(http_requests_total{job="my-service",status=~"5.*"}[5m]))
                /
                sum(rate(http_requests_total{job="my-service"}[5m]))

      # 4. Increase canary traffic to 50%.
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 50

      # 5. Wait for manual approval before completing the rollout.
      - name: WAIT_APPROVAL
        with:
          timeout: 1h

      # 6. Promote: update the PRIMARY task set to the new version.
      #    Primary still receives 50% traffic during rollout.
      - name: ECS_PRIMARY_ROLLOUT

      # 7. Route 100% of traffic back to primary (new version).
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100

      # 8. Remove the canary task set.
      - name: ECS_CANARY_CLEAN

Blue/Green deployment

Deploys the new version (green) at full scale alongside the old version (blue), then cuts over all traffic automatically after approval. Requires two ALB target groups (primary and canary) both attached to the same listener.

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-service
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        targetGroups:
          primary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-blue/YYYY
            containerName: web
            containerPort: 80
          canary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-green/ZZZZ
            containerName: web
            containerPort: 80
  pipeline:
    stages:
      # 1. Deploy the green task set at 100% capacity alongside the existing blue.
      #    Green receives no traffic yet.
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 100

      # 2. Wait for approval before cutting over traffic.
      - name: WAIT_APPROVAL
        with:
          timeout: 1h

      # 3. Cut over: send 100% of traffic to green (canary target group).
      #    Blue tasks are still running as a fallback.
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 100

      # 4. Update the PRIMARY task set to the new version.
      - name: ECS_PRIMARY_ROLLOUT

      # 5. Switch traffic back to the primary target group (now running the new version).
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100

      # 6. Remove the green (canary) task set.
      - name: ECS_CANARY_CLEAN

Migrating from v0

This section covers the steps specific to ECS applications. For the general migration process (updating pipectl, migrating the Control Plane database, installing pipedv1), follow the Migrate to PipeCD v1 guide first.

1. Update the piped configuration

In v0, ECS was configured as a platform provider with type: ECS. In v1, it is a plugin.

v0 piped config:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  platformProviders:
    - name: ecs-dev
      type: ECS
      config:
        region: us-east-1
        credentialsFile: ~/.aws/credentials
        profile: default
        roleARN: arn:aws:iam::XXXX:role/deployment-role
        tokenFile: /var/run/secrets/token

v1 piped config:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  plugins:
    - name: ecs
      port: 7003
      url: https://github.com/pipe-cd/pipecd/releases/download/<version>/ecs-plugin
      deployTargets:
        - name: ecs-dev
          config:
            region: us-east-1
            credentialsFile: ~/.aws/credentials
            profile: default
            roleARN: arn:aws:iam::XXXX:role/deployment-role
            tokenFile: /var/run/secrets/token

The credential fields (region, credentialsFile, profile, roleARN, tokenFile) are identical. They move from platformProviders[].config to plugins[].deployTargets[].config.

2. Update the application configuration

The application configuration file format changes in two ways: the kind field and the location of ECS-specific fields.

v0 application configuration file:

apiVersion: pipecd.dev/v1beta1
kind: ECSApp
spec:
  name: my-service
  labels:
    env: production
  input:
    serviceDefinitionFile: servicedef.yaml
    taskDefinitionFile: taskdef.yaml
    targetGroups:
      primary:
        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-primary/YYYY
        containerName: web
        containerPort: 80
      canary:
        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-canary/ZZZZ
        containerName: web
        containerPort: 80
  quickSync:
    recreate: false
  pipeline:
    stages:
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 30
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 20
      - name: ECS_PRIMARY_ROLLOUT
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100
      - name: ECS_CANARY_CLEAN

v1 application configuration file:

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-service
  labels:
    env: production
  plugin: ecs
  deployTarget: ecs-dev
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        targetGroups:
          primary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-primary/YYYY
            containerName: web
            containerPort: 80
          canary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-canary/ZZZZ
            containerName: web
            containerPort: 80
      quickSync:
        recreate: false
  pipeline:
    stages:
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 30
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 20
      - name: ECS_PRIMARY_ROLLOUT
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100
      - name: ECS_CANARY_CLEAN

Summary of field changes:

v0	v1
`kind: ECSApp`	`kind: Application`
(no field)	`spec.plugin: ecs`
(no field)	`spec.deployTarget: <deploy-target-name>`
`spec.input.*`	`spec.plugins.ecs.input.*`
`spec.quickSync.*`	`spec.plugins.ecs.quickSync.*`
`spec.pipeline.*`	`spec.pipeline.*` (unchanged)
`spec.name`, `spec.labels`	unchanged

3. Review behavioral changes

The v1 plugin includes several fixes to behaviors that could cause service disruptions in v0. Read the Changes from v0 section to understand what changed before running your first v1 deployment.

Changes from v0

This section describes behavioral differences between the legacy ECS provider in PipeCD v0 and the ECS plugin in PipeCD v1. If you are migrating from v0, review these changes before deploying.

ECS_PRIMARY_ROLLOUT: eliminates 503 errors during canary promotion

v0 behavior: ECS_PRIMARY_ROLLOUT deleted all ACTIVE task sets (including the CANARY task set) before promoting the new PRIMARY. This created a window where no task set was serving traffic, causing HTTP 503 errors on the load balancer: issue #4710.

v1 behavior: ECS_PRIMARY_ROLLOUT records the current PRIMARY task set ARN before creating the new one, promotes the new task set to PRIMARY, then deletes only the old PRIMARY. Any CANARY task set created by an earlier ECS_CANARY_ROLLOUT stage remains intact and continues to serve its share of traffic throughout the rollout window. The CANARY is cleaned up separately by ECS_CANARY_CLEAN.

This change eliminates the 503 window that existed in v0 during canary deployments.

Rollback: eliminates 503 errors when reverting

v0 behavior: During rollback, task sets were recreated first. This left a window where the ALB listener was still sending a fraction of traffic to the canary target group even though its tasks were being deleted, resulting in 503 errors for requests hitting that target group.

v1 behavior: The ECS_ROLLBACK stage restores ALB listener weights to 100% primary / 0% canary before touching any task set. Listener ARNs and the canary target group ARN are persisted in deployment metadata by ECS_TRAFFIC_ROUTING, so rollback can look them up without an additional AWS API call. Only after the listener is safe does rollback create the new task set, promote it to PRIMARY, and delete the remaining task sets.

Drift detection: no false alerts from AWS-managed changes

v0 behavior: Drift detection compared the fields of the live ECS resources against what was declared in the Git definition files. This produced false OUT_OF_SYNC signals whenever AWS mutated a field outside of PipeCD’s control, for example when Auto Scaling adjusted desiredCount, or when AWS updated internal service metadata.

v1 behavior: The plugin stamps a pipecd/commit-hash tag onto each PRIMARY task set at the end of every deployment. Drift detection compares this tag value against the current Git commit hash:

If they match: SYNCED
If they differ: OUT_OF_SYNC, with the deployed and expected hashes shown as the reason

AWS-side mutations that do not change the deployed commit (such as Auto Scaling adjustments) no longer trigger drift alerts.

Application live state

The ECS plugin continuously monitors your application’s live state and displays it on the PipeCD UI. piped periodically polls AWS and compares the running state against the commit hash declared in Git.

Sync status

Status	Meaning
SYNCED	The PRIMARY task set on AWS is tagged with the current Git commit hash.
OUT_OF_SYNC	The commit hash tag on the PRIMARY task set does not match the current Git commit, the service was not found, or no PRIMARY task set exists.
UNKNOWN	The application is a standalone task (no persistent service to observe), or live state could not be fetched due to a transient error.
INVALID_CONFIG	`serviceDefinitionFile` is missing from the application configuration.

Resource tree

The UI displays the ECS resources as a hierarchy. The structure depends on the deployment controller type configured in the service definition.

EXTERNAL controller (required by this plugin for canary/blue-green):

ECS:Service
└── ECS:TaskSet  (one per variant: PRIMARY, CANARY, etc.)
    └── ECS:Task

Resource metadata

Each resource type exposes the following metadata fields in the UI:

ECS:Service

Field	Description
status	Service status (`ACTIVE`, `DRAINING`, `INACTIVE`)
runningCount	Number of tasks currently running
desiredCount	Number of tasks the service intends to maintain
pendingCount	Number of tasks in the process of starting

ECS:TaskSet (EXTERNAL controller only)

Field	Description
status	Task set status (`PRIMARY`, `ACTIVE`, `DRAINING`)
taskDefinition	ARN of the task definition revision running in this task set
scale	Traffic weight assigned to this task set (e.g. `30%`)
commit	Git commit hash that created this task set

ECS:Task

Field	Description
lastStatus	Last known task status (`RUNNING`, `PENDING`, `STOPPED`)
startedAt	Timestamp when the task transitioned to RUNNING

Health status

Resource	HEALTHY condition	UNHEALTHY condition
Service	Status is `ACTIVE`, `pendingCount` is 0, and `runningCount ≥ desiredCount`	Status is `DRAINING`/`INACTIVE`, or tasks are pending
TaskSet	Stability status is `STEADY_STATE`	Stability status is `STABILIZING`
Deployment	Rollout state is `COMPLETED`	Rollout state is `FAILED` or `IN_PROGRESS`
Task	Last status is `RUNNING` and container health checks pass	Last status is `PENDING`/`STOPPED`, or container health checks are failing

Plan preview

Before a deployment is triggered, PipeCD can show a preview of what will change. The ECS plugin compares the running definition files (from the last deployed commit) against the target definition files (from the incoming commit) and displays a unified diff.

What is shown

Item	Description
Task definition diff	Unified diff between the running `taskdef` file and the target `taskdef` file
Service definition diff	Unified diff between the running `servicedef` file and the target `servicedef` file (only shown when `serviceDefinitionFile` is set)
Summary	A one-line summary: `task definition changed`, `service definition changed`, or `No changes were detected`

Example output

When only the container image in the task definition is updated, the plan preview looks like:

--- taskdef (running)
+++ taskdef (target)
@@ -3,7 +3,7 @@
 containerDefinitions:
   - name: web
-    image: public.ecr.aws/nginx/nginx:1.25
+    image: public.ecr.aws/nginx/nginx:1.27
     cpu: 100
     memory: 100
     portMappings:

If no files changed between the two commits, the summary shows No changes were detected and no diff is displayed.

Notes

When using an ALB, all listener rules that reference the configured target groups are controlled by PipeCD. Attach the target groups to your listener rules before deploying.
Service Connect uses the ECS deployment controller, which is incompatible with the EXTERNAL controller required by this plugin. Canary and blue/green deployments are not available when using Service Connect.
When using Service Auto Scaling, omit desiredCount from the service definition file to prevent PipeCD from reconciling it on every deployment.

Configuration reference

ECSDeployTargetConfig

Configured under plugins[].deployTargets[].config in the piped configuration.

Field	Type	Description	Required
region	string	AWS region (e.g. `us-east-1`).	Yes
profile	string	AWS credentials profile name. Defaults to the `default` profile.	No
credentialsFile	string	Path to the AWS shared credentials file. Defaults to `~/.aws/credentials`.	No
roleARN	string	IAM role ARN to assume for cross-account access.	No
tokenFile	string	Path to the OIDC token file. Required when `roleARN` is set for OIDC-based authentication.	No

ECSDeploymentInput

Configured under plugins.ecs.input in the application configuration.

Field	Type	Default	Description
taskDefinitionFile	string	`taskdef.json`	Path to the task definition file (YAML/JSON).
serviceDefinitionFile	string		Path to the service definition file (YAML/JSON). Omit for standalone tasks.
runStandaloneTask	bool	`false`	When `true`, runs the task directly without creating or updating an ECS service. Only quick sync is supported.
clusterArn	string		ARN of the ECS cluster.
launchType	string	`FARGATE`	Task launch type. Valid values: `EC2`, `FARGATE`.
accessType	string	`ELB`	How the service is accessed. Valid values: `ELB`, `SERVICE_DISCOVERY`.
awsvpcConfiguration	ECSVpcConfiguration		VPC configuration. Required for `FARGATE` or `EC2` with `awsvpc` network mode.
targetGroups	ECSTargetGroups		Load balancer target groups. Required when `accessType` is `ELB`.

ECSVpcConfiguration

Field	Type	Description	Required
subnets	[]string	VPC subnet IDs where tasks will be launched. Maximum 16.	Yes
assignPublicIp	string	Assign a public IP to the task’s ENI. Valid values: `ENABLED`, `DISABLED`.	No
securityGroups	[]string	Security group IDs for the task’s ENI. Maximum 5. Uses the VPC default security group if omitted.	No

ECSTargetGroups

Field	Type	Description
primary	ECSTargetGroup	Target group for the primary variant.
canary	ECSTargetGroup	Target group for the canary variant. Required for canary/blue-green deployments.

ECSTargetGroup

Field	Type	Description
targetGroupArn	string	ARN of the target group.
containerName	string	Name of the container to associate with the target group.
containerPort	int	Port on the container to associate with the target group.

ECSSyncStageOptions (quickSync)

Configured under plugins.ecs.quickSync.

Field	Type	Default	Description
recreate	bool	`false`	When `true`, stops all running tasks before creating the new task set. Guarantees a clean restart but causes brief downtime.

ECS_CANARY_ROLLOUT options

Field	Type	Description
scale	float	Percentage of the primary workload capacity to deploy as canary (0–100). For example, with 10 primary tasks and `scale: 30`, the canary will have 3 tasks.

ECS_TRAFFIC_ROUTING options

Specify either primary or canary. The other variant automatically receives the remainder.

Field	Type	Description
primary	int	Percentage of traffic routed to the primary variant.
canary	int	Percentage of traffic routed to the canary variant.

Docs-V1.0.x: Wait plugin

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

The wait plugin provides the WAIT stage, which pauses the pipeline for a fixed duration before continuing to the next stage. Because it is a stage plugin, WAIT can be added to any deployment pipeline.

Prerequisites

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  # ...
  plugins:
    - name: wait
      port: 7004
      url: file:///path/to/plugin/binary  # or an https:// release URL

The WAIT stage

Add a WAIT stage and set how long to pause under with.duration. For example, wait 5 minutes between a canary rollout and the primary rollout:

pipeline:
  stages:
    - name: K8S_CANARY_ROLLOUT
      with:
        replicas: 10%
    - name: WAIT
      with:
        duration: 5m
    - name: K8S_PRIMARY_ROLLOUT

Configuration reference

WAIT stage options

Field	Type	Description	Required
duration	duration	How long to pause before continuing (e.g. `5m`).	Yes

Docs-V1.0.x: Wait approval plugin

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

The waitapproval plugin provides the WAIT_APPROVAL stage, which pauses the pipeline until the required number of users approve the deployment from the PipeCD console. Because it is a stage plugin, WAIT_APPROVAL can be added to any deployment pipeline.

Prerequisites

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  # ...
  plugins:
    - name: waitapproval
      port: 7005
      url: file:///path/to/plugin/binary  # or an https:// release URL

The WAIT_APPROVAL stage

Add a WAIT_APPROVAL stage and set the approvers and the number of approvals required under with. For example, require one approval before applying an infrastructure change:

pipeline:
  stages:
    - name: TERRAFORM_PLAN
    - name: WAIT_APPROVAL
      with:
        approvers:
          - user-a
          - user-b
        minApproverNum: 1
    - name: TERRAFORM_APPLY

The stage waits until at least minApproverNum users have approved it from the console, then continues.

Configuration reference

WAIT_APPROVAL stage options

Field	Type	Description	Required
approvers	[]string	Users designated as approvers of the deployment.	Yes
minApproverNum	int	Number of approvals required before the pipeline continues.	No (default `1`)

Docs-V1.0.x: Analysis plugin

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

The analysis plugin provides the ANALYSIS stage, which evaluates a running deployment for a defined period by querying metrics, logs, or HTTP endpoints. If the results fall outside the configured expectations, the stage fails and the deployment is rolled back. Because it is a stage plugin, ANALYSIS can be added to any deployment pipeline (for example between a canary rollout and a primary rollout).

Analysis uses providers that are configured once in the piped configuration. Each ANALYSIS stage then references a provider by name.

Provider support by analysis type:

Analysis type	Providers
Metrics	Prometheus, Datadog
Logs	Stackdriver
HTTP	None (the stage queries the URL directly)

Prerequisites

Register the plugin and its providers in the piped configuration. Add an analysis plugin block and list your providers under config.analysisProviders:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  # ...
  plugins:
    - name: analysis
      port: 7003
      url: file:///path/to/plugin/binary  # or an https:// release URL
      config:
        analysisProviders:
          - name: prometheus-dev
            type: PROMETHEUS
            config:
              address: https://your-prometheus.dev

Add an ANALYSIS stage to a deployment pipeline and reference the provider by name (see The ANALYSIS stage).

Analysis providers

Providers are defined under the plugin’s config.analysisProviders in the piped configuration. Each entry has a name, a type, and a type-specific config.

Prometheus

Used for metrics analysis. piped queries the Prometheus range query endpoint.

analysisProviders:
  - name: prometheus-dev
    type: PROMETHEUS
    config:
      address: https://your-prometheus.dev

See AnalysisProviderPrometheusConfig for all fields.

Datadog

Used for metrics analysis. piped queries the Datadog query timeseries endpoint.

analysisProviders:
  - name: datadog-dev
    type: DATADOG
    config:
      apiKeyFile: /etc/piped-secret/datadog-api-key
      applicationKeyFile: /etc/piped-secret/datadog-application-key

See AnalysisProviderDatadogConfig for all fields.

If you install piped with Helm, use --set-file to mount the key files during the upgrade 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}

Stackdriver

Used for log analysis.

analysisProviders:
  - name: stackdriver-dev
    type: STACKDRIVER
    config:
      serviceAccountFile: /etc/piped-secret/gcp-service-account.json

See AnalysisProviderStackdriverConfig for all fields.

The ANALYSIS stage

Add an ANALYSIS stage to a pipeline and configure it under with. The duration field is required and sets how long the analysis runs. Within that window, the stage can run three kinds of checks, each a list:

metrics - query a metrics provider (Prometheus or Datadog).
logs - query a log provider (Stackdriver).
https - send HTTP requests and check the response.

Example: run a canary, then evaluate its error rate against a threshold before promoting to primary.

pipeline:
  stages:
    - name: K8S_CANARY_ROLLOUT
      with:
        replicas: 10%
    - name: ANALYSIS
      with:
        duration: 10m
        metrics:
          - provider: prometheus-dev
            strategy: THRESHOLD
            query: |
              sum(rate(http_requests_total{job="my-app",status=~"5.."}[1m]))
              / sum(rate(http_requests_total{job="my-app"}[1m]))
            interval: 1m
            expected:
              max: 0.01
    - name: K8S_PRIMARY_ROLLOUT

Metrics strategies

Metrics analysis supports four strategies, set per metrics check with the strategy field:

THRESHOLD (default) - compare each query result against the expected range (min/max).
PREVIOUS - compare the result against the same query from the previous successful deployment.
CANARY_BASELINE - compare the canary variant against the baseline variant.
CANARY_PRIMARY - compare the canary variant against the primary variant. (Not recommended, since primary may serve production traffic.)

For PREVIOUS, CANARY_BASELINE, and CANARY_PRIMARY, use deviation to set which direction counts as a failure (LOW, HIGH, or EITHER).

Configuration reference

AnalysisStageOptions

Options for the ANALYSIS stage, set under with.

Field	Type	Description	Required
duration	duration	How long the analysis runs (e.g. `10m`).	Yes
restartThreshold	int	Allowed number of pod restarts during the analysis.	No
metrics	[]AnalysisMetrics	Metrics checks to run.	No
logs	[]AnalysisLog	Log checks to run.	No
https	[]AnalysisHTTP	HTTP checks to run.	No

AnalysisMetrics

Field	Type	Description	Required
strategy	string	One of `THRESHOLD`, `PREVIOUS`, `CANARY_BASELINE`, `CANARY_PRIMARY`.	No (default `THRESHOLD`)
provider	string	Name of a metrics provider defined in the piped configuration.	Yes
query	string	Query run against the provider.	Yes
expected	AnalysisExpected	Expected result range. Required for the `THRESHOLD` strategy.	For `THRESHOLD`
interval	duration	How often the query runs.	Yes
failureLimit	int	Number of failed checks tolerated before the analysis fails.	No (default `0`)
skipOnNoData	bool	Treat “no data returned” as a success.	No (default `false`)
timeout	duration	Query timeout.	No (default `30s`)
deviation	string	Failure direction for non-threshold strategies: `LOW`, `HIGH`, or `EITHER`.	No (default `EITHER`)
canaryArgs	map[string]string	Template args for the canary query, referenced as `{{ .VariantArgs.xxx }}`.	No
baselineArgs	map[string]string	Template args for the baseline query.	No
primaryArgs	map[string]string	Template args for the primary query.	No

AnalysisExpected

At least one of min or max is required.

Field	Type	Description	Required
min	float	Minimum acceptable value.	No
max	float	Maximum acceptable value.	No

AnalysisLog

Field	Type	Description	Required
provider	string	Name of a log provider defined in the piped configuration.	Yes
query	string	Query run against the provider.	Yes
interval	duration	How often the query runs.	Yes
failureLimit	int	Number of failed checks tolerated before the analysis fails.	No (default `0`)
skipOnNoData	bool	Treat “no data returned” as a success.	No (default `false`)
timeout	duration	Query timeout.	No

AnalysisHTTP

Field	Type	Description	Required
url	string	URL to send the request to.	Yes
method	string	HTTP method.	No
headers	[]AnalysisHTTPHeader	Request headers.	No
expectedCode	int	Expected HTTP status code.	No
expectedResponse	string	Expected response body.	No
interval	duration	How often the request is sent.	Yes
failureLimit	int	Number of failed checks tolerated before the analysis fails.	No (default `0`)
skipOnNoData	bool	Treat “no data returned” as a success.	No (default `false`)
timeout	duration	Request timeout.	No

AnalysisHTTPHeader

Field	Type	Description	Required
key	string	Header name.	Yes
value	string	Header value.	Yes

AnalysisProviderPrometheusConfig

Configured under config.analysisProviders[].config in the piped configuration.

Field	Type	Description	Required
address	string	Address of the Prometheus server.	Yes
usernameFile	string	Path to a file containing the username for basic auth.	No
passwordFile	string	Path to a file containing the password for basic auth.	No

AnalysisProviderDatadogConfig

Field	Type	Description	Required
address	string	Datadog API server address. One of `datadoghq.com`, `us3.datadoghq.com`, `datadoghq.eu`, `ddog-gov.com`.	No (default `datadoghq.com`)
apiKeyFile	string	Path to the API key file. Mutually exclusive with `apiKeyData`.	Yes (or `apiKeyData`)
applicationKeyFile	string	Path to the application key file. Mutually exclusive with `applicationKeyData`.	Yes (or `applicationKeyData`)
apiKeyData	string	Base64-encoded API key. Mutually exclusive with `apiKeyFile`.	No
applicationKeyData	string	Base64-encoded application key. Mutually exclusive with `applicationKeyFile`.	No

AnalysisProviderStackdriverConfig

Field	Type	Description	Required
serviceAccountFile	string	Path to the GCP service account file.	Yes

AnalysisApplicationSpec

The spec of an application using analysis shares the common application fields and adds the following under plugins.analysis:

Field	Type	Description	Required
appCustomArgs	map[string]string	Custom arguments populated into queries, referenced as `{{ .AppCustomArgs.xxx }}`.	No

Docs-V1.0.x: Script run plugin

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

The scriptrun plugin provides the SCRIPT_RUN stage, which runs arbitrary shell commands as a step in the pipeline. Because it is a stage plugin, SCRIPT_RUN can be added to any deployment pipeline. It is useful for tasks such as smoke tests, notifications, or custom checks between deployment stages.

Prerequisites

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  # ...
  plugins:
    - name: scriptrun
      port: 7006
      url: file:///path/to/plugin/binary  # or an https:// release URL

The SCRIPT_RUN stage

Add a SCRIPT_RUN stage and set the command to run under with.run. You can pass environment variables with env, and provide an onRollback command that runs if the deployment is rolled back:

pipeline:
  stages:
    - name: K8S_CANARY_ROLLOUT
    - name: SCRIPT_RUN
      with:
        env:
          APP_URL: https://example.com
        run: |
          curl -sSf "$APP_URL/healthz"
        onRollback: |
          echo "rolling back"
    - name: K8S_PRIMARY_ROLLOUT

If onRollback is set, PipeCD runs it during rollback through an automatically inserted SCRIPT_RUN_ROLLBACK stage. You do not add SCRIPT_RUN_ROLLBACK to your pipeline.

Configuration reference

SCRIPT_RUN stage options

Field	Type	Description	Required
run	string	The command(s) to run.	Yes
env	map[string]string	Environment variables to set when running the command.	No
onRollback	string	The command(s) to run if the deployment is rolled back.	No