Context Extension in Aptakube

Set the alias, icon, color, tags, Change Protection and order of your contexts in your Kubeconfig file, and share them with your team.

Aptakube lets you give each context an alias, an icon, a color, tags and Change Protection, so you can tell your clusters apart at a glance and keep production safe. You can set them in the app: right-click a context and choose Customize. They're then saved in Aptakube's preferences, on your machine only.

Or you can set them in your Kubeconfig file, with an extension named aptakube on the context. Everyone who uses that file gets the same aliases, icons, colors, tags and protection, which is handy when your team shares a Kubeconfig or generates it with a script.

Aptakube's contexts screen: the EKS clusters in Europe and the US are shown as Production EU and Production US, with a flag icon and a red ring, the data platform is read-only, and the contexts are grouped by the production, staging and local tags
Aliases, icons, colors, tags, Change Protection and order, all from the Kubeconfig file

Quick start

Everything on this page needs Aptakube 1.22 or later, and alias needs 1.22.2 or later.

Open your Kubeconfig file (~/.kube/config by default) and add an extensions list to the context, next to its cluster and user, with an extension named aptakube:

contexts:
  - name: prod-eu-west-1
    context:
      cluster: prod-eu-west-1
      user: prod-eu-west-1
      extensions:
        - name: aptakube
          extension:
            alias: Production EU
            icon: library:flag-eu
            color: red
            tags: [production]
            change-protection: protected

Save the file, then in Aptakube click the settings button next to the search on the contexts screen and choose Refresh contexts, or press ⌘R there (Ctrl+R on Windows and Linux). Aptakube also reads the file again when it starts.

The extension goes in the context of an entry in the contexts list, not in a cluster or a user. A context Aptakube doesn't find an aptakube extension on keeps the settings you gave it in the app.

Not sure where the file is? In Aptakube, right-click the context, choose Customize, then Learn how: it shows the Kubeconfig file the context is in, with a button to show it in Finder (Show in Folder on Windows and Linux).

Example with every setting

Every field is optional, so set only the ones you need. Here's a context with all of them:

apiVersion: v1
kind: Config
clusters:
  - name: prod-eu-west-1
    cluster:
      server: https://8F2D1C6A0B3E47A9.gr7.eu-west-1.eks.amazonaws.com
      certificate-authority-data: LS0tLS1CRUdJTi...
users:
  - name: prod-eu-west-1
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: aws
        args: [eks, get-token, --cluster-name, prod-eu-west-1]
contexts:
  - name: prod-eu-west-1
    context:
      cluster: prod-eu-west-1
      user: prod-eu-west-1
      namespace: checkout
      extensions:
        - name: aptakube
          extension:
            # Shown instead of the context's name
            alias: Production EU
            # An icon of Aptakube's library (library:<id>), a website's domain,
            # an image URL, or an image file: an absolute path, ~/..., or relative to this file
            icon: library:flag-eu
            # red, orange, amber, green, teal, blue, violet or pink
            color: red
            # Lowercase letters, digits and dashes, without the #
            tags: [production, eu-west]
            # off, protected or read-only
            change-protection: protected
            # Contexts with a lower order are listed first
            order: 1
current-context: prod-eu-west-1
FieldValuesWhen it isn't set
aliasAny text, e.g. Production EUThe context's name
iconlibrary:<id>, a domain, an image URL or an image fileDetected from the cluster
colorred orange amber green teal blue violet pinkNo color
tagsA list, e.g. [production, eu-west]No tags
change-protectionoff protected read-onlyOff
orderA whole number, lowest first, e.g. 1After the contexts with an order

How Aptakube uses it

  • The extension takes precedence. A context with an aptakube extension takes all its settings from it, and the ones you gave it in the app are ignored. That includes the settings the extension leaves out: with only tags, the context has no color, the automatic icon and no Change Protection.
  • It can only be changed in the file. Context Settings shows each setting with a lock and the line of the extension that sets it, and has a button to show the Kubeconfig file.
  • Aptakube never writes to your Kubeconfig files. Extensions are part of the Kubeconfig format, so kubectl ignores them, and keeps them when it changes the file.
Context Settings of prod-eu-west-1, shown as Production EU: a banner says it's customized with a Context Extension in its Kubeconfig file, and the alias setting shows the line alias: Production EU
Settings from the extension are read-only in the app

Alias

Shown instead of the context's name across Aptakube: the contexts screen, the sidebar, the Context column of lists, window titles, dialogs and the command palette. It's handy when a context is named after an EKS cluster's ARN, or after whatever a script generated.

extensions:
  - name: aptakube
    extension:
      alias: Production EU

The context's name is still there: under the alias on the contexts screen and in Context Settings, and in a tooltip everywhere else. Searching the contexts screen and filtering lists by context finds either one.

The alias is only shown. kubectl, Helm, terminals, port forwards and links to the context keep using its name, so an alias never changes which cluster a command goes to. An alias that's the name or alias of another context is ignored, so two contexts never look the same.

Icon

Shown with the context's name, in the contexts list, the sidebar and terminals. Without an icon, Aptakube shows the logo of the cluster's platform (EKS, GKE, AKS, Docker Desktop, ...) or the Kubernetes logo. It also falls back to it when the icon can't be found or loaded.

