From d9c4c749e25141b51f477aa36b60d3d05f27ba59 Mon Sep 17 00:00:00 2001 From: Yuwen Ma Date: Fri, 19 Nov 2021 16:45:55 -0800 Subject: [PATCH] improve docs with examples for nameReference --- .../builtinpluginconsts/namereference.go | 3 + examples/transformerconfigs/README.md | 478 +++++++++++++++++- 2 files changed, 456 insertions(+), 25 deletions(-) diff --git a/api/konfig/builtinpluginconsts/namereference.go b/api/konfig/builtinpluginconsts/namereference.go index 26a344f4d..724e9a996 100644 --- a/api/konfig/builtinpluginconsts/namereference.go +++ b/api/konfig/builtinpluginconsts/namereference.go @@ -3,6 +3,7 @@ package builtinpluginconsts +// LINT.IfChange const ( nameReferenceFieldSpecs = ` nameReference: @@ -398,3 +399,5 @@ nameReference: kind: Ingress ` ) + +// LINT.ThenChange(/examples/transformerconfigs/README.md) diff --git a/examples/transformerconfigs/README.md b/examples/transformerconfigs/README.md index 368f53543..6b3d8b56d 100644 --- a/examples/transformerconfigs/README.md +++ b/examples/transformerconfigs/README.md @@ -119,44 +119,472 @@ commonAnnotations: ## Name reference transformer -Name reference transformer's configuration is different from all other transformers. It contains a list of `nameReferences`, which represent all of the possible fields that a type could be used as a reference in other types of resources. A `nameReference` contains a type such as ConfigMap as well as a list of `fieldSpecs` where ConfigMap is referenced in other resources. Here is an example: +`nameReference` Transformer is used to tie a target resource's name to a list of other resources' referrers' names. +Once tied, the referrers' names will change alongside the target name via transformers like `namePrefix` and `nameSuffix` +### Usage + - The syntax `nameReference` should be written in the `configurations` files, not directly in `kustomization.yaml` + - kustomize has a set of builtin nameReference, and you don't need to write additional configs to use those nameReference. Check the full list [here](#builtin-namereference). + - The referrer's `name` has to match the target's `name`. Otherwise, the referrer's name won't be changed. This name can be the target's current name, or, if the target has been through multiple name transformations, can be any of the target's previous names. + - `nameReference` should be used together with other name-changing transformers. Using it alone won't make any changes. + +### Example + +kustomization.yaml ```yaml -kind: ConfigMap -version: v1 -fieldSpecs: -- kind: Pod - version: v1 - path: spec/volumes/configMap/name -- kind: Deployment - path: spec/template/spec/volumes/configMap/name -- kind: Job - path: spec/template/spec/volumes/configMap/name +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: + # resources.yaml contains a Gorilla and a AnimalPark + - resources.yaml + +# Add name prefix "sample-" to the Gorilla's and AnimalPark's name +namePrefix: sample- + +configurations: + # Tie target Gorilla to AnimalPark's referrer spec.gorillaRef. + # Once Gorilla name is changed, the AnimalPark referrerd Gorilla name will be changed as well. + - nameReference.yaml +``` +nameReference.yaml +```yaml +nameReference: + - kind: Gorilla + fieldSpecs: + - kind: AnimalPark + path: spec/gorillaRef/name ``` -Name reference transformer's configuration contains a list of `nameReferences` for resources such as ConfigMap, Secret, Service, Role, and ServiceAccount. Here is an example configuration: +resources.yaml +```yaml +apiVersion: animal/v1 +kind: Gorilla +metadata: + name: gg +--- +apiVersion: animal/v1 +kind: AnimalPark +metadata: + name: ap +spec: + gorillaRef: + name: gg + kind: Gorilla + apiVersion: animal/v1 +``` +Output of `kustomize build` +```yaml +apiVersion: animal/v1 +kind: AnimalPark +metadata: + name: sample-ap # changed by `namePrefix` +spec: + gorillaRef: + apiVersion: animal/v1 + kind: Gorilla + name: sample-gg # changed by `nameReference` +--- +apiVersion: animal/v1 +kind: Gorilla +metadata: + name: sample-gg # changed by `namePrefix` +``` + +### builtin NameReference ```yaml nameReference: +- kind: Deployment + fieldSpecs: + - path: spec/scaleTargetRef/name + kind: HorizontalPodAutoscaler + +- kind: ReplicationController + fieldSpecs: + - path: spec/scaleTargetRef/name + kind: HorizontalPodAutoscaler + +- kind: ReplicaSet + fieldSpecs: + - path: spec/scaleTargetRef/name + kind: HorizontalPodAutoscaler + +- kind: StatefulSet + fieldSpecs: + - path: spec/scaleTargetRef/name + kind: HorizontalPodAutoscaler + - kind: ConfigMap version: v1 fieldSpecs: - - path: spec/volumes/configMap/name - version: v1 - kind: Pod - - path: spec/containers/env/valueFrom/configMapKeyRef/name - version: v1 - kind: Pod - # ... + - path: spec/volumes/configMap/name + version: v1 + kind: Pod + - path: spec/containers/env/valueFrom/configMapKeyRef/name + version: v1 + kind: Pod + - path: spec/initContainers/env/valueFrom/configMapKeyRef/name + version: v1 + kind: Pod + - path: spec/containers/envFrom/configMapRef/name + version: v1 + kind: Pod + - path: spec/initContainers/envFrom/configMapRef/name + version: v1 + kind: Pod + - path: spec/volumes/projected/sources/configMap/name + version: v1 + kind: Pod + - path: template/spec/volumes/configMap/name + kind: PodTemplate + - path: spec/template/spec/volumes/configMap/name + kind: Deployment + - path: spec/template/spec/containers/env/valueFrom/configMapKeyRef/name + kind: Deployment + - path: spec/template/spec/initContainers/env/valueFrom/configMapKeyRef/name + kind: Deployment + - path: spec/template/spec/containers/envFrom/configMapRef/name + kind: Deployment + - path: spec/template/spec/initContainers/envFrom/configMapRef/name + kind: Deployment + - path: spec/template/spec/volumes/projected/sources/configMap/name + kind: Deployment + - path: spec/template/spec/volumes/configMap/name + kind: ReplicaSet + - path: spec/template/spec/containers/env/valueFrom/configMapKeyRef/name + kind: ReplicaSet + - path: spec/template/spec/initContainers/env/valueFrom/configMapKeyRef/name + kind: ReplicaSet + - path: spec/template/spec/containers/envFrom/configMapRef/name + kind: ReplicaSet + - path: spec/template/spec/initContainers/envFrom/configMapRef/name + kind: ReplicaSet + - path: spec/template/spec/volumes/projected/sources/configMap/name + kind: ReplicaSet + - path: spec/template/spec/volumes/configMap/name + kind: DaemonSet + - path: spec/template/spec/containers/env/valueFrom/configMapKeyRef/name + kind: DaemonSet + - path: spec/template/spec/initContainers/env/valueFrom/configMapKeyRef/name + kind: DaemonSet + - path: spec/template/spec/containers/envFrom/configMapRef/name + kind: DaemonSet + - path: spec/template/spec/initContainers/envFrom/configMapRef/name + kind: DaemonSet + - path: spec/template/spec/volumes/projected/sources/configMap/name + kind: DaemonSet + - path: spec/template/spec/volumes/configMap/name + kind: StatefulSet + - path: spec/template/spec/containers/env/valueFrom/configMapKeyRef/name + kind: StatefulSet + - path: spec/template/spec/initContainers/env/valueFrom/configMapKeyRef/name + kind: StatefulSet + - path: spec/template/spec/containers/envFrom/configMapRef/name + kind: StatefulSet + - path: spec/template/spec/initContainers/envFrom/configMapRef/name + kind: StatefulSet + - path: spec/template/spec/volumes/projected/sources/configMap/name + kind: StatefulSet + - path: spec/template/spec/volumes/configMap/name + kind: Job + - path: spec/template/spec/containers/env/valueFrom/configMapKeyRef/name + kind: Job + - path: spec/template/spec/initContainers/env/valueFrom/configMapKeyRef/name + kind: Job + - path: spec/template/spec/containers/envFrom/configMapRef/name + kind: Job + - path: spec/template/spec/initContainers/envFrom/configMapRef/name + kind: Job + - path: spec/template/spec/volumes/projected/sources/configMap/name + kind: Job + - path: spec/jobTemplate/spec/template/spec/volumes/configMap/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/volumes/projected/sources/configMap/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/containers/env/valueFrom/configMapKeyRef/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/initContainers/env/valueFrom/configMapKeyRef/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/containers/envFrom/configMapRef/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/initContainers/envFrom/configMapRef/name + kind: CronJob + - path: spec/configSource/configMap + kind: Node + - path: rules/resourceNames + kind: Role + - path: rules/resourceNames + kind: ClusterRole + - path: metadata/annotations/nginx.ingress.kubernetes.io\/fastcgi-params-configmap + kind: Ingress + - kind: Secret version: v1 fieldSpecs: - - path: spec/volumes/secret/secretName - version: v1 - kind: Pod - - path: spec/containers/env/valueFrom/secretKeyRef/name - version: v1 - kind: Pod + - path: spec/volumes/secret/secretName + version: v1 + kind: Pod + - path: spec/containers/env/valueFrom/secretKeyRef/name + version: v1 + kind: Pod + - path: spec/initContainers/env/valueFrom/secretKeyRef/name + version: v1 + kind: Pod + - path: spec/containers/envFrom/secretRef/name + version: v1 + kind: Pod + - path: spec/initContainers/envFrom/secretRef/name + version: v1 + kind: Pod + - path: spec/imagePullSecrets/name + version: v1 + kind: Pod + - path: spec/volumes/projected/sources/secret/name + version: v1 + kind: Pod + - path: spec/template/spec/volumes/secret/secretName + kind: Deployment + - path: spec/template/spec/containers/env/valueFrom/secretKeyRef/name + kind: Deployment + - path: spec/template/spec/initContainers/env/valueFrom/secretKeyRef/name + kind: Deployment + - path: spec/template/spec/containers/envFrom/secretRef/name + kind: Deployment + - path: spec/template/spec/initContainers/envFrom/secretRef/name + kind: Deployment + - path: spec/template/spec/imagePullSecrets/name + kind: Deployment + - path: spec/template/spec/volumes/projected/sources/secret/name + kind: Deployment + - path: spec/template/spec/volumes/secret/secretName + kind: ReplicaSet + - path: spec/template/spec/containers/env/valueFrom/secretKeyRef/name + kind: ReplicaSet + - path: spec/template/spec/initContainers/env/valueFrom/secretKeyRef/name + kind: ReplicaSet + - path: spec/template/spec/containers/envFrom/secretRef/name + kind: ReplicaSet + - path: spec/template/spec/initContainers/envFrom/secretRef/name + kind: ReplicaSet + - path: spec/template/spec/imagePullSecrets/name + kind: ReplicaSet + - path: spec/template/spec/volumes/projected/sources/secret/name + kind: ReplicaSet + - path: spec/template/spec/volumes/secret/secretName + kind: DaemonSet + - path: spec/template/spec/containers/env/valueFrom/secretKeyRef/name + kind: DaemonSet + - path: spec/template/spec/initContainers/env/valueFrom/secretKeyRef/name + kind: DaemonSet + - path: spec/template/spec/containers/envFrom/secretRef/name + kind: DaemonSet + - path: spec/template/spec/initContainers/envFrom/secretRef/name + kind: DaemonSet + - path: spec/template/spec/imagePullSecrets/name + kind: DaemonSet + - path: spec/template/spec/volumes/projected/sources/secret/name + kind: DaemonSet + - path: spec/template/spec/volumes/secret/secretName + kind: StatefulSet + - path: spec/template/spec/containers/env/valueFrom/secretKeyRef/name + kind: StatefulSet + - path: spec/template/spec/initContainers/env/valueFrom/secretKeyRef/name + kind: StatefulSet + - path: spec/template/spec/containers/envFrom/secretRef/name + kind: StatefulSet + - path: spec/template/spec/initContainers/envFrom/secretRef/name + kind: StatefulSet + - path: spec/template/spec/imagePullSecrets/name + kind: StatefulSet + - path: spec/template/spec/volumes/projected/sources/secret/name + kind: StatefulSet + - path: spec/template/spec/volumes/secret/secretName + kind: Job + - path: spec/template/spec/containers/env/valueFrom/secretKeyRef/name + kind: Job + - path: spec/template/spec/initContainers/env/valueFrom/secretKeyRef/name + kind: Job + - path: spec/template/spec/containers/envFrom/secretRef/name + kind: Job + - path: spec/template/spec/initContainers/envFrom/secretRef/name + kind: Job + - path: spec/template/spec/imagePullSecrets/name + kind: Job + - path: spec/template/spec/volumes/projected/sources/secret/name + kind: Job + - path: spec/jobTemplate/spec/template/spec/volumes/secret/secretName + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/volumes/projected/sources/secret/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/containers/env/valueFrom/secretKeyRef/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/initContainers/env/valueFrom/secretKeyRef/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/containers/envFrom/secretRef/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/initContainers/envFrom/secretRef/name + kind: CronJob + - path: spec/jobTemplate/spec/template/spec/imagePullSecrets/name + kind: CronJob + - path: spec/tls/secretName + kind: Ingress + - path: metadata/annotations/ingress.kubernetes.io\/auth-secret + kind: Ingress + - path: metadata/annotations/nginx.ingress.kubernetes.io\/auth-secret + kind: Ingress + - path: metadata/annotations/nginx.ingress.kubernetes.io\/auth-tls-secret + kind: Ingress + - path: spec/tls/secretName + kind: Ingress + - path: imagePullSecrets/name + kind: ServiceAccount + - path: parameters/secretName + kind: StorageClass + - path: parameters/adminSecretName + kind: StorageClass + - path: parameters/userSecretName + kind: StorageClass + - path: parameters/secretRef + kind: StorageClass + - path: rules/resourceNames + kind: Role + - path: rules/resourceNames + kind: ClusterRole + - path: spec/template/spec/containers/env/valueFrom/secretKeyRef/name + kind: Service + group: serving.knative.dev + version: v1 + - path: spec/azureFile/secretName + kind: PersistentVolume + +- kind: Service + version: v1 + fieldSpecs: + - path: spec/serviceName + kind: StatefulSet + group: apps + - path: spec/rules/http/paths/backend/serviceName + kind: Ingress + - path: spec/backend/serviceName + kind: Ingress + - path: spec/rules/http/paths/backend/service/name + kind: Ingress + - path: spec/defaultBackend/service/name + kind: Ingress + - path: spec/service/name + kind: APIService + group: apiregistration.k8s.io + - path: webhooks/clientConfig/service + kind: ValidatingWebhookConfiguration + group: admissionregistration.k8s.io + - path: webhooks/clientConfig/service + kind: MutatingWebhookConfiguration + group: admissionregistration.k8s.io + +- kind: Role + group: rbac.authorization.k8s.io + fieldSpecs: + - path: roleRef/name + kind: RoleBinding + group: rbac.authorization.k8s.io + +- kind: ClusterRole + group: rbac.authorization.k8s.io + fieldSpecs: + - path: roleRef/name + kind: RoleBinding + group: rbac.authorization.k8s.io + - path: roleRef/name + kind: ClusterRoleBinding + group: rbac.authorization.k8s.io + +- kind: ServiceAccount + version: v1 + fieldSpecs: + - path: subjects + kind: RoleBinding + group: rbac.authorization.k8s.io + - path: subjects + kind: ClusterRoleBinding + group: rbac.authorization.k8s.io + - path: spec/serviceAccountName + kind: Pod + - path: spec/template/spec/serviceAccountName + kind: StatefulSet + - path: spec/template/spec/serviceAccountName + kind: Deployment + - path: spec/template/spec/serviceAccountName + kind: ReplicationController + - path: spec/jobTemplate/spec/template/spec/serviceAccountName + kind: CronJob + - path: spec/template/spec/serviceAccountName + kind: Job + - path: spec/template/spec/serviceAccountName + kind: DaemonSet + +- kind: PersistentVolumeClaim + version: v1 + fieldSpecs: + - path: spec/volumes/persistentVolumeClaim/claimName + kind: Pod + - path: spec/template/spec/volumes/persistentVolumeClaim/claimName + kind: StatefulSet + - path: spec/template/spec/volumes/persistentVolumeClaim/claimName + kind: Deployment + - path: spec/template/spec/volumes/persistentVolumeClaim/claimName + kind: ReplicationController + - path: spec/jobTemplate/spec/template/spec/volumes/persistentVolumeClaim/claimName + kind: CronJob + - path: spec/template/spec/volumes/persistentVolumeClaim/claimName + kind: Job + - path: spec/template/spec/volumes/persistentVolumeClaim/claimName + kind: DaemonSet + +- kind: PersistentVolume + version: v1 + fieldSpecs: + - path: spec/volumeName + kind: PersistentVolumeClaim + - path: rules/resourceNames + kind: ClusterRole + +- kind: StorageClass + version: v1 + group: storage.k8s.io + fieldSpecs: + - path: spec/storageClassName + kind: PersistentVolume + - path: spec/storageClassName + kind: PersistentVolumeClaim + - path: spec/volumeClaimTemplates/spec/storageClassName + kind: StatefulSet + +- kind: PriorityClass + version: v1 + group: scheduling.k8s.io + fieldSpecs: + - path: spec/priorityClassName + kind: Pod + - path: spec/template/spec/priorityClassName + kind: StatefulSet + - path: spec/template/spec/priorityClassName + kind: Deployment + - path: spec/template/spec/priorityClassName + kind: ReplicationController + - path: spec/jobTemplate/spec/template/spec/priorityClassName + kind: CronJob + - path: spec/template/spec/priorityClassName + kind: Job + - path: spec/template/spec/priorityClassName + kind: DaemonSet + +- kind: IngressClass + version: v1 + group: networking.k8s.io/v1 + fieldSpecs: + - path: spec/ingressClassName + kind: Ingress ``` ## Customizing transformer configurations