Skip to content

Commit 7d4722f

Browse files
ffjlaboffjlabo
authored
Add README for k8s multi cluster plugin (#5854)
* Add README for pipedv1 Signed-off-by: Yoshiki Fujikane <[email protected]> * Add README for k8s multi cluster Signed-off-by: Yoshiki Fujikane <[email protected]> * Add Config Reference Signed-off-by: Yoshiki Fujikane <[email protected]> --------- Signed-off-by: Yoshiki Fujikane <[email protected]>
1 parent f095ba5 commit 7d4722f

File tree

8 files changed

+285
-0
lines changed

8 files changed

+285
-0
lines changed

‎pkg/app/pipedv1/plugin/kubernetes_multicluster/README.md

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Kubernetes Multicluster Plugin
2+
3+
## Specification
4+
5+
The current specification is described in the [RFC](../../../../../docs/rfcs/0014-multi-cluster-deployment-for-k8s.md).
6+
The configuration format is unstable and may change in the future.
7+
8+
Note:
9+
- Currently, only QuickSync is supported.
10+
11+
## Try k8s multicluster plugin locally
12+
13+
**Switch to the upstream commit of the master branch**
14+
15+
The whole fixes for plugins are stored in the master branch and some of the versions don't have them.
16+
17+
```sh
18+
git switch master
19+
git pull
20+
```
21+
22+
**Prepare the PipeCD Control Plane**
23+
24+
Please refer to [pipe-cd/pipecd/cmd/pipecd/README.md](../../../../../cmd/pipecd/README.md) to set up the Control Plane in your local environment.
25+
26+
**Prepare two k8s clusters**
27+
28+
```sh
29+
kind create cluster --name cluster1
30+
kind export kubeconfig --name cluster1 --kubeconfig /path/to/kubeconfig/for/cluster1
31+
32+
kind create cluster --name cluster2
33+
kind export kubeconfig --name cluster2 --kubeconfig /path/to/kubeconfig/for/cluster2
34+
```
35+
36+
**Start pipedv1 locally**
37+
38+
Please refer to [pipe-cd/pipecd/cmd/pipedv1/README.md](../../../../../cmd/pipedv1/README.md) to set up the Control Plane in your local environment.
39+
At this time, please modify the `spec.plugins` section of the piped config as shown below.
40+
41+
```yaml
42+
apiVersion: pipecd.dev/v1beta1
43+
kind: Piped
44+
spec:
45+
...
46+
plugins:
47+
- name: kubernetes_multicluster
48+
port: 7002 # any unused port
49+
url: file:///path/to/.piped/plugins/kubernetes_multicluster # It's OK using any value for now because it's a dummy. We will implement it later.
50+
deployTargets:
51+
- name: cluster1
52+
config:
53+
masterURL: https://127.0.0.1:61337 # shown by kubectl cluster-info
54+
kubeConfigPath: /path/to/kubeconfig/for/cluster1
55+
- name: cluster2
56+
config:
57+
masterURL: https://127.0.0.1:62082 # shown by kubectl cluster-info
58+
kubeConfigPath: /path/to/kubeconfig/for/cluster2
59+
```
60+
61+
**Prepare the manifest**
62+
63+
- Please create a new repository for the manifest because an error will occur if there is an app.pipecd.yaml in the format before supporting the plugin mechanism for now.
64+
For example usage, see the [Examples](#examples) section below.
65+
66+
**Register the application**
67+
68+
![adding-application](./docs/static/adding-application.png)
69+
70+
At this time, please select multiple DeployTargets.
71+
72+
## Examples
73+
There are examples under `./example`.
74+
75+
| Name | Description |
76+
|------|-------------|
77+
| [simple](./example/simple/) | Deploy the same resources to the multiple clusters. |
78+
| [multi-sources-template-none](./example/multi-sources-template-none/) | Deploy the different resources to the multiple clusters. |
79+
80+
## Config Reference
81+
82+
### Piped Config
83+
84+
```yaml
85+
apiVersion: pipecd.dev/v1beta1
86+
kind: Piped
87+
spec:
88+
...
89+
plugins:
90+
# Plugin name.
91+
- name: kubernetes_multicluster
92+
# Port number used to listen plugin server.
93+
port: 7002
94+
# The URL where the plugin binary located.
95+
# It's OK using any value for now because it's a dummy. We will implement it later.
96+
url: file:///path/to/.piped/plugins/kubernetes_multicluster
97+
# List of the information for each target platform.
98+
# This is alternative for the platform providers.
99+
deployTargets:
100+
# Then name of deploy target.
101+
- name: cluster1
102+
# The plugin-specific config.
103+
config:
104+
# The master URL of the kubernetes cluster.
105+
# Empty means in-cluster.
106+
masterURL: https://127.0.0.1:61337
107+
# The path to the kubeconfig file.
108+
# Empty means in-cluster.
109+
kubeConfigPath: /path/to/kubeconfig/for/cluster1
110+
# Version of kubectl will be used.
111+
kubectlVersion: 1.32.0
112+
- name: cluster2
113+
config:
114+
masterURL: https://127.0.0.1:62082
115+
kubeConfigPath: /path/to/kubeconfig/for/cluster2
116+
```
117+
118+
### app.pipecd.yaml
119+
120+
```yaml
121+
apiVersion: pipecd.dev/v1beta1
122+
kind: Application
123+
spec:
124+
...
125+
plugins:
126+
kubernetes_multicluster:
127+
input:
128+
# List of manifest files in the application directory used to deploy.
129+
# Empty means all manifest files in the directory will be used.
130+
manifests:
131+
- deployment.yaml
132+
- service.yaml
133+
# Version of kubectl will be used.
134+
kubectlVersion: 1.32.0
135+
# The namespace where manifests will be applied.
136+
namespace: example
137+
# Automatically create a new namespace if it does not exist.
138+
# Default is false.
139+
autoCreateNamespace: false
140+
# List of the setting for each deploy targets.
141+
# You can also set config for them separately.
142+
multiTargets:
143+
# The identity of the deploy target.
144+
# You can specify deploy target by some of them.
145+
- target:
146+
# The name of deploy target
147+
name: cluster1
148+
# List of manifest files in the application directory used to deploy.
149+
# Empty means all manifest files in the directory will be used.
150+
manifests:
151+
- ./cluster1/deployment.yaml
152+
# Version of kubectl will be used.
153+
kubectlVersion: 1.32.2
154+
- target:
155+
name: cluster2
156+
manifests:
157+
- ./cluster2/deployment.yaml
158+
kubectlVersion: 1.32.2
159+
```

‎pkg/app/pipedv1/plugin/kubernetes_multicluster/docs/static/adding-application.png

249 KB
Loading

‎pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/app.pipecd.yaml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
apiVersion: pipecd.dev/v1beta1
2+
kind: Application
3+
spec:
4+
name: multi-sources-template-none
5+
labels:
6+
env: example
7+
plugins:
8+
kubernetes_multicluster:
9+
quickSync:
10+
prune: true
11+
input:
12+
multiTargets:
13+
- target:
14+
name: cluster1
15+
manifests:
16+
- ./cluster1/deployment.yaml
17+
- target:
18+
name: cluster2
19+
manifests:
20+
- ./cluster2/deployment.yaml
21+
kubectlVersion: 1.32.2

‎pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/cluster1/deployment.yaml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
apiVersion: apps/v1
2+
kind: Deployment
3+
metadata:
4+
name: cluster1
5+
labels:
6+
app: cluster1
7+
spec:
8+
replicas: 2
9+
selector:
10+
matchLabels:
11+
app: cluster1
12+
pipecd.dev/variant: primary
13+
template:
14+
metadata:
15+
labels:
16+
app: cluster1
17+
pipecd.dev/variant: primary
18+
annotations:
19+
sidecar.istio.io/inject: "false"
20+
spec:
21+
containers:
22+
- name: helloworld
23+
image: ghcr.io/pipe-cd/helloworld:v0.32.0
24+
args:
25+
- server
26+
ports:
27+
- containerPort: 9085

‎pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/cluster2/deployment.yaml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
apiVersion: apps/v1
2+
kind: Deployment
3+
metadata:
4+
name: cluster2
5+
labels:
6+
app: cluster2
7+
spec:
8+
replicas: 2
9+
selector:
10+
matchLabels:
11+
app: cluster2
12+
pipecd.dev/variant: primary
13+
template:
14+
metadata:
15+
labels:
16+
app: cluster2
17+
pipecd.dev/variant: primary
18+
annotations:
19+
sidecar.istio.io/inject: "false"
20+
spec:
21+
containers:
22+
- name: helloworld
23+
image: ghcr.io/pipe-cd/helloworld:v0.32.0
24+
args:
25+
- server
26+
ports:
27+
- containerPort: 9085

‎pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/app.pipecd.yaml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
apiVersion: pipecd.dev/v1beta1
2+
kind: Application
3+
spec:
4+
name: simple
5+
labels:
6+
env: example
7+
plugins:
8+
kubernetes_multicluster:
9+
input:
10+
manifests:
11+
- deployment.yaml
12+
- service.yaml
13+
kubectlVersion: 1.32.2

‎pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/deployment.yaml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
apiVersion: apps/v1
2+
kind: Deployment
3+
metadata:
4+
name: simple
5+
labels:
6+
app: simple
7+
spec:
8+
replicas: 2
9+
selector:
10+
matchLabels:
11+
app: simple
12+
pipecd.dev/variant: primary
13+
template:
14+
metadata:
15+
labels:
16+
app: simple
17+
pipecd.dev/variant: primary
18+
annotations:
19+
sidecar.istio.io/inject: "false"
20+
spec:
21+
containers:
22+
- name: helloworld
23+
image: ghcr.io/pipe-cd/helloworld:v0.32.0
24+
args:
25+
- server
26+
ports:
27+
- containerPort: 9085

‎pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/service.yaml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
apiVersion: v1
2+
kind: Service
3+
metadata:
4+
name: simple
5+
spec:
6+
selector:
7+
app: simple
8+
ports:
9+
- protocol: TCP
10+
port: 9085
11+
targetPort: 9085

0 commit comments

Comments
 (0)