From 9fe3861938a1ec8fd7d0b0db4fb93e317f6bed71 Mon Sep 17 00:00:00 2001
From: Katrina Verey <katrina.verey@shopify.com>
Date: Thu, 23 Dec 2021 18:32:35 -0500
Subject: [PATCH] Update KEPS 2299 and 2953

---
 .../README.md                                 | 28 ++++---
 .../kep.yaml                                  |  2 +-
 .../README.md                                 | 75 +++++++++++++------
 .../2953-kustomize-plugin-graduation/kep.yaml |  2 +-
 4 files changed, 68 insertions(+), 39 deletions(-)

diff --git a/keps/sig-cli/2299-kustomize-plugin-composition/README.md b/keps/sig-cli/2299-kustomize-plugin-composition/README.md
index 802d27efe7ad..cb906fed7d04 100644
--- a/keps/sig-cli/2299-kustomize-plugin-composition/README.md
+++ b/keps/sig-cli/2299-kustomize-plugin-composition/README.md
@@ -158,7 +158,7 @@ transformers:
 # generate resources for a Java application
 - apiVersion: example.com/v1
   kind: JavaApplication
-  provider: {container: {image: docker.example.co/kustomize_transformers/java:v1.0.0}}
+  runtime: {container: {image: docker.example.co/kustomize_transformers/java:v1.0.0}}
   metadata:
     name: my-app
   spec:
@@ -167,7 +167,7 @@ transformers:
 # transform resources to inject a logger
 - apiVersion: example.com/v1
   kind: Logger
