kubeapply

README

kubeapply

kubeapply is a microservice for running kubectl apply through a web API.

kubeapply makes it easier to use Kubernetes in a declarative manner while Kubernetes API still doesn't have an endpoint similar to kubectl apply.

Server-side Apply enhancement workaround

kubectl apply is a core part of the Kubernetes config workflow. However, its implementation is in the client-side of a CLI tool. As of February 2019, there is work in progress to migrate the functionality to the server-side.

This middleware is a workaround useful for using Kubernetes kubectl apply over an HTTP connection while work on this integration is still in progress.

• Kubernetes Enhancement Proposals: Apply
• v2 API proposal "desired vs actual #17333"
• Server-side Apply #555
• Umbrella Issue for Server Side Apply #73723

Dependencies

• Go ≥ 1.11 to generate the server binary.
• Kubernetes 1.10 or greater.

Commands

• Run make server

You might want to run cmd/server --help to list the available options.

The environment variable DEBUG sets the logging to debug mode.

kubectl must be available on the machine.

A Docker image is publicly available as wedeploy/kubeapply. Kubernetes cluster configurations are stored in the /configurations directory.

Security

It is unsafe to run this software unless you protect this service appropriately. You must run it on an isolated machine with limited network connectivity.

Port 9000 (API) is only accessible from localhost, except in the Docker image. Port 8081 (debugging tool) is enabled by default only for localhost.

For your safety, you must assume that anyone who can reach this middleware endpoints has total control over the machine it is running on. Reasons: cluster options, file-system access, etc.

To communicate with other machines outside of a trusted network use a secure layer and proper client and server authentication protocols.

Endpoints

/version

curl http://localhost:9000/version -v returns the local kubectl version.

/apply

You can use all flags available on kubectl apply (including global ones).

{
	"flags": {
		"dry-run": true,
		"output": "wide"
	},
	"files": {
		"relative/path/cert.yaml": "apiVersion: ...",
		"server.json": {"apiVersion": "..."}
	}
}

You can use command attribute to call another kubectl command.

Example: "command": "create" calls kubectl create.

A JSON object is returned containing the explanation of the executed command and its result.

Some details:

• cmd_line is the corresponding command you can copy and paste on a shell to execute the command yourself.
• exit_code is the process exit code.
• dir is the relative path to the stored configuration and logs.
• stderr is always a string.
• stdout is JSON body by default. For other output formats, it is returned as a string value.

Recordings and logs

Configurations requested are recorded on a directory inside configurations named by the id of the request and organized by date. No rotation policy is in place.

You don't need to pass the --filename flag as if no file is found on your YAML, --filename=./ and --recursive are automatically set.

Run example with --dry-run: curl -d @example.json -v -XPUT http://localhost:9000/apply -H "Content-Type: application/json" | jq

Flags

You don't need to prefix flags or shortcuts with -- or -. You also can use numbers or booleans directly.

Example:

{
	"flags": {
		"--dry-run": true,
		"timeout": "1m",
		"R": true,
		"f": "service.yaml"
	}
}

This configuration is similar to kubectl apply --dry-run=true --timeout=1m -R -f=service.yaml.

Contributing

You can get the latest source code with go get -u github.com/henvic/kubeapply

The following commands are available and require no arguments:

• make test: run tests

In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Integration tests should be written as well.

Committing and pushing changes

The master branch of this repository on GitHub is protected:

• force-push is disabled
• tests MUST pass on Travis before merging changes to master
• branches MUST be up to date with master before merging

Keep your commits neat and well documented. Try to always rebase your changes before publishing them.

Maintaining code quality

goreportcard can be used online or locally to detect defects and static analysis results from tools with a great overview.

Using go test and go cover are essential to make sure your code is covered with unit tests.

Always run make test before submitting changes.

Documentation

Index

• Constants
• Variables
• type Apply
  • func (a *Apply) Command() (string, []string)
  • func (a *Apply) Run(ctx context.Context) (Response, error)
• type Flags
  • func (f Flags) Keys() []string
  • func (f Flags) Timeout() (time.Duration, error)
• type Output
  • func (o Output) MarshalJSON() ([]byte, error)
• type Response

Constants

const Executable = "kubectl"

Executable to call.

Variables

var Command = "apply"

Command is the first argument of "kubectl".

Types

type Apply

type Apply struct {
	Flags Flags
	Files map[string][]byte

	IP string

	RequestDump []byte

	Subcommand string
	// contains filtered or unexported fields
}

Apply command.

func (*Apply) Command

func (a *Apply) Command() (string, []string)

Command prepared to be invoked by Run.

func (*Apply) Run

func (a *Apply) Run(ctx context.Context) (Response, error)

Run command.

type Flags

type Flags map[string]string

Flags for kubectl.

func (Flags) Keys

func (f Flags) Keys() []string

Keys of the used flags.

func (Flags) Timeout

func (f Flags) Timeout() (time.Duration, error)

Timeout for the task.

type Output

type Output string

Output can be used to encode an outgoing output value to a JSON structure.

func (Output) MarshalJSON

func (o Output) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON string encoding of v.

type Response

type Response struct {
	ID string `json:"id,omitempty"`

	Command string   `json:"cmd"`
	Args    []string `json:"args"`
	CmdLine string   `json:"cmdline"`

	Stderr string `json:"stderr"`
	Stdout Output `json:"stdout,omitempty"`

	ExitCode int `json:"exit_code"`

	Dir string `json:"dir,omitempty"`
}

Response for the apply command.