The icon field takes:

  • An icon of Aptakube's library: library: and the icon's id, e.g. library:aws or library:flag-us-va. They're all below.
  • A website's icon: the website's domain, e.g. hetzner.com or github.com, without https:// or a path.
  • An image URL: e.g. https://example.com/icons/prod.png.
  • An image file: PNG, JPG, GIF, WebP or SVG. Use an absolute path, a path starting with ~/ for your home folder, or a path relative to the folder of the Kubeconfig file (the first one, with several files in KUBECONFIG), so the icons can live next to a Kubeconfig you share, e.g. icons/prod.png.

A square image works best, as it's shown in a circle.

A website's icon is its favicon, which Aptakube gets through aptakube.com, so the website has to be public. It's handy for a platform that isn't in the library, like Hetzner or Scaleway, or for a context per customer.

extensions:
  - name: aptakube
    extension:
      icon: library:flag-us-va
      # icon: hetzner.com
      # icon: https://example.com/icons/prod.png
      # icon: ~/.kube/icons/prod.png
      # icon: C:\Users\alex\.kube\icons\prod.png

Two clusters on the same cloud look the same with their platform's logo. A flag for their region, or a symbol for their environment, tells them apart:

Platforms

  • Kuberneteslibrary:kubernetes
  • AWSlibrary:aws
  • Azurelibrary:azure
  • Google Cloudlibrary:gcp
  • DigitalOceanlibrary:digitalocean
  • Oracle Cloudlibrary:oracle
  • Docker Desktoplibrary:docker
  • Minikubelibrary:minikube
  • OrbStacklibrary:orbstack

Flags

  • United Stateslibrary:flag-us
  • United Kingdomlibrary:flag-gb
  • European Unionlibrary:flag-eu
  • Germanylibrary:flag-de
  • Francelibrary:flag-fr
  • Netherlandslibrary:flag-nl
  • Irelandlibrary:flag-ie
  • Canadalibrary:flag-ca
  • Japanlibrary:flag-jp
  • Australialibrary:flag-au
  • Indialibrary:flag-in
  • Singaporelibrary:flag-sg
  • Brazillibrary:flag-br
  • South Korealibrary:flag-kr
  • Virginialibrary:flag-us-va
  • Ohiolibrary:flag-us-oh
  • Iowalibrary:flag-us-ia
  • Texaslibrary:flag-us-tx
  • Californialibrary:flag-us-ca
  • Oregonlibrary:flag-us-or
  • Washingtonlibrary:flag-us-wa

Symbols

  • Productionlibrary:production
  • Staginglibrary:staging
  • Developmentlibrary:development
  • Debuglibrary:debug
  • Locallibrary:local
  • Homelibrary:home
  • Serverlibrary:server
  • On-premiseslibrary:on-premises
  • Cloudlibrary:cloud
  • Globallibrary:global
  • Databaselibrary:database
  • Securelibrary:secure
  • Sandboxlibrary:sandbox

Color

Shown as the ring around the context's icon and as a dot next to its name, for example in the Context column of lists. A color per environment, like red for production, makes it hard to mistake one for another.

  • red
  • orange
  • amber
  • green
  • teal
  • blue
  • violet
  • pink
extensions:
  - name: aptakube
    extension:
      color: red

A color Aptakube doesn't know is ignored, and the context has no color.

Tags

Tags group related contexts. On the contexts screen, each tag gets a card that connects to all its contexts in one click, and you can search and filter by tag.

extensions:
  - name: aptakube
    extension:
      tags: [production, eu-west]

Tags have lowercase letters, digits and dashes only. Aptakube shows them as #production, but the # isn't part of the tag, so leave it out. Other characters become a dash, so Prod EU is read as prod-eu.

Change Protection

Change Protection guards a cluster against changes made in Aptakube: create, edit, delete, scale, restart, drain, Helm, shell and exec.

  • Offchange-protection: offNothing is blocked, you can make any change to the cluster. The default.
  • Protectedchange-protection: protectedChanges are blocked. You can unlock the context for up to 4 hours to make temporary changes.
  • Read-onlychange-protection: read-onlyChanges are always blocked, and the context can't be unlocked.
extensions:
  - name: aptakube
    extension:
      change-protection: read-only

As the extension can't be changed in the app, it's a good way to make sure production is protected for everyone who uses your Kubeconfig file. A value Aptakube doesn't know, like a typo, is read as read-only, so a mistake never leaves a context unprotected.

Change Protection is a safety net against mistakes in Aptakube, not access control: use Kubernetes RBAC to control what people can do on a cluster.

Order

Contexts with an extension are listed first, sorted by order, lowest first. The ones with an extension but no order come after them, then the contexts without an extension, in the order you arranged them in Settings → Contexts.

contexts:
  - name: staging
    context:
      cluster: staging
      user: staging
      extensions:
        - name: aptakube
          extension:
            order: 2
  - name: prod-eu-west-1
    context:
      cluster: prod-eu-west-1
      user: prod-eu-west-1
      extensions:
        - name: aptakube
          extension:
            order: 1 # listed before staging

Context name

Without an alias, Aptakube shows contexts with the name they have in the Kubeconfig file. To give one a shorter name in kubectl and every other tool too, like prod-eu-west-1 instead of an EKS cluster's ARN, rename it in the file:

kubectl config rename-context arn:aws:eks:eu-west-1:123456789012:cluster/prod prod-eu-west-1

Settings you gave a context in the app are saved by its name, so they don't follow a rename. An extension does, as it's part of the context.


Questions or ideas for the extension? Ask on GitHub, join our Discord or email hello@aptakube.com.