Context Extension in Aptakube

Aptakube lets you give each context 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 icons, colors, tags and protection, which is handy when your team shares a Kubeconfig or generates it with a script.

Everything on this page needs Aptakube 1.22 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:
            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.

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).

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:
            # 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

• 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.

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:

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 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 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.

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

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

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.