Skip to content


Repository files navigation


npm version Dependencies Status ci JavaScript Style Guide

Fastify Kubernetes client plugin.

This plugin uses the official Node.js Kubernetes client under the hood.


The installed version of @kubernetes/client-node is the v0.20.x. The targeted Kubernetes version is from the v1.26 to v1.28.

For more info about supported Kubernetes version see here.

Generally speaking newer clients will work with older Kubernetes, but compatability isn't 100% guaranteed.


npm install --save fastify-kubernetes


Add it to your project with register and you are done!

const fastify = require('fastify')()

fastify.register(require('fastify-kubernetes'), {
  // Optional, defaults to OS default Kubeconfig file location
  file: '/home/app/.kube/config',
  // Context to use
  context: 'production'

fastify.get('/pods', async function (req, reply) {
  const client = this.kubernetes.api.CoreV1Api
  const result = await client.listNamespacedPod(this.kubernetes.namespace)

fastify.listen(3000, err => {
  if (err) throw err


All properties are optional.

  • kubeconfig: Kubernetes config file loading mode. Default is "auto".
    • "auto": Choose the first available mode in this order: Choose the first available config mode in this order: "file", "yaml", "in-cluster", and "default".
    • "default": Load config file the default OS location.
    • "file": Load config file from file option.
    • "in-cluster": Load in-cluster kubeconfig file.
    • "yaml": Load config from yaml option.
    • KubeConfig: Load custom KubeConfig instance.
  • file: Config file path.
  • yaml: Config file content (string or buffer).
  • context: Wanted context. If the context does not exist, an error will be thrown.
  • cluster: Wanted cluster. If the cluster does not exist, an error will be thrown.
  • user: Wanted user. If the user does not exist, an error will be thrown.
  • namespace: Wanted namespace.

A name option can be used in order to connect to multiple kubernetes clusters.

const fastify = require('fastify')()

  .register(require('fastify-kubernetes'), {
    context: 'eu-cluster-0',
    name: 'eu'
  .register(require('fastify-kubernetes'), {
    context: 'us-cluster-0',
    name: 'us'

fastify.get('/', async function (req, reply) {
  const euClient =
  const usClient =
  // ------------
  // do your stuff here
  // ------------


The plugin will inject six properties under kubernetes decorator.

  • config is the KubeConfig instance
  • context is the current context name
  • cluster is the context's cluster
  • user is the context's user
  • namespace is the context's namespace, defaults to "default"
  • api is an object containing all possible client types


You can retrieve a client by its original name from the kubernetes lib.

const client0 = this.kubernetes.api.CoreV1Api
const client1 = this.kubernetes.api.BatchV1Api
const client2 = this.kubernetes.api.BatchV1beta1Api