From 1d579d98b6e956a75b3096cc322c062f6bc6e646 Mon Sep 17 00:00:00 2001 From: Yoshiki Fujikane Date: Mon, 9 Jun 2025 19:27:50 +0900 Subject: [PATCH 1/7] WIP Signed-off-by: Yoshiki Fujikane --- pkg/app/pipedv1/plugin/kubernetes/README.md | 205 ++++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 pkg/app/pipedv1/plugin/kubernetes/README.md diff --git a/pkg/app/pipedv1/plugin/kubernetes/README.md b/pkg/app/pipedv1/plugin/kubernetes/README.md new file mode 100644 index 0000000000..fed632bbf3 --- /dev/null +++ b/pkg/app/pipedv1/plugin/kubernetes/README.md @@ -0,0 +1,205 @@ +# Kubernetes plugin + +## Overview + + +## Plugin Configuration + +### Piped Config + +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Piped +spec: + plugins: + - name: kubernetes + port: 7002 # any unused port + url: file:///path/to/.piped/plugins/kubernetes # or remoteUrl(TBD) + deployTargets: + ... +``` + +| Field | Type | Description | Required | +|-|-|-|-| +| deployTargets | [][DeployTargetConfig](#DeployTargetConfig) | The config for the destinations to deploy applications | Yes | + +#### DeployTargetConfig + +| Field | Type | Description | Required | +|-|-|-|-| +| name | string | The name of the deploy target. | Yes | +| labels | string | The labes of the deploy target. | No | +| config | [KubernetesDeployTargetConfig](#KubernetesDeployTargetConfig) | The configuration of the deploy target for k8s plugin. | No | + +##### KubernetesDeployTargetConfig + +| Field | Type | Description | Required | +|-|-|-|-| +| masterURL | string | The master URL of the kubernetes cluster. Empty means in-cluster. | No | +| kubectlVersion | string | Version of kubectl which will be used to connect to your cluster. Empty means the [default version](https://github.com/pipe-cd/pipecd/blob/master/pkg/app/pipedv1/plugin/kubernetes/toolregistry/registry.go#L25) will be used. | No | +| kubeConfigPath | string | The path to the kubeconfig file. Empty means in-cluster. | No | + +### Application Config + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: Application +spec: +... + plugins: + kubernetes: # same name as the one defined in `spec.plugins[].name` + input: + pipeline: + service: + workloads: + variantLabel: +``` + +| Field | Type | Description | Required | +|-|-|-|-| +| input | [KubernetesDeploymentInput](#kubernetesdeploymentinput) | Input for Kubernetes deployment such as kubectl version, helm version, manifests filter... | No | +| pipeline | [Pipeline](#pipeline) | Pipeline for deploying progressively. | No | +| service | [K8sResourceReference](#K8sResourceReference) | Which Kubernetes resource should be considered as the Service of application. Empty means the first Service resource will be used. | No | +| workloads | [][K8sResourceReference](#K8sResourceReference) | Which Kubernetes resources should be considered as the Workloads of application. Empty means all Deployment resources. | No | +| variantLabel | [KubernetesVariantLabel](#kubernetesvariantlabel) | The label will be configured to variant manifests used to distinguish them. | No | + +#### KubernetesDeploymentInput + +| Field | Type | Description | Required | +|-|-|-|-| +| manifests | []string | List of manifest files in the application directory used to deploy. Empty means all manifest files in the directory will be used. | No | +| kubectlVersion | string | Version of kubectl will be used. Empty means the version set on [piped config](#KubernetesDeployTargetConfig) or [default version](https://github.com/pipe-cd/pipecd/blob/master/pkg/app/pipedv1/plugin/kubernetes/toolregistry/registry.go#L25) will be used. | No | +| kustomizeVersion | string | Version of kustomize will be used. Empty means the [default version](https://github.com/pipe-cd/pipecd/blob/master/pkg/app/pipedv1/plugin/kubernetes/toolregistry/registry.go#L26) will be used. | No | +| kustomizeOptions | map[string]string | List of options that should be used by Kustomize commands. | No | +| helmVersion | string | Version of helm will be used. Empty means the [default version](https://github.com/pipe-cd/pipecd/blob/master/pkg/app/pipedv1/plugin/kubernetes/toolregistry/registry.go#L27) will be used. | No | +| helmChart | [HelmChart](#helmchart) | Where to fetch helm chart. | No | +| helmOptions | [HelmOptions](#helmoptions) | Configurable parameters for helm commands. | No | +| namespace | string | The namespace where manifests will be applied. | No | +| autoCreateNamespace | bool | Automatically create a new namespace if it does not exist. Default is `false`. | No | + +##### HelmChart + + +| Field | Type | Description | Required | +|-|-|-|-| +| ref | string | The commit SHA or tag value. Only valid when gitRemote is not empty. | No | +| path | string | Relative path from the repository root to the chart directory. | No | +| name | string | The chart name. | No | +| version | string | The chart version. | No | + +##### HelmOptions + +| Field | Type | Description | Required | +|-|-|-|-| +| releaseName | string | The release name of helm deployment. By default, the release name is equal to the application name. | No | +| setValues | map[string]string | List of values. | No | +| valueFiles | []string | List of value files should be loaded. Only local files stored under the application directory or remote files served at the http(s) endpoint are allowed. | No | +| setFiles | map[string]string | List of file path for values. | No | +| apiVersions | []string | Kubernetes api versions used for Capabilities.APIVersions. | No | +| kubeVersion | string | Kubernetes version used for Capabilities.KubeVersion. | No | + +#### Pipeline + +| Field | Type | Description | Required | +|-|-|-|-| +| stages | [][PipelineStage](#pipelinestage) | List of deployment pipeline stages. | No | + +##### PipelineStage + +| Field | Type | Description | Required | +|-|-|-|-| +| id | string | The unique ID of the stage. | No | +| name | string | One of the provided stage names. | Yes | +| desc | string | The description about the stage. | No | +| timeout | duration | The maximum time the stage can be taken to run. | No | +| with | [Stage Config](#Stage Config) | Specific configuration for the stage. This must be one of these [Stage Config](#Stage Config). | No | + +#### K8sResourceReference + +| Field | Type | Description | Required | +|-|-|-|-| +| kind | string | The kind name of resources. | No | +| name | string | The name of resources. | No | + +#### KubernetesVariantLabel + +| Field | Type | Description | Required | +|-|-|-|-| +| key | string | The key of the label. Default is `pipecd.dev/variant`. | No | +| primaryValue | string | The label value for PRIMARY variant. Default is `primary`. | No | +| canaryValue | string | The label value for CANARY variant. Default is `canary`. | No | +| baselineValue | string | The label value for BASELINE variant. Default is `baseline`. | No | + +### Stage Config + +#### `K8S_SYNC` + +| Field | Type | Description | Required | +|-|-|-|-| +| addVariantLabelToSelector | bool | Whether the PRIMARY variant label should be added to manifests if they were missing. | No | +| prune | string | Whether the resources that are no longer defined in Git should be removed or not. | No | + +#### `K8S_PRIMARY_ROLLOUT` + +| Field | Type | Description | Required | +|-|-|-|-| +| suffix | string | Suffix that should be used when naming the PRIMARY variant's resources. Default is "primary". | No | +| createService | bool | Whether the PRIMARY service should be created. | No | +| addVariantLabelToSelector | bool | Whether the PRIMARY variant label should be added to manifests if they were missing. | No | +| prune | string | Whether the resources that are no longer defined in Git should be removed or not. | No | + +#### `K8S_CANARY_ROLLOUT` + +| Field | Type | Description | Required | +|-|-|-|-| +| replicas | int | How many pods for CANARY workloads. Default is `1` pod. Alternatively, can be specified a string suffixed by "%" to indicate a percentage value compared to the pod number of PRIMARY. | No | +| suffix | string | Suffix that should be used when naming the CANARY variant's resources. Default is `canary`. | No | +| createService | bool | Whether the CANARY service should be created. Default is `false`. | No | +| Patches | [][K8sResourcePatch](#K8sResourcePatch) | List of patches used to customize manifests for CANARY variant. | No | + +#### K8sResourcePatch + +| Field | Type | Description | Required | +|-|-|-|-| +| target | [K8sResourcePatchTarget](#K8sResourcePatchTarget) | Which manifest, which field will be the target of patch operations. | Yes | +| ops | [][K8sResourcePatchOp](#K8sResourcePatchOp) | List of operations should be applied to the above target. | No | + +##### K8sResourcePatchTarget + +| Field | Type | Description | Required | +|-|-|-|-| +| kind | string | The resource kind. e.g. `ConfigMap` | Yes | +| name | string | The resource name. e.g. `config-map-name` | Yes | +| documentRoot | string | In case you want to manipulate the YAML or JSON data specified in a field of the manfiest, specify that field's path. The string value of that field will be used as input for the patch operations. Otherwise, the whole manifest will be the target of patch operations. e.g. `$.data.envoy-config` | No | + +##### K8sResourcePatchOp + +| Field | Type | Description | Required | +|-|-|-|-| +| op | string | The operation type. This must be one of `yaml-replace`, `yaml-add`, `yaml-remove`, `json-replace`, `text-regex`. Default is `yaml-replace`. | No | +| path | string | The path string pointing to the manipulated field. For yaml operations it looks like `$.foo.array[0].bar`. | No | +| value | string | The value string whose content will be used as new value for the field. | No | + + +#### `K8S_CANARY_CLEAN` + +| Field | Type | Description | Required | +|-|-|-|-| + +#### `K8S_BASELINE_ROLLOUT` + +| Field | Type | Description | Required | +|-|-|-|-| +| replicas | int | How many pods for BASELINE workloads. Default is `1` pod. Alternatively, can be specified a string suffixed by "%" to indicate a percentage value compared to the pod number of PRIMARY | No | +| suffix | string | Suffix that should be used when naming the BASELINE variant's resources. Default is `baseline`. | No | +| createService | bool | Whether the BASELINE service should be created. Default is `false`. | No | + +#### `K8S_BASELINE_CLEAN` + +| Field | Type | Description | Required | +|-|-|-|-| + +#### `K8S_ROLLBACK` + +| Field | Type | Description | Required | +|-|-|-|-| From bb25820949a395b25b4ba28545f02d6fbe96e081 Mon Sep 17 00:00:00 2001 From: Yoshiki Fujikane Date: Tue, 10 Jun 2025 10:23:27 +0900 Subject: [PATCH 2/7] Add overview Signed-off-by: Yoshiki Fujikane --- pkg/app/pipedv1/plugin/kubernetes/README.md | 51 +++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/pkg/app/pipedv1/plugin/kubernetes/README.md b/pkg/app/pipedv1/plugin/kubernetes/README.md index fed632bbf3..f6634258f0 100644 --- a/pkg/app/pipedv1/plugin/kubernetes/README.md +++ b/pkg/app/pipedv1/plugin/kubernetes/README.md @@ -2,6 +2,57 @@ ## Overview +Kubernetes plugin supports the Deployment for Kubernetes. + +> [!CAUTION] Currently, this is alpha status. + +### Quick sync + +Quick sync is a fast way to sync application to the state specified in the target Git commit without any progressive strategy. It just applies all the defined manifiests to sync the application. +The quick sync will be planned in one of the following cases: +- no pipeline was specified in the application configuration file +- [pipeline](#pipeline) was specified but the PR did not make any changes on workload (e.g. Deployment's pod template) or config (e.g. ConfigMap, Secret) + +For example, the application configuration as below is missing the pipeline field. This means any pull request touches the application will trigger a quick sync deployment. + +``` yaml +apiVersion: pipecd.dev/v1beta1 +kind: KubernetesApp +spec: + input: + helmChart: + repository: pipecd + name: helloworld + version: v0.3.0 +``` + +In another case, even when the pipeline was specified, a PR that just changes the Deployment's replicas number for scaling will also trigger a quick sync deployment. + +### Pipeline sync + +The `pipeline` field in the application configuration is used to customize the way to do deployment by specifying and configuring the execution stages. You may want to configure those stages to enable a progressive deployment with a strategy like canary, blue-green, a manual approval, an analysis stage. + +To enable customization, PipeCD defines three variants for each Kubernetes application: primary (aka stable), baseline and canary. +- `primary` runs the current version of code and configuration. +- `baseline` runs the same version of code and configuration as the primary variant. (Creating a brand-new baseline workload ensures that the metrics produced are free of any effects caused by long-running processes.) +- `canary` runs the proposed change of code or configuration. + +Depending on the configured pipeline, any variants can exist and receive the traffic during the deployment process but once the deployment is completed, only the `primary` variant should be remained. + +These are the provided stages for Kubernetes application you can use to build your pipeline: + +- `K8S_SYNC` + - sync application to the state specified in the target Git commit without any progressive strategy +- `K8S_PRIMARY_ROLLOUT` + - update the primary resources to the state defined in the target commit +- `K8S_CANARY_ROLLOUT` + - generate canary resources based on the definition of the primary resource in the target commit and apply them +- `K8S_CANARY_CLEAN` + - remove all canary resources +- `K8S_BASELINE_ROLLOUT` + - generate baseline resources based on the definition of the primary resource in the target commit and apply them +- `K8S_BASELINE_CLEAN` + - remove all baseline resources ## Plugin Configuration From 34d075b0130bce0b822c917fcdc83c6a425abdc7 Mon Sep 17 00:00:00 2001 From: Yoshiki Fujikane Date: Tue, 10 Jun 2025 10:36:54 +0900 Subject: [PATCH 3/7] Fix doc Signed-off-by: Yoshiki Fujikane --- pkg/app/pipedv1/plugin/kubernetes/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pkg/app/pipedv1/plugin/kubernetes/README.md b/pkg/app/pipedv1/plugin/kubernetes/README.md index f6634258f0..c4d1f694b5 100644 --- a/pkg/app/pipedv1/plugin/kubernetes/README.md +++ b/pkg/app/pipedv1/plugin/kubernetes/README.md @@ -4,7 +4,8 @@ Kubernetes plugin supports the Deployment for Kubernetes. -> [!CAUTION] Currently, this is alpha status. +> [!CAUTION] +> Currently, this is alpha status. ### Quick sync @@ -163,7 +164,7 @@ spec: | name | string | One of the provided stage names. | Yes | | desc | string | The description about the stage. | No | | timeout | duration | The maximum time the stage can be taken to run. | No | -| with | [Stage Config](#Stage Config) | Specific configuration for the stage. This must be one of these [Stage Config](#Stage Config). | No | +| with | [Stage Config](#Stage-Config) | Specific configuration for the stage. This must be one of these [Stage Config](#Stage-Config). | No | #### K8sResourceReference From f17cc04b614cf7241a87fcc905888ff97133c96c Mon Sep 17 00:00:00 2001 From: Yoshiki Fujikane Date: Tue, 10 Jun 2025 10:59:30 +0900 Subject: [PATCH 4/7] Remove pipeline section Signed-off-by: Yoshiki Fujikane --- pkg/app/pipedv1/plugin/kubernetes/README.md | 51 +++++++++++---------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/pkg/app/pipedv1/plugin/kubernetes/README.md b/pkg/app/pipedv1/plugin/kubernetes/README.md index c4d1f694b5..c0532ca08a 100644 --- a/pkg/app/pipedv1/plugin/kubernetes/README.md +++ b/pkg/app/pipedv1/plugin/kubernetes/README.md @@ -101,7 +101,6 @@ spec: plugins: kubernetes: # same name as the one defined in `spec.plugins[].name` input: - pipeline: service: workloads: variantLabel: @@ -110,7 +109,6 @@ spec: | Field | Type | Description | Required | |-|-|-|-| | input | [KubernetesDeploymentInput](#kubernetesdeploymentinput) | Input for Kubernetes deployment such as kubectl version, helm version, manifests filter... | No | -| pipeline | [Pipeline](#pipeline) | Pipeline for deploying progressively. | No | | service | [K8sResourceReference](#K8sResourceReference) | Which Kubernetes resource should be considered as the Service of application. Empty means the first Service resource will be used. | No | | workloads | [][K8sResourceReference](#K8sResourceReference) | Which Kubernetes resources should be considered as the Workloads of application. Empty means all Deployment resources. | No | | variantLabel | [KubernetesVariantLabel](#kubernetesvariantlabel) | The label will be configured to variant manifests used to distinguish them. | No | @@ -131,7 +129,6 @@ spec: ##### HelmChart - | Field | Type | Description | Required | |-|-|-|-| | ref | string | The commit SHA or tag value. Only valid when gitRemote is not empty. | No | @@ -150,22 +147,6 @@ spec: | apiVersions | []string | Kubernetes api versions used for Capabilities.APIVersions. | No | | kubeVersion | string | Kubernetes version used for Capabilities.KubeVersion. | No | -#### Pipeline - -| Field | Type | Description | Required | -|-|-|-|-| -| stages | [][PipelineStage](#pipelinestage) | List of deployment pipeline stages. | No | - -##### PipelineStage - -| Field | Type | Description | Required | -|-|-|-|-| -| id | string | The unique ID of the stage. | No | -| name | string | One of the provided stage names. | Yes | -| desc | string | The description about the stage. | No | -| timeout | duration | The maximum time the stage can be taken to run. | No | -| with | [Stage Config](#Stage-Config) | Specific configuration for the stage. This must be one of these [Stage Config](#Stage-Config). | No | - #### K8sResourceReference | Field | Type | Description | Required | @@ -184,6 +165,33 @@ spec: ### Stage Config +```yaml +apiVersion: pipecd.dev/v1beta1 +kind: Application +spec: +... + pipeline: + stages: + - name: K8S_SYNC + with: + ... + - name: K8S_PRIMARY_ROLLOUT + with: + ... + - name: K8S_CANARY_ROLLOUT + with: + ... + - name: K8S_CANARY_CLEAN + with: + ... + - name: K8S_BASELINE_ROLLOUT + with: + ... + - name: K8S_BASELINE_CLEAN + with: + ... +``` + #### `K8S_SYNC` | Field | Type | Description | Required | @@ -250,8 +258,3 @@ spec: | Field | Type | Description | Required | |-|-|-|-| - -#### `K8S_ROLLBACK` - -| Field | Type | Description | Required | -|-|-|-|-| From b6a0fcb43b8bc807008a0f33dd91983cff46c63f Mon Sep 17 00:00:00 2001 From: Yoshiki Fujikane Date: Tue, 10 Jun 2025 11:09:39 +0900 Subject: [PATCH 5/7] Remove link Signed-off-by: Yoshiki Fujikane --- pkg/app/pipedv1/plugin/kubernetes/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/app/pipedv1/plugin/kubernetes/README.md b/pkg/app/pipedv1/plugin/kubernetes/README.md index c0532ca08a..4f219a153f 100644 --- a/pkg/app/pipedv1/plugin/kubernetes/README.md +++ b/pkg/app/pipedv1/plugin/kubernetes/README.md @@ -12,7 +12,7 @@ Kubernetes plugin supports the Deployment for Kubernetes. Quick sync is a fast way to sync application to the state specified in the target Git commit without any progressive strategy. It just applies all the defined manifiests to sync the application. The quick sync will be planned in one of the following cases: - no pipeline was specified in the application configuration file -- [pipeline](#pipeline) was specified but the PR did not make any changes on workload (e.g. Deployment's pod template) or config (e.g. ConfigMap, Secret) +- `pipeline` was specified but the PR did not make any changes on workload (e.g. Deployment's pod template) or config (e.g. ConfigMap, Secret) For example, the application configuration as below is missing the pipeline field. This means any pull request touches the application will trigger a quick sync deployment. From eddc9df8f89fc4159caa30397dea4030a17bc284 Mon Sep 17 00:00:00 2001 From: Yoshiki Fujikane Date: Tue, 10 Jun 2025 11:34:57 +0900 Subject: [PATCH 6/7] Fix overview Signed-off-by: Yoshiki Fujikane --- pkg/app/pipedv1/plugin/kubernetes/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pkg/app/pipedv1/plugin/kubernetes/README.md b/pkg/app/pipedv1/plugin/kubernetes/README.md index 4f219a153f..1bb358ca0f 100644 --- a/pkg/app/pipedv1/plugin/kubernetes/README.md +++ b/pkg/app/pipedv1/plugin/kubernetes/README.md @@ -9,8 +9,9 @@ Kubernetes plugin supports the Deployment for Kubernetes. ### Quick sync -Quick sync is a fast way to sync application to the state specified in the target Git commit without any progressive strategy. It just applies all the defined manifiests to sync the application. -The quick sync will be planned in one of the following cases: +Quick sync just applies all the defined manifiests to sync the application. + +It will be planned in one of the following cases: - no pipeline was specified in the application configuration file - `pipeline` was specified but the PR did not make any changes on workload (e.g. Deployment's pod template) or config (e.g. ConfigMap, Secret) @@ -18,12 +19,12 @@ For example, the application configuration as below is missing the pipeline fiel ``` yaml apiVersion: pipecd.dev/v1beta1 -kind: KubernetesApp +kind: Application spec: input: helmChart: - repository: pipecd name: helloworld + path: /path/to/chart version: v0.3.0 ``` @@ -31,16 +32,16 @@ In another case, even when the pipeline was specified, a PR that just changes th ### Pipeline sync -The `pipeline` field in the application configuration is used to customize the way to do deployment by specifying and configuring the execution stages. You may want to configure those stages to enable a progressive deployment with a strategy like canary, blue-green, a manual approval, an analysis stage. +You can configure the pipeline to enable a progressive deployment with a strategy like canary, blue-green. -To enable customization, PipeCD defines three variants for each Kubernetes application: primary (aka stable), baseline and canary. +To enable customization, Kubernetes plugin defines three variants for each application: primary (aka stable), baseline and canary. - `primary` runs the current version of code and configuration. - `baseline` runs the same version of code and configuration as the primary variant. (Creating a brand-new baseline workload ensures that the metrics produced are free of any effects caused by long-running processes.) - `canary` runs the proposed change of code or configuration. Depending on the configured pipeline, any variants can exist and receive the traffic during the deployment process but once the deployment is completed, only the `primary` variant should be remained. -These are the provided stages for Kubernetes application you can use to build your pipeline: +These are the provided stages for Kubernetes plugin you can use to build your pipeline: - `K8S_SYNC` - sync application to the state specified in the target Git commit without any progressive strategy @@ -131,7 +132,6 @@ spec: | Field | Type | Description | Required | |-|-|-|-| -| ref | string | The commit SHA or tag value. Only valid when gitRemote is not empty. | No | | path | string | Relative path from the repository root to the chart directory. | No | | name | string | The chart name. | No | | version | string | The chart version. | No | From e9792b8d89f88494da2d8c40e177ce08f68aadec Mon Sep 17 00:00:00 2001 From: Yoshiki Fujikane Date: Tue, 10 Jun 2025 11:43:42 +0900 Subject: [PATCH 7/7] Fix example Signed-off-by: Yoshiki Fujikane --- pkg/app/pipedv1/plugin/kubernetes/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/pkg/app/pipedv1/plugin/kubernetes/README.md b/pkg/app/pipedv1/plugin/kubernetes/README.md index 1bb358ca0f..1a065cfd0a 100644 --- a/pkg/app/pipedv1/plugin/kubernetes/README.md +++ b/pkg/app/pipedv1/plugin/kubernetes/README.md @@ -21,11 +21,13 @@ For example, the application configuration as below is missing the pipeline fiel apiVersion: pipecd.dev/v1beta1 kind: Application spec: - input: - helmChart: - name: helloworld - path: /path/to/chart - version: v0.3.0 + plugins: + kubernetes: + input: + helmChart: + name: helloworld + path: /path/to/chart + version: v0.3.0 ``` In another case, even when the pipeline was specified, a PR that just changes the Deployment's replicas number for scaling will also trigger a quick sync deployment.