Forge Home


Module for creating resources in Kubernetes


10,399 latest version

4.1 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.6.0 (latest)
  • 0.5.1
  • 0.5.0
  • 0.4.0
  • 0.3.0
  • 0.2.0
  • 0.1.1
  • 0.1.0
released Aug 3rd 2017

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'garethr-kubernetes', '0.6.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add garethr-kubernetes
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install garethr-kubernetes --version 0.6.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



garethr/kubernetes — version 0.6.0 Aug 3rd 2017

Forge Build
Status Documentation
Status Puppet Forge

  1. Overview
  2. Description - What the module does and why it is useful
  3. Setup
  1. Getting Started with Kubernetes
  2. Usage - Configuration options and additional functionality
  3. Reference - An under-the-hood peek at what the module is doing and how
  1. 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 Puppet language supports logic and abstractions, allowing for the crafting of business specific user interfaces and avoiding repetition
  • Modifications can be made to the Puppet code and Puppet will handle updating the relevant resources, without having to describe the full state of the resource
  • Puppet supports relationships between resources, so you can enforce ordering where necessary

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.


  • Kubeclient ruby gem
  • Ruby 2.x, Kubeclient won't work with 1.8.7 or 1.9.x

Installing the Kubernetes module

Install the required gems with this command:

/opt/puppetlabs/puppet/bin/gem install activesupport -v 4.1.14
/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:

  • nix Systems: /etc/puppetlabs/puppet
  • Windows: C:\ProgramData\PuppetLabs\puppet\etc
  • non-root users: ~/.puppetlabs/etc/puppet

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 resource like so:

puppet resource kubernetes_pod sample-pod ensure=absent

More usage examples

The module examples folder contains additional usage examples:

Converting existing Kubernetes YAML files

You may already have YAML files describing your Kubernetes resources, or be using Helm to download existing Charts. The module includes an experimental puppet kubernetes convert command for just this situation.

puppet kubernetes convert examples/guestbook.yaml

The above command will output to stdout the Puppet equivalent to the YAML description of Kubernetes resources, including correctly handling multi-document files like the example guestbook.

puppet kubernetes convert examples/guestbook.yaml > guestbook.pp
puppet apply --test guestbook.pp

If you want to then use that Puppet file the simplest way to do so is to redirect the output to a file and then run it with Puppet as shown above.

Compile Puppet DSL to Kubernetes YAML

You might want to see the YAML being sent over the wire, or integrate Puppet with other Kubernetes tooling. For this we have the compile subcommand.

puppet kubernetes compile --manifest examples/guestbook.pp

The above will output YAML to stdout which could them be used with kubectl or similar tooling.



The following are some of the types available in the module. For a full list use puppet resource --types | grep kubernetes.

  • kubernetes_pod
  • kubernetes_service
  • kubernetes_replication_controller
  • kubernetes_node
  • kubernetes_event
  • kubernetes_endpoint
  • kubernetes_namespace
  • kubernetes_secret
  • kubernetes_resource_quota
  • kubernetes_limit_range
  • kubernetes_peristent_volume
  • kubernetes_persistent_volume_claim
  • kubernetes_component_status
  • kubernetes_service_account
  • kubernetes_deployment


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.