»Kubernetes

For a step by step tutorial, visit HashiCorp Learn.

»Builders

Kubernetes uses Docker images for building, which are generated by these builders:

»kubernetes (platform)

Deploy the application into a Kubernetes cluster using Deployment objects.

»Interface

»Examples

deploy "kubernetes" {
    image_secret = "registry_secret"
    replicas = 3
    probe_path = "/_healthz"
}

deploy "kubernetes" {    image_secret = "registry_secret"    replicas = 3    probe_path = "/_healthz"}

»Required Parameters

These parameters are used in the use stanza for this plugin.

»pod (category)

The configuration for a pod.

Pod describes the configuration for a pod when deploying.

»pod.container (category)

Container describes the commands and arguments for a container config.

»pod.container.args

An array of string arguments to pass through to the container.

»pod.container.command

An array of strings to run for the container.

»pod.pod_security_context (category)

Holds pod-level security attributes and container settings.

»pod.pod_security_context.fs_group

A special supplemental group that applies to all containers in a pod.

»pod.pod_security_context.run_as_non_root

Indicates that the container must run as a non-root user.

»pod.pod_security_context.run_as_user

The UID to run the entrypoint of the container process.

»pod.security_context

Type: k8s.PodSecurityContext

»probe (category)

Configuration to control liveness and readiness probes.

Probe describes a health check to be performed against a container to determine whether it is alive or ready to receive traffic.

»probe.failure_threshold

Number of times a liveness probe can fail before the container is killed.

FailureThreshold * TimeoutSeconds should be long enough to cover your worst case startup times.

Type: uint
Optional
Default: 5

»probe.initial_delay

Time in seconds to wait before performing the initial liveness and readiness probes.

Type: uint
Optional
Default: 5

»probe.timeout

Time in seconds before the probe fails.

Type: uint
Optional
Default: 5

»Optional Parameters

These parameters are used in the use stanza for this plugin.

»annotations

Annotations to be added to the application pod.

Annotations are added to the pod spec of the deployed application. This is useful when using mutating webhook admission controllers to further process pod events.

Type: map of string to string
Optional

»context

The kubectl context to use, as defined in the kubeconfig file.

Type: string
Optional

»image_secret

Name of the Kubernetes secrete to use for the image.

This references an existing secret, waypoint does not create this secret.

Type: string
Optional

»kubeconfig

Path to the kubeconfig file to use.

By default uses from current user's home directory.

Type: string
Optional

»labels

A map of key value labels to apply to the deployment pod.

Type: map of string to string
Optional

»namespace

Namespace to target deployment into.

Namespace is the name of the Kubernetes namespace to apply the deployment in. This is useful to create deployments in non-default namespaces without creating kubeconfig contexts for each.

Type: string
Optional

»ports

A map of ports and options that the application is listening on.

Used to define and expose multiple ports that the application is listening on for the container in use. Available keys are 'port', 'name' , 'host_port', and 'host_ip'. Ports defined will be TCP protocol.

Type: list of map of string to string
Optional

»probe_path

The HTTP path to request to test that the application is running.

Without this, the test will simply be that the application has bound to the port.

Type: string
Optional

»replicas

The number of replicas to maintain.

If the replica count is maintained outside waypoint, for instance by a pod autoscaler, do not set this variable.

Type: int32
Optional

»resources

A map of resource limits and requests to apply to a pod on deploy.

Resource limits and requests for a pod. limits and requests options must start with either 'limits_' or 'requests_'. Any other options will be ignored.

Type: map of string to string
Optional

»scratch_path

A path for the service to store temporary data.

A path to a directory that will be created for the service to store temporary data using tmpfs.

Type: list of string
Optional

»service_account

Service account name to be added to the application pod.

Service account is the name of the Kubernetes service account to add to the pod. This is useful to apply Kubernetes RBAC to the application.

Type: string
Optional

»service_port