-  provider: {container: {image: docker.example.co/kustomize_transformers/logger:v1.0.3}}
+  runtime: {container: {image: docker.example.co/kustomize_transformers/logger:v1.0.3}}
   metadata:
     name: logger
 ```
@@ -199,7 +199,7 @@ transformers:
 # transform resources from imported transformers to inject metrics
 - apiVersion: example.com/v1
   kind: Prometheus
-  provider: {container: {image: docker.example.co/kustomize_transformers/prometheus:v1.0.2}}
+  runtime: {container: {image: docker.example.co/kustomize_transformers/prometheus:v1.0.2}}
   metadata:
     name: metrics
   spec:
@@ -230,7 +230,7 @@ graduation to beta does not require this. `Composition` support MUST be included
 #### Plugin execution flags
 
 This KEP does not propose any changes to the flags used to gate plugins, or to the parameters
-available to configure container/exec/starlark plugin execution. All plugin execution from either
+available to configure container/exec plugin execution. All plugin execution from either
 Kind will remain gated behind `--enable-alpha-plugins`, as well as existing additional flags for
 particular plugin provider types. Any changes to plugin gating should apply identically to both
 Kinds. This does limit the usefulness of `Composition` within `kubectl -k` for the time being, since
@@ -290,7 +290,7 @@ transformerOverrides:
 transformers:
 - apiVersion: example.com/v1
   kind: Prometheus
-  provider:
+  runtime:
     container:
       image: example/prometheus:v1.0.2
   metadata:
@@ -308,8 +308,7 @@ Notes:
 - One notable difference from `Kustomization` is that in addition to being able to provide a path to
   a file containing the transformer config, you can specify the config itself (not strigified)
   inline.
-- A second difference is the introduction of a top-level reserved `provider` field, replacing the
-  JSON annotation currently used for this information.
+- The examples here use a new a top-level reserved `runtime` field instead of the JSON annotation currently used for this information. This field may be introduced as part of KEP 2953. It does not block this KEP, and usage within Kustomization and Composition will be identical regardless.
 - The `metadata.name` field is defaulted to `Kind` in kebab case. However, `metadata.name` MUST be
 specified when using multiple independent instances of the same GVK within a `Composition` tree.
 
@@ -343,7 +342,7 @@ definitions:
             minLength: 1
             maxLength: 253
             pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$"
-      provider:
+      runtime:
         type: object
         additionalProperties: false
         properties:
@@ -356,7 +355,7 @@ definitions:
               image:
                 type: string
                 minLength: 1
-          starlark:
+          exec:
             type: object
             required:
             - path
@@ -491,18 +490,16 @@ Testing can be done purely on the client-side without the need for a cluster.
 
 #### Alpha
 
-- `Composition` implemented with an alpha GV and supported by `kustomize build`
-  - Compatibility with existing built-in transformers
-  - `ResourceAccumulator` extracted as a transformer
-  - `transformer`, `transformersFrom` and `transformerOverrides` fields implemented.
-  - reserved `provider` field
+- `Composition` implemented with an alpha GV and supported by `kustomize build`. This includes implementing the `transformer`, `transformersFrom`, `transformerOverrides` and `transformerOrder` fields.
+- `ResourceGenerator` extracted as a transformer
+- Introduce a way to use default `fieldSpecs` when invoking builtin transformers from the transformers field (and generators from the generators field, etc.).
+- Built-in generators updated to work in transformers fields
 - Basic documentation added to the Kustomize website.
 
 #### Beta
 
 - `Composition` beta GV supported by `kustomize build`
   - `Kustomization` transformer implemented
-  - `transformerOrder` field implemented
 - `Composition` supported by the `resources`, `transformers`, `generators` and `validators` fields
   in `Kustomization` and `Component`
 - Thorough documentation and examples published on the Kustomize website.
@@ -657,6 +654,7 @@ N/A -- feature is client-side-only
 
 - April 27, 2021: Provisional KEP merged
 - August 2021: Proposal updated and marked implementable.
+- December 2021: Prototype PR opened at [kustomize/#4323](https://github.com/kubernetes-sigs/kustomize/pull/4323) and KEP updated to reflect additional work discovered.
 
 <!--
 Major milestones in the lifecycle of a KEP should be tracked in this section. Major milestones might
diff --git a/keps/sig-cli/2299-kustomize-plugin-composition/kep.yaml b/keps/sig-cli/2299-kustomize-plugin-composition/kep.yaml
index 45cbfcd285ce..024db1efcf77 100644
--- a/keps/sig-cli/2299-kustomize-plugin-composition/kep.yaml
+++ b/keps/sig-cli/2299-kustomize-plugin-composition/kep.yaml
@@ -17,4 +17,4 @@ approvers:
 see-also:
 - "/keps/sig-cli/993-kustomize-generators-transformers"
 stage: alpha
-latest-milestone: "v1.23"
+latest-milestone: "v1.24"
diff --git a/keps/sig-cli/2953-kustomize-plugin-graduation/README.md b/keps/sig-cli/2953-kustomize-plugin-graduation/README.md
index 3bc749b45088..b7052916b3f1 100644
--- a/keps/sig-cli/2953-kustomize-plugin-graduation/README.md
+++ b/keps/sig-cli/2953-kustomize-plugin-graduation/README.md
@@ -177,10 +177,12 @@ This KEP proposes converging Kustomize's various alpha extension mechanisms into
 
 *KRM*: [Kubernetes Resource Model](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md)
 
-*Plugin*: User-authored generator, transformer or validator (refers to both the "provider" program that implements it and the "config" YAML required to use it).
+*Plugin*: User-authored generator, transformer or validator (refers to both the program that implements it and the "config" YAML required to use it).
 
 *Plugin provider*: The program that implements the plugin (e.g. container, script, Go program). Analogous to the controller for a custom resource.
 
+*Plugin runtime*: The substrate upon which the plugin provider must be executed. Supported runtimes include container and exec.
+
 *Plugin config*: The KRM-style YAML document that declares the desired state the plugin implements. In some plugin styles, it must also specify the plugin provider to execute and the specification to follow in doing so. Analogous to a custom resource object.
 
 ## Motivation
@@ -261,7 +263,7 @@ This KEP proposes using the concept of a "trusted plugin catalog" from the [Cata
 
 **Plugins from a user-specified trusted catalog**
 
-When using plugins with a trusted catalog, only one flag will be required, regardless of the runtime type of the provider: `--trusted-plugin-catalog=""` .
+When using plugins with a trusted catalog, only one flag will be required, regardless of the runtime type of the provider: `--trusted-catalog=""` .
 
 This new repeatable flag will be introduced by the [Catalog KEP]. When that flag is present, plugins in the referenced catalogs will be executed without the need for any additional flags. The integrity of the plugin provider will be validated against the Catalog entry before execution. This all applies whether the providers are defined explicitly in the Kustomization (and the explicit entry matches the catalog) or looked up dynamically in the catalog.
 
@@ -273,25 +275,23 @@ Optionally, it should be possible for a user to compile a bespoke distribution o
 
 **Plugins NOT in a trusted catalog**
 
-*Recommended Option: no such thing*
+*There's no such thing*
 
-Trusted catalogs are always required to use plugins; uncatalogued plugins will not be executed. Kustomizations that require ad-hoc plugins must be accompanied by a `Catalog` that the end user can reference locally, e.g. `kustomize build dir/ --trusted-plugin-catalog=dir/catalog.yaml`. There will be no additional plugin-related flags. The end user will be expected to inspect this catalog before trusting it, which must always be done explicitly on the command line.
+Trusted catalogs are always required to use plugins; uncatalogued plugins will not be executed. Kustomizations that require ad-hoc plugins must be accompanied by a `Catalog` that the end user can reference locally, e.g. `kustomize build dir/ --trusted-catalog=dir/catalog.yaml`. There will be no additional plugin-related flags. The end user will be expected to inspect this catalog before trusting it, which must always be done explicitly on the command line.
 
 A `kustomize edit generate-catalog` command will be implemented to streamline local plugin workflows. That command will take a Kustomization, collect all the uncatalogued plugins into a list, and build that list into the catalog resource format, using local references relative to the root Kustomization (plugins outside the root will result in an error). Optionally, this command can extract the provider references from the Kustomization, since they are most likely redundant once the catalog has been constructed. Optionally, this command can localize all required entries from referenced remote catalogs into the generated catalog.
 
 While this does introduce some friction, it is far less than is required to install and use plugins today. It also has the advantage of making the plugins required highly reviewable in a gitops workflow, and of not requiring the large suite of CLI flags needed for plugin execution today.
 
-*Alternative: many flags*
-
-By default, plugins not listed in a trusted catalog will not be executed and an error will be printed. The providers for these plugins must be listed explicitly in each plugin config, and additional flags are always required to use them. Which flags are required depends on the provider type.
-
-For plugins distributed as containers, the `--enable-container-plugins` flag will need to be provided. The containers will continue to be denied disk and network access by default. To enable access, the existing network/mount restriction flags will be retained but renamed to clarify what they govern:  `--plugin-container-networks=[STRING]` `--plugin-container-mounts=[STRING]`.
-
-For plugins distributed as executables (typically committed in git along with the Kustomization), every provider the Kustomization needs must be explicitly named in a new flag:  `--trust-embedded-exec-plugins=base/plugin/transformer.sh,overlay/scripts/gen.sh`. By using this flag, the user demonstrates they are aware of what will be executed and accept the risk of running each one. To make the list less painful to construct, the error message thrown when this list is not provided or is incomplete will inform the user of which are missing.
+To mitigate the inconvenience to users who tend to work with a specific set of catalogs across many Kustomizations, we will introduce a Kustomize user preferences file in which a list of catalogs to be trusted by default can be stored. This list of trusted catalogs should support wildcard specification of catalog sources, e.g. `github.com/my-co/krm-functions/catalogs/*` to trust all catalogs published in or below that location. The contents of the preferences file will itself be properly typed KRM object, extensible to other use cases.
 
-**Additional constraints for exec providers**
+**Additional constraints for local exec providers**
 
-The location of exec providers that are local will be subject Kustomize's load restrictor, i.e. the LoadRestrictionsRootOnly policy will apply to them by default (it does not today). If this is deemed insufficient, we could take it a step further and force the LoadRestrictionsRootOnly policy even when a different loader policy is provided by flag.
+The location of exec providers that are local will be constrained as follows:
+- We will stop using `exec.LookPath` to find plugins. Local plugin locations will always need to be explicit, to guarantee that what Catalog is allowing and what Kustomize invokes are indeed the same thing.
+- Relative paths will be subject Kustomize's load restrictor, i.e. the LoadRestrictionsRootOnly policy will apply to them by default (it does not today).
+- Absolute paths will be permitted, and will be subjected to a new load restriction rule that requires them to be within a specific root, such as `$XGD_CONFIG_HOME/kustomize/plugins`. This is needed to support airgap use cases, as discussed in https://github.com/kubernetes-sigs/kustomize/issues/4288.
+  + This also provides a migration path for legacy exec plugins, which already exist in such a location. Kustomize should be able to derive Catalogs for them automatically in cases where they are already configured declaratively (i.e. do not require bespoke args).
 
 ### Supported runtimes
 
@@ -311,7 +311,7 @@ A plugin developer guide will be added to the Kustomize documentation, replacing
 
 All plugins must be configured using KRM-style custom-resource-like objects.
 
-The `config.kubernetes.io/function` annotation that currently contains a nested JSON blob of plugin provider configuration will be graduated to a reserved top-level field called `provider` (ALTERNATIVE: it could be nested as `metadata.provider`, but that would make the object meta non-standard). That field will be made optional by the [Catalog KEP].
+The `config.kubernetes.io/function` contains a nested JSON blob of plugin provider configuration. It field will be made optional by the [Catalog KEP]. If we find that users still need to author it frequently in practice, we should consider graduating it to a top-level `runtime` field. If we do, orchestrators will need to strip it from plugin configuration objects when they are read, since it is not a valid part of the plugin's own schema. Alternatively, plugin authors could be expected to include it in their schemas, as with object and type metadata.
 
 The `metadata.name` field is optional as long as the config's GVK uniquely identifies it. In Kustomization, it is not required unless the config is being handled as a resource. In Composition, it is always recommended, because transformer config is always handled as a resource before execution and uniqueness must be global across all Compositions in the tree. 
 
@@ -321,7 +321,7 @@ The `env` field for container plugins will be deprecated. In line with Kustomize
 
 Although legacy plugins are still in alpha, the alpha has been around in standalone Kustomize for quite a while. Documentation on the migration process will be provided. See the [Rollout Plan](#rollout-plan) section for more detail on deprecation and removal of the existing alphas.
 
-The exec plugin conversion process should be relatively straightforward: copy the provider in-tree and update the configuration that referred to it to have a Provider stanza pointing to the new location. `argsFromFile` and `argsOneLiner` can be straightforwardly converted to the `args` subfield the KRM Functions style already supports.
+The exec plugin conversion process should be relatively straightforward: copy the provider in-tree and update the configuration that referred to it to have a Provider stanza pointing to the new location. Plugins using `argsFromFile` and `argsOneLiner` will need to be modified to accept the data in question declaratively instead of as args.
 
 For authors who build plugins for distribution (as opposed to bespoke plugins where embedding within an end-user Kustomization is an appropriate solution), the recommendation will be to upgrade to the Catalog model. A Catalog guide will be added to the Kustomize website and will address the scenario of migrating a legacy style plugin.
 
@@ -336,7 +336,7 @@ As an end user, I want to develop a simple plugin for my particular Kustomizatio
 1. Write a script that adheres to the [KRM Functions Specification] and place it within the Kustomization root.
 2. Write a corresponding plugin config and reference it from the Kustomization's generator or transformer field as appropriate.
 3. Run `kustomize edit generate-catalog`
-3. Run `kustomize build --trusted-plugin-catalog=catalog.yaml`
+3. Run `kustomize build --trusted-catalog=catalog.yaml`
 
 ```bash
 # Possible directory structure
@@ -380,7 +380,7 @@ kind: Catalog
 metadata:
   name: "local-plugins"
 spec:
-  modules:
+  functions:
   - apiVersion: local-config.example.co/v1
     kind: CustomSorter
     provider:
@@ -395,7 +395,7 @@ spec:
 As an end user, I want to use one or more plugins published by a third party I trust.
 
 1. Write the config objects for the plugins you want to use, and reference them from your Kustomization's generators or transformers field as appropriate.
-2. Run `kustomize build --trusted-plugin-catalog=https://catalog.kpt.dev/1.2.3.json`
+2. Run `kustomize build --trusted-catalog=https://catalog.kpt.dev/1.2.3.json`
 
 
 ```bash
@@ -461,7 +461,7 @@ As a platform developer for a large organization, I want to provide internal use
 ```yaml
 # Example end-user Composition
 kind: Composition
-modules:
+transformers:
 - apiVersion: kustomize.example.co/v1
   kind: JavaApplication
   metadata:
@@ -476,6 +476,23 @@ modules:
 ```
 
 
+#### Story 4
+
+As a Kustomize user who regularly works with a consistent set of plugins, I can trust certain plugin catalogs by default in my Kustomize preferences file.
+
+1. Run `kustomize config trust [catalog]`
+2. Run `kustomize build` on Kustomizations that require plugins from my default trusted catalogs, without needing the `--trusted-catalog` flag.
+
+```yaml
+# Example $XDG_CONFIG_HOME/kustomize/config.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: KustomizeConfig
+trustedCatalogs:
+- github.com/my-co/krm-functions/catalogs/*
+- https://krm-functions.io/catalogs/kustomize/v20210924.yaml
+- ~/kustomize/my-own-plugins.yaml
+```
+
 
 ### Notes/Constraints/Caveats (Optional)
 
@@ -493,10 +510,11 @@ Individual Kustomizations/Compositions can contain catalog references. These ref
 
 ## Design Details
 
-Example execution flow for `kustomize build --trusted-plugin-catalog=company.com/foo.json`:
+Example execution flow for `kustomize build --trusted-catalog=company.com/foo.json`:
 
 1. Kustomize retrieves all trusted catalogs specified on the command line.
-1. Kustomization is read. If it includes a `catalogs` field, that field is compared to the trusted catalogs from the command line. If any required catalogs have not been trusted, a warning is printed with the details of the missing catalog (which remains untrusted).
+1. Kustomize reads the user's Kustomize preferences file and loads the list of default trusted catalogs, combining this with the list from the command line.
+1. Kustomization is read. If it includes a `catalogs` field, that field is compared to the trusted catalogs. If any required catalogs have not been trusted, a warning is printed with the details of the missing catalog (which remains untrusted).
 1. When preparing to execute a plugin, Kustomize looks for a corresponding entry in the trusted catalogs. If none is found, an error is thrown an execution halts. If one is found, the plugin provider configuration (e.g. network, storage) listed in the plugin config (if any) is compared to the requirements declared in the catalog entry. If they are not a strict subset, an error is thrown and execution halts.
 1. Having successfully identified the catalog entry for the given plugin, Kustomize attempts to retrieve the plugin provider from the specified location.
 1. Having successfully retrieved the plugin provider, Kustomize hashes it and compares the result to the catalog entry. If it is not an exact match, an error is thrown and execution halts.
@@ -526,12 +544,14 @@ Kustomize already has a test harness capable of running plugins, but coverage of
 
 - Beta GVs for Composition and Catalog introduced
 - `kustomize edit fix` supports migrating legacy exec to non-KRM exec plugins
-- "alpha" removed from `--trusted-plugin-catalog` flag name
+- "alpha" removed from `--trusted-catalog` flag name
+- Kustomize user preferences file created with support for default sets of trusted catalogs.
 - Deprecated plugin-related flags removed.
 - Starlark, legacy exec and Go plugin support removed.
 - Plugin provider identity verification implemented.
 - New plugin developer guide published. Exec provider documentation enhanced.
 - `kubectl kustomize` released with beta Catalog support, beta Composition support, identical build flags to standalone kustomize, and full beta plugins support (including KRM exec support)
+- Function annotation graduated to reserved `runtime` field, if deemed necessary.
 
 #### GA
 
@@ -745,6 +765,17 @@ It makes it easier for Kustomize users to invoke third party code, which can be
 * Graduate "KRM Function style" plugins as described (including removing starlark and further restricting exec), but do not introduce Catalog or Composition.
   * This would be a less usable and useful plugin system than the one proposed, but better than nothing. Catalog and Composition are encapsulated enough that plugin GA can proceed without them if they fail or lose contributor bandwidth before completion. Changes to the flag strategy would be required.
 
+
+_Alternative for the handling of plugins that are not included in a Catalog:_
+
+Instead of disallowing uncatalogued plugins, we could introduce a series of flags to govern them specifically. This is not recommended because it complicates the overall mental model of how plugins work, and because the flags themselves would likely be unwieldy to use. That said, this is how such an alternative could work.
+
+By default, plugins not listed in a trusted catalog will not be executed and an error will be printed. The providers for these plugins must be listed explicitly in each plugin config, and additional flags are always required to use them. Which flags are required depends on the provider type.
+
+For plugins distributed as containers, the `--enable-container-plugins` flag will need to be provided. The containers will continue to be denied disk and network access by default. To enable access, the existing network/mount restriction flags will be retained but renamed to clarify what they govern:  `--plugin-container-networks=[STRING]` `--plugin-container-mounts=[STRING]`.
+
+For plugins distributed as executables (typically committed in git along with the Kustomization), every provider the Kustomization needs must be explicitly named in a new flag:  `--trust-embedded-exec-plugins=base/plugin/transformer.sh,overlay/scripts/gen.sh`. By using this flag, the user demonstrates they are aware of what will be executed and accept the risk of running each one. To make the list less painful to construct, the error message thrown when this list is not provided or is incomplete will inform the user of which are missing.
+
 ## Infrastructure Needed (Optional)
 
 None. This will be implemented within the existing Kustomize repo.
diff --git a/keps/sig-cli/2953-kustomize-plugin-graduation/kep.yaml b/keps/sig-cli/2953-kustomize-plugin-graduation/kep.yaml
index 00beac32fcfc..56f3b43c7c8d 100644
--- a/keps/sig-cli/2953-kustomize-plugin-graduation/kep.yaml
+++ b/keps/sig-cli/2953-kustomize-plugin-graduation/kep.yaml
@@ -35,7 +35,7 @@ stage: alpha
 # The most recent milestone for which work toward delivery of this KEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
 # worked on.
-latest-milestone: "v1.23"
+latest-milestone: "v1.24"
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone: