|
| 1 | +--- |
| 2 | +title: "Plugin development resources" |
| 3 | +linkTitle: "Plugin development resources" |
| 4 | +weight: 5 |
| 5 | +description: > |
| 6 | + Links and short notes for developing PipeCD plugins. |
| 7 | +--- |
| 8 | + |
| 9 | +> **Note:** |
| 10 | +> This section is still a work in progress. A full tutorial and an in-docs translation of the Zenn book are planned over time. |
| 11 | +> |
| 12 | +> For a hands-on walkthrough, read [**Build and learn PipeCD plugins**](https://zenn.dev/warashi/books/try-and-learn-pipecd-plugin) (Zenn; Japanese title *作って学ぶ PipeCD プラグイン*). The same book is linked again in [Links](#links), together with other references. Use your browser's translate feature if you need English. Verify commands and field names against this documentation and the [`pipecd`](https://github.com/pipe-cd/pipecd) repository. |
| 13 | +
|
| 14 | +Use this page together with [Contribute to PipeCD plugins](../), which covers layout, `make` targets, and how to open a pull request. |
| 15 | + |
| 16 | +## How the pieces fit together |
| 17 | + |
| 18 | +- **Control plane**: registers projects and `piped` agents; the web UI shows deployment status. |
| 19 | +- **`piped`**: runs your plugins as separate binaries and talks to them over gRPC. |
| 20 | +- **Plugins**: carry out deployments (and optionally live state and drift) for a platform or tool. |
| 21 | + |
| 22 | +If you are new to PipeCD v1, read [Plugins](/docs-v1.0.x/concepts/#plugins) and [Migrating from v0 to v1](/docs-v1.0.x/migrating-from-v0-to-v1/). |
| 23 | + |
| 24 | +### Terms |
| 25 | + |
| 26 | +| Term | Meaning | |
| 27 | +|------|---------| |
| 28 | +| **Application** | Git content for one deployable unit: manifests plus a `*.pipecd.yaml` file. | |
| 29 | +| **Deployment** | One run of the deployment pipeline for an app (from Git, a trigger, or the UI). | |
| 30 | +| **Deploy target** | Where the plugin deploys, set under `spec.plugins` in the `piped` config. | |
| 31 | +| **Pipeline** | Ordered **stages** (for example sync, canary, wait) from the application config. | |
| 32 | +| **Stage** | One step in the pipeline; your plugin implements the stages it supports. | |
| 33 | + |
| 34 | +For plugin interfaces (**Deployment**, **LiveState**, **Drift**), see [Plugin types](../#plugin-types). A first plugin usually implements **Deployment** only. |
| 35 | + |
| 36 | +## Local development |
| 37 | + |
| 38 | +Use a `piped` v1 build that matches your work. From the repo you can run `make run/piped` as in the [contributing guide](../#build-and-test). To install a release binary, see [Installing on a single machine](/docs-v1.0.x/installation/install-piped/installing-on-single-machine/). |
| 39 | + |
| 40 | +Example when running the v1 `piped` CLI: |
| 41 | + |
| 42 | +```console |
| 43 | +./piped run --config-file=PATH_TO_PIPED_CONFIG --insecure=true |
| 44 | +``` |
| 45 | + |
| 46 | +Use `--insecure=true` only when it matches your control plane (for example plain HTTP or your dev TLS settings). |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +Older blog posts or books may target an older `piped`. Prefer this documentation and the default branch of [`pipecd`](https://github.com/pipe-cd/pipecd). |
| 51 | + |
| 52 | +## `piped` config and application config |
| 53 | + |
| 54 | +You need both: |
| 55 | + |
| 56 | +1. **`piped` configuration**: control plane address, Git `repositories`, and `spec.plugins` (URL, port, `deployTargets`, plugin-specific fields). See [Configuring a Plugin](/docs-v1.0.x/user-guide/managing-piped/configuring-a-plugin/) and [Piped configuration reference](/docs-v1.0.x/user-guide/managing-piped/configuration-reference/). |
| 57 | +2. **Application configuration**: the `*.pipecd.yaml` in Git (plugin, pipeline, deploy options). See [Adding an application](/docs-v1.0.x/user-guide/managing-application/adding-an-application/) and [Application configuration reference](/docs-v1.0.x/user-guide/managing-application/configuration-reference/). |
| 58 | + |
| 59 | +Code in your plugin reads the application config via its own types (often under `config/`). `deployTargets` come from the `piped` config. |
| 60 | + |
| 61 | +## Example plugins |
| 62 | + |
| 63 | +| Plugin | Notes | |
| 64 | +|--------|-------| |
| 65 | +| [kubernetes](https://github.com/pipe-cd/pipecd/tree/master/pkg/app/pipedv1/plugin/kubernetes) | Full official plugin | |
| 66 | +| [wait](https://github.com/pipe-cd/pipecd/tree/master/pkg/app/pipedv1/plugin/wait) | Small official example | |
| 67 | +| [example-stage](https://github.com/pipe-cd/community-plugins/tree/main/plugins/example-stage) | Community sample (see [Installing on a single machine](/docs-v1.0.x/installation/install-piped/installing-on-single-machine/)) | |
| 68 | + |
| 69 | +## Cache under ~/.piped |
| 70 | + |
| 71 | +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`. |
| 72 | + |
| 73 | +## Debugging |
| 74 | + |
| 75 | +- **Web UI**: deployment and stage status. |
| 76 | +- **Stdout**: logs from `piped` and the plugin (verbose but quick for local work). |
| 77 | +- **Stage logs**: through the SDK; see [`StageLogPersister`](https://github.com/pipe-cd/pipecd/blob/master/pkg/plugin/sdk/logpersister/persister.go) in the repo. |
| 78 | + |
| 79 | +## Links |
| 80 | + |
| 81 | +| Resource | Notes | |
| 82 | +|----------|-------| |
| 83 | +| [**Build and learn PipeCD plugins** (Zenn)](https://zenn.dev/warashi/books/try-and-learn-pipecd-plugin) | Japanese tutorial book (*作って学ぶ PipeCD プラグイン*) | |
| 84 | +| [DeepWiki (pipecd)](https://deepwiki.com/pipe-cd/pipecd) | Unofficial wiki-style overview of the repository. | |
| 85 | +| [Plugin Architecture RFC](https://github.com/pipe-cd/pipecd/blob/master/docs/rfcs/0015-pipecd-plugin-arch-meta.md) | Design (RFC) | |
| 86 | +| [Plugin Architecture overview (blog)](https://pipecd.dev/blog/2024/11/28/overview-of-the-plan-for-pluginnable-pipecd/) | Architecture overview | |
| 87 | +| [Plugin alpha release (blog)](https://pipecd.dev/blog/2025/06/16/plugin-architecture-piped-alpha-version-has-been-released/) | Piped plugin alpha | |
| 88 | +| [#pipecd (CNCF Slack)](https://cloud-native.slack.com/) | Community chat | |
| 89 | + |
| 90 | +See also [Contributing to PipeCD](/docs-v1.0.x/contribution-guidelines/contributing-to-pipecd/) for local control plane setup and pull requests. |
0 commit comments