Docs-V1.0.x: Plugin development resources

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

Note: This section is still a work in progress. A full tutorial and an in-docs translation of the Zenn book are planned over time.

For a hands-on walkthrough, read Build and learn PipeCD plugins (Zenn; Japanese title 作って学ぶ PipeCD プラグイン). The same book is linked again in Links, together with other references. Use your browser’s translate feature to read this in English. Verify commands and field names against this documentation and the pipecd repository.

Use this page together with Contribute to PipeCD plugins, which covers layout, make targets, and how to open a pull request.

How the pieces fit together

Control plane: registers projects and piped agents; the web UI shows deployment status.
piped: runs your plugins as separate binaries and talks to them over gRPC.
Plugins: carry out deployments (and optionally live state and drift) for a platform or tool.

If you are new to PipeCD v1, read Plugins and Migrating from v0 to v1.

Terms

Term	Meaning
Application	Git content for one deployable unit: manifests plus a `*.pipecd.yaml` file.
Deployment	One run of the deployment pipeline for an app (from Git, a trigger, or the UI).
Deploy target	Where the plugin deploys, set under `spec.plugins` in the `piped` config.
Pipeline	Ordered stages (for example sync, canary, wait) from the application config.
Stage	One step in the pipeline; your plugin implements the stages it supports.

For plugin interfaces (Deployment, LiveState, Drift), see Plugin types. A first plugin usually implements Deployment only.

Local development

Use a piped v1 build that matches your work. From the repo you can run make run/piped as in the contributing guide. To install a release binary, see Installing on a single machine.

Example when running the v1 piped CLI:

./piped run --config-file=PATH_TO_PIPED_CONFIG --insecure=true

Use --insecure=true only when it matches your control plane (for example plain HTTP or your dev TLS settings).

The install guide linked above uses the same run subcommand. If another page or tutorial shows different syntax, run ./piped --help on your binary to match your build.

Older blog posts or books may target an older piped. Prefer this documentation and the default branch of pipecd.

`piped` config and application config

You need both:

piped configuration: control plane address, Git repositories, and spec.plugins (URL, port, deployTargets, plugin-specific fields). See Configuring a Plugin and Piped configuration reference.
Application configuration: the *.pipecd.yaml in Git (plugin, pipeline, deploy options). See Adding an application and Application configuration reference.

Code in your plugin reads the application config via its own types (often under config/). deployTargets come from the piped config.

Example plugins

Plugin	Notes
kubernetes	Full official plugin
wait	Small official example
example-stage	Community sample (see Installing on a single machine)

Cache under ~/.piped

After rebuilding a plugin, piped may still use files under ~/.piped (including ~/.piped/plugins). If your changes do not show up, remove those directories or clear the cache your team uses, then restart piped.

Debugging

Web UI: deployment and stage status.
Stdout: logs from piped and the plugin (verbose but quick for local work).
Stage logs: through the SDK; see StageLogPersister in the repo.

Links

Resource	Notes
Build and learn PipeCD plugins (Zenn)	Japanese tutorial book (作って学ぶ PipeCD プラグイン)
DeepWiki (pipecd)	Unofficial wiki-style overview of the repository.
Plugin Architecture RFC	Design (RFC)
Plugin Architecture overview (blog)	Architecture overview
Plugin alpha release (blog)	Piped plugin alpha
#pipecd (CNCF Slack)	Community chat

See also Contributing to PipeCD for local control plane setup and pull requests.

PipeCD – Contribute to PipeCD plugins