diff --git a/keps/sig-cli/0008-kustomize.md b/keps/sig-cli/0008-kustomize.md index cb47f8d79a74..d0825e092fef 100644 --- a/keps/sig-cli/0008-kustomize.md +++ b/keps/sig-cli/0008-kustomize.md @@ -13,14 +13,14 @@ approvers: - "@soltysh" editor: "@droot" creation-date: 2018-05-05 -last-updated: 2018-05-23 +last-updated: 2019-01-09 status: implemented see-also: - n/a replaces: - kinflate # Old name for kustomize superseded-by: - - n/a + - "kustomize-subbcommand-integration.md" --- # Kustomize diff --git a/keps/sig-cli/0031-kustomize-integration.md b/keps/sig-cli/0031-kustomize-integration.md deleted file mode 100644 index 204847d653e5..000000000000 --- a/keps/sig-cli/0031-kustomize-integration.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -kep-number: 31 -title: Enable kustomize in kubectl -authors: - - "@Liujingfang1" -owning-sig: sig-cli -participating-sigs: - - sig-cli -reviewers: - - "@pwittrock" - - "@seans3" - - "@soltysh" -approvers: - - "@pwittrock" - - "@seans3" - - "@soltysh" -editor: TBD -creation-date: 2018-11-07 -last-updated: 2019-01-07 -status: implementable -see-also: - - "[KEP-0008](https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md)" -replaces: - - n/a -superseded-by: - - n/a ---- - -# Enable kustomize in kubectl - -## Table of Contents -* [Table of Contents](#table-of-contents) -* [Summary](#summary) -* [Motivation](#motivation) - * [Goals](#goals) - * [Non-Goals](#non-goals) -* [Kustomize Introduction](#kustomize-introduction) -* [Proposal](#proposal) - * [UX](#UX) - * [apply](#apply) - * [get](#get) - * [delete](#delete) - * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints) - * [Risks and Mitigations](#risks-and-mitigations) -* [Graduation Criteria](#graduation-criteria) -* [Implementation History](#implementation-history) -* [Alternatives](#alternatives) - -[Tools for generating]: https://github.com/ekalinin/github-markdown-toc - -## Summary -[Kustomize](https://github.com/kubernetes-sigs/kustomize) was developed as a distinct tool from kubectl to rapidly experiment on declarative configuration. The code was developed to solve some long standing, complex kubectl [issues](https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/0008-kustomize.md#long-standing-issues). The final step is to close the issues by bringing the code into kubectl. This KEP describes how to do this with consistent kubectl UX. - -## Motivation - -Declarative specification of Kubernetes objects is the recommended way to manage Kubernetes applications or workloads. There is some gap in kubectl on declarative support. To eliminate the gap, a [KEP](https://github.com/kubernetes/community/blob/master/keps/sig-cli/0008-kustomize.md#faq) was proposed months ago and Kustomize was developed. After more than 10 iterations, Kustomize has a complete set of features and reached a good state to be integrated into kubectl. - -### Goals - -Integrate kustomize with kubectl so that kubectl can recognize kustomization directories and expand resources from kustomization.yaml before running kubectl subcommands. This integration should be transparent. It doesn't change kubectl UX. This integration should also be backward compatible. For non kustomization directories, kubectl behaves the same as current. The integration shouldn't have any impact on those parts. - - -### Non-Goals -- provide an editing functionality of kustomization.yaml from kubectl -- further integration with other kubectl flags - -## Kustomize Introduction - -Kustomize has following subcommands: -- build -- edit, edit also has subcommands - - Set - - imagetag - - namespace - - nameprefix - - Add - - base - - resource - - patch - - label - - annotation - - configmap -- config -- version -- help - -`edit` and `build` are most commonly used subcommands. - -`edit` is to modify the fields in `kustomization.yaml`. A `kustomization.yaml` includes configurations that are consumed by Kustomize. Here is an example of `kustomization.yaml` file. - -`build` is to perform a set of pre-processing transformations on the resources inside one kustomization. Those transformations include: -- Get objects from the base -- Apply patches -- Add name prefix to all resources -- Add common label and annotation to all resources -- Replace imageTag is specified -- Update objects’ names where they are referenced -- Resolve variables and substitute them - -``` -apiVersion: v1beta1 -kind: Kustomization -namePrefix: alices- - -commonAnnotations: - oncallPager: 800-555-1212 - -configMapGenerator: -- name: myJavaServerEnvVars - literals: - - JAVA_HOME=/opt/java/jdk - - JAVA_TOOL_OPTIONS=-agentlib:hprof - -secretGenerator: -- name: app-sec - commands: - username: "echo admin" - password: "echo secret" -``` -The build output of this sample kustomizaiton.yaml file is -``` -apiVersion: v1 -data: - JAVA_HOME: /opt/java/jdk - JAVA_TOOL_OPTIONS: -agentlib:hprof -kind: ConfigMap -metadata: - annotations: - oncallPager: 800-555-1212 - name: alices-myJavaServerEnvVars-7bc9c27cmf ---- -apiVersion: v1 -data: - password: c2VjcmV0Cg== - username: YWRtaW4K -kind: Secret -metadata: - annotations: - oncallPager: 800-555-1212 - name: alices-app-sec-c7c5tbh526 -type: Opaque -``` - -## Proposal - -### UX - -When apply, get or delete is run on a directory, check if it contains a kustomization.yaml file. If there is, apply, get or delete the output of kustomize build. Kubectl behaves the same as current for directories without kustomization.yaml. - -#### apply -The command visible to users is -``` -kubectl apply -f -``` -To view the objects in a kustomization without applying them to the cluster -``` -kubectl apply -f --dry-run -o yaml|json -``` - -#### get -The command visible to users is -``` -kubectl get -f -``` -To get the detailed objects in a kustomization -``` -kubectl get -f --dry-run -o yaml|json -``` - -#### delete -The command visible to users is -``` -kubectl delete -f -``` - -### Implementation Details/Notes/Constraints - -To enable kustomize in kubectl, the function `FilenameParam` inside Builder type will be updated to recognize kustomization directories. The Builder will expand the sources in a kustomization directory and pass them to a subcommand. - - Since kustomization directories themselves have a recursive structure, `-R` will be ignored on those directories. Allowing recursive visit to the same files will lead to duplicate resources. - -The examples and descriptions for apply, get and delete will be updated to include the support of kustomization directories. - -### Risks and Mitigations - -This KEP doesn't provide a editing command for kustomization.yaml file. Users will either manually edit this file or use `Kusotmize edit`. - -## Graduation Criteria - -There are two signals that can indicate the success of this integration. -- Kustomize users drop the piped commands `kustomize build | kubectl apply -f - ` and start to use apply directly. -- Kubectl users put their configuration files in kustomization directories. - - -## Implementation History - -Most implementation will be in cli-runtime - -- [x] vendor `kustomize/pkg` into kubernetes -- [x] copy `kustomize/k8sdeps` into cli-runtime -- [x] Implement a Visitor for kustomization directory which - - execute kustomize build to get a list of resources - - write the output to a StreamVisitor -- [x] When parsing filename parameters in FilenameParam, look for kustomization directories -- [ ] documentation: - - update the examples in kubectl commands - - Improve help messages or documentations to list kubectl subcommands that can work with kustomization directories - -## Alternatives - -The approaches in this section are considered, but rejected. -### Copy kustomize into staging -Copy kustomize code into kubernetes/staging and have the staging kustomize as source of truth. The public kustomize repo will be synced automatically with the staging kustomize. -- Pros - - Issues can be managed in the public repo - - The public repo can provide a kustomize binary - - The public repo can be used as kustomize libraries - - Empower further integration of kubectl with kustomize -- Cons - - The staging repo is designed for libraries that will be separated out. Moving kustomize into staging sounds controversial - - Kustomize will be in staging, the development will be done in k/k repository - - Development velocity will be reduced of every release - -### Add kustomize as a subcommand in kubectl -Add kustomize as a subcommand into kubectl was the first way we tried to enable kustomize in kubectl. The PR was [add kustomize as a subcommand of kubectl](https://github.com/kubernetes/kubernetes/pull/70213). -- Pros - - kustomize command is visible to users - - the code change is straightforward - - easy to test -- Cons - - UX is not consistent with other kubectl subcommands - - Apply command will include two parts - `kubectl kustomize build dir | kubectl apply -f -` diff --git a/keps/sig-cli/kep-faq.md b/keps/sig-cli/kep-faq.md new file mode 100644 index 000000000000..fc29bf4cfeb6 --- /dev/null +++ b/keps/sig-cli/kep-faq.md @@ -0,0 +1,23 @@ +# SIG CLI KEP FAQ + +## Why not as a kubectl plugin instead of compiled in? + +- The kubectl plugin mechanism does not provide a solution for distribution. Because the functionality is intended as + the project's solution to issues within kubectl, we want it to be available to users of kubectl without additional + steps. Having users manually download only Kustomize as a plugin might be ok, but it won't scale as a good approach + as the set of commands grows. +- The effort to build and test the tool for all targets, develop a release process, etc. would be much higher for SIG + CLI, also, and it would exacerbate kubectl's version-skew challenges. +- It will not support integration at more than a surface level - such as into the resource builder + (which does not offer a plugin mechanism). + - It was previously decided we didn't want to add a plugin mechanism to the resource builder. + This could be reconsidered, but would need to think through it more and figure out how to address + previously brought up issues. There may be other issues not listed here as well. + - https://github.com/kubernetes/kubernetes/issues/13241 + - https://github.com/kubernetes/kubernetes/pull/14993 + - https://github.com/kubernetes/kubernetes/pull/14918 +- There is a risk that publishing each command as a separately built binary could cause the aggregate download + size of the toolset to balloon. The kubectl binary is *52M* and the kustomize binary is *31M*. (extrapolate to + 30+ commands x 30MB). Before going down this route, we should consider how to we might want to design a solution + and the tradeoffs. + diff --git a/keps/sig-cli/kustomize-file-processing-integration.md b/keps/sig-cli/kustomize-file-processing-integration.md new file mode 100644 index 000000000000..0f8c6987f25a --- /dev/null +++ b/keps/sig-cli/kustomize-file-processing-integration.md @@ -0,0 +1,110 @@ +--- +title: Kustomize File Processing Integration +authors: + - "@pwittrock" +owning-sig: sig-cli +participating-sigs: + - sig-cli +reviewers: + - "@liggitt" + - "@seans3" + - "@soltysh" + - "@monopole" +approvers: + - "@liggitt" + - "@seans3" + - "@soltysh" + - "@monopole" +editors: + - "@pwittrock" +creation-date: 2019-01-17 +last-updated: 2019-01-17 +status: provisional +see-also: + - "kustomize-subcommand-integration.md" +replaces: +superseded-by: + - n/a +--- + +# Kustomize File Processing Integration + +## Table of Contents +* [Table of Contents](#table-of-contents) +* [Summary](#summary) +* [Motivation](#motivation) + * [Goals](#goals) + * [Non-Goals](#non-goals) +* [Proposal](#proposal) + * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints) + * [Risks and Mitigations](#risks-and-mitigations) +* [Graduation Criteria](#graduation-criteria) +* [Implementation History](#implementation-history) +* [Alternatives](#alternatives) + +[Tools for generating]: https://github.com/ekalinin/github-markdown-toc + +## Summary + +This is a follow up to [KEP Kustomize Subcommand Integration](kustomize-subcommand-integration.md) + +[Kustomize](https://github.com/kubernetes-sigs/kustomize) was introduced as +subcommand of kubectl to allow users to build their kustomizations directly. +However users need to pipe the kustomize output to other commands in order +to use the kustomizations. + +This KEP proposes integrating the kustomization libraries into the cli-runtime +file processing libraries. Doing so will provide a cleaner, simpler UX +and provide a path for addressing issues around error handling and messaging. + +## Motivation + +- It is capable of removing friction that requires deeper integration - such as producing errors referencing line + numbers of the original files (rather than the output files) and providing the right error code if kustomization + fails. +- It is more consistent with UX workflow with other commands and flags +- It has a cleaner and simpler UX than pipes +- It is clear which commands it should be used with - apply, get, delete, etc. + +### Goals + +- Provide a clean and integrated user experience when working with files from kubectl. +- Provide consistent UX across kubectl commands for working with kustomized applications. + +### Non-Goals + +## Proposal + +Integrate kustomize directly into libraries that enable file processing for cli-runtime (e.g. resource builder). +Kubectl commands taking the common flags (`-f`, `--filename`, `-R`, `--recursive`) will support `kustomization.yaml` +files. + +Cli-runtime will add the flags `-k, --kustomize=[]`, which will be registered along side the other file processing +flags. If the `-k` flags are provided to a command, the experience will be similar to if the user had piped +kustomize to stdin - e.g. `kubectl kustomize | kubectl -f -`. It will differ in that it provides +improved error handling and messaging. + +Example: `kubectl apply -k ` + +Tools outside kubectl that use the cli-runtime to register file processing +flags and build resources will get the `-k` by default, but can opt-out if +they do not want the functionality. + +The `-f` and `-k` flags will be mutually exclusive and specifying both +will cause kubectl to exit with and error. + +### Risks and Mitigations + +Low: + +When run against a `kustomization.yaml` with multiple bases, kubectl may perform multiple requests as part of the +preprocessing. Since `-k` is a separate flag from `-f`, it is transparent to a user whether they are running +against a kustomization file or a directory of Resource Config. + +## Graduation Criteria + +NA + +## Implementation History + +## Alternatives diff --git a/keps/sig-cli/kustomize-subcommand-integration.md b/keps/sig-cli/kustomize-subcommand-integration.md new file mode 100644 index 000000000000..6e26b93b571b --- /dev/null +++ b/keps/sig-cli/kustomize-subcommand-integration.md @@ -0,0 +1,393 @@ +--- +title: Kustomize Subcommand Integration +authors: + - "@Liujingfang1" +owning-sig: sig-cli +participating-sigs: + - sig-cli +reviewers: + - "@liggitt" + - "@seans3" + - "@soltysh" +approvers: + - "@liggitt" + - "@seans3" + - "@soltysh" +editors: + - "@pwittrock" +creation-date: 2018-11-07 +last-updated: 2019-01-17 +status: implementable +see-also: + - "[kustomize](https://github.com/kubernetes-sigs/kustomize/blob/master/docs/workflows.md)" + - "kustomize-file-processing-integration.md" +replaces: + - "0008-kustomize.md" +superseded-by: + - n/a +--- + +# Kustomize Subcommand Integration + +## Table of Contents +* [Table of Contents](#table-of-contents) +* [Summary](#summary) +* [Motivation](#motivation) + * [Goals](#goals) + * [Non-Goals](#non-goals) +* [Kustomize Introduction](#kustomize-introduction) +* [Proposal](#proposal) + * [UX](#UX) + * [apply](#apply) + * [get](#get) + * [delete](#delete) + * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints) + * [Risks and Mitigations](#risks-and-mitigations) +* [Graduation Criteria](#graduation-criteria) +* [Implementation History](#implementation-history) +* [Alternatives](#alternatives) + +[Tools for generating]: https://github.com/ekalinin/github-markdown-toc + +Link to tracking issue: kubernetes/enhancements#633 + +See: + +- [KEP FAQ](kep-faq.md) for questions such as "why not as as plugin?". +- [Why this should be part of kubectl](#why-this-should-be-part-of-kubectl) + +## Summary + +[Kustomize](https://github.com/kubernetes-sigs/kustomize) +was developed as a subproject of sig-cli by kubectl maintainers to address +a collection of [issues](#motivation)) creating friction for declarative workflows in kubectl +(e.g. `kubectl apply`). The +goal of the kustomize subproject was to bring this functionality back to kubectl to better complement +`kubectl apply` and other declarative workflow commands. + +- declaratively generating Resource config +- declaratively transforming Resource config +- composing collections of Resource config across files and directories +- layering the above on top of one another + +It is independent of, but complementary to, the [*server-side apply*](https://github.com/kubernetes/enhancements/issues/555) +initiative that was started later and targeted at a separate collection of +`kubectl apply` issues. + +Kustomize offers generators and transformations in a declarative form that +improve on functionality provided by existing imperative commands in kubectl. + +The declarative approach offers a clear path to accountability (all input can +be kept in version control), can safely exploit a holistic, unbounded view of +disparate resources and their interdependence (it's a plan about what to do, +not a direct action), and can be easily constrained to verifiable rules +across this view (all edits must be structured, no removal semantics, no +environment side-effects, etc.). + +Imperative kubectl commands / flags available through kustomize: + +- `kubectl create configmap` +- `kubectl create secret` +- `kubectl annotate` +- `kubectl label` +- `kubectl patch` +- `-n` (namespace) +- `-f ` (kubectl processes files with lists of Resources) + +Kubectl commands / flags similar to what is available through kustomize: + +- `-f -R` (kubectl - recursing through directories, kustomize may follow references) +- `kubectl set image` (kustomize directive to set the image tag only, not the image) + +Things in kustomize that are not imperative kubectl commands / flags: + +- `namePrefix` (prepend all resource names with this) +- `nameSuffix` (append all resource names with this) +- for a limited set of fields allow one field value to be set to match another + +## Motivation + +**Background:** Kubectl Apply + +Kubectl apply is intended to provide a declarative workflow for working with the Kubernetes API. Similar to kustomize, +`apply` (client-side) pre-processes Resource Config and transforms it into Kubernetes patches sent to the +apiserver (transformation is a function of live cluster state and Resource Config). Apply addresses user friction +such as: + +- updating Resources from Resource Config without wiping out control-plane defined fields (e.g. Service clusterIp) +- automatically deciding whether to create, update or delete Resources + +**Present:** + +However apply does contain user friction in its declarative workflow, the majority of which could be either reduced +or solved through augmenting and leveraging capabilities already present in kubectl imperative commands from a +declarative context. To this end, kustomize was developed. + +Example GitHub issues addressed by kustomize: + +- Declarative Updates of Secrets + ConfigMaps + [kubernetes/kubernetes#24744](https://github.com/kubernetes/kubernetes/issues/24744) +- Declarative Updates of ConfigMaps (duplicate) + [kubernetes/kubernetes#30337](https://github.com/kubernetes/kubernetes/issues/30337) +- Collecting Resource Config Across multiple targets (e.g. files / urls) + [kubernetes/kubernetes#24649](https://github.com/kubernetes/kubernetes/issues/24649) +- Facilitate Rollouts of ConfigMaps on update + [kubernetes/kubernetes#22368](https://github.com/kubernetes/kubernetes/issues/22368) +- Transformation (and propagation) of Names, Labels, Selectors + [kubernetes/kubernetes#1698](https://github.com/kubernetes/kubernetes/issues/1698) + +Some of the solutions provided by kustomize could also be done as bash scripts to generate and transform +Resource config using either kubectl or other commands (e.g. creating a Secret from a file). + +As an example: [this](https://github.com/osixia/docker-openldap/tree/stable/example/kubernetes/using-secrets/environment) +is a repo publishing Kubernetes Resource config and with it provides a bash script to help facilitate users generating +Secret data from files. e.g. We want to discourage as a pattern teaching users to run arbitrary bash scripts from +GitHub. + +Another example: [this](https://github.com/kubernetes/kubernetes/issues/23233) is suggesting writing a script to +invoke kubectl's patch and apply logic from a script (add-on manager circa 2016). + +Users have asked for a declarative script-free way to apply changes to Resource Config. + +### Goals + +Solve common kubectl user friction (such as those defined in the Motivation section) by publishing kustomize +functionality from kubectl to complement commands which are targeted at declarative workflows. + +- Complement commands targeted at declarative workflows: `kubectl apply`, `kubectl diff` +- Complement the *server-side apply* initiative targeted at improving declarative workflows. + +User friction solved through capabilities such as: + +- Generating Resource Config for Resources with data frequently populated from other sources - ConfigMap and Secret +- Performing common cross-cutting transformations intended to be applied across Resource Configs - e.g. + name prefixing / suffixing, labeling, annotating, namespacing, imageTag setting. +- Performing flexible targeted transformations intended to be applied to specific Resource Configs - e.g. + strategic patch, json patch +- Composing and layering Resource Config with schema-aware transformations +- Facilitating rolling updates to Resources such as ConfigMaps and Secrets via Resource Config transformations +- Facilitating creation of Resources that require the creation to be ordered - e.g. namespaces, crds + +### Non-Goals + +- Exposing all imperative kubectl commands as declarative options +- Exposing all kubectl generators and schema-aware transformations +- Providing simpler alternatives to the APIs for declaring Resource Config (e.g. a simple way to create deployments) +- Providing a templating or general substitution mechanism (e.g. for generating Resource Config) + +### Why this should be part of kubectl + +- It was purposefully built to address user friction in kubectl declarative workflows. Leaving these issues unaddressed + in the command itself reduces the quality of the product. +- The techniques it uses to address the issues are based on the existing kubectl imperative commands. It is + consistent with the rest of kubectl. +- Bridging the imperative and declarative workflows helps bring a more integrated feel and consistent story to + kubectl's command set. +- Kustomize is already part of the Kubernetes project and owned by SIG CLI (the same sig that owns kubectl). + SIG CLI members have expertise in the kustomize codebase and are committed to maintaining the solution going forward. +- Providing it as part of kubectl will ensure that it is available to users of kubectl apply and simplify the + getting started experience. + +## Proposal + +Kustomize Standalone Sub Command + +Publish the `kustomize build` command as `kubectl kustomize`. Update +documentation to demonstrate using kustomize as `kubectl kustomize | kubectl apply -f -`. + +`kubectl kustomize` takes a single argument with is the location of a directory containing a file named `kustomization.yaml` +and writes to stdout the kustomized Resource Config. + +If the directory does not contain a `kustomization.yaml` file, it returns an +error. + +Defer deeper integration into ResourceBuilder (e.g. `kubectl apply -k `) as a follow up after discussing +the precise UX and technical tradeoffs. (i.e. deeper integration is more delicate and can be done independently.) + +### Justification for this approach + +The end goal is to have kustomize fully integrated into cli-runtime as part of the Resource processing +libraries (e.g. ResourceBuilder) and supported by all commands that take the `-f` flag. + +Introducing it as a standalone subcommand first is a simple way of introducing kustomize functionality to kubectl, +and will be desirable even after kustomize is integrated into cli-runtime. The benefits of introducing it +as a standalone command are: + +- Users can view the kustomize output (i.e. without invoking other commands in dry-run mode) + - Allows users to experiment with kustomizations + - Allows users to debug kustomizations + - It is easier to educate users about kustomizations when they can run it independently +- The subcommand UX is simple and well defined +- The technical integration is simple and well defined + +### Justification for follow up + +- It can't address user friction requiring deeper integration - e.g. produce meaningful line numbers in error + messages and exit codes. +- Most commands would require the same input pipe - e.g. get, delete, etc. would all need pipes. Direct integration + is cleaner than always piping everything. +- We haven't trained user with this pattern + - We don't currently follow this pattern by default for other commands such as `kubectl create deployment`- which requires + additional flags to output content to pipe `--dry-run -o yaml` + - We don't do this for file, dir or url targets - e.g. we don't do `curl something | kubectl apply -f -` +- When both subcommand and ResourceBuilder integration were demoed at sig-cli, the integrated UX was preferred +- Kustomize is the way we are addressing issues with declarative workflows so we should make it as simple and easy + to use as raw Resource Config files. + +## Kustomize Example + +Following is an example of a `kustomization.yaml` file used by kustomize: + +``` +apiVersion: v1beta1 +kind: Kustomization +namePrefix: alices- + +commonAnnotations: + oncallPager: 800-555-1212 + +configMapGenerator: +- name: myJavaServerEnvVars + literals: + - JAVA_HOME=/opt/java/jdk + - JAVA_TOOL_OPTIONS=-agentlib:hprof + +secretGenerator: +- name: app-sec + files: + - secret/password + - secret/username +``` + +The result of running `kustomize build` on this sample kustomizaiton.yaml file is: + +``` +apiVersion: v1 +kind: ConfigMap +metadata: + name: alices-myJavaServerEnvVars-7bc9c27cmf + annotations: + oncallPager: 800-555-1212 +data: + JAVA_HOME: /opt/java/jdk + JAVA_TOOL_OPTIONS: -agentlib:hprof +--- +apiVersion: v1 +kind: Secret +metadata: + name: alices-app-sec-c7c5tbh526 + annotations: + oncallPager: 800-555-1212 +type: Opaque +data: + password: c2VjcmV0Cg== + username: YWRtaW4K +``` + +### Implementation Details/Notes/Constraints + +In contrast to `kubectl apply`, which was developed directly in kubernetes/kubernetes and had minimal usage or +real world experience prior, kustomize was built as an outside of kubernetes/kubernetes in the +kubernetes-sigs/kustomize repo. After `kubectl apply` was published, many issues were uncovered in it that should +have been discovered earlier. Implementing kustomize independently allowed more time for gathering feedback and +identifying issues. + +Kustomize library code will be moved from its current repository (location) to the cli-runtime repository used by +kubectl. + +### Risks and Mitigations + +Low: + +- Kustomize can be run against remote urls. A user could run it on a URL containing malicious workflows. However this + would only generate the config, and the user would need to pipe it to apply for the workloads to be run. This is also + true for `kubectl apply -f ` and or `kubectl create deployment --image `. + +Low: + +- Kustomize has other porcelain commands to facilitate common workflows. This proposal does not include integrating + them into kubectl. Users would need to download kustomize separate to get these benefits. + +Low: + +- `kubectl kustomize ` doesn't take a `-f` flag like the other commands. + +## Graduation Criteria + +The API version for kustomize is defined in the `kustomization.yaml` file. The KEP is targeted `v1beta1`. + +The criteria for graduating from `v1beta1` for the kustomize sub-command should be determined as part of +evaluating the success and maturity of kustomize as a command within kubectl. + +Metrics for success and adoption could include but are not limited to: + +- number of `kustomization.yaml` files seen on sources such as GitHub +- complexity (required) of `kustomization.yaml` files seen on sources such as GitHub. +- (if available) number of calls to `kubectl kustomize` being performed +- adoption or integration of kustomize by other tools + +Metrics for maturity and stability could include but are not limited to: + +- number and severity of kustomize related bugs filed that are intended to be fixed +- the frequency of API changes and additions +- understanding of relative use and importance of kustomize features + +**Note:** Being integrated into ResourceBuilder is *not* considered graduation and *not* gated on GA. + +## Implementation History + +Most implementation will be in cli-runtime + +- [ ] vendor `kustomize/pkg` into kubernetes +- [ ] copy `kustomize/k8sdeps` into cli-runtime + - Once cli-runtime is out of k/k, move the kustomize libraries there (but + not the commands) +- [ ] Implement a function in cli-runtime to run kustomize build with input as fSys and/or path. + - execute kustomize build to get a list of resources + - write the output to io.Writer +- [ ] Add a subcommand `kustomize` in kubectl. This command accepts one argument and write the output to stdout + kubectl kustomize +- [ ] documentation: + - Write full doc for `kubectl kustomize` + - Update the examples in kubectl apply/delete to include the usage of kustomize + +## Alternatives + +The approaches in this section are considered, but rejected. + +### Copy kustomize code into staging + +Don't wait until kubectl libraries are moved out of staging before integrating, immediately copy kustomize code into +kubernetes/staging and move to this as the source of truth. + +- Pros + - It could immeidately live with the other kubectl code owned by sig-cli, instead of waiting until this + is moved out. +- Cons + - We are trying to move code **out** of kubernetes/kubernetes. This is doing the opposite. + - We are trying to move kubectl **out** of kubernetes/kubernetes. This is doing the opposite. + +### Leave kustomize functionality separate from kubectl + +- Pros + - It is (marginally) less engineering work +- Cons + - It leaves long standing issues in kubectl unaddressed within the tool itself. + - It does not support any deeper integrations - such as giving error messages with meaningful line numbers. + +### Build a separate tools targeted at Kubernetes declarative workflows. + +Copy the declarative code from kubectl into a new tool. Use this for declarative workflows. + +Questions: + +- Do we deprecate / remove it from kubectl or have it in both places? +- If in both places do we need to support both? Can they diverge? +- What needs to be updated? Docs, Blogs, etc. + +- Pros + - It makes kubectl simpler +- Cons + - Not clear how this helps users + - Does't address distribution problems + - User friction around duplication of functionality or remove of functionality \ No newline at end of file