KEP 2299: Kustomize Plugin Composition API (#2300)

* KEP for Kustomize Plugin Composition

* Incorporate feedback

* Add comparison of Kustomization and Composition with transformer config transformations

* Update ToC

keps/sig-cli/2299-kustomize-plugin-composition/example/composition/base/composition.yaml

@@ -0,0 +1,62 @@
+apiVersion: kustomize.config.k8s.io/v1alpha1
+kind: Composition
+
+modules:
+- apiVersion: kustomize.config.k8s.io/v1alpha1
+  kind: StaticResources
+  metadata:
+    name: local-resources
+  spec:
+    paths:
+    - resources
+- apiVersion: team.example.com/v1alpha1
+  kind: WebServer
+  metadata:
+    name: web-server
+  provider:
+    container:
+      image: docker.example.com/kustomize-modules/web-server:v0.1.0
+  spec:
+    appName: nginx-example
+    image: nginx:1.18
+    replicas: 2
+    expose:
+      http: yes
+- apiVersion: team.example.com/v1alpha1
+  kind: Logger
+  metadata:
+    name: logging
+  provider:
+    container:
+      image: docker.example.com/kustomize-modules/logger:v0.1.0
+  spec:
+    selector:
+      matchLabels:
+        app: nginx-example
+    source:
+      paths:
+        - /var/log/nginx/error.log
+        - /var/log/nginx/access.log
+- apiVersion: team.example.com/v1alpha1
+  kind: HTTPLoadBalancer
+  metadata:
+    name: lb
+  provider:
+    container:
+      image: docker.example.com/kustomize-modules/lb:v0.1.1
+  spec:
+    selector:
+      matchLabels:
+        app: nginx-example
+    loadBalancer:
+      domain: nginx-example.myco-dev.io
+    expose:
+      serviceName: nginx
+      port: 80
+- apiVersion: kustomize.config.k8s.io/v1alpha1
+  kind: Kustomize
+  metadata:
+    name: my-kustomize
+  spec:
+    commonLabels:
+      foo: bar

keps/sig-cli/2299-kustomize-plugin-composition/example/composition/base/resources/configmap.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: game-demo
+data:
+  player_initial_lives: "3"

keps/sig-cli/2299-kustomize-plugin-composition/example/composition/composition.yaml

@@ -0,0 +1,24 @@
+apiVersion: kustomize.config.k8s.io/v1alpha1
+kind: Composition
+
+modulesFrom:
+- path: base/composition.yaml
+
+moduleOverrides:
+- apiVersion: team.example.com/v1alpha1
+  kind: HTTPLoadBalancer
+  metadata:
+    name: lb
+  spec:
+    loadBalancer:
+      domain: foo.app.example.com
+
+modules:
+- apiVersion: kustomize.config.k8s.io/v1alpha1
+  kind: Kustomize
+  metadata:
+    name: productionizer
+  spec:
+    commonLabels:
+      env: production
+    namespace: nginx-example-prod

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/kustomization.yaml

@@ -0,0 +1,12 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- prod-integration-base
+
+# This layer is needed because the plugins are transformers, and the transformers field is executed after the built-in like the label transformer. So most of the resources wouldn't be labelled if we included this in prod-integration-base instead.
+commonLabels:
+  env: production
+  foo: bar # Ideally this label would be at a lower layer, but that won't work.
+
+namespace: nginx-example-prod

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/prod-integration-base/builtins-base/kustomization.yaml

@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - resources/configmap.yaml

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/prod-integration-base/builtins-base/resources/configmap.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: game-demo
+data:
+  player_initial_lives: "3"

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/prod-integration-base/kustomization.yaml

@@ -0,0 +1,9 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- builtins-base
+
+# This layer changes the transformer configs from being treated as resources to being executed. Transformer config must be fully resolved by this point. It is not possible to create a true "base" Kustomization that incorporates resources/built-ins with generic transformer configs. Instead, transformer config must be finalized (e.g. with production values) below this layer, and built-ins (e.g. label transformer config) must be specified above it (to apply to the results of the transformers).
+transformers:
+- prod-plugin-transformation

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/prod-integration-base/prod-plugin-transformation/kustomization.yaml

@@ -0,0 +1,16 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - plugins-base
+
+patchesStrategicMerge:
+  - |-
+    apiVersion: team.example.com/v1alpha1
+    kind: HTTPLoadBalancer
+    metadata:
+      name: lb
+    spec:
+      loadBalancer:
+        domain: foo.app.example.com
+

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/prod-integration-base/prod-plugin-transformation/plugins-base/kustomization.yaml

@@ -0,0 +1,9 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+# The ordering here becomes super important once they're transformers, and in practice it is preserved. But it's not obvious at the point where they become transformers.
+# It isn't possible to mix base resources that should remain resources with ones that need to become transformers. This makes sense in the Kustomization paradigm, but forces splitting apart the pieces of a given logical layer.
+resources:
+- web-server.yaml
+- logger.yaml
+- lb.yaml

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/prod-integration-base/prod-plugin-transformation/plugins-base/lb.yaml

@@ -0,0 +1,15 @@
+apiVersion: team.example.com/v1alpha1
+kind: HTTPLoadBalancer
+metadata:
+  name: lb
+  annotations:
+    config.kubernetes.io/function: |
+      container:
+        image: docker.example.com/kustomize-modules/lb:v0.1.1
+spec:
+  selector:
+    matchLabels:
+      app: nginx-example
+  expose:
+    serviceName: nginx
+    port: 80

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/prod-integration-base/prod-plugin-transformation/plugins-base/logger.yaml

@@ -0,0 +1,16 @@
+  apiVersion: team.example.com/v1alpha1
+  kind: Logger
+  metadata:
+    name: logging
+    annotations:
+      config.kubernetes.io/function: |
+        container:
+          image: docker.example.com/kustomize-modules/logger:v0.1.0
+  spec:
+    selector:
+      matchLabels:
+        app: nginx-example
+    source:
+      paths:
+        - /var/log/nginx/error.log
+        - /var/log/nginx/access.log

keps/sig-cli/2299-kustomize-plugin-composition/example/kustomization/prod-integration-base/prod-plugin-transformation/plugins-base/web-server.yaml

@@ -0,0 +1,14 @@
+apiVersion: team.example.com/v1alpha1
+kind: WebServer
+metadata:
+  name: web-server
+  annotations:
+    config.kubernetes.io/function: |
+      container:
+        image: docker.example.com/kustomize-modules/web-server:v0.1.0
+spec:
+  appName: nginx-example
+  image: nginx:1.18
+  replicas: 2
+  expose:
+    http: yes

keps/sig-cli/2299-kustomize-plugin-composition/kep.yaml

@@ -0,0 +1,18 @@
+title: Kustomize Plugin Composition API
+kep-number: 2299
+authors:
+  - "@knverey"
+  - "@campoy"
+owning-sig: sig-cli
+participating-sigs:
+  - sig-cli
+status: provisional
+creation-date: 2021-01-20
+reviewers:
+  - "@monopole"
+  - "@pwittrock"
+approvers:
+  - "@monopole"
+  - "@pwittrock"
+stage: alpha
+latest-milestone: "v1.22"