Skip to content

Fix README-usage #5944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ffjlabo merged 4 commits into from
Jun 13, 2025
Merged

Fix README-usage #5944

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e2df7b5
Fix README-usage
ffjlabo Jun 12, 2025
7acb023
Update README alpha
ffjlabo Jun 12, 2025
8212ad6
Update
ffjlabo Jun 12, 2025
835c665
Fix as --insecure option
ffjlabo Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 103 additions & 41 deletions cmd/pipedv1/README-usage-alpha.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,16 @@
# Usage of pipedv1 and plugins (alpha)
# Usage of plugin-arched piped and plugins (alpha)

_This page is still in preparation. The content will be changed and might not work well yet._

This page shows how to run pipedv1 and plugins of alpha status.
This page shows how to run piped and plugins of alpha status.

See [cmd/pipedv1/README.md](https://github.com/pipe-cd/pipecd/blob/master/cmd/pipedv1/README.md) if you want to develop or debug pipedv1.
See [cmd/pipedv1/README.md](https://github.com/pipe-cd/pipecd/blob/master/cmd/pipedv1/README.md) if you want to develop or debug piped.

_This page might be moved to another place in the future._


## Prerequisites

- docker
- kubectl and a k8s cluster (They are not required if you won't use the kubernetes plugin)

## 1. Setup Control Plane
Expand All @@ -20,20 +19,33 @@ _This page might be moved to another place in the future._
- The Control Plane version must be v0.52.0 or later.

2. Generate a new piped key/ID.

2.1. Access the Control Plane console.

2.2. Go to the piped list page. (https://{console-address}/settings/piped)

2.4. Add a new piped via the `+ADD` button.

2.5. Copy the generated piped ID and base64 encoded key.

## 2. Run pipedv1
## 2. Run plugin-arched piped

1. Download piped binary.

```sh
# OS="darwin" or "linux" CPU_ARCH="arm64" or "amd64"
curl -Lo ./piped_kubecon_jp_2025 https://github.com/pipe-cd/pipecd/releases/download/kubecon-jp-2025/piped_kubecon_jp_2025_{OS}_{CPU_ARCH}

chmod +x ./piped_kubecon_jp_2025
```

1. Create a piped config file like the following.
2. Create a piped config file like the following.

```yaml
apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
apiAddress: {CONTROL_PLANE_API_ADDRESS} # like "localhost:443"
apiAddress: {CONTROL_PLANE_API_ADDRESS} # like "localhost:8080"
projectID: {PROJECT_ID}
pipedID: {PIPED_ID}
pipedKeyData: {BASE64_ENCODED_PIPED_KEY} # or use pipedKeyFile
Expand All @@ -47,72 +59,122 @@ spec:
plugins:
- name: kubernetes
port: 7001 # Any unused port
url: https://github.com/pipe-cd/pipecd/xxxxxxxxxxx # TODO: Ref to the Release
url: https://github.com/pipe-cd/pipecd/releases/download/kubecon-jp-2025/plugin_kubernetes_kubecon_jp_2025_darwin_arm64 # choose binary on the release for your own OS and CPU arch
deployTargets:
- name: cluster1
config:
masterURL: https://127.0.0.1:61337 # shown by kubectl cluster-info
kubeConfigPath: /path/to/kubeconfig
kubectlVersion: 1.33.0
- name: wait
port: 7002 # Any unused port
url: https://github.com/pipe-cd/pipecd/xxxxxxxxxxx # TODO: Ref to the Release
url: https://github.com/pipe-cd/pipecd/releases/download/kubecon-jp-2025/plugin_wait_kubecon_jp_2025_darwin_arm64 # choose binary on the release for your own OS and CPU arch

- name: example-stage
port: 7003 # Any unused port
url: https://github.com/pipe-cd/community-plugins/xxxxxxxxxxx # TODO: Ref to the Release
url: https://github.com/pipe-cd/community-plugins/releases/download/kubecon-jp-2025/plugin_example-stage_kubecon_jp_2025_darwin_arm64 # choose binary on the release for your own OS and CPU arch
config:
- commonMessage: "[common message]"
```

2. Run pipedv1
3. Run piped

```sh
docker run pipe-cd/pipecd/pipedv1:v0.52.0 piped --config-file=/path/to/piped-config.yaml --tools-dir=/tmp/piped-bin
./piped_kubecon_jp_2025 piped --config-file=/path/to/piped-config.yaml --tools-dir=/tmp/piped-bin
```

- The pipedv1 version must be v0.52.0 or later.
- If your Control Plane runs on local, add `INSECURE=true` to the command to skip TLS certificate checks.
- If your Control Plane runs on local, add `--insecure=true` to the command to skip TLS certificate checks.


## 3. Deploy an application

Let's create application with kubernetes plugin.

1. Create an app.pipecd.yaml like the following.

```yaml
apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
# `input` field is not used in pipedv1
...
pipeline:
```yaml
apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
name: canary
labels:
env: example
team: product
pipeline:
stages:
- name: K8sXXXX # TODO: Set stages and options
with: ...
- name: WAIT # wait stage plugin
# Deploy the workloads of CANARY variant. In this case, the number of
# workload replicas of CANARY variant is 10% of the replicas number of PRIMARY variant.
- name: K8S_CANARY_ROLLOUT
with:
duration: 10s
- name: EXAMPLE_HELLO # example-stage plugin
replicas: 10%
# Wait 10 seconds before going to the next stage.
- name: WAIT
with:
name: "Bob"

plugins:
kubernetes:
... # TODO: configure

```

2. Push the app.pipecd.yaml to your remote repository.
3. On the Control Plane console, register the application via `PIPED V1 ADD FROM SUGGESTIONS` tab.
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
```

2. Create Resources in the same dir as app.pipecd.yaml.

deployment.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: canary
labels:
app: canary
spec:
replicas: 2
revisionHistoryLimit: 2
selector:
matchLabels:
app: canary
pipecd.dev/variant: primary
template:
metadata:
labels:
app: canary
pipecd.dev/variant: primary
spec:
containers:
- name: helloworld
image: ghcr.io/pipe-cd/helloworld:v0.32.0
args:
- server
ports:
- containerPort: 9085
```

service.yaml
```yaml
apiVersion: v1
kind: Service
metadata:
name: canary
spec:
selector:
app: canary
ports:
- protocol: TCP
port: 9085
targetPort: 9085
```

3. Push the app.pipecd.yaml and the resources to your remote repository.
4. On the Control Plane console, register the application via `PIPED V1 ADD FROM SUGGESTIONS` tab.

## See also

<!-- TODO: Link to each config reference -->
- kubernetes plugin: TBA
- kubernetes plugin: [README.md](/pkg/app/pipedv1/plugin/kubernetes/README.md)
- wait stage plugin: [README.md](/pkg/app/pipedv1/plugin/wait/README.md)
- example-stage plugin: TBA
- example-stage plugin: [README.md](https://github.com/pipe-cd/community-plugins/blob/main/plugins/example-stage/README.md)

## Note

- Currently, on the Deployment detail UI, each stage is not visible until it starts.
- The cause is that the `Visible` field of each stage is set to `false` by default in pipedv1. Instead, the new field `Rollback` is used to determine if the stage is a rollback stage.
- This will be modified before releasing pipedv1 beta.
- The cause is that the `Visible` field of each stage is set to `false` by default in piped. Instead, the new field `Rollback` is used to determine if the stage is a rollback stage.
- This will be modified before releasing piped beta.