|
| 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 | + |
| 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 | +``` |
0 commit comments