Kubernetes Cluster

The k8s_cluster resource allows the creation of Kubernetes clusters running in Docker.

Minimal example

k8s_cluster "k3s" {
driver = "k3s" // default
version = "v1.17.4-k3s1"
nodes = 1 // default
network {
name = "network.local"
network "local" {
subnet = ""

Run this example:

shipyard run github.com/shipyard-run/shipyard-website/examples/k8s_cluster//minimal


k8s_cluster resources run in an isolated Docker container using Rancher's K3s. On creation the k8s_cluster resource adds a Kubernetes Configuration file to your local computer to at the path ${HOME}/.shipyard/config/<cluster name>/kubeconfig.yaml. This allows you to interact with the cluster using local tooling like kubectl and helm.

➜ kubectl get pods --all-namespaces
kube-system local-path-provisioner-58fb86bdfd-w6bg6 1/1 Running 0 111s
kube-system metrics-server-6d684c7b5-86f86 1/1 Running 0 111s
kube-system coredns-6c6bb68b64-m4nqj 1/1 Running 0 111s

Deploying applications

Besides using local tooling to deploy applications to your cluster you can use the Shipyard resources helm and k8s_config, these resources allow you to provision Helm charts and vanilla Kubernetes resource files.

Deploying Helm charts

The following example shows a helm resource which would install a remote Helm chart for HashiCorp Vault.

Since Shipyard has a full understanding of the dependencies in your application the helm charts do not run until the cluster is fully up and running. Simply referencing the cluster in the helm chart stanza is the only thing required. Health checks can also be added to helm chart resources ensuring the next step of the dependency chain does not start before the applicaiton is running.

For more information on the helm resource type please see the documentation for that resource /docs/resources/helm.

helm "vault" {
cluster = "k8s_cluster.k3s"
chart = "github.com/hashicorp/vault-helm"
values_string = {
"server.dataStorage.size" = "128Mb"

Deploying Kubernetes Resource files

The following example shows a k8s_config resource which would apply the Kubernetes resources defined in the referenced pahts to the Kubernetes cluster.

The k8s_config resource is only applied once the referenced cluster is running and healthy, in addition it is possible to specify optional dependencies. In this case there is an optional dependency on the successful application of a helm resource.

For more information on the k8s_config resource type please see the documentation for that resource /docs/resources/k8s_config.

k8s_config "app" {
depends_on = ["helm.vault"]
cluster = "k8s_cluster.k3s"
paths = [
wait_until_ready = true

Exposing resources

Resources running in your Kubernetes cluster can be exposed using the k8s_ingress resource type. The following example shows how a Kubernetes service vault port 8200 can be exposed to the local host at port 18200. For more information on the k8s_ingress resource please see the documentation /docs/resouces/k8s_ingress.

k8s_ingress "vault-http" {
cluster = "k8s_cluster.k3s"
service = "vault"
network {
name = "network.cloud"
port {
local = 8200
remote = 8200
host = 18200



Type: []string
Required: false

Depends on allows you to specify resources which should be created before this one. In the instance of a destruction, this container will be destroyed before resources in.


Type: network_attachment
Required: true

Network attaches the container to an existing network defined in a separate stanza. This block can be specified multiple times to attach the container to multiple networks.


Type: string "k3s"
Required: true

The k8s_cluster resource can create Kubernetes clusters using different versions of Kubernetes, currently only Ranchers K3s is supported however support for Kind is also planned.


Type: string
Required: false

Version of the driver to use, for a list of supported values please see the matrix below. If not specified the latest version of the driver will be used.


Type: int
Required: false

Number of client nodes to create for a cluster, a value of 1 creates a combined server and client. Currently only single node clusters are supported.


Type: []image
Required: false

The image block allows you to specifiy images which will be copied from the local cache to the remote cluster. Kubernetes clusters have their own local Docker image cache, if images are not preloaded to the local cache then Kubernetes will attempt to retrieve these from a remote repository when starting a container.

image can also be used to push local builds which are not stored in a remote container registry.

Can be specified multiple times.

Type image

Image defines a Docker image used when creating this container. An Image can be stored in a public or a private repository.


Type: string
Required: true

Name of the image to use when creating the container, can either be the full canonical name or short name for Docker official images. e.g. consul:v1.6.1 or docker.io/consul:v1.6.1.


Type: string
Required: false

Username to use when connecting to a private image repository


Type: string
Required: false

Password to use when connecting to a private image repository, for both username and password interpolated environment variables can be used in place of static values.

image {
name = "myregistry.io/myimage:latest"
username = "${env("REGISTRY_USERNAME")}"
password = "${env("REGISTRY_PASSWORD")}"

Supported Kubernetes Versions