Kubectl Data Driven Command KEP
This commit is contained in:
Phillip Wittrock
parent
37e8fe7cca
commit
a1eaa11e1a
|
|
@ -0,0 +1,412 @@
|
|||
---
|
||||
kep-number: 31
|
||||
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.
|
||||
|
||||
## 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
|
||||
|
||||
// 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"`
|
||||
|
||||
// Output is a go-template used write the command output. 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"}}.
|
||||
//
|
||||
// It 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
|
||||
Output string `json:"output,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
|
||||
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.
|
||||
//
|
||||
// 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}"
|
||||
output: |
|
||||
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`)
|
||||
- Approach is hard to maintain, complex, etc
|
||||
- Initially restrict to only `create` commands, get feedback
|
||||
|
||||
|
||||
## 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
|
||||
Loading…
Reference in New Issue