1. Overview

  2. Description - What the module does and why it is useful

  3. Setup

  4. Requirements

  5. Installing the Kubernetes module

  6. Getting Started with Kubernetes

  7. Usage - Configuration options and additional functionality

  8. Reference - An under-the-hood peek at what the module is doing and how

  9. Types

  10. Limitations - OS compatibility, etc.


The garethr-kubernetes module allows you to use the Puppet DSL for managing Pods, ReplicationControllers, Services and more in Kubernetes. It doesn't install the various Kubernetes components.


The module allows for defining Kubernetes resources in Puppet, and then for Puppet to create or update those resources. This improves on the basic YAML file approach in a few ways:

The user interface of the Puppet code however follows the API/YAML format exactly. This allows for a familiar interface for anyone used to the Kubernetes API, at the same time as providing a low level building block for creating higher level types.


Note that the following assumes you have a Kubernetes cluster up and running.


Installing the Kubernetes module

Install the required gems with this command:

/opt/puppetlabs/puppet/bin/gem install kubeclient --no-ri --no-rdoc

Configuring credentials

You can provide the required information in a standard kubectl configuration file. Store this as kubernetes.conf in the relevant confdir. This should be:

If you have a working kubectl setup you can export the file using the following command:

kubectl config view --raw=true

Finally install the module with:

puppet module install garethr-kubernetes

Getting started with Kubernetes

This module allows for describing resources in Kubernetes (like Pods, Services and ReplicationControllers) using the Puppet DSL. To create a new Pod for example:

kubernetes_pod { 'sample-pod':
  ensure   => present,
  metadata => {
    namespace => 'default',
  spec     => {
    containers => [{
      name  => 'container-name',
      image => 'nginx',


List and manage Kubernetes resources

In addition to creating and managing resources this module supports listing and interactive management of resources via puppet resource. For example:

puppet resource kubernetes_node


puppet resource kubernetes_service

You can use this to describe the state of your Kubernetes cluster and export the results to a file, which can then be used to maintain that state over time.

Delete resources

You can also delete the resources we created above by setting the ensure property to absent in the manifest or using puppet resouce like so:

puppet resource kubernetes_pod sample-pod ensure=absent

More usage examples

The module examples folder contains additional usage examples:




This module is a proof of concept, demonstrating both the power of auto-generating Puppet types and providers from Swagger specifications and of managing higher level tools like Kubernetes with Puppet. It likely has several bugs and rough edges at the moment. Please report those on GitHub.


Much of the code for this module is auto-generated using the puppet-swagger-generator project. This means modifications to the types and providers should be done there, rather than within this project. Files which are auto-generated should have a suitable comment indicating as such.