This manual is for Kubed 0.4.0, a rich Emacs interface for Kubernetes.
Kubed is a rich Kubernetes interface within Emacs. It helps you work
with your Kubernetes clusters and deployments with the full power of
kubectl, and with the comfort and confidence of an intuitive
interactive interface.
You can use Kubed to:
These features and others are documented in the rest of this manual, along with many options that Kubed provides for you to customize its behavior.
Get Kubed from GNU ELPA with M-x package-install, or use your favorite Emacs package manager to install Kubed from Git. You can clone the Kubed Git repository from any of the following locations:
To get started with Kubed, all you need is kubectl and Emacs.
Kubed tries to find kubectl in the directories listed in the
Emacs variable exec-path. When Emacs is started from a shell, it
initializes exec-path from the shell’s PATH environment
variable which normally includes the location of kubectl in
common kubectl installations. If Emacs doesn’t find the
kubectl executable via exec-path, you can tell Kubed
where to find it by customizing kubed-kubectl-program.
Name of kubectl executable file to use.
Kubed comes with a large number of Emacs command for interacting with Kubernetes. Some commands perform one action on one resource, while others show you a menu with many resources and let you interact with any number of them. Some commands are specific to one type of resources, while others act on resources of any type. There are different ways to use Kubed, depending on your use case.
The two most important entry points for Kubed are
kubed-prefix-map and kubed-transient:
Keymap with bindings for many useful Kubed commands.
The prefix keymap kubed-prefix-map gives you quick access to the
main Kubed commands. You may want to bind it to a convenient key in
your global keymap, for example:
(keymap-global-set "C-c k" 'kubed-prefix-map)
With this binding in place, you can create a new Kubernetes resource with C-c k + and attach to a running pod with C-c k p a. The C-c k binding is just a suggestion of course, feel free to pick any key sequence you like.
You can also access all of the commands in kubed-prefix-map via
the menu-bar ‘Kubernetes’ menu—to add this menu to your
menu-bar, enable the global minor mode kubed-menu-bar-mode:
The other important entry point that Kubed provides for exploring and
performing different Kubernetes operations is kubed-transient:
Open the main Kubed transient menu.
This command pops up the Kubed transient menu, which gives you interactive guidance for invoking Kubed commands. See (transient)Top.
The following sections describe in detail the various Kubed commands.
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:
Display a Kubernetes resource.
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:
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 for buffers that display a Kubernetes resource.
This minor mode does the following:
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.
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.
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.
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.
The common parent major mode is kubed-list-mode:
Major mode for listing generic Kubernetes resources.
This mode provides the following commands for all type-specific derived modes:
Display the resource at point in the current window
(kubed-list-select-resource).
Display the resource at point in another window and select that window
(kubed-list-select-resource-other-window).
Display the resource at point in another window without selecting it
(kubed-list-display-resource).
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.
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.
Copy name of resource at point into the kill ring
(kubed-list-copy-as-kill).
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).
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).
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.
In all Kubernetes resource list buffers, you can use /
(kubed-list-set-filter) to filter the list of resources.
This command sets the filter of the current buffer, which specifies
conditions on resources (lines). Resources that don’t satisfy the
conditions are hidden, so you can focus on those that do.
Filters can be simple (atomic filters) or complex (composed filters). In the simple case, you enter a filter in the minibuffer in the format ‘op col val’, where op is a comparison operator, one of ‘=’, ‘~’, ‘<’ and ‘>’; col is a column name; and val is a value to compare to values of col with op.
If op is ‘=’, it says to keep only lines whose col equals val. If op is ‘~’, it says to keep lines whose col matches the val as a regular expression. ‘<’ and ‘>’ compare column values to numeric values. For example, the filter ‘= Name foobar’ keeps only resources whose name is ‘foobar’. To include whitespace in val, wrap val in double quotes: ‘= Name "foo bar"’.
The possible values of op and their meanings are defined in
kubed-list-filter-operator-alist, which is a user option you
can use to add or change the meaning of filter operators:
Association list of filter operators and corresponding Emacs Lisp functions. See the documentation string of this option for specifics.
You can use more refined filters by composing simple filters. To add another filter that resources must satisfy, wrap your two filters in parentheses and put them next to each other:
(= Name foobar) (~ Namespace kube)
This filter keeps only resources whose name is ‘foobar’ in namespaces that include ‘kube’ as a substring, it expresses the conjunction of the two simple filters.
To negate a simple filter, put a single quote ahead of it, like so:
(= Name foobar) '(~ Namespace kube)
This matches resources named ‘foobar’ in namespaces that do not contain ‘kube’.
To specify a disjunction of simple filters (and negated simple filters), add another level of nesting:
((= Name spam) (= Name foobar)) '(~ Namespace kube)
This filter matches resources named either ‘spam’ or ‘foobar’, in namespaces that do not contain ‘kube’.
While entering a filter in the minibuffer, TAB completion is available for column names and values. To clear the filter, just exit the minibuffer with an empty input.
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 determines the
default local context and namespace.
Default kubectl context and Kubernetes namespace for Kubed
commands. The value of this option is either a cons cell
(context . namespace) or nil. If it is
nil, Kubed initializes this option to a cons cell with the
current kubectl context and namespace for that context on
the first time Kubed consults this option.
As mentioned above, most Kubed commands use the local context and namespace 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 local context and namespace for buffer in which you call them:
Return the local kubectl context for the current buffer.
Return the local Kubernetes namespace for the current buffer.
Return the local context and namespace for the current buffer as a
cons cell (context . namespace).
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, 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.
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,
either in the global keymap or under kubed-prefix-map:
(keymap-global-set "s-k" #'kubed-transient) (keymap-set kubed-prefix-map "k" #'kubed-transient)
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.
Kubed has built-in support for many common types of Kubernetes
resources. “Support” for a resource type in Kubed just means
providing common commands for working with resources of that type,
such as a command for showing the interactive list of these resources,
like kubed-list-pods for Kubernetes pods. In Kubed, the macro
kubed-define-resource is used to define these common commands
and add support for more resource types:
Define commands for resource.
Say you want to add support for your Kubernetes service accounts.
With kubed-define-resource, all you need to do is to add the
following line to your Emacs initialization file:
(kubed-define-resource serviceaccount)
This line defines the following commands for you:
kubed-display-serviceaccount
kubed-list-serviceaccounts
kubed-edit-serviceaccount
kubed-delete-serviceaccount
kubed-create-serviceaccount
kubed-explain-serviceaccounts
See the documentation string of kubed-define-resource
(C-h f) for details about the optional arguments of this
macro: the properties argument which lets you specify what Kubed
should show in the resource list buffer and the commands argument
which lets you associate additional commands with your resource type.
We highly appreciate all contributions, including bug reports, patches, improvement suggestions, and general feedback!
The best way to get in touch with the Kubed maintainers is via the Kubed mailing list.
Report a bug in Kubed to the maintainers via mail.
You can use the command M-x kubed-submit-bug-report to easily contact the Kubed maintainers from within Emacs. This command opens a new buffer with a message template ready to be sent to the development mailing list.
| Jump to: | K N P R T |
|---|
| Jump to: | K N P R T |
|---|
| Jump to: | ?
{
}
/
|
C D E G N O P R S T U W X |
|---|
| Jump to: | ?
{
}
/
|
C D E G N O P R S T U W X |
|---|
| Jump to: | G I K P R |
|---|
| Index Entry | Section | |
|---|---|---|
| G | ||
| global prefix keymap | Usage | |
| I | ||
| installation | Getting Started | |
| K | ||
| keymap, for global commands | Usage | |
| Kubed | Overview | |
| kubed | Overview | |
| P | ||
| prefix keymap, global commands | Usage | |
| R | ||
| requirements | Getting Started | |
| Jump to: | G I K P R |
|---|