»Deploying Applications without YAML

For many applications, Waypoint can deploy to Kubernetes with only a handful of lines of configuration in the waypoint.hcl file and zero external configuration. For new applications, this is a great option to get up and running easily. If your application becomes more complex later, you can always switch deployment plugins.

»A Simple Application

For a simple web application, you can get started with almost zero configuration:

app "my-app" {
  deploy {
    use "kubernetes" {}
  }
}

app "my-app" {
  deploy {
    use "kubernetes" {}
  }
}

With zero configuration, Waypoint will create a Kubernetes Deployment with a PORT environment variable that your application is expected to listen on. And Waypoint will expose this application using a ClusterIP service. This is a perfect, minimal deployment for an internal service.

»Scaling Up

With one more line of configuration, you can scale your application to more replicas:

app "my-app" {
  deploy {
    use "kubernetes" {
      replicas = 3
    }
  }
}

app "my-app" {
  deploy {
    use "kubernetes" {
      replicas = 3
    }
  }
}

»Health Checking

With one line of configuration, you can specify an HTTP health check that Kubernetes will use for both liveness and readiness. This HTTP endpoint should listen on the service port and respond with a 2XX status code for success.

app "my-app" {
  deploy {
    use "kubernetes" {
      probe_path = "/_healthz"
    }
  }
}

app "my-app" {
  deploy {
    use "kubernetes" {
      probe_path = "/_healthz"
    }
  }
}

»Alternate or Additional Ports

With zero configuration, your application must listen on the PORT environment variable set by Waypoint. You can change the primary service port using service_port:

app "my-app" {
  deploy {
    use "kubernetes" {
      service_port = 1234
    }
  }
}

app "my-app" {
  deploy {
    use "kubernetes" {
      service_port = 1234
    }
  }
}

This is optimized and very simple for applications that have only one primary listening port. If you require multiple ports, you must use the slightly more complex ports configuration and must NOT use the service_port field (they are mutually exclusive).

app "my-app" {
  deploy {
    use "kubernetes" {
      pod {
        container {
          port {
            name = "http"
            port = 1234
          }

          port {
            name = "https"
            port = 2345
          }
        }
      }
    }
  }
}

app "my-app" {
  deploy {
    use "kubernetes" {
      pod {
        container {
          port {
            name = "http"
            port = 1234
          }

          port {
            name = "https"
            port = 2345
          }
        }
      }
    }
  }
}

»Autoscaling

Waypoint can configure horizontal autoscaling in just a few lines:

app "my-app" {
  deploy {
    use "kubernetes" {
      cpu {
        request = "250m"
        limit   = "500m"
      }

      autoscale {
        min_replicas = 1
        max_replicas = 5
        cpu_percent = 20
      }
    }
  }
}

app "my-app" {
  deploy {
    use "kubernetes" {
      cpu {
        request = "250m"
        limit   = "500m"
      }

      autoscale {
        min_replicas = 1
        max_replicas = 5
        cpu_percent = 20
      }
    }
  }
}

Note that this requires that a metrics server is running in your Kubernetes cluster. Waypoint will not set this up automatically. Installing the metrics server is typically a single kubectl apply or Helm install.

»Release Management

With the default Kubernetes deployment configuration, Waypoint creates a single ClusterIP type service. This is perfect for internal services but doesn't work if you want to expose your application to the public internet. By configuring a kubernetes release stanza, configuring release management for your service is also only a few lines of HCL.

»LoadBalancer Service

The simplest way to expose your application to the global internet is to use a LoadBalancer service type. This is a one line change:

app "my-app" {
  release {
    use "kubernetes" {
      load_balancer = true
    }
  }
}

app "my-app" {
  release {
    use "kubernetes" {
      load_balancer = true
    }
  }
}

»Ingress

You can expose your application through a Kubernetes Ingress:

app "my-app" {
  release {
    use "kubernetes" {
      ingress "http" {
        path_type = "Prefix"
        path      = "/"
      }
    }
  }
}

app "my-app" {
  release {
    use "kubernetes" {
      ingress "http" {
        path_type = "Prefix"
        path      = "/"
      }
    }
  }
}

»Reference Documentation

To view a full list of the available options for the Kubernetes plugin, please see the plugin reference documentation. This documentation is more dense and has less examples, but is an exhaustive list of the available options.