The TCP port that the application is listening on.

By default, this config variable is used for exposing a single port for the container in use. For multi-port configuration, use 'ports' instead.

Type: uint
Optional
Default: 3000

»static_environment

Environment variables to control broad modes of the application.

Environment variables that are meant to configure the application in a static way. This might be control an image that has multiple modes of operation, selected via environment variable. Most configuration should use the waypoint config commands.

Type: map of string to string
Optional

»Output Attributes

Output attributes can be used in your waypoint.hcl as variables via artifact or deploy.

»id

Type: string

»name

Type: string

»resource_state

Type: anypb.Any

»kubernetes-apply (platform)

Deploy Kubernetes resources directly from a single file or a directory of YAML or JSON files.

This plugin lets you use any pre-existing set of Kubernetes resource files to deploy to Kubernetes. This plugin supports all the features of Waypoint. You may use Waypoint's templating features to template the resources with information such as the artifact from a previous build step, entrypoint environment variables, etc.

»Requirements

This plugin requires "kubectl" to be installed since this plugin works by subprocessing to "kubectl apply". Other Waypoint Kubernetes plugins sometimes use the API directly but this plugin requires "kubectl".

"kubectl" must also be configured to access your Kubernetes cluster. You may specify an alternate kubeconfig file using the "kubeconfig" configuration parameter. If this isn't specified, the default kubectl lookup paths will be used.

»Artifact Access

You may use Waypoint's templating features to access information such as the artifact from the build or push stages. An example below shows this by using templatedir mixed with variables such as artifact.image to dynamically configure the Docker image within a Kubernetes Deployment.

»Entrypoint Functionality

Waypoint entrypoint functionality such as logs, exec, app configuration, and more require two properties to be true:

The running image must already have the Waypoint entrypoint installed and configured as the entrypoint. This should happen in the build stage.
Proper environment variables must be set so the entrypoint knows how to communicate to the Waypoint server. This step happens in this deployment stage.

Step 2 does not happen automatically. You must manually set the entrypoint environment variables using the templating feature. One of the examples below shows the entrypoint environment variables being injected.

»URL Service

If you want your workload to be accessible by the Waypoint URL service, you must set the PORT environment variable within the pod with your web service and also be using the Waypoint entrypoint (documented in the previous section).

The PORT environment variable should be the port that your web service is listening on that the URL service will connect to. See one of the examples below for more details.

»Interface

»Examples

// The waypoint.hcl file
deploy {
  use "kubernetes-apply" {
    // Templated to perhaps bring in the artifact from a previous
    // build/registry, entrypoint env vars, etc.
    path        = templatedir("${path.app}/k8s")
    prune_label = "app=myapp"
  }
}

// ./k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  labels:
    app: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: ${artifact.image}:${artifact.tag}
        env:
          %{ for k,v in entrypoint.env ~}
          - name: ${k}
            value: "${v}"
          %{ endfor ~}

          # Ensure we set PORT for the URL service. This is only necessary
          # if we want the URL service to function.
          - name: PORT
            value: "3000"

// The waypoint.hcl filedeploy {  use "kubernetes-apply" {    // Templated to perhaps bring in the artifact from a previous    // build/registry, entrypoint env vars, etc.    path        = templatedir("${path.app}/k8s")    prune_label = "app=myapp"  }}
// ./k8s/deployment.yamlapiVersion: apps/v1kind: Deploymentmetadata:  name: my-deployment  labels:    app: myappspec:  replicas: 3  selector:    matchLabels:      app: myapp  template:    metadata:      labels:        app: myapp    spec:      containers:      - name: myapp        image: ${artifact.image}:${artifact.tag}        env:          %{ for k,v in entrypoint.env ~}          - name: ${k}            value: "${v}"          %{ endfor ~}
          # Ensure we set PORT for the URL service. This is only necessary          # if we want the URL service to function.          - name: PORT            value: "3000"

»Required Parameters

These parameters are used in the use stanza for this plugin.

»path

Path to a file or directory of YAML or JSON files.

This will be used for kubectl apply to create a set of Kubernetes resources. Pair this with templatefile or templatedir templating functions to inject dynamic elements into your Kubernetes resources. Subdirectories are included recursively.

Type: string

»prune_label

Label selector to prune resources that aren't present in the path.

This is a label selector that is used to search for any resources that are NOT present in the configured path and delete them.

Type: string

»Optional Parameters

These parameters are used in the use stanza for this plugin.

»context

The kubectl context to use, as defined in the kubeconfig file.

Type: string
Optional

»kubeconfig

Path to the kubeconfig file to use.

If this isn't set, the default lookup used by kubectl will be used.

Type: string
Optional

»Output Attributes

Output attributes can be used in your waypoint.hcl as variables via artifact or deploy.

»prune_label

Type: string

»kubernetes (releasemanager)

Manipulates the Kubernetes Service activate Deployments.

»Interface

»Required Parameters

This plugin has no required parameters.

»Optional Parameters

These parameters are used in the use stanza for this plugin.

»annotations

Type: map of string to string
Optional

»context

The kubectl context to use, as defined in the kubeconfig file.

Type: string
Optional

»kubeconfig

Path to the kubeconfig file to use.

By default uses from current user's home directory.

Type: string
Optional

»load_balancer

Indicates if the Kubernetes Service should LoadBalancer type.

If the Kubernetes Service is not a LoadBalancer and node_port is not set, then the Service uses ClusterIP.

Type: bool
Optional

»namespace

Namespace to create Service in.

Namespace is the name of the Kubernetes namespace to create the deployment in This is useful to create Services in non-default namespaces without creating kubeconfig contexts for each.

Type: string
Optional

»node_port

The TCP port that the Service should consume as a NodePort.

If this is set but load_balancer is not, the service will be NodePort type, but if load_balancer is also set, it will be LoadBalancer.

Type: uint
Optional

»port

The TCP port that the application is listening on.

Type: uint
Optional
Default: 80

»ports

A map of ports and options that the application is listening on.

Used to define and configure multiple ports that the application is listening on. Available keys are 'port', 'node_port', 'name', and 'target_port'. If 'node_port' is set but 'load_balancer' is not, the service will be NodePort type. If 'load_balancer' is also set, it will be LoadBalancer. Ports defined will be TCP protocol. Note that 'name' is required if defining more than one port.

Type: list of map of string to string
Optional

»kubernetes (configsourcer)

Read configuration values from Kubernetes ConfigMap or Secret resources.

»Examples

config {
  env = {
    PORT = configdynamic("kubernetes", {
      name = "my-config-map"
      key = "port"
    })

    DATABASE_PASSWORD = configdynamic("kubernetes", {
      name = "database-creds"
      key = "password"
      secret = true
    })
  }
}

config {  env = {    PORT = configdynamic("kubernetes", {      name = "my-config-map"      key = "port"    })
    DATABASE_PASSWORD = configdynamic("kubernetes", {      name = "database-creds"      key = "password"      secret = true    })  }}

»Required Parameters

These parameters are used in configdynamic for dynamic configuration syncing.

»key

The key in the ConfigMap or Secret to read the value from.

ConfigMaps and Secrets store data in key/value format. This specifies the key to read from the resource. If you want multiple values you must specify multiple dynamic values.

Type: string

»name

The name of the ConfigMap of Secret.

Type: string

»Optional Parameters

These parameters are used in configdynamic for dynamic configuration syncing.

»namespace

The namespace to load the ConfigMap or Secret from.

By default this will use the namespace of the running pod. If this config source is used outside of a pod, this will use the namespace from the kubeconfig.

Type: string
Optional

»secret

This must be set to true to read from a Secret. If it is false we read from a ConfigMap.

Type: bool
Optional