diff --git a/pkg/app/pipedv1/plugin/kubernetes_multicluster/README.md b/pkg/app/pipedv1/plugin/kubernetes_multicluster/README.md new file mode 100644 index 0000000000..22f583786c --- /dev/null +++ b/pkg/app/pipedv1/plugin/kubernetes_multicluster/README.md @@ -0,0 +1,159 @@ +# Kubernetes Multicluster Plugin + +## Specification + +The current specification is described in the [RFC](../../../../../docs/rfcs/0014-multi-cluster-deployment-for-k8s.md). +The configuration format is unstable and may change in the future. + +Note: +- Currently, only QuickSync is supported. + +## Try k8s multicluster plugin locally + +**Switch to the upstream commit of the master branch** + +The whole fixes for plugins are stored in the master branch and some of the versions don't have them. + +```sh +git switch master +git pull +``` + +**Prepare the PipeCD Control Plane** + +Please refer to [pipe-cd/pipecd/cmd/pipecd/README.md](../../../../../cmd/pipecd/README.md) to set up the Control Plane in your local environment. + +**Prepare two k8s clusters** + +```sh +kind create cluster --name cluster1 +kind export kubeconfig --name cluster1 --kubeconfig /path/to/kubeconfig/for/cluster1 + +kind create cluster --name cluster2 +kind export kubeconfig --name cluster2 --kubeconfig /path/to/kubeconfig/for/cluster2 +``` + +**Start pipedv1 locally** + +Please refer to [pipe-cd/pipecd/cmd/pipedv1/README.md](../../../../../cmd/pipedv1/README.md) to set up the Control Plane in your local environment. +At this time, please modify the `spec.plugins` section of the piped config as shown below. + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + ... + plugins: + - name: kubernetes_multicluster + port: 7002 # any unused port + 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. + deployTargets: + - name: cluster1 + config: + masterURL: https://127.0.0.1:61337 # shown by kubectl cluster-info + kubeConfigPath: /path/to/kubeconfig/for/cluster1 + - name: cluster2 + config: + masterURL: https://127.0.0.1:62082 # shown by kubectl cluster-info + kubeConfigPath: /path/to/kubeconfig/for/cluster2 +``` + +**Prepare the manifest** + +- 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. +For example usage, see the [Examples](#examples) section below. + +**Register the application** + +![adding-application](./docs/static/adding-application.png) + +At this time, please select multiple DeployTargets. + +## Examples +There are examples under `./example`. + +| Name | Description | +|------|-------------| +| [simple](./example/simple/) | Deploy the same resources to the multiple clusters. | +| [multi-sources-template-none](./example/multi-sources-template-none/) | Deploy the different resources to the multiple clusters. | + +## Config Reference + +### Piped Config + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + ... + plugins: + # Plugin name. + - name: kubernetes_multicluster + # Port number used to listen plugin server. + port: 7002 + # The URL where the plugin binary located. + # It's OK using any value for now because it's a dummy. We will implement it later. + url: file:///path/to/.piped/plugins/kubernetes_multicluster + # List of the information for each target platform. + # This is alternative for the platform providers. + deployTargets: + # Then name of deploy target. + - name: cluster1 + # The plugin-specific config. + config: + # The master URL of the kubernetes cluster. + # Empty means in-cluster. + masterURL: https://127.0.0.1:61337 + # The path to the kubeconfig file. + # Empty means in-cluster. + kubeConfigPath: /path/to/kubeconfig/for/cluster1 + # Version of kubectl will be used. + kubectlVersion: 1.32.0 + - name: cluster2 + config: + masterURL: https://127.0.0.1:62082 + kubeConfigPath: /path/to/kubeconfig/for/cluster2 +``` + +### app.pipecd.yaml + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Application +spec: + ... + plugins: + kubernetes_multicluster: + input: + # List of manifest files in the application directory used to deploy. + # Empty means all manifest files in the directory will be used. + manifests: + - deployment.yaml + - service.yaml + # Version of kubectl will be used. + kubectlVersion: 1.32.0 + # The namespace where manifests will be applied. + namespace: example + # Automatically create a new namespace if it does not exist. + # Default is false. + autoCreateNamespace: false + # List of the setting for each deploy targets. + # You can also set config for them separately. + multiTargets: + # The identity of the deploy target. + # You can specify deploy target by some of them. + - target: + # The name of deploy target + name: cluster1 + # List of manifest files in the application directory used to deploy. + # Empty means all manifest files in the directory will be used. + manifests: + - ./cluster1/deployment.yaml + # Version of kubectl will be used. + kubectlVersion: 1.32.2 + - target: + name: cluster2 + manifests: + - ./cluster2/deployment.yaml + kubectlVersion: 1.32.2 +``` diff --git a/pkg/app/pipedv1/plugin/kubernetes_multicluster/docs/static/adding-application.png b/pkg/app/pipedv1/plugin/kubernetes_multicluster/docs/static/adding-application.png new file mode 100644 index 0000000000..e2279966c7 Binary files /dev/null and b/pkg/app/pipedv1/plugin/kubernetes_multicluster/docs/static/adding-application.png differ diff --git a/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/app.pipecd.yaml b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/app.pipecd.yaml new file mode 100644 index 0000000000..24ac32f82b --- /dev/null +++ b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/app.pipecd.yaml @@ -0,0 +1,21 @@ +apiVersion: pipecd.dev/v1beta1 +kind: Application +spec: + name: multi-sources-template-none + labels: + env: example + plugins: + kubernetes_multicluster: + quickSync: + prune: true + input: + multiTargets: + - target: + name: cluster1 + manifests: + - ./cluster1/deployment.yaml + - target: + name: cluster2 + manifests: + - ./cluster2/deployment.yaml + kubectlVersion: 1.32.2 diff --git a/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/cluster1/deployment.yaml b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/cluster1/deployment.yaml new file mode 100644 index 0000000000..59be9ff742 --- /dev/null +++ b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/cluster1/deployment.yaml @@ -0,0 +1,27 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: cluster1 + labels: + app: cluster1 +spec: + replicas: 2 + selector: + matchLabels: + app: cluster1 + pipecd.dev/variant: primary + template: + metadata: + labels: + app: cluster1 + pipecd.dev/variant: primary + annotations: + sidecar.istio.io/inject: "false" + spec: + containers: + - name: helloworld + image: ghcr.io/pipe-cd/helloworld:v0.32.0 + args: + - server + ports: + - containerPort: 9085 diff --git a/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/cluster2/deployment.yaml b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/cluster2/deployment.yaml new file mode 100644 index 0000000000..63330878ca --- /dev/null +++ b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/multi-sources-template-none/cluster2/deployment.yaml @@ -0,0 +1,27 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: cluster2 + labels: + app: cluster2 +spec: + replicas: 2 + selector: + matchLabels: + app: cluster2 + pipecd.dev/variant: primary + template: + metadata: + labels: + app: cluster2 + pipecd.dev/variant: primary + annotations: + sidecar.istio.io/inject: "false" + spec: + containers: + - name: helloworld + image: ghcr.io/pipe-cd/helloworld:v0.32.0 + args: + - server + ports: + - containerPort: 9085 diff --git a/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/app.pipecd.yaml b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/app.pipecd.yaml new file mode 100644 index 0000000000..3d77aae80f --- /dev/null +++ b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/app.pipecd.yaml @@ -0,0 +1,13 @@ +apiVersion: pipecd.dev/v1beta1 +kind: Application +spec: + name: simple + labels: + env: example + plugins: + kubernetes_multicluster: + input: + manifests: + - deployment.yaml + - service.yaml + kubectlVersion: 1.32.2 diff --git a/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/deployment.yaml b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/deployment.yaml new file mode 100644 index 0000000000..f1e0d4b29a --- /dev/null +++ b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/deployment.yaml @@ -0,0 +1,27 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: simple + labels: + app: simple +spec: + replicas: 2 + selector: + matchLabels: + app: simple + pipecd.dev/variant: primary + template: + metadata: + labels: + app: simple + pipecd.dev/variant: primary + annotations: + sidecar.istio.io/inject: "false" + spec: + containers: + - name: helloworld + image: ghcr.io/pipe-cd/helloworld:v0.32.0 + args: + - server + ports: + - containerPort: 9085 diff --git a/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/service.yaml b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/service.yaml new file mode 100644 index 0000000000..52ca9d1f59 --- /dev/null +++ b/pkg/app/pipedv1/plugin/kubernetes_multicluster/example/simple/service.yaml @@ -0,0 +1,11 @@ +apiVersion: v1 +kind: Service +metadata: + name: simple +spec: + selector: + app: simple + ports: + - protocol: TCP + port: 9085 + targetPort: 9085