Info
+This page is a work-in-progress. More to come!
+Thanks for your interest in contributing to Kele! We’re glad to have you. 
This page will give you all (well, most) of the information you’ll need to get +started.
+Every symbol should be documented. This applies to both “public”
+(kele-function-name) and “private” (kele--function-name) symbols.
Kele’s documentation loosely follows the Diataxis framework.
+All new functionality should have corresponding user-facing +documentation. Function docstrings are not a substitute for proper user-facing +tutorials, usage instructions, etc.
+We keep a changelog for Kele. Any change that is user-facing should be called +out in the changelog.
+We use architecture decision records (ADRs) in Kele very sparingly. Not every design +decision made warrants an ADR of its own. As a contributor, you may be asked to write an ADR for your contribution, but +only if it materially impacts Kele’s user-facing behavior.
+We use Buttercup to write tests.
+All PRs should have corresponding unit/integration tests. I am far more likely +to review and generally consider your PR if it has tests.
+ + + + + + +This page compares Kele with some of its peer packages.
+Note
+Given Kele’s relative infancy, this page compares less on concrete +features and capabilities and more on design philosophy and overall +goals. All packages listed here are, as of today, far more feature-complete +than Kele.
+kubernetes-el is a Kubernetes cluster management package for Emacs. It draws +heavy inspiration from Magit, from its “status page”-centric interface +design down to its prevalent use of Transient-based keybindings.
+Kele itself draws inspiration from kubernetes-el. In fact, the author of Kele +is a co-maintainer of kubernetes-el.
+Kele draws from some lessons learned during kubernetes-el development and +strives for a cluster management experience that has +PLANS. Kele aims for a Kubernetes cluster management +experience that is less intrusive, requires less context-switching, and is +overall more performant than kubernetes-el. If Kele proves to be flexible +enough that kubernetes-el could be re-implemented on top of Kele, then that’s +a sign that we’ve done a good job here.
+More critically, however, one of kubernetes-el‘s biggest limitations is its
+lack of support for custom resources. Not only does this
+limitation impose a very low ceiling on the package’s utility, the design
+decisions underpinning that limitation extend to kubernetes-el‘s incomplete
+support for the Kubernetes core API (see
+kubernetes-el/kubernetes-el#306. Overhauling the
+associated design decisions would amount, in my co-maintainer’s opinion, to a
+complete rewrite of kubernetes-el – hence my decision to kick off
+development on Kele.
kubel is a similar “UI-centric” cluster management package to +kubernetes-el. Its advantage over kubernetes-el is its accommodation of +users with limited privilege/permissions within the clusters in question.
+Similar to kubernetes-el, Kele focuses on providing a cluster management +experience that is more “piecemeal” (“get this targeted piece of information as +quickly as possible and move on with your life”) and requires less +context-switching – unavoidable with a status-page-centric user interface – +than kubel.
+ + + + + + +This page goes into some of the design particulars of Kele. As an end user, feel free to explore at your curiosity, but +rest assured that none of the information here is strictly necessary for your successful use of Kele.
+Tip
+This page may at times contain forward-looking statements, e.g. of design +details that are upcoming but have not yet made their way into the main +branch.
+Kele revolves around two main in-memory caches:
+kubeconfig contents (kele--kubeconfig);kele--discovery-cache).Both of these caches are populated asynchronously on kele-mode initialization.
The kubeconfig cache is kept in sync via a file watcher, which allows Kele to only incur read costs when
+they’re actually needed. This is particularly useful for the kubeconfig cache, since the Kubeconfig itself is only
+occasionally modified in response to discrete user events, such as switching context or the default namespace for a
+given context. In combination with asynchronous IO via the async package, Kele is able to keep itself in sync
+with the underlying Kube configurations and caches without deadlocking users’ Emacs environment.
On the other hand, the discovery cache is timer-based and pulls the contents of the discovery cache from the filesystem
+at a set interval, as dictated by kele-discovery-refresh-interval.
Why?
+We elect not to use file-watchers for the discovery cache due to the risk of completely exhausting the file
+descriptors Emacs can use. For more details, see adr-01.
Kele is well-integrated with the Emacs ecosystem.
+Kele is integrated with the Emacs menu bar. The Kubernetes section lets +you achieve many of the tasks that you’d normally use keybindings for.
+
This page outlines the customization options available to you in Kele.
+Kele comes with a spread of recommended keybindings predefined as part of
+kele-command-map. kele-command-map is not assigned to a keybinding by
+default, so as to be minimally disruptive to your personal configurations.
Using kele-command-map, you can choose your own keybinding to act as the
+keybinding prefix for all of Kele’s keybindings.
To bind, say, s-k as the keybinding prefix:
(define-key kele-mode-map (kbd "s-k") kele-command-map)
+Now you can use, for example, s-k c to access context-related
+commands. Give it a try!
When displaying a single resource
+with kele-get, kele-get retrieves the full manifest for the requested
+resource. This may include “noisy” sub-fields like
+.metadata.managedFields or the
+kubectl.kubernetes.io/last-applied-configuration
+annotation that distract from the “important” bits.
You can routinely filter out such fields using the kele-filtered-fields custom
+variable. For example, to filter out both of the above:
(setq kele-filtered-fields
+ '((metadata managedFields)
+ (metadata annotations kubectl.kubernetes.io/last-applied-configuration)))
+The results buffer for kele-get prints out a header blurb outlining the
+keybindings available to you. If this is distracting to you or offends your
+minimalist tendencies, use kele-get-show-instructions to disable printing of
+the kele-get result buffer’s keybindings.
(setq kele-get-show-instructions nil)
+Kele provides a handful of customization variables with which you can influence cache +behavior.
+If you’d like Kele to poll the discovery cache more or less frequently than the default, set
+kele-discovery-refresh-interval, then disable and re-enable kele-mode.
(setq kele-discovery-refresh-interval)
+(kele-mode -1)
+(kele-mode +1)
+There is a potential for Kele’s copy of the discovery cache to have outdated (relative to clusters’ “true” state)
+information, even immediately after a poll. This is due to Kele’s polling interval being separate from kubectl‘s
+own default TTL for the discovery cache, which is 10 minutes “lazily” (that is, the cache is invalidated and its
+contents re-pulled at the next kubectl invocation after 10 minutes).
Given Kele’s extensive usage of kubectl under the hood, this should rarely present an actual issue to you as a
+user. If it does, consider pegging the value of kele-discovery-refresh-interval to hover roughly around 10
+minutes. The default value of kele-discovery-refresh-interval is 600 seconds, i.e. 10 minutes.
Kele contains several integrations with select packages.
+awesome-tray “folds” the
+modeline into the minibuffer for a compact UI.
Kele ships with awesome-tray integration that will display the current context
+and namespace in your “modeline.”
To enable, simply add "kele" to your desired place in
+awesome-tray-active-modules, like so:
(add-to-list 'awesome-tray-active-modules "kele" t)
+Note
+You’ll notice this page is pretty sparse. Kele is an early-stage package +with lots of room to grow. Stay tuned for more!
+Note
+Kele doesn’t have a default keybinding prefix for its commands. All examples
+documented here assume that you’ve opted for s-k.
For instructions on how to set your own keybinding prefix, see: How-Tos > +Customization.
+| Keybinding | +Interactive function | +
|---|---|
s-k ? |
+kele-dispatch |
+
Kele provides kele-dispatch as a launchpad for all subsequent Kele
+functionality. If you ever forget what the keybinding is for what you’re trying
+to accomplish, reach for kele-dispatch.
Interacting with resources in Kele centers around the s-k r prefix, which is
+bound to kele-resource.
kele-resource allows you to act on specific resource kinds. With
+kele-resource, you can, for example:
kele-resource supports custom resources too!
kele-resource will first prompt you to select the kind that you’d like to
+work with, after which you can choose to get a specific object of that kind
+by name. If the resource is namespaced, you will also be presented with the
+option to choose the namespace to select from.
You can get a single resource of the given kind with: +
s-k r <kind name> g <resource name>`
+This is bound to kele-get.
You can list all resources of a single kind with: +
s-k r <kind name> l
+This is bound to kele-list.
This will list all resources of the specified group-version and kind in a +separate buffer in a table. From here, you can:
+g;RET on any of the entries to display its full manifest in a
+ separate buffer.You can press g in a kele-get buffer to re-fetch and refresh the current resource.
Kele commands involving Kubernetes contexts center around the s-k c prefix (kele-config).
| Keybinding | +Functionality | +Interactive function | +Demo | +
|---|---|---|---|
s-k c s |
+Switching from one context to another | +kele-context-switch |
+ |
+
s-k c r |
+Renaming a context | +kele-context-rename |
+ |
+
s-k c d |
+Deleting a context | +kele-context-delete |
++ |
s-k c n |
+Changing the default namespace | +kele-namespace-switch-for-current-context |
++ |
Tip
+Most context-related Kele functionality can also be done via Embark on any +completion candidate in any context-related Kele command.
+Kele allows for starting and stopping HTTP +proxies +for each context. The status of each context’s proxy is displayed in the +annotations for each cluster completion candidate.
+
Note
+Any proxy server created via Kele is ephemeral; they are automatically
+closed and terminated after a set amount of time. For more details, see
+kele-proxy-ttl.
Note
+Each context can only have one proxy server active at a time. This is an +artificial limitation put in place by Kele.
+| Keybinding | +Functionality | +Interactive function | +
|---|---|---|
s-k p p |
+Start/stop proxy server process for the current context | +kele-proxy-toggle |
+
s-k p P |
+Start/stop proxy server process for a specific context | +kele-proxy-toggle |
+
+
+
Kele (kě lè, or kə-ˈlə) (“Kubernetes Enablement Layer for Emacs”) is a +Kubernetes cluster management package. It empowers you to perform operations as +coarse or fine-grained as you need, fast, and get back to your work.
+With Kele, you can:
+See How-Tos > Usage for more details on what’s possible +with Kele.
+
+
Tip
+To learn more about how Kele compares to some other Kubernetes packages for +Emacs, see: Explanations > Comparisons with Similar +Packages/Tools.
+Note
+Kele is not an official Kubernetes project.
+Kele requires Emacs 28.1+.
+
(use-package kele
+ :config
+ (kele-mode 1)
+ (bind-key (kbd "s-k") kele-command-map kele-mode-map))
+Kele aims to have PLANS. Namely, it aims to be:
+kubectl to get
+ the info you need instead of Kele, then Kele has failed;The name Kele comes from the Mandarin term for cola, 可乐 (kě lè). It is +also an abbreviation of “Kubernetes Enablement Layer for Emacs.”
+ + + + + + + + +Implemented in #150.
+As of 2023-03-05, Kele uses a naive set of two separate caches:
+kele-kubeconfig-path);Note
+The latter, confusingly, shares the same name with the discovery cache that
+lives in the user’s filesystem, typically under
+~/.kube/cache/discovery. We use “discovery cache” to refer specifically
+to the Kele data structure, and use “filesystem discovery cache” to refer to
+the “actual” discovery cache.
On enablement of kele-mode, Kele initializes both the kubeconfig cache and the discovery cache. The kubeconfig cache
+loads the contents of the user’s kubeconfig file into memory; likewise, the discovery cache loads the contents of the
+user’s filesystem discovery cache into memory. Both caches initialize [file watchers] that “auto-refresh” the respective
+cache contents on changes to the underlying file(s).
The combined use of these two caches enables near-instant completion of:
+The aforementioned “all-at-once” approach has proven to have several shortcomings.
+The most fundamental problem is that the discovery cache does not scale. Emacs file-watching uses file descriptors +under the hood, which Emacs has a [finite number available for use at any given time][1]. Exceeding this limit results +in an error to the following effect:
+File watching not possible, no file descriptor left: 975
+This limit is, to my knowledge, not user-configurable. Even if it were, it is an unreasonably invasive thing to ask +users to do – for an Emacs package of all things. Most notably, this limit is, like all things, shared globally +within Emacs, e.g. by [LSP-Mode][lsp-mode] and [auto-revert-mode], making the “real” limit for Kele much lower. In order +to be a “good Emacs citizen,” Kele needs to be much more conservative and strategic in its use of file-watchers.
+We note that it is very easy to hit this limit. Anecdotally, I maintain kubectl access to a handful of +production-scale clusters as part of my day job, and simply adding a couple more ad-hoc [Kind] clusters as part of +integration-testing for this very package is enough for me to hit the limit. Doing so requires me to manually delete the +filesystem discovery cache directories corresponding to these transient Kind clusters On top of being annoying, this is +also a fundamentally unreasonable workaround; what happens if a user simply has that many clusters to maintain?
+The simplest and “stupidest” solution to this problem is to make caching of the filesystem discovery cache timer-based +rather than filewatch-based.
+This approach represents, to an extent, a “regression” of sorts in the functionality of the discovery cache, as now the
+contents thereof are not guaranteed to be fully up-to-date with those of the filesystem dicovery cache. We decide that
+this is safe, as the set of group-version-kinds present in a cluster are unlikely to change that frequently. This is
+consistent with kubectl‘s own refresh policy for the filesystem discovery cache, which refills the cache every ten
+minutes – and lazily, at that, i.e. on the next user invocation of kubectl after the ten-minute mark.
This section collects “architecture decision records (ADRs)” for Kele. These are records of “architecturally +significant” decisions, that materially impact Kele’s design and capabilities.
+Tip
+For more information about ADRs, see Michael Nygard’s seminal post “Documenting Architecture Decisions”.
+All notable changes to this project will be documented here.
+The format is based on Keep a Changelog, +and this project adheres to semantic +versioning.
+kele-mode errors out when the kubeconfig file does not
+ exist yetcurl errors are not properly caught, resulting in attempts
+ to query the kubectl proxy server before it is readyplz from 0.3 to 0.7.3awesome-traykele-resource, result in false-positive
+ timeout errors when starting up the proxy server.Lots of fun stuff in this release.
+Most importantly, Kele 0.4.0 introduces kele-list (s-k <resource type> l)
+and – with it – the ability to list all resources of a given type in tabulated
+form. Before, you could only fetch single resources. Now, with kele-list, you
+can create ad-hoc “overviews” of specific resource types within a given context
+and namespace; hitting Enter on any entry in this list brings up the resource’s
+full manifest.
Kele 0.4.0 also introduces the kele-proxy command palette (s-k p) for
+starting/stopping proxy servers for contexts. It also fleshes out the Kubeconfig
+management command palette (s-k c).
For more details, see: How-Tos > Usage.
+kele-proxy command prefix for managing proxy serverskele-context to enable/disable the proxy server for
+ the current contextkele-context for deleting a contextkele-kubeconfig-path in a bufferkele-resource to support listing out all resources of
+ a given type (kele-list)kele-context and kele-resource now wait on kubeconfig sync completion to
+ finish if one is currently in progresskele-mode (via either
+ (kele-mode 1) or (kele-mode -1)) when kele-mode is already active or
+ inactive (respectively) resulted in errorss-k <resource name> g sometimes
+ results in the following error: transient-setup: Suffix
+ transient:kele-resource::command is not defined or autoloaded as a commandkele-context to kele-configkele-proxy-ttl from 60 to 180kele-get in kele-get-mode changed from U to gThis release focuses on providing Kele’s command palette and user interface with
+a scalable foundation for future growth. As Kele’s spread of user-facing
+commands grows, it becomes less and less reasonable to expect users to M-x
+everything.
To that end, this release adds the following:
+kele-context,
+ kele-resource, and kele-dispatch – for nested command discovery and
+ ad-hoc configuration, e.g. overriding the context and namespace to use for
+ resource fetching. Again, see How-Tos > Usage for more details.I’m optimistic that these two additions make Kele’s user interface much more +pleasant and nimble, while also giving it ample room to grow in complexity and +scope in the coming releases.
+kele-get resource name input now supports completion! 
kele-get buffers now have keybindings for quitting and killing the resource
+ display bufferU in kele-get buffers to re-fetch and refresh the
+ current resourcekele-get buffers’ front matter now outlines the available keybindingskele-dispatch command for when you forget the specific keybinding of
+ what you’re trying to accomplishkele-context command prefix for context-related actionskele-resources command prefix for acting on specific resource kinds,
+ e.g. getting, with support for selecting the context, namespace, and the
+ group-version to use (in cases of ambiguity)srequestsThis release focuses on refining the kele-get experience – usability
+improvements and general bugfixes.
kele-get buffers now have a dedicated minor mode, kele-get-mode.kele-get buffers now print a header detailing, for the resource under
+ display: the context it was fetched from; and the time of retrievalkele-filtered-fields with which you can routinely
+ filter out resource fields from display in kele-getkele-get results buffer incorrectly prints namespace
+ for un-namespaced resources as nilkele-get refused to display the retrieved resource, if
+ a buffer corresponding to that resource already existskele-get completion for the resource type now only returns resources that
+ support the get verbThis release introduces kele-get – kubectl get, the Emacs way
+
. With kele-get you can interactively specify the kind and name of the
+resource that you’d like to get and display its manifest in a separate
+buffer. What’s more, it supports custom resources right out the gate – a
+long-standing functionality gap in kubernetes-el.
See How-Tos > Usage > Working with +Resources for details and a demo +GIF. It’s very much an MVP so there are some rough edges. Please open an issue +for any peculiar behavior that you notice.
+kele-get for interactively getting and displaying a given
+ resourcekele-proxy-start, kele-proxy-stop, and kele-proxy-togglekele-mode resulted in an error reporting
+ unbound slot filewatch-id on kele--discovery-cachehttps://127.0.0.1:51134, were not recognized properlykele-cache-dir is now ~/.kube/cache; before it was
+ relative to the value of kele-kubeconfig-path (and unreliably so)kele-namespace-switch-for-context where the selection
+ candidates were pulled for the current context rather than the argument
+ contextkubectl
+ invocationsKele is born!
+This initial release of Kele has a very simple goal: “kubectx and
+kubens, but make it Emacs.” Its feature set is limited but lays the
+foundation – both in terms of implementation and “design philosophy” – for
+future enhancements.
This section contains technical descriptions of the inner workings and development of Kele. As a user, you will rarely +if ever need to read these contents; you’ll know if/when you do.
+ + + + + + +Kele (k\u011b l\u00e8, or k\u0259-\u02c8l\u0259) (\u201cKubernetes Enablement Layer for Emacs\u201d) is a Kubernetes cluster management package. It empowers you to perform operations as coarse or fine-grained as you need, fast, and get back to your work.
With Kele, you can:
See How-Tos > Usage for more details on what\u2019s possible with Kele.
Tip
To learn more about how Kele compares to some other Kubernetes packages for Emacs, see: Explanations > Comparisons with Similar Packages/Tools.
Note
Kele is not an official Kubernetes project.
"},{"location":"#getting-started","title":"Getting Started","text":"Kele requires Emacs 28.1+.
(use-package kele\n:config\n(kele-mode 1)\n(bind-key (kbd \"s-k\") kele-command-map kele-mode-map))\nKele aims to have PLANS. Namely, it aims to be:
kubectl to get the info you need instead of Kele, then Kele has failed;The name Kele comes from the Mandarin term for cola, \u53ef\u4e50 (k\u011b l\u00e8). It is also an abbreviation of \u201cKubernetes Enablement Layer for Emacs.\u201d
"},{"location":"contributing/","title":"Contributor Guide","text":"Info
This page is a work-in-progress. More to come!
Thanks for your interest in contributing to Kele! We\u2019re glad to have you.
This page will give you all (well, most) of the information you\u2019ll need to get started.
"},{"location":"contributing/#documentation","title":"Documentation","text":"Every symbol should be documented. This applies to both \u201cpublic\u201d (kele-function-name) and \u201cprivate\u201d (kele--function-name) symbols.
Kele\u2019s documentation loosely follows the Diataxis framework.
All new functionality should have corresponding user-facing documentation. Function docstrings are not a substitute for proper user-facing tutorials, usage instructions, etc.
"},{"location":"contributing/#changelog","title":"Changelog","text":"We keep a changelog for Kele. Any change that is user-facing should be called out in the changelog.
"},{"location":"contributing/#architecture-decision-records-adrs","title":"Architecture Decision Records (ADRs)","text":"We use architecture decision records (ADRs) in Kele very sparingly. Not every design decision made warrants an ADR of its own. As a contributor, you may be asked to write an ADR for your contribution, but only if it materially impacts Kele\u2019s user-facing behavior.
"},{"location":"contributing/#testing","title":"Testing","text":"We use Buttercup to write tests.
All PRs should have corresponding unit/integration tests. I am far more likely to review and generally consider your PR if it has tests.
"},{"location":"explanations/comparisons/","title":"Comparisons with Similar Packages/Tools","text":"This page compares Kele with some of its peer packages.
Note
Given Kele\u2019s relative infancy, this page compares less on concrete features and capabilities and more on design philosophy and overall goals. All packages listed here are, as of today, far more feature-complete than Kele.
"},{"location":"explanations/comparisons/#kubernetes-el","title":"kubernetes-el","text":"kubernetes-el is a Kubernetes cluster management package for Emacs. It draws heavy inspiration from Magit, from its \u201cstatus page\u201d-centric interface design down to its prevalent use of Transient-based keybindings.
Kele itself draws inspiration from kubernetes-el. In fact, the author of Kele is a co-maintainer of kubernetes-el.
Kele draws from some lessons learned during kubernetes-el development and strives for a cluster management experience that has PLANS. Kele aims for a Kubernetes cluster management experience that is less intrusive, requires less context-switching, and is overall more performant than kubernetes-el. If Kele proves to be flexible enough that kubernetes-el could be re-implemented on top of Kele, then that\u2019s a sign that we\u2019ve done a good job here.
More critically, however, one of kubernetes-el\u2018s biggest limitations is its lack of support for custom resources. Not only does this limitation impose a very low ceiling on the package\u2019s utility, the design decisions underpinning that limitation extend to kubernetes-el\u2018s incomplete support for the Kubernetes core API (see kubernetes-el/kubernetes-el#306. Overhauling the associated design decisions would amount, in my co-maintainer\u2019s opinion, to a complete rewrite of kubernetes-el \u2013 hence my decision to kick off development on Kele.
kubel is a similar \u201cUI-centric\u201d cluster management package to kubernetes-el. Its advantage over kubernetes-el is its accommodation of users with limited privilege/permissions within the clusters in question.
Similar to kubernetes-el, Kele focuses on providing a cluster management experience that is more \u201cpiecemeal\u201d (\u201cget this targeted piece of information as quickly as possible and move on with your life\u201d) and requires less context-switching \u2013 unavoidable with a status-page-centric user interface \u2013 than kubel.
"},{"location":"explanations/design/","title":"Design","text":"This page goes into some of the design particulars of Kele. As an end user, feel free to explore at your curiosity, but rest assured that none of the information here is strictly necessary for your successful use of Kele.
Tip
This page may at times contain forward-looking statements, e.g. of design details that are upcoming but have not yet made their way into the main branch.
"},{"location":"explanations/design/#caches","title":"Caches","text":"Kele revolves around two main in-memory caches:
kubeconfig contents (kele--kubeconfig);kele--discovery-cache).Both of these caches are populated asynchronously on kele-mode initialization.
The kubeconfig cache is kept in sync via a file watcher, which allows Kele to only incur read costs when they\u2019re actually needed. This is particularly useful for the kubeconfig cache, since the Kubeconfig itself is only occasionally modified in response to discrete user events, such as switching context or the default namespace for a given context. In combination with asynchronous IO via the async package, Kele is able to keep itself in sync with the underlying Kube configurations and caches without deadlocking users\u2019 Emacs environment.
On the other hand, the discovery cache is timer-based and pulls the contents of the discovery cache from the filesystem at a set interval, as dictated by kele-discovery-refresh-interval.
Why?
We elect not to use file-watchers for the discovery cache due to the risk of completely exhausting the file descriptors Emacs can use. For more details, see adr-01.
Kele is well-integrated with the Emacs ecosystem.
"},{"location":"explanations/integrations/#menu-bar","title":"Menu Bar","text":"Kele is integrated with the Emacs menu bar. The Kubernetes section lets you achieve many of the tasks that you\u2019d normally use keybindings for.
"},{"location":"how-tos/customization/","title":"Customization","text":"This page outlines the customization options available to you in Kele.
"},{"location":"how-tos/customization/#keybindings","title":"Keybindings","text":""},{"location":"how-tos/customization/#defining-a-keybinding-prefix","title":"Defining a keybinding prefix","text":"Kele comes with a spread of recommended keybindings predefined as part of kele-command-map. kele-command-map is not assigned to a keybinding by default, so as to be minimally disruptive to your personal configurations.
Using kele-command-map, you can choose your own keybinding to act as the keybinding prefix for all of Kele\u2019s keybindings.
To bind, say, s-k as the keybinding prefix:
(define-key kele-mode-map (kbd \"s-k\") kele-command-map)\nNow you can use, for example, s-k c to access context-related commands. Give it a try!
When displaying a single resource with kele-get, kele-get retrieves the full manifest for the requested resource. This may include \u201cnoisy\u201d sub-fields like .metadata.managedFields or the kubectl.kubernetes.io/last-applied-configuration annotation that distract from the \u201cimportant\u201d bits.
You can routinely filter out such fields using the kele-filtered-fields custom variable. For example, to filter out both of the above:
(setq kele-filtered-fields\n'((metadata managedFields)\n(metadata annotations kubectl.kubernetes.io/last-applied-configuration)))\nThe results buffer for kele-get prints out a header blurb outlining the keybindings available to you. If this is distracting to you or offends your minimalist tendencies, use kele-get-show-instructions to disable printing of the kele-get result buffer\u2019s keybindings.
(setq kele-get-show-instructions nil)\nKele provides a handful of customization variables with which you can influence cache behavior.
"},{"location":"how-tos/customization/#change-the-discovery-cache-polling-interval","title":"Change the discovery cache polling interval","text":"If you\u2019d like Kele to poll the discovery cache more or less frequently than the default, set kele-discovery-refresh-interval, then disable and re-enable kele-mode.
(setq kele-discovery-refresh-interval)\n(kele-mode -1)\n(kele-mode +1)\nThere is a potential for Kele\u2019s copy of the discovery cache to have outdated (relative to clusters\u2019 \u201ctrue\u201d state) information, even immediately after a poll. This is due to Kele\u2019s polling interval being separate from kubectl\u2018s own default TTL for the discovery cache, which is 10 minutes \u201clazily\u201d (that is, the cache is invalidated and its contents re-pulled at the next kubectl invocation after 10 minutes).
Given Kele\u2019s extensive usage of kubectl under the hood, this should rarely present an actual issue to you as a user. If it does, consider pegging the value of kele-discovery-refresh-interval to hover roughly around 10 minutes. The default value of kele-discovery-refresh-interval is 600 seconds, i.e. 10 minutes.
Kele contains several integrations with select packages.
"},{"location":"how-tos/integrations/#awesome-tray","title":"awesome-tray","text":"awesome-tray \u201cfolds\u201d the modeline into the minibuffer for a compact UI.
Kele ships with awesome-tray integration that will display the current context and namespace in your \u201cmodeline.\u201d
To enable, simply add \"kele\" to your desired place in awesome-tray-active-modules, like so:
(add-to-list 'awesome-tray-active-modules \"kele\" t)\nNote
You\u2019ll notice this page is pretty sparse. Kele is an early-stage package with lots of room to grow. Stay tuned for more!
Note
Kele doesn\u2019t have a default keybinding prefix for its commands. All examples documented here assume that you\u2019ve opted for s-k.
For instructions on how to set your own keybinding prefix, see: How-Tos > Customization.
"},{"location":"how-tos/usage/#dispatch","title":"Dispatch","text":"Keybinding Interactive functions-k ? kele-dispatch Kele provides kele-dispatch as a launchpad for all subsequent Kele functionality. If you ever forget what the keybinding is for what you\u2019re trying to accomplish, reach for kele-dispatch.
Interacting with resources in Kele centers around the s-k r prefix, which is bound to kele-resource.
kele-resource allows you to act on specific resource kinds. With kele-resource, you can, for example:
kele-resource supports custom resources too!
kele-resource will first prompt you to select the kind that you\u2019d like to work with, after which you can choose to get a specific object of that kind by name. If the resource is namespaced, you will also be presented with the option to choose the namespace to select from.
You can get a single resource of the given kind with:
s-k r <kind name> g <resource name>`\nThis is bound to kele-get.
You can list all resources of a single kind with:
s-k r <kind name> l\nThis is bound to kele-list.
This will list all resources of the specified group-version and kind in a separate buffer in a table. From here, you can:
g;RET on any of the entries to display its full manifest in a separate buffer.You can press g in a kele-get buffer to re-fetch and refresh the current resource.
Kele commands involving Kubernetes contexts center around the s-k c prefix (kele-config).
s-k c s Switching from one context to another kele-context-switch s-k c r Renaming a context kele-context-rename s-k c d Deleting a context kele-context-delete s-k c n Changing the default namespace kele-namespace-switch-for-current-context Tip
Most context-related Kele functionality can also be done via Embark on any completion candidate in any context-related Kele command.
"},{"location":"how-tos/usage/#managing-proxy-servers","title":"Managing proxy servers","text":"Kele allows for starting and stopping HTTP proxies for each context. The status of each context\u2019s proxy is displayed in the annotations for each cluster completion candidate.
DemoNote
Any proxy server created via Kele is ephemeral; they are automatically closed and terminated after a set amount of time. For more details, see kele-proxy-ttl.
Note
Each context can only have one proxy server active at a time. This is an artificial limitation put in place by Kele.
Keybinding Functionality Interactive functions-k p p Start/stop proxy server process for the current context kele-proxy-toggle s-k p P Start/stop proxy server process for a specific context kele-proxy-toggle"},{"location":"references/","title":"References","text":"This section contains technical descriptions of the inner workings and development of Kele. As a user, you will rarely if ever need to read these contents; you\u2019ll know if/when you do.
"},{"location":"references/changelog/","title":"Changelog","text":"All notable changes to this project will be documented here.
The format is based on Keep a Changelog, and this project adheres to semantic versioning.
"},{"location":"references/changelog/#unreleased","title":"Unreleased","text":""},{"location":"references/changelog/#added","title":"Added","text":"kele-mode errors out when the kubeconfig file does not exist yetcurl errors are not properly caught, resulting in attempts to query the kubectl proxy server before it is readyplz from 0.3 to 0.7.3awesome-traykele-resource, result in false-positive timeout errors when starting up the proxy server.Lots of fun stuff in this release.
Most importantly, Kele 0.4.0 introduces kele-list (s-k <resource type> l) and \u2013 with it \u2013 the ability to list all resources of a given type in tabulated form. Before, you could only fetch single resources. Now, with kele-list, you can create ad-hoc \u201coverviews\u201d of specific resource types within a given context and namespace; hitting Enter on any entry in this list brings up the resource\u2019s full manifest.
Kele 0.4.0 also introduces the kele-proxy command palette (s-k p) for starting/stopping proxy servers for contexts. It also fleshes out the Kubeconfig management command palette (s-k c).
For more details, see: How-Tos > Usage.
"},{"location":"references/changelog/#added_1","title":"Added","text":"kele-proxy command prefix for managing proxy serverskele-context to enable/disable the proxy server for the current contextkele-context for deleting a contextkele-kubeconfig-path in a bufferkele-resource to support listing out all resources of a given type (kele-list)kele-context and kele-resource now wait on kubeconfig sync completion to finish if one is currently in progresskele-mode (via either (kele-mode 1) or (kele-mode -1)) when kele-mode is already active or inactive (respectively) resulted in errorss-k <resource name> g sometimes results in the following error: transient-setup: Suffix transient:kele-resource::command is not defined or autoloaded as a commandkele-context to kele-configkele-proxy-ttl from 60 to 180kele-get in kele-get-mode changed from U to gThis release focuses on providing Kele\u2019s command palette and user interface with a scalable foundation for future growth. As Kele\u2019s spread of user-facing commands grows, it becomes less and less reasonable to expect users to M-x everything.
To that end, this release adds the following:
kele-context, kele-resource, and kele-dispatch \u2013 for nested command discovery and ad-hoc configuration, e.g. overriding the context and namespace to use for resource fetching. Again, see How-Tos > Usage for more details.I\u2019m optimistic that these two additions make Kele\u2019s user interface much more pleasant and nimble, while also giving it ample room to grow in complexity and scope in the coming releases.
"},{"location":"references/changelog/#added_2","title":"Added","text":"kele-get resource name input now supports completion! kele-get buffers now have keybindings for quitting and killing the resource display bufferU in kele-get buffers to re-fetch and refresh the current resourcekele-get buffers\u2019 front matter now outlines the available keybindingskele-dispatch command for when you forget the specific keybinding of what you\u2019re trying to accomplishkele-context command prefix for context-related actionskele-resources command prefix for acting on specific resource kinds, e.g. getting, with support for selecting the context, namespace, and the group-version to use (in cases of ambiguity)srequestsThis release focuses on refining the kele-get experience \u2013 usability improvements and general bugfixes.
kele-get buffers now have a dedicated minor mode, kele-get-mode.kele-get buffers now print a header detailing, for the resource under display: the context it was fetched from; and the time of retrievalkele-filtered-fields with which you can routinely filter out resource fields from display in kele-getkele-get results buffer incorrectly prints namespace for un-namespaced resources as nilkele-get refused to display the retrieved resource, if a buffer corresponding to that resource already existskele-get completion for the resource type now only returns resources that support the get verbThis release introduces kele-get \u2013 kubectl get, the Emacs way . With kele-get you can interactively specify the kind and name of the resource that you\u2019d like to get and display its manifest in a separate buffer. What\u2019s more, it supports custom resources right out the gate \u2013 a long-standing functionality gap in kubernetes-el.
See How-Tos > Usage > Working with Resources for details and a demo GIF. It\u2019s very much an MVP so there are some rough edges. Please open an issue for any peculiar behavior that you notice.
"},{"location":"references/changelog/#added_4","title":"Added","text":"kele-get for interactively getting and displaying a given resourcekele-proxy-start, kele-proxy-stop, and kele-proxy-togglekele-mode resulted in an error reporting unbound slot filewatch-id on kele--discovery-cachehttps://127.0.0.1:51134, were not recognized properlykele-cache-dir is now ~/.kube/cache; before it was relative to the value of kele-kubeconfig-path (and unreliably so)kele-namespace-switch-for-context where the selection candidates were pulled for the current context rather than the argument contextkubectl invocationsplzasyncKele is born!
This initial release of Kele has a very simple goal: \u201ckubectx and kubens, but make it Emacs.\u201d Its feature set is limited but lays the foundation \u2013 both in terms of implementation and \u201cdesign philosophy\u201d \u2013 for future enhancements.
This section collects \u201carchitecture decision records (ADRs)\u201d for Kele. These are records of \u201carchitecturally significant\u201d decisions, that materially impact Kele\u2019s design and capabilities.
Tip
For more information about ADRs, see Michael Nygard\u2019s seminal post \u201cDocumenting Architecture Decisions\u201d.
"},{"location":"references/adrs/00-template/","title":"ADR 0000: [title]","text":""},{"location":"references/adrs/00-template/#status","title":"Status","text":""},{"location":"references/adrs/00-template/#context","title":"Context","text":""},{"location":"references/adrs/00-template/#decision","title":"Decision","text":""},{"location":"references/adrs/00-template/#consequences","title":"Consequences","text":""},{"location":"references/adrs/01-timer-based-discovery-cache/","title":"adr-01: Timer-based discovery-cache caching","text":""},{"location":"references/adrs/01-timer-based-discovery-cache/#status","title":"Status","text":"Implemented in #150.
"},{"location":"references/adrs/01-timer-based-discovery-cache/#context","title":"Context","text":"As of 2023-03-05, Kele uses a naive set of two separate caches:
kele-kubeconfig-path);Note
The latter, confusingly, shares the same name with the discovery cache that lives in the user\u2019s filesystem, typically under ~/.kube/cache/discovery. We use \u201cdiscovery cache\u201d to refer specifically to the Kele data structure, and use \u201cfilesystem discovery cache\u201d to refer to the \u201cactual\u201d discovery cache.
On enablement of kele-mode, Kele initializes both the kubeconfig cache and the discovery cache. The kubeconfig cache loads the contents of the user\u2019s kubeconfig file into memory; likewise, the discovery cache loads the contents of the user\u2019s filesystem discovery cache into memory. Both caches initialize [file watchers] that \u201cauto-refresh\u201d the respective cache contents on changes to the underlying file(s).
The combined use of these two caches enables near-instant completion of:
The aforementioned \u201call-at-once\u201d approach has proven to have several shortcomings.
"},{"location":"references/adrs/01-timer-based-discovery-cache/#gratuitous-file-watching","title":"Gratuitous File-Watching","text":"The most fundamental problem is that the discovery cache does not scale. Emacs file-watching uses file descriptors under the hood, which Emacs has a [finite number available for use at any given time][1]. Exceeding this limit results in an error to the following effect:
File watching not possible, no file descriptor left: 975\nThis limit is, to my knowledge, not user-configurable. Even if it were, it is an unreasonably invasive thing to ask users to do \u2013 for an Emacs package of all things. Most notably, this limit is, like all things, shared globally within Emacs, e.g. by [LSP-Mode][lsp-mode] and [auto-revert-mode], making the \u201creal\u201d limit for Kele much lower. In order to be a \u201cgood Emacs citizen,\u201d Kele needs to be much more conservative and strategic in its use of file-watchers.
We note that it is very easy to hit this limit. Anecdotally, I maintain kubectl access to a handful of production-scale clusters as part of my day job, and simply adding a couple more ad-hoc [Kind] clusters as part of integration-testing for this very package is enough for me to hit the limit. Doing so requires me to manually delete the filesystem discovery cache directories corresponding to these transient Kind clusters On top of being annoying, this is also a fundamentally unreasonable workaround; what happens if a user simply has that many clusters to maintain?
"},{"location":"references/adrs/01-timer-based-discovery-cache/#decision","title":"Decision","text":"The simplest and \u201cstupidest\u201d solution to this problem is to make caching of the filesystem discovery cache timer-based rather than filewatch-based.
"},{"location":"references/adrs/01-timer-based-discovery-cache/#consequences","title":"Consequences","text":"This approach represents, to an extent, a \u201cregression\u201d of sorts in the functionality of the discovery cache, as now the contents thereof are not guaranteed to be fully up-to-date with those of the filesystem dicovery cache. We decide that this is safe, as the set of group-version-kinds present in a cluster are unlikely to change that frequently. This is consistent with kubectl\u2018s own refresh policy for the filesystem discovery cache, which refills the cache every ten minutes \u2013 and lazily, at that, i.e. on the next user invocation of kubectl after the ten-minute mark.