diff --git a/docs/proposals/20220615-sidecarset-patch-pod-metadata.md b/docs/proposals/20220615-sidecarset-patch-pod-metadata.md new file mode 100644 index 0000000000..529cce47a4 --- /dev/null +++ b/docs/proposals/20220615-sidecarset-patch-pod-metadata.md @@ -0,0 +1,106 @@ +--- +title: SidecarSetPatchPodMetadata +authors: +- "@zmberg" +reviewers: +- "@furykerry" +- "@FillZpp" +creation-date: 2021-06-15 +last-updated: 2021-06-15 +status: implementable +--- + +# SidecarSet Patch Pod Metadata + +## Table of Contents + +A table of contents is helpful for quickly jumping to sections of a proposal and for highlighting +any additional information provided beyond the standard proposal template. +[Tools for generating](https://github.com/ekalinin/github-markdown-toc) a table of contents from markdown are available. + +- [Title](#title) +- [Table of Contents](#table-of-contents) +- [Motivation](#motivation) +- [Proposal](#proposal) +- [API Definition](#api-definition) +- [Permission Control](#permission-control) + +## Motivation +Some sidecar containers may require special configurations that take effect via annotations/labels. Thus, sidecarSet should support inject or in-place update these configurations. + +**User Story:** +- log-agent sidecar container inject pod annotation[oom-score]='{"log-agent": 1}' to set sidecar oom score. + +## Proposal +SidecarSet support patch pod annotations/labels, as follows: + +### Api Definition +```yaml +/ SidecarSetSpec defines the desired state of SidecarSet +type SidecarSetSpec struct { + // Patch can be decoded as PatchPodMetadata, and will patch these fields in PatchPodMetadata + // to the pod at injection stage + PatchPodMetadata *PatchPodMetadata `json:"patchPodMetadata,omitempty"` +} + +type PatchPodMetadata struct { + // PatchPodFields collects the fields that need to patch pod at injection stage. + PatchPodFields `json:",inline"` + // patch pod metadata policy, Default is "Ignore" + PatchPolicy PatchPolicyType `json:"patchPolicy,omitempty"` +} + +type PatchPodFields struct { + Annotations map[string]string `json:"annotations,omitempty"` +} + +type PatchPolicyType string +var ( + // OverwritePatchPolicy indicates if PatchPodFields conflicts with Pod, + // SidecarSet will apply PatchPodFields to overwrite the corresponding fields of pods. + // SidecarSet webhook cannot allow the conflict of PatchPodFields between SidecarSets under this policy type. + OverwritePatchPolicy PatchPolicyType = "Overwrite" + + // IgnorePatchPolicy indicates if PatchPodFields conflicts with Pod, + // will ignore PatchPodFields, and keep the corresponding fields of pods. + IgnorePatchPolicy PatchPolicyType = "Ignore" + + // MergePatchJsonPatchPolicy indicate that sidecarSet use application/merge-patch+json to patch annotation value, + // for example, A patch annotation[oom-score] = '{"log-agent": 1}' and B patch annotation[oom-score] = '{"envoy": 2}' + // result pod annotation[oom-score] = '{"log-agent": 1, "envoy": 2}' + MergePatchJsonPatchPolicy PatchPolicyType = "MergePatchJson" + + // JsonPatchPolicy indicate that sidecarSet use application/json-patch+json to patch annotation value, + // for example, pod annotation[extend-containers] = '{"containers": {"name": "log-agent", "hostConfig": {"oomScore": 5}}}' + // and A patch annotation[extend-containers] = '[{"op": "replace", "patch": "/containers/hostConfig/oomScore", "value": 2}]', + // result pod annotation[extend-containers] = '{"containers": {"name": "log-agent", "hostConfig": {"oomScore": 2}}}' + JsonPatchPolicy PatchPolicyType = "JsonPatch" +) +``` + +### Permission Control +SidecarSet should not modify any configuration outside the sidecar container from permission perspective. Metadata, as an important configuration of Pod, should not be modified by sidecarSet by default. + +Objectively, sidecar does need to have some annotations or labels injected into the pod as well. In order to meet the needs of sidecar and security considerations. +if sidecarSet needs to modify the metadata, it needs to be whitelisted in kruise configmap which is maintained by the system administrator. + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + labels: + kruise.io/system-config: kruise-manager +name: kruise-manager +namespace: kruise-system +data: + "kruise.sidecarset.patch.pod.metadata.whitelist": | + type WhiteList struct { + WhiteStrategic []WhiteStrategic + } + type WhiteStrategic struct { + // selector sidecarSet + SelectorSidecarSet *metav1.LabelSelector + // Support for regular expressions + AnnotationKeys []string + } +```