Deploying Applications using YAML

Warning

This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.

Waypoint can mimic kubectl apply and deploy from a directory of YAML files. This option lets you adopt Waypoint very easily with existing applications. A downside of this option is that Waypoint cannot help automatically configure any aspect of Kubernetes (such as autoscaling). Instead, users are expected to write YAML and exactly control their deployments.

There are other deployment options. Waypoint supports many other mechanisms for deploying to Kubernetes. You can use the kubernetes plugin for highly opinionated, no YAML deployments. Or you can use Helm.

A Simple Deployment

The example below shows how we can use the kubernetes-apply plugin to deploy a directory of YAML files to create a single Kubernetes "Deployment" resource:

deploy {
  use "kubernetes-apply" {
    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}

We use the templatedir function so that we can access the artifact variable and use this to dynamically set our image for the deployment based on the image built in the build step. The ability to access HCL variables and functions in our YAML files is one big benefit of using Waypoint.

The prune_label option specifies a Kubernetes label selector that Waypoint uses to know what resources to delete if and when the deployment is eventually destroyed. This should be set to a label selector that uniquely identifies the resources created by your YAML files.

Entrypoint Functionality

With this plugin, Waypoint does not automatically inject the necessary environment variables for the Waypoint Entrypoint. Therefore, features such as logs, exec, etc. will not be available by default. If you wish to use this functionality, you can manually inject the necessary environment variables by using the entrypoint variable paired with templating as shown above.

The YAML file below shows the same deployment resource being created as the previous examples, but extends it to use the entrypoint variable to set the proper environment variables so that the entrypoint functions.

This requires the entrypoint to be in your container image. If you're using the docker builder plugin, this happens automatically. If you're using externally built images, you may need to manually inject the entrypoint.

// ./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"