diff options
| author | Stephen Augustus <foo@agst.us> | 2018-12-01 02:40:42 -0500 |
|---|---|---|
| committer | Stephen Augustus <foo@agst.us> | 2018-12-01 02:40:42 -0500 |
| commit | 1004e56177eb12d85b6e0f6cf1ccd00431f7336b (patch) | |
| tree | e2a87f95b32e046ed32a2eea6cde661704e61fbd /keps/sig-cli | |
| parent | 973b19523840d207ae206175ac2093d3b564668c (diff) | |
Add KEP tombstones
Signed-off-by: Stephen Augustus <foo@agst.us>
Diffstat (limited to 'keps/sig-cli')
| -rw-r--r-- | keps/sig-cli/0008-kustomize.md | 226 | ||||
| -rw-r--r-- | keps/sig-cli/0024-kubectl-plugins.md | 238 | ||||
| -rw-r--r-- | keps/sig-cli/0031-datadrivencommands.md | 449 | ||||
| -rw-r--r-- | keps/sig-cli/0031-kustomize-integration.md | 237 |
4 files changed, 16 insertions, 1134 deletions
diff --git a/keps/sig-cli/0008-kustomize.md b/keps/sig-cli/0008-kustomize.md index cb47f8d7..cfd1f5fa 100644 --- a/keps/sig-cli/0008-kustomize.md +++ b/keps/sig-cli/0008-kustomize.md @@ -1,222 +1,4 @@ ---- -kep-number: 8 -title: Kustomize -authors: - - "@pwittrock" - - "@monopole" -owning-sig: sig-cli -participating-sigs: - - sig-cli -reviewers: - - "@droot" -approvers: - - "@soltysh" -editor: "@droot" -creation-date: 2018-05-05 -last-updated: 2018-05-23 -status: implemented -see-also: - - n/a -replaces: - - kinflate # Old name for kustomize -superseded-by: - - n/a ---- - -# Kustomize - -## Table of Contents - -- [Kustomize](#kustomize) - - [Table of Contents](#table-of-contents) - - [Summary](#summary) - - [Motivation](#motivation) - - [Goals](#goals) - - [Non-Goals](#non-goals) - - [Proposal](#proposal) - - [Implementation Details/Notes/Constraints [optional]](#implementation-detailsnotesconstraints-optional) - - [Risks and Mitigations](#risks-and-mitigations) - - [Risks of Not Having a Solution](#risks-of-not-having-a-solution) - - [Graduation Criteria](#graduation-criteria) - - [Implementation History](#implementation-history) - - [Drawbacks](#drawbacks) - - [Alternatives](#alternatives) - - [FAQ](#faq) - -## Summary - -Declarative specification of Kubernetes objects is the recommended way to manage Kubernetes -production workloads, however gaps in the kubectl tooling force users to write their own scripting and -tooling to augment the declarative tools with preprocessing transformations. -While most of these transformations already exist as imperative kubectl commands, they are not natively accessible -from a declarative workflow. - -This KEP describes how `kustomize` addresses this problem by providing a declarative format for users to access -the imperative kubectl commands they are already familiar natively from declarative workflows. - -## Motivation - -The kubectl command provides a cli for: - -- accessing the Kubernetes apis through json or yaml configuration -- porcelain commands for generating and transforming configuration off of command line flags. - -Examples: - -- Generate a configmap or secret from a text or binary file - - `kubectl create configmap`, `kubectl create secret` - - Users can manage their configmaps and secrets text and binary files - -- Create or update fields that cut across other fields and objects - - `kubectl label`, `kubectl annotate` - - Users can add and update labels for all objects composing an application - -- Transform an existing declarative configuration without forking it - - `kubectl patch` - - Users may generate multiple variations of the same workload - -- Transform live resources arbitrarily without auditing - - `kubectl edit` - -To create a Secret from a binary file, users must first base64 encode the binary file and then create a Secret yaml -config from the resulting data. Because the source of truth is actually the binary file, not the config, -users must write scripting and tooling to keep the 2 sources consistent. - -Instead, users should be able to access the simple, but necessary, functionality available in the imperative -kubectl commands from their declarative workflow. - -#### Long standing issues - -Kustomize addresses a number of long standing issues in kubectl. - -- Declarative enumeration of multiple files [kubernetes/kubernetes#24649](https://github.com/kubernetes/kubernetes/issues/24649) -- Declarative configmap and secret creation: [kubernetes/kubernetes#24744](https://github.com/kubernetes/kubernetes/issues/24744), [kubernetes/kubernetes#30337](https://github.com/kubernetes/kubernetes/issues/30337) -- Configmap rollouts: [kubernetes/kubernetes#22368](https://github.com/kubernetes/kubernetes/issues/22368) - - [Example in kustomize](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/helloWorld#how-this-works-with-kustomize) -- Name/label scoping and safer pruning: [kubernetes/kubernetes#1698](https://github.com/kubernetes/kubernetes/issues/1698) - - [Example in kustomize](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/breakfast.md#demo-configure-breakfast) -- Template-free add-on customization: [kubernetes/kubernetes#23233](https://github.com/kubernetes/kubernetes/issues/23233) - - [Example in kustomize](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/helloWorld#staging-kustomization) - -### Goals - -- Declarative support for defining ConfigMaps and Secrets generated from binary and text files -- Declarative support for adding or updating cross-cutting fields - - labels & selectors - - annotations - - names (as transformation of the original name) -- Declarative support for applying patches to transform arbitrary fields - - use strategic-merge-patch format -- Ease of integration with CICD systems that maintain configuration in a version control repository - as a single source of truth, and take action (build, test, deploy, etc.) when that truth changes (gitops). - -### Non-Goals - -#### Exposing every imperative kubectl command in a declarative fashion - -The scope of kustomize is limited only to functionality gaps that would otherwise prevent users from -defining their workloads in a purely declarative manner (e.g. without writing scripts to perform pre-processing -or linting). Commands such as `kubectl run`, `kubectl create deployment` and `kubectl edit` are unnecessary -in a declarative workflow because a Deployment can easily be managed as declarative config. - -#### Providing a simpler facade on top of the Kubernetes APIs - -The community has developed a number of facades in front of the Kubernetes APIs using -templates or DSLs. Attempting to provide an alternative interface to the Kubernetes API is -a non-goal. Instead the focus is on: - -- Facilitating simple cross-cutting transformations on the raw config that would otherwise require other tooling such - as *sed* -- Generating configuration when the source of truth resides elsewhere -- Patching existing configuration with transformations - -## Proposal - -### Capabilities - -**Note:** This proposal has already been implemented in `github.com/kubernetes/kubectl`. - -Define a new meta config format called *kustomization.yaml*. - -#### *kustomization.yaml* will allow users to reference config files - -- Path to config yaml file (similar to `kubectl apply -f <file>`) -- Urls to config yaml file (similar to `kubectl apply -f <url>`) -- Path to *kustomization.yaml* file (takes the output of running kustomize) - -#### *kustomization.yaml* will allow users to generate configs from files - -- ConfigMap (`kubectl create configmap`) -- Secret (`kubectl create secret`) - -#### *kustomization.yaml* will allow users to apply transformations to configs - -- Label (`kubectl label`) -- Annotate (`kubectl annotate`) -- Strategic-Merge-Patch (`kubectl patch`) -- Name-Prefix - -### UX - -Kustomize will also contain subcommands to facilitate authoring *kustomization.yaml*. - -#### Edit - -The edit subcommands will allow users to modify the *kustomization.yaml* through cli commands containing -helpful messaging and documentation. - -- Add ConfigMap - like `kubectl create configmap` but declarative in *kustomization.yaml* -- Add Secret - like `kubectl create secret` but declarative in *kustomization.yaml* -- Add Resource - adds a file reference to *kustomization.yaml* -- Set NamePrefix - adds NamePrefix declaration to *kustomization.yaml* - -#### Diff - -The diff subcommand will allow users to see a diff of the original and transformed configuration files - -- Generated config (configmap) will show the files as created -- Transformations (name prefix) will show the files as modified - -### Implementation Details/Notes/Constraints [optional] - -Kustomize has already been implemented in the `github.com/kubernetes/kubectl` repo, and should be moved to a -separate repo for the subproject. - -Kustomize was initially developed as its own cli, however once it has matured, it should be published -as a subcommand of kubectl or as a statically linked plugin. It should also be more tightly integrated with apply. - -- Create the *kustomize* sig-cli subproject and update sigs.yaml -- Move the existing kustomize code from `github.com/kubernetes/kubectl` to `github.com/kubernetes-sigs/kustomize` - -### Risks and Mitigations - - -### Risks of Not Having a Solution - -By not providing a viable option for working directly with Kubernetes APIs as json or -yaml config, we risk the ecosystem becoming fragmented with various bespoke API facades. -By ensuring the raw Kubernetes API json or yaml is a usable approach for declaratively -managing applications, even tools that do not use the Kubernetes API as their native format can -better work with one another through transformation to a common format. - -## Graduation Criteria - -- Dogfood kustomize by either: - - moving one or more of our own (OSS Kubernetes) services to it. - - getting user feedback from one or more mid or large application deployments using kustomize. -- Publish kustomize as a subcommand of kubectl. - -## Implementation History - -kustomize was implemented in the kubectl repo before subprojects became a first class thing in Kubernetes. -The code has been fully implemented, but it must be moved to a proper location. - -## Drawbacks - - -## Alternatives - -1. Users write their own bespoke scripts to generate and transform the config before it is applied. -2. Users don't work with the API directly, and use or develop DSLs for interacting with Kubernetes. - -## FAQs +KEPs have moved to https://git.k8s.io/enhancements/. +<!-- +This file is a placeholder to preserve links. Please remove after 6 months or the release of Kubernetes 1.15, whichever comes first. +-->
\ No newline at end of file diff --git a/keps/sig-cli/0024-kubectl-plugins.md b/keps/sig-cli/0024-kubectl-plugins.md index a79fcc4e..cfd1f5fa 100644 --- a/keps/sig-cli/0024-kubectl-plugins.md +++ b/keps/sig-cli/0024-kubectl-plugins.md @@ -1,234 +1,4 @@ ---- -kep-number: 24 -title: Kubectl Plugins -authors: - - "@juanvallejo" -owning-sig: sig-cli -participating-sigs: - - sig-cli -reviewers: - - "@pwittrock" - - "@deads2k" - - "@liggitt" - - "@soltysh" -approvers: - - "@pwittrock" - - "@soltysh" -editor: juanvallejo -creation-date: 2018-07-24 -last-updated: 2018-08-09 -status: provisional -see-also: - - n/a -replaces: - - "https://github.com/kubernetes/community/blob/master/contributors/design-proposals/cli/kubectl-extension.md" - - "https://github.com/kubernetes/community/pull/481" -superseded-by: - - n/a ---- - -# Kubectl Plugins - -## Table of Contents - -* [Table of Contents](#table-of-contents) -* [Summary](#summary) -* [Motivation](#motivation) - * [Limitations of the Existing Design](#limitations-of-the-existing-design) - * [Goals](#goals) - * [Non-Goals](#non-goals) -* [Proposal](#proposal) - * [Scenarios](#scenarios) - * [Implementation Details/Design/Constraints](#implementation-detailsdesign) - * [Naming Conventions](#naming-conventions) - * [Implementation Notes/Constraints](#implementation-notesconstraints) - * [Risks and Mitigations](#risks-and-mitigations) -* [Graduation Criteria](#graduation-criteria) -* [Implementation History](#implementation-history) -* [Drawbacks](#drawbacks) -* [Future Improvements/Considerations](#future-improvementsconsiderations) - -## Summary - -This proposal introduces the main design for a plugin mechanism in `kubectl`. -The mechanism is a git-style system, that looks for executables on a user's `$PATH` whose name begins with `kubectl-`. -This allows plugin binaries to override existing command paths and add custom commands and subcommands to `kubectl`. - -## Motivation - -The main motivation behind a plugin system for `kubectl` stems from being able to provide users with a way to extend -the functionality of `kubectl`, beyond what is offered by its core commands. - -By picturing the core commands provided by `kubectl` as essential building blocks for interacting with a Kubernetes -cluster, we can begin to think of plugins as a means of using these building blocks to provide more complex functionality. -A new command, `kubectl set-ns`, for example, could take advantage of the rudimentary functionality already provided by -the `kubectl config` command, and build on top of it to provide users with a powerful, yet easy-to-use way of switching -to a new namespace. - -For example, the user experience for switching namespaces could go from: - -```bash -kubectl config set-context $(kubectl config current-context) --namespace=mynewnamespace -``` - -to: - -``` -kubectl set-ns mynewnamespace -``` - -where `set-ns` would be a user-provided plugin which would call the initial `kubectl config set-context ...` command -and set the namespace flag according to the value provided as the plugin's first parameter. - -The `set-ns` command above could have multiple variations, or be expanded to support subcommands with relative ease. -Since plugins would be distributed by their authors, independent from the core Kubernetes repository, plugins could -release updates and changes at their own pace. - -### Limitations of the Existing Design - -The existing alpha plugin system in `kubectl` presents a few limitations with its current design. -It forces plugin scripts and executables to exist in a pre-determined location, requires a per-plugin metadata file for -interpretation, and does not provide a clear way to override existing command paths or provide additional subcommands -without having to override a top-level command. - -The proposed git-style re-design of the plugin system allows us to implement extensibility requests from users that the -current system is unable to address. -See https://github.com/kubernetes/kubernetes/issues/53640 and https://github.com/kubernetes/kubernetes/issues/55708. - -### Goals - -* Avoid any kind of installation process (no additional config, users drop an executable in their `PATH`, for example, - and they are then able to use that plugin with `kubectl`). - No additional configuration is needed, only the plugin executable. - A plugin's filename determines the plugin's intention, such as which path in the command tree it applies to: - `/usr/bin/kubectl-educate-dolphins` would, for example be invoked under the command `kubectl educate dolphins --flag1 --flag2`. - It is up to a plugin to parse any arguments and flags given to it. A plugin decides when an argument is a - subcommand, as well as any limitations or constraints that its flags should have. -* Relay all information given to `kubectl` (via command line args) to plugins as-is. - Plugins receive all arguments and flags provided by users and are responsible for adjusting their behavior - accordingly. -* Provide a way to limit which command paths can and cannot be overridden by plugins in the command tree. - -### Non-Goals - -* The new plugin mechanism will not be a "plugin installer" or wizard. It will not have specific or baked-in knowledge - regarding a plugin's location or composition, nor will it provide a way to download or unpack plugins in a correct - location. -* Plugin discovery is not a main focus of this mechanism. As such, it will not attempt to collect data about every - plugin that exists in an environment. -* Plugin management is out of the scope of this design. A mechanism for updating and managing lifecycle of existing - plugins should be covered as a separate design (See https://github.com/kubernetes/community/pull/2340). -* Provide a standard package of common cli utilities that is consumed by `kubectl` and plugins alike. - This should be done as an independent effort of this plugin mechanism. - -## Proposal - -### Scenarios - -* Developer wants to create and expose a plugin to `kubectl`. - They use a programming language of their choice and create an executable file. - The executable's filename consists of the command path to implement, and is prefixed with `kubectl-`. - The executable file is placed on the user's `PATH`. - -### Implementation Details/Design - -The proposed design passes through all environment variables, flags, input, and output streams exactly as they are given -to the parent `kubectl` process. This has the effect of letting plugins run without the need for any special parsing -or case-handling in `kubectl`. - -In essence, a plugin binary must be able to run as a standalone process, completely independent of `kubectl`. - -* When `kubectl` is executed with a subcommand _foo_ that does not exist in the command tree, it will attempt to look -for a filename `kubectl-foo` (`kubectl-foo.exe` on Windows) in the user's `PATH` and execute it, relaying all arguments given -as well as all environment variables to the plugin child-process. - -A brief example (not an actual prototype) is provided below to clarify the core logic of the proposed design: - -```go -// treat all args given by the user as pieces of a plugin binary's filename -// and short-circuit once we find an arg that appears to be a flag. -remainingArgs := []string{} // all "non-flag" arguments - -for idx := range cmdArgs { - if strings.HasPrefix(cmdArgs[idx], "-") { - break - } - remainingArgs = append(remainingArgs, strings.Replace(cmdArgs[idx], "-", "_", -1)) -} - -foundBinaryPath := "" - -// find binary in the user's PATH, starting with the longest possible filename -// based on the given non-flag arguments by the user -for len(remainingArgs) > 0 { - path, err := exec.LookPath(fmt.Sprintf("kubectl-%s", strings.Join(remainingArgs, "-"))) - if err != nil || len(path) == 0 { - remainingArgs = remainingArgs[:len(remainingArgs)-1] - continue - } - - foundBinaryPath = path - break -} - -// if we are able to find a suitable plugin executable, perform a syscall.Exec call -// and relay all remaining arguments (in order given), as well as environment vars. -syscall.Exec(foundBinaryPath, append([]string{foundBinaryPath}, cmdArgs[len(remainingArgs):]...), os.Environ()) -``` - -#### Naming Conventions - -Under this proposal, `kubectl` would identify plugins by looking for filenames beginning with the `kubectl-` prefix. -A search for these names would occur on a user's `PATH`. Only files that are executable and begin with this prefix -would be identified. - -### Implementation Notes/Constraints - -The current implementation details for the proposed design rely on using a plugin executable's name to determine what -command the plugin is adding. -For a given command `kubectl foo --bar baz`, an executable `kubectl-foo` will be matched on a user's `PATH`, -and the arguments `--bar baz` will be passed to it in that order. - -A potential limitation of this could present itself in the order of arguments provided by a user. -A user could intend to run a plugin `kubectl-foo-bar` with the flag `--baz` with the following command -`kubectl foo --baz bar`, but instead end up matching `kubectl-foo` with the flag `--baz` and the argument `bar` based -on the placement of the flag `--baz`. - -A notable constraint of this design is that it excludes any form of plugin lifecycle management, or version compatibility. -A plugin may depend on other plugins based on the decision of a plugin author, however the proposed design does nothing -to facilitate such dependencies. It is up to the plugin's author (or a separate / independent plugin management system) to -provide documentation or instructions on how to meet any dependencies required by a plugin. - -Further, with the proposed design, plugins that rely on multiple "helper" files to properly function, should provide an -"entrypoint" executable (which is placed on a user's `PATH`), with any additional files located elsewhere (e.g. ~/.kubeplugins/myplugin/helper1.py). - -### Risks and Mitigations - -Unlike the existing alpha plugin mechanism, the proposed design does not constrain commands added by plugins to exist as subcommands of the -`kubectl plugin` design. Commands provided by plugins under the new mechanism can be invoked as first-class commands (`/usr/bin/kubectl-foo` provides the `kubectl foo` parent command). - -A potential risk associated with this could present in the form of a "land-rush" by plugin providers. -Multiple plugin authors would be incentivized to provide their own version of plugin `foo`. -Users would be at the mercy of whichever variation of `kubectl-foo` is discovered in their `PATH` first when executing that command. - -A way to mitigate the above scenario would be to have users take advantage of the proposed plugin mechanism's design by renaming multiple variations of `kubectl-foo` -to include the provider's name, for example: `kubectl-acme-foo`, or `kubectl-companyB-foo`. - -Conflicts such as this one could further be mitigated by a plugin manager, which could perform conflict resolution among similarly named plugins on behalf of a user. - -## Graduation Criteria - -* Make this mechanism a part of `kubectl`'s command-lookup logic. - -## Implementation History - -This plugin design closely follows major aspects of the plugin system design for `git`. - -## Drawbacks - -Implementing this design could potentially conflict with any ongoing work that depends on the current alpha plugin system. - -## Future Improvements/Considerations - -The proposed design is flexible enough to accommodate future updates that could allow certain command paths to be overwritten -or extended (with the addition of subcommands) via plugins. +KEPs have moved to https://git.k8s.io/enhancements/. +<!-- +This file is a placeholder to preserve links. Please remove after 6 months or the release of Kubernetes 1.15, whichever comes first. +-->
\ No newline at end of file diff --git a/keps/sig-cli/0031-datadrivencommands.md b/keps/sig-cli/0031-datadrivencommands.md index 4f386c5f..cfd1f5fa 100644 --- a/keps/sig-cli/0031-datadrivencommands.md +++ b/keps/sig-cli/0031-datadrivencommands.md @@ -1,445 +1,4 @@ ---- -kep-number: 32 -title: Data Driven Commands for Kubectl -authors: - - "@pwittrock" -owning-sig: sig-cli -participating-sigs: -reviewers: - - "@soltysh" - - "@juanvallejo" - - "@seans3 " -approvers: - - "@soltysh" -editor: TBD -creation-date: 2018-11-13 -last-updated: 2018-11-13 -status: provisional -see-also: -replaces: -superseded-by: ---- - -# data driven commands - -## Table of Contents - -* [Table of Contents](#table-of-contents) -* [Summary](#summary) -* [Motivation](#motivation) - * [Goals](#goals) - * [Non-Goals](#non-goals) -* [Proposal](#proposal) - * [Implementation Details](#implementation-details) - * [Risks and Mitigations](#risks-and-mitigations) -* [Graduation Criteria](#graduation-criteria) -* [Alternatives](#alternatives) - -## Summary - -Many Kubectl commands make requests to specific Resource endpoints. The request bodies are populated by flags -provided by the user. - -Examples: - -- `create <resource>` -- `set <field> <resource>` -- `logs` - -Although these commands are compiled into the kubectl binary, their workflow is similar to a form on a webpage and -could be complete driven by the server providing the client with the request (endpoint + body) and a set of flags -to populate the request body. - -Publishing commands as data from the server addresses cli integration with API extensions as well as client-server -version skew. - -**Note:** No server-side changes are required for this, all Request and Response template expansion is performed on -the client side. - -## Motivation - -Kubectl provides a number of commands to simplify working with Kubernetes by making requests to -Resources and SubResources. These requests are mostly static, with fields filled in by user -supplied flags. Today the commands are compiled into the client, which as the following challenges: - -- Extension APIs cannot be compiled into the client -- Version-Skewed clients (old client) may be missing commands for new APIs or send outdated requests -- Version-Skewed clients (new client) may have commands for APIs that are not present in the server or expose - fields not present in older API versions - -### Goals - -Allow client commands that make a single request to a specific resource and output the result to be data driven -from the server. - -- Address cli support for extension APIs -- Address user experience for version skewed clients - -### Non-Goals - -Allow client commands that have complex client-side logic to be data driven. - -- Require a TTY -- Are Agnostic to Specific Resources - -## Proposal - -Define a format for publishing simple cli commands as data. CLI commands would be limited to: - -- Sending one or more requests to Resource or SubResource Endpoints -- Populating requests from command line flags and arguments -- Writing output populated from the Responses - -**Proof of Concept:** [cnctl](https://github.com/pwittrock/kubectl/tree/cnctl/cmd/cnctl) - -Instructions to run PoC: - -- `go run ./main.go` (no commands show up) -- `kubectl apply` the `cli_v1alpha1_clitestresource.yaml` (add the CRD with the commands) -- `go run ./main.go` (create command shows up) -- `go run ./main create deployment -h` (view create command help) -- `go run ./main create deploy --image nginx --name nginx` (create a deployment) -- `kubectl get deployments` - -### Implementation Details - -**Publishing Data:** - -Alpha: No apimachinery changes required - -- Alpha: publish extension Resource Commands as an annotation on CRDs. -- Alpha: publish core Resource Commands as openapi extension. - -Beta: apimachinery changes required - -- Beta: publish extension Resource Commands a part of the CRD Spec. -- Beta: publish core Resource Commands from new endpoint (like *swagger.json*) - -**Data Command Structure:** - -```go -/* -Copyright 2018 The Kubernetes Authors. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -*/ - -package v1alpha1 - -type OutputType string - -const ( - // Use the outputTemplate field to format the response on the client-side - OUTPUT_TEMPLATE OutputType = "TEMPLATE" - - // Use Server-Side Printing and output the response table in a columnar format - OUTPUT_TABLE = "TABLE" -) - -// ResourceCommand defines a command that is dynamically defined as an annotation on a CRD -type ResourceCommand struct { - // Command is the cli Command - Command Command `json:"command"` - - // Requests are the requests the command will send to the apiserver. - // +optional - Requests []ResourceRequest `json:"requests,omitempty"` - - // OutputType is used to determine what output type to print - // +optional - OutputType OutputType `json:"outputTemplate,omitempty"` - - // OutputTemplate is a go-template used by the kubectl client to format the server responses as command output - // (STDOUT). - // - // The template may reference values specified as flags using - // {{index .Flags.Strings "flag-name"}}, {{index .Flags.Ints "flag-name"}}, {{index .Flags.Bools "flag-name"}}, - // {{index .Flags.Floats "flag-name"}}. - // - // The template may also reference values from the responses that were saved using saveResponseValues - // {{index .Responses.Strings "response-value-name"}}. - // - // Example: - // deployment.apps/{{index .Responses.Strings "responsename"}} created - // - // +optional - OutputTemplate string `json:"outputTemplate,omitempty"` -} - -type ResourceOperation string - -const ( - CREATE_RESOURCE ResourceOperation = "CREATE" - UPDATE_RESOURCE = "UPDATE" - DELETE_RESOURCE = "DELETE" - GET_RESOURCE = "GET" - PATCH_RESOURCE = "PATCH" -) - -type ResourceRequest struct { - // Group is the API group of the request endpoint - // - // Example: apps - Group string `json:"group"` - - // Version is the API version of the request endpoint - // - // Example: v1 - Version string `json:"version"` - - // Resource is the API resource of the request endpoint - // - // Example: deployments - Resource string `json:"resource"` - - // Operation is the type of operation to perform for the request. One of: Create, Update, Delete, Get, Patch - Operation ResourceOperation `json:"operation"` - - // BodyTemplate is a go-template for the request Body. It may reference values specified as flags using - // {{index .Flags.Strings "flag-name"}}, {{index .Flags.Ints "flag-name"}}, {{index .Flags.Bools "flag-name"}}, - // {{index .Flags.Floats "flag-name"}} - // - // Example: - // apiVersion: apps/v1 - // kind: Deployment - // metadata: - // name: {{index .Flags.Strings "name"}} - // namespace: {{index .Flags.Strings "namespace"}} - // labels: - // app: nginx - // spec: - // replicas: {{index .Flags.Ints "replicas"}} - // selector: - // matchLabels: - // app: {{index .Flags.Strings "name"}} - // template: - // metadata: - // labels: - // app: {{index .Flags.Strings "name"}} - // spec: - // containers: - // - name: {{index .Flags.Strings "name"}} - // image: {{index .Flags.Strings "image"}} - // - // +optional - BodyTemplate string `json:"bodyTemplate,omitempty"` - - // SaveResponseValues are values read from the response and saved in {{index .Responses.Strings "flag-name"}}. - // They may be used in the ResourceCommand.Output go-template. - // - // Example: - // - name: responsename - // jsonPath: "{.metadata.name}" - // - // +optional - SaveResponseValues []ResponseValue `json:"saveResponseValues,omitempty"` -} - -// Flag defines a cli flag that should be registered and available in request / output templates. -// -// Flag is used only by the client to expand Request and Response templates with user defined values provided -// as command line flags. -type Flag struct { - Type FlagType `json:"type"` - - Name string `json:"name"` - - Description string `json:"description"` - - // +optional - StringValue string `json:"stringValue,omitempty"` - - // +optional - StringSliceValue []string `json:"stringSliceValue,omitempty"` - - // +optional - BoolValue bool `json:"boolValue,omitempty"` - - // +optional - IntValue int32 `json:"intValue,omitempty"` - - // +optional - FloatValue float64 `json:"floatValue,omitempty"` -} - -// ResponseValue defines a value that should be parsed from a response and available in output templates -type ResponseValue struct { - Name string `json:"name"` - JsonPath string `json:"jsonPath"` -} - -type FlagType string - -const ( - STRING FlagType = "String" - BOOL = "Bool" - FLOAT = "Float" - INT = "Int" - STRING_SLICE = "StringSlice" -) - -type Command struct { - // Use is the one-line usage message. - Use string `json:"use"` - - // Path is the path to the sub-command. Omit if the command is directly under the root command. - // +optional - Path []string `json:"path,omitempty"` - - // Short is the short description shown in the 'help' output. - // +optional - Short string `json:"short,omitempty"` - - // Long is the long message shown in the 'help <this-command>' output. - // +optional - Long string `json:"long,omitempty"` - - // Example is examples of how to use the command. - // +optional - Example string `json:"example,omitempty"` - - // Deprecated defines, if this command is deprecated and should print this string when used. - // +optional - Deprecated string `json:"deprecated,omitempty"` - - // Flags are the command line flags. - // - // Flags are used by the client to expose command line flags to users and populate the Request go-templates - // with the user provided values. - // - // Example: - // - name: namespace - // type: String - // stringValue: "default" - // description: "deployment namespace" - // - // +optional - Flags []Flag `json:"flags,omitempty"` - - // SuggestFor is an array of command names for which this command will be suggested - - // similar to aliases but only suggests. - SuggestFor []string `json:"suggestFor,omitempty"` - - // Aliases is an array of aliases that can be used instead of the first word in Use. - Aliases []string `json:"aliases,omitempty"` - - // Version defines the version for this command. If this value is non-empty and the command does not - // define a "version" flag, a "version" boolean flag will be added to the command and, if specified, - // will print content of the "Version" variable. - // +optional - Version string `json:"version,omitempty"` -} - -// ResourceCommandList contains a list of Commands -type ResourceCommandList struct { - Items []ResourceCommand `json:"items"` -} -``` - -**Example Command:** - -```go -# Set Label: "cli.sigs.k8s.io/cli.v1alpha1.CommandList": "" -# Set Annotation: "cli.sigs.k8s.io/cli.v1alpha1.CommandList": '<json>' ---- -items: -- command: - path: - - "create" # Command is a subcommand of this path - use: "deployment" # Command use - aliases: # Command alias' - - "deploy" - - "deployments" - short: Create a deployment with the specified name. - long: Create a deployment with the specified name. - example: | - # Create a new deployment named my-dep that runs the busybox image. - kubectl create deployment --name my-dep --image=busybox - flags: - - name: name - type: String - stringValue: "" - description: deployment name - - name: image - type: String - stringValue: "" - description: Image name to run. - - name: replicas - type: Int - intValue: 1 - description: Image name to run. - - name: namespace - type: String - stringValue: "default" - description: deployment namespace - requests: - - group: apps - version: v1 - resource: deployments - operation: Create - bodyTemplate: | - apiVersion: apps/v1 - kind: Deployment - metadata: - name: {{index .Flags.Strings "name"}} - namespace: {{index .Flags.Strings "namespace"}} - labels: - app: nginx - spec: - replicas: {{index .Flags.Ints "replicas"}} - selector: - matchLabels: - app: {{index .Flags.Strings "name"}} - template: - metadata: - labels: - app: {{index .Flags.Strings "name"}} - spec: - containers: - - name: {{index .Flags.Strings "name"}} - image: {{index .Flags.Strings "image"}} - saveResponseValues: - - name: responsename - jsonPath: "{.metadata.name}" - outputTemplate: | - deployment.apps/{{index .Responses.Strings "responsename"}} created -``` - -### Risks and Mitigations - -- Command name collisions: CRD publishes command that conflicts with another command - - Initially require the resource name to be the command name (e.g. `create foo`, `set image foo`) - - Mitigation: Use the discovery service to manage preference (as it does for the K8S APIs) -- Command makes requests on behalf of the user that may be undesirable - - Mitigation: Automatically output the Resource APIs that command uses as part of the command description - - Mitigation: Support dry-run to emit the requests made to the server without actually making them - - Migration: Possibly restrict the APIs commands can use (e.g. CRD published commands can only use the APIs for that - Resource). -- Approach is hard to maintain, complex, etc - - Initially restrict to only `create` commands, get feedback -- Doesn't work well with auto-complete - - TODO: Investigate if this is true and how much it matters. - -## Graduation Criteria - -- Simple commands for Core Resources have been migrated to be data driven -- In use by high profile extension APIs - e.g. Istio -- Published as first class item for Extension and Core Resources - -## Alternatives - -- Use plugins for these cases - - Still suffer from version skew - - Require users to download and install binaries - - Hard to keep in sync with set of Resources for each cluster -- Don't support cli commands for Extension Resources
\ No newline at end of file +KEPs have moved to https://git.k8s.io/enhancements/. +<!-- +This file is a placeholder to preserve links. Please remove after 6 months or the release of Kubernetes 1.15, whichever comes first. +-->
\ No newline at end of file diff --git a/keps/sig-cli/0031-kustomize-integration.md b/keps/sig-cli/0031-kustomize-integration.md index 1c2af9c7..cfd1f5fa 100644 --- a/keps/sig-cli/0031-kustomize-integration.md +++ b/keps/sig-cli/0031-kustomize-integration.md @@ -1,233 +1,4 @@ ---- -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: yyyy-mm-dd -status: pending -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) is a tool developed to provide declarative support for kubernetes objects. It has been adopted by many projects and users. Having kustomize enabled in kubectl will address a list of long standing issues. This KEP describes how `kustomize` is integrated into kubectl subcommands with consistent 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 - -``` -# TODO: currently kustomization.yaml is not versioned -# Need to version this with apiVersion and Kind -# https://github.com/kubernetes-sigs/kustomize/issues/588 -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 <dir> -``` -To view the objects in a kustomization without applying them to the cluster -``` -kubectl apply -f <dir> --dry-run -o yaml|json -``` - -#### get -The command visible to users is -``` -kubectl get -f <dir> -``` -To get the detailed objects in a kustomization -``` -kubectl get -f <dir> --dry-run -o yaml|json -``` - -#### delete -The command visible to users is -``` -kubectl delete -f <dir> -``` - -### 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 <dir> | 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 - -- vendor `kustomize/pkg` into kubernetes -- copy `kustomize/k8sdeps` into cli-runtime -- Implement a Visitor for kustomization directory which - - execute kustomize build to get a list of resources - - write the output to a StreamVisitor -- When parsing filename parameters in FilenameParam, look for kustomization directories -- 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 -` +KEPs have moved to https://git.k8s.io/enhancements/. +<!-- +This file is a placeholder to preserve links. Please remove after 6 months or the release of Kubernetes 1.15, whichever comes first. +-->
\ No newline at end of file |
