- Description
- Installing the Module
- Setup - The basics of getting started with kubernetes
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
The Puppet kubernetes module installs and configures the Kubernetes system which arranges containers into logical units to improve management and discovery.
This module installs and configures Kubernetes. Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications.
It groups containers that make up an application into logical units for easy management and discovery.
To use this module, add this declaration to your Puppetfile:
mod 'puppetlabs-kubernetes', '1.0.3'
To manually install this module with puppet module tool:
puppet module install puppetlabs-kubernetes --version 1.0.3
This module includes a configuration tool called kubetool to auto generate all the security parameters, the bootstrap token, and other configurations for your Kubernetes cluster into a Hiera file. The tool is available as a Docker image to simplify installation and use.
If you do not already have Docker installed on your workstation, install it here
The kubetool docker image takes each of the parameters as environment variables. When run as follows it will output a kubernetes.yaml
file in your current working directory. Please note the version of kubetool you use is tied to the version of the module on the Puppet Forge. So if you are using the module version 1.0.0 you would use puppet/kubetool:1.0.0
:
docker run --rm -v $(pwd):/mnt -e OS=debian -e VERSION=1.9.2 -e CONTAINER_RUNTIME=docker -e CNI_PROVIDER=weave -e FQDN=kubernetes -e IP=172.17.10.101 -e BOOTSTRAP_CONTROLLER_IP=172.17.10.101 -e ETCD_INITIAL_CLUSTER="etcd-kube-master=http://172.17.10.101:2380" -e ETCD_IP="%{::ipaddress_enp0s8}" -e KUBE_API_ADVERTISE_ADDRESS="%{::ipaddress_enp0s8}" -e INSTALL_DASHBOARD=true puppet/kubetool:{$module-version}
The parameters are:
OS
: the os kubernetes will run on.VERSION
: the version of kubernetes you want to deployCONTAINER_RUNTIME
: the container runtime kubernetes will use, this can only be set todocker
orcri_containerd
CNI_PROVIDER
: This is the CNI network to install. This can be set toweave
,flannel
orcalico
.FQDN
: the cluster api fqdn. Should resolve toIP
.IP
: the cluster api IP. When in production, should be load balanced between the controllers.BOOTSTRAP_CONTROLLER_IP
: the ip address of the controller puppet will use to create things like cluster role bindings, kube dns, and the Kubernetes dashboard.ETCD_INITIAL_CLUSTER
: the server addresses. When in production, include three, five, or seven nodes for etcd.ETCD_IP
andKUBE_API_ADVERTISE_ADDRESS
: the IP each etcd/apiserver instance will use on each controller. We recommend passing the fact for the interface to be used by the cluster.INSTALL_DASHBOARD
: a boolean to install the dashboard or not.
The kubetool creates a kubernetes.yaml
file. To view the file contents on
screen, run the cat kubernetes.yaml
command.
The tool also creates a bootstrap token and base64 encodes any values that need
to be encoded for Kubernetes. If you run the kubetool
command again, all the
values are re-generated, including the certificates and tokens.
The resulting kubernetes.yaml
file should be added to your control repo where you keep your Hiera data, usually the data
directory. Each cluster can be given its own configuration by leveraging location facts such as the pp_datacenter trusted fact.
After your kubernetes.yaml
file has been added to the Hiera directory on your Puppet server, configure your node with one of the following parameters:
A bootstrap controller is the node a cluster uses to add cluster addons (such as kube dns, cluster role bindings etc). After the cluster is bootstrapped, the bootstrap controller should be changed to a normal controller.
To make a node a bootstrap controller, add the following code to the manifest:
class {'kubernetes':
controller => true,
bootstrap_controller => true,
}
A controller in Kubernetes contains the control plane and etcd
. In a production cluster you should have three, five, or seven controllers.
To make a node a controller, add the following code to the manifest:
class {'kubernetes':
controller => true,
}
A worker node runs your applications. You can add as many of these as Kubernetes can handle. For information about nodes in Kubernetes, see the Kubernetes docs.
To make a node a worker node, add the following code to the manifest:
class {'kubernetes':
worker => true,
}
Please note that a node can not be a controller and a worker. It must be one or the other.
The version of the Kubernetes containers to install.
Defaults to 1.9.2
.
The version the Kubernetes OS packages to install, such as kubectl and kubelet.
Defaults to 1.9.2
.
The name of the docker package you would like to install.
Defaults to docker-engine
.
The version of the docker package you would like to install.
Defaults depends on operating system.
- Red Hat:
1.12.6
- Debian:
1.12.0
If you would like to pin versions of Docker and Kubernetes packages. Works only for Debian/Ubuntu.
Defaults to true
.
The name of the cni package you would like to install.
Defaults to kubernetes-cni
.
The version of the cni package to install.
Defaults to 0.6.0
.
The url to get the cni providers yaml file. This can only be weave or flannel
defaults to undef
The version of kube DNS to install.
Defaults to 1.14.2
.
Choose between docker or cri_containerd
Defaults to docker
Specifies whether to set the node as a Kubernetes controller.
Valid values are true
, false
.
Defaults to false
.
Specifies whether to set the node as the bootstrap controller.
The bootstrap controller is used only for creating the initial cluster.
Valid values are true
, false
.
Defaults to false
.
The IP address of the bootstrap controller.
Defaults to undef
.
Specifies whether to set a node as a worker.
Defaults to undef
.
The IP address you want exposed by the API server.
An example with hiera would be kubernetes::kube_api_advertise_address:"%{::ipaddress_enp0s8}"
.
Defaults to undef
.
An array of extra configuration you can pass to the Kubernetes api container defaults to []
The version of etcd to use.
Defaults to 3.0.17
.
The IP address you want etcd to use for communications.
An example with hiera would be kubernetes::etcd_ip:"%{::ipaddress_enp0s8}"
.
Defaults to undef
.
This will tell etcd how many nodes will be in the cluster and is passed as a string.
A Hiera example is kubernetes::etcd_initial_cluster: etcd-kube-master=http://172.17.10.101:2380,etcd-kube-replica-master-01=http://172.17.10.210:2380,etcd-kube-replica-master-02=http://172.17.10.220:2380
.
Defaults to undef
.
The token Kubernetes uses to start components.
For information on bootstrap tokens, see https://kubernetes.io/docs/admin/bootstrap-tokens/
Defaults to undef
.
The name of the bootstrap token.
An example with hiera would be kubernetes::bootstrap_token_name: bootstrap-token-95e1e0
.
Defaults to undef
.
The base64 encoded description of the bootstrap token.
A Hiera example is kubernetes::bootstrap_token_description: VGhlIGRlZmF1bHQgYm9vdHN0cmFwIHRva2VuIHBhc3NlZCB0byB0aGUgY2x1c3RlciB2aWEgUHVwcGV0Lg== # lint:ignore:140chars
.
The base64 encoded ID the cluster uses to point to the token.
A Hiera example is kubernetes::bootstrap_token_id: OTVlMWUwDQo=
.
Defaults to undef
.
The base64 encoded secret which validates the bootstrap token.
An example with hiera would be kubernetes::bootstrap_token_secret: OTVlMWUwLmFlMmUzYjkwYTdmYjlkMzYNCg==
.
Defaults to undef
.
The base64 encoded bool which uses the bootstrap token. (true = dHJ1ZQ==)
An example with hiera would be kubernetes::bootstrap_token_usage_bootstrap_authentication: dHJ1ZQ==
.
Defaults to undef
.
The base64 encoded bool which uses the bootstrap signing. (true = dHJ1ZQ==)
An example with hiera would be kubernetes::bootstrap_token_usage_bootstrap_signing: dHJ1ZQ==
.
Defaults to undef
.
The string value for the cluster ca certificate data.
Defaults to undef
.
The client certificate for the controller. Must be a string value.
Defaults to undef
.
The client certificate for the controller manager. Must be a string value.
Defaults to undef
.
The client certificate for the scheduler. Must be a string value.
Defaults to undef
.
The client certificate for the kubernetes worker. Must be a string value.
Defaults to undef
.
The client certificate key for the controller. Must be a string value.
Defaults to undef
.
The client certificate key for the controller manager. Must be a string value.
Defaults to undef
.
The client certificate key for the scheduler. Must be a string value.
Defaults to undef
.
The client certificate key for the kubernetes worker. Must be a string value.
Defaults to undef
.
The certificate for the kubelet api server. Must be a certificate value and not a file.
Defaults to undef
.
The client key for the kubelet api server. Must be a certificate value and not a file.
Defaults to undef
.
The certificate for the api server. Must be a certificate value and not a file.
Defaults to undef
.
The key for the api server. Must be a certificate value and not a file.
Defaults to undef
.
The ca certificate for the cluster. Must be a certificate value and not a file.
Defaults to undef
.
The ca key for the cluster. Must be a certificate value and not a file.
Defaults to undef
.
The ca certificate for the front proxy. Must be a certificate value and not a file.
Defaults to undef
.
The ca key for the front proxy. Must be a certificate value and not a file.
Defaults to undef
.
The client certificate for the front proxy. Must be a certificate value and not a file.
Defaults to undef
.
The client key for front proxy. Must be a certificate value and not a file.
Defaults to undef
.
The key for the service account. Must be a certificate value and not a file.
Defaults to undef
.
The public key for the service account. Must be a certificate value and not a file.
Defaults to undef
.
The network deployment URL that kubectl can locate.
We support networking providers that supports cni.
This defaults to https://git.io/weave-kube-1.6
.
Specifies whether the kubernetes dashboard is installed.
Valid values are true
, false
.
Defaults to false
.
Specifies whether to add the NoSchedule taint to any controller nodes in the cluster.
Valid values are true,
false`.
Defaults to true
Allows the user to override the label of a node.
Defaults for hostname
The version of kube DNS you would like to install
Defaults to 1.14.2
The version of kube-proxy you would like to install
Defaults to match the kubernetes_version
The overlay (internal) network range to use.
Defaults to undef
(don't specify for kube-controller-manager). kube_tool sets this per cni provider.
This triggers allocate-node-cidrs=true
to be added to the controller-manager.
Defaults to false
.
The overlay (internal) network range to use for cluster services. This should be a subset of the cni_cluster_cidr
. kube_api_ip
and kube_dns_ip
should be in this range.
Defaults to undef
(don't specify for kube-apiserver). kube_tool sets this per cni provider.
The cluster service IP to use for kube-dns.
Defaults to undef
The cluster service IP to use for the kube api.
Defaults to undef
This module supports Kubernetes 1.6 to 1.9.x.
This module supports only Puppet 4 and above.
This module has been tested on the following OS
RedHat 7.x CentOS 7.x Ubuntu 16.04
If you would like to contribute to this module please follow the rules in the CONTRIBUTING.md.