Kubed: Kubernetes, Emacs, done! ¶

3.1 Display Resource ¶

You can view the YAML description of any resource in your Kubernetes cluster. In Kubed, this is referred to as displaying the given resource. The following commands display a Kubernetes resource:

Command: kubed-display-resource ¶

Display a Kubernetes resource.

Command: kubed-display-pod ¶

Command: kubed-display-deployment ¶

Command: kubed-display-namespace ¶

Command: kubed-display-foo ¶

Display Kubernetes resource of a given type.

Command kubed-display-resource can display any Kubernetes resource. It prompts you to select a resource type and a resource name, and displays that resource in a dedicated buffer. By default, this command assumes you want to display a resource that is in the current namespace, but if you invoke kubed-display-resource with a prefix argument (C-u) and choose a namespaced resource type, then it also lets you select the namespace of the resource. With a double prefix argument, it lets you select which kubectl context to use too. See Context and Namespace.

If you have kubed-prefix-map bound to C-c k, you can invoke kubed-display-resource with C-c k RET. This command is also available from the menu-bar “Kubernetes” menu (see Definition of kubed-menu-bar-mode), and from the transient “Kubernetes Display” menu (see Transient Menus).

You can also display the resource at point in resources list buffers by simply typing RET. See Browse Resources.

Kubed also provides a dedicated kubed-display-foo command for each supported resource type foo. These commands are just like kubed-display-resource, except that they do not prompt you for a type, since they are type-specific. For example, kubed-display-pod only prompts you for a pod name, and then displays it like kubed-display-resource does.

You can invoke these commands by adding a type-specific key before RET in C-c k RET: C-c k p RET invokes kubed-display-pod, C-c k d RET invokes kubed-display-deployment, and so on.

When Kubed prepares a buffer for displaying a resource, it runs the hook kubed-yaml-setup-hook right after populating the buffer with the YAML description of the resource:

User Option: kubed-yaml-setup-hook ¶

List of functions to call, in order, to prepare YAML buffers. The first function on this hook is normally the major mode you want to use for YAML buffers that display Kubernetes resources. By default, this is the list (yaml-ts-mode view-mode).

In addition, Kubed enables a bespoke minor mode kubed-display-resource-mode in buffers that display Kubernetes resources:

Minor Mode: kubed-display-resource-mode ¶

Minor mode for buffers that display a Kubernetes resource.

This minor mode does the following:

• It shows the word ‘Kubed’ in the mode line, so you know you’re seeing a rendered Kubernetes resource, rather than any old YAML file.
• It allows you to bookmark the resource your viewing and your position in its YAML description with the regular Emacs bookmarks commands (see (emacs)Bookmarks), namely C-x r m.
• It binds the key sequence C-c C-j to command kubed-display-resource-jump-to-list, which pops up the resources list buffer for the type of the displayed resource, and takes you to the line corresponding to it.
• It binds C-c C-c to command kubed-display-resource-replace, which lets you apply any changes that you make in the YAML buffer back to the resource. When you hit C-c C-c, Kubed asks you for confirmation before proceeding; you can reply with d (‘diff’) to show a diff between the current state of the resource and the current buffer contents. You can also display this diff anytime with C-c C-=. Note that by default Kubed displays resources in read-only buffers, so you may need to hit C-x C-q (read-only-mode) before making changes in the buffer.
• It lets you repopulate the buffer with updated information about the resource with C-x x g (revert-buffer-quick) and M-x revert-buffer. This is also useful if you edit the resource and want to restart from a clean slate.

Type C-x C-q in a resource YAML buffer to edit it, C-c C-c to apply

3.2 Browse Resources ¶

Kubed gives you an interactive list of resources for each type, that you access with the kubed-list-resources commands, such as kubed-list-pods.

These commands are bound to l in Kubed’s type-specific prefix keymaps, most of which are accessible via the global kubed-prefix-map by default (see Definition of kubed-prefix-map). So if you’ve bound kubed-prefix-map to C-c k, you can pop up the pods list with C-c k p l, the deployments list with C-c k d l, the jobs list with C-c k j l, etc. Normally, Kubed shows the list of resources in the current namespace, but if you invoke these commands with a prefix argument (say, C-u C-c k p l), they first prompt you to select a namespace, and then show resources in the namespace you selected.

The list of resources in shown a buffer called *Kubed resources@namespace[context]*, where context is a kubectl context, and namespace is a namespace in context. For example, Kubed shows the list of pods in namespace ‘default’ for context ‘minikube’ in buffer *Kubed pos@default[minikube]. For non-namespaced resources, the ‘@namespace’ part is omitted.

Each resource type has its own major mode for list buffers with type-specific commands and operations, but they are all also derived from a shared parent mode. The pods list uses the kubed-pods-mode (‘Kubernetes Pods’) major mode, the list of Kubernetes deployments uses kubed-deployments-mode, and so on.

Browse your pods, deployments, and other resources with Kubed list buffers

The common parent major mode is kubed-list-mode:

Major Mode: kubed-list-mode ¶

Major mode for listing generic Kubernetes resources.

This mode provides the following commands for all type-specific derived modes:

? ¶

Show help in transient menu (kubed-list-transient).

RET

Display the resource at point in the current window (kubed-list-select-resource).

o

Display the resource at point in another window and select that window (kubed-list-select-resource-other-window).

C-o

Display the resource at point in another window without selecting it (kubed-list-display-resource).

D

Delete the resource at point (kubed-list-delete).

e

Edit the resource at point (kubed-list-edit).

P

Patch the resource at point (kubed-list-patch).

g

Update the resources list by fetching new information from Kubernetes (kubed-list-update).

/

Filter the current list of resources (kubed-list-set-filter). See Filtering Resource Lists.

d

Mark the resource at point for deletion (kubed-list-mark-for-deletion). Resources marked for deletion have a ‘D’ in the beginning of their line.

x

Delete marked resources (kubed-list-delete-marked).

u

Unmark from resource at point (kubed-list-unmark).

w

Copy name of resource at point into the kill ring (kubed-list-copy-as-kill).

n

Move point to the next line (next-line).

p

Move point to the previous line (previous-line).

TAB

Move point to the next column. If point is already at the last column, move to the first column of the next line instead (kubed-list-next-column).

S-TAB

Move point to the previous column. If point is already at the first column, move to the last column of the previous line instead (kubed-list-previous-column).

S

Sort lines by the column at point (tabulated-list-sort).

|

Fit width of column at point to its content (kubed-list-fit-column-width-to-content). With non-negative prefix argument n (for example, 0 |), fit nth column. With negative prefix argument (- |), fit all columns.

{

Narrow the column at point (tabulated-list-narrow-current-column).

}

Widen the column at point (tabulated-list-widen-current-column).

In addition, you can bookmark any Kubed resources list buffer with the usual C-x r m. See (emacs)Bookmarks.

Note that kubed-list-mode (and its type-specific derivatives) bind the g key, which is commonly bound to revert-buffer, to kubed-list-update. The difference between these commands is that revert-buffer only refreshes the list display, without fetching updated data from Kubernetes. You can still invoke revert-buffer with C-x x g or M-x, if you need it.

Whenever Kubed is fetching data from Kubernetes to update a resources list buffer, the mode line of that list buffer shows the ‘[...]’ indicator. You can set user option kubed-list-mode-line-format to customize this indicator.

• Filtering Resource Lists

(= Name foobar) (~ Namespace kube)

(= Name foobar) '(~ Namespace kube)

((= Name spam) (= Name foobar)) '(~ Namespace kube)

3.3 Resource Logs ¶

Kubed lets you view logs of containers running in Kubernetes, using kubectl logs under the hood. The most general command for viewing logs is kubed-logs, which is bound to L in kubed-prefix-map (see Definition of kubed-prefix-map):

Command: kubed-logs ¶

Show logs for containers running in a Kubernetes resource. This command asks you for a resource type and name, and pops up a buffer with the logs of the containers running in that resource.

In resource list buffers that support logs—such as those for pods, deployments, services, and jobs—you can view logs for the resource at point directly:

l ¶

Show logs for the resource at point (kubed-list-logs). Kubed opens a new buffer with the log output.

L ¶

Open a type-specific logs transient menu for the resource at point, with the resource pre-selected. Kubed also pre-populates the ‘--tail’ and ‘--follow’ options from kubed-logs-tail-lines and kubed-logs-follow, which you can adjust before invoking the command. See Transient Menus.

Two user options control the default behavior of these commands:

User Option: kubed-logs-tail-lines ¶

Number of most recent log lines to fetch and show when displaying Kubernetes logs. The default is 128. Set this option to 0 to show all available log lines without limit.

User Option: kubed-logs-follow ¶

Whether to follow new log entries when displaying Kubernetes logs. The default is t.

When Kubed sets up a buffer for displaying logs, it runs the following hook:

User Option: kubed-logs-setup-hook ¶

List of functions to call, in order, to set up Kubernetes logs buffers. The default value is (view-mode).

3.4 Context and Namespace ¶

Kubed uses kubectl to interact with Kubernetes clusters, and you can use multiple kubectl contexts in Kubed to work with different Kubernetes clusters in parallel. Within each context, Kubed lets you work in multiple namespaces too. In general, each buffer has its own local context and local namespace, and Kubed commands use these local context and namespace by default. This is similar to how different buffers have different values of default-directory (see (emacs)File Names), and how that affects commands that interact with the filesystem.

For Kubed buffers that display a Kubernetes resource (see Display Resource) or a list of resources (see Browse Resources), the buffer-local context and namespace are the context and namespace of the resources the buffer displays. For non-Kubed buffers, the user option kubed-default-context-and-namespace-alist determines the default local context and namespace.

In addition to kubectl contexts, Kubed is aware of the host on which it invokes kubectl. When default-directory is a remote location (see (emacs)Remote Files), Kubed runs kubectl on that remote host rather than on the local machine. Each host has its own independent set of kubectl contexts, so you can simultaneously work with Kubernetes clusters reachable from different hosts. See Kubed over Tramp for more details.

User Option: kubed-default-context-and-namespace-alist ¶

Association list mapping hosts to their default kubectl context and Kubernetes namespace for Kubed commands. Each entry is a cons cell (host . context-and-namespace), where host is either a string identifying a connection to the host (as returned by file-remote-p, e.g. /ssh:user@some.host:), or nil for the local host. context-and-namespace is either a cons cell (context . namespace), or nil. If it is nil, Kubed initializes the entry to a cons cell with the current kubectl context and the default namespace of that context on the first time Kubed consults this option for the given host.

For example, you can configure Kubed to use the my-context context and my-namespace namespace on the local host by default as follows:

(setopt kubed-default-context-and-namespace-alist
        '((nil . ("my-context" . "my-namespace"))))

;; Or, if you want to preserves other entries:

(setf (alist-get nil kubed-default-context-and-namespace-alist)
      '("my-context" . "my-namespace"))

Variable: kubed-default-context-and-namespace ¶

This is an obsolete variable that served a similar purpose as kubed-default-context-and-namespace-alist prior to Kubed gaining support for remote hosts. For backward compatibility with user configurations that set this variable, Kubed by default initializes the local host entry in kubed-default-context-and-namespace-alist from the value of this variable if it is set.

As mentioned above, most Kubed commands use the buffer-local context and namespace if available by default. It is also conventional for Kubed commands to let you choose a different namespace if you invoke them with a prefix argument (C-u), and to also let you choose a different context if you invoke them with a double prefix argument (C-u C-u).

The following functions return the buffer-local context and namespace for the buffer in which you call them:

Function: kubed-local-context ¶

Return the local kubectl context for the current buffer.

Function: kubed-local-namespace ¶

Return the local Kubernetes namespace for the current buffer.

Function: kubed-local-context-and-namespace ¶

Return the local context and namespace for the current buffer as a cons cell (context . namespace).

3.5 Transient Menus ¶

Kubed provides a set of keyboard-driven transient menus (see (transient)Top) that you can use to explore and invoke various commands. Transient menus show you available commands along with their key bindings, which helps you use many different commands without the need to remember the key bindings for all them. Additionally, the transient menus allow you to specify options and switches for the commands you invoke, which may not be available when invoking these commands directly. For example, while you can invoke command kubed-logs directly to view logs from a container running in Kubernetes (see Resource Logs), the “Kubernetes Logs” transient menu which you open with kubed-transient-logs lets you set a maximum number of logs to retrieve, among other knobs and handles.

Explore Kubed commands with transient menus

Command kubed-transient opens the Kubed “root” transient menu, which is a dispatch that lets you access different transient menus, such as the aforementioned “Kubernetes Logs” transient menu. It’s a good idea to bind kubed-transient to a convenient key:

(keymap-global-set "s-k" #'kubed-transient)

By default, kubed-transient is bound to k in kubed-prefix-map, so if you bind the prefix map to C-c k you can open the root transient menu with C-c k k. See Definition of kubed-prefix-map.

In Kubed resource list buffers, type ? to pop up a transient menu with commands that are specific to the type of resources the buffer displays. See Browse Resources.

3.6 Scale Deployment ¶

You can use Kubed to scale Kubernetes a deployment, which means setting the size of the deployment in terms of the number of replicas it governs.

Command: kubed-scale-deployment ¶

Scale a Kubernetes deployment.

kubed-scale-deployment is bound to $ in the kubed-deployment-prefix-map, so if you have kubed-prefix-map bound to C-c k then you can invoke it with C-c k d $. See Definition of kubed-prefix-map. This command prompts you for a deployment and then lets you select a new number of replicas for that deployment. By default you are prompted for deployment in the local context and namespace (see Context and Namespace); with a prefix argument, you can specify a different namespace; with a double prefix argument (C-u C-u), you can specify a different context too.

In the deployments list buffer, you can scale the deployment at point by simply typing $. See Browse Resources.

Scale deployments with $ in the deployments list buffer

Lastly, you can scale deployments using the transient menu kubed-transient-scale-deployment, which is available from the main Kubed transient by pressing $. See Transient Menus.

3.7 Kubed over Tramp ¶

Kubed can run kubectl on remote hosts, letting you manage Kubernetes clusters that are only reachable from a specific machine, or use a kubectl installation that lives on a remote server. This works by leveraging Emacs’s Tramp remote file access facility (see (tramp)Top).

Essentially, Kubed respects the value of default-directory when deciding where to run kubectl. When default-directory refers to a local directory, Kubed invokes the local kubectl. When default-directory refers to a remote directory (i.e., it is a Tramp file name), Kubed instead invokes kubectl on the corresponding remote host. This means that you can point Kubed at a remote host simply by visiting a remote directory via Tramp—for example, by opening a file on a remote server with C-x C-f and Tramp file name syntax, such as /ssh:user@some.host:/home/user/.

Each remote host has its own independent set of kubectl contexts and namespaces. Kubed keeps track of the default context and namespace per host in the user option kubed-default-context-and-namespace-alist (see Context and Namespace). When Kubed list buffers are showing resources fetched from a remote host, the buffer name includes ‘ from host’ to make it clear which host was used.

You may have kubectl installed at different paths on different hosts, or you may want to use a wrapper script instead of the bare kubectl executable on some hosts. Kubed consults the connection-local value of option kubed-kubectl-program to determine how to invoke kubectl, so you can configure the kubectl executable per host. For example, to tell Kubed to use /home/user/.local/bin/kubectl on ‘some.host’, add the following to your Emacs initialization file:

(connection-local-set-profile-variables
 'my-kubed-profile-for-somehost
 '((kubed-kubectl-program . "/home/user/.local/bin/kubectl")))

(connection-local-set-profiles
 '(:application kubed :machine "some.host")
 'my-kubed-profile-for-somehost)