June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Infrastructure
    • terraform
    • packer
  • Networking
    • consul
  • Security
    • vault
    • boundary
  • Applications
    • nomad
    • waypoint
    • vagrant
  • HashiCorp Cloud Platform

    A fully managed platform to automate infrastructure on any cloud with HashiCorp products.

    • consul
    • terraform
    • vault
    • packerbeta
    Visit cloud.hashicorp.com
  • Overview
  • Tutorials
  • Docs
  • CLI
  • Plugins
  • Community
GitHub
Download
    • v0.8.x (latest)
    • v0.7.x
    • v0.6.x
    • v0.5.x
    • v0.4.x
    • v0.3.x
    • v0.2.x
    • v0.1.x
    • Overview
      • Overview
      • Helm
      • Heroku, Vercel, etc.
      • Kubernetes
  • Getting Started
    • Overview
    • Compatibility Promise
    • Protocol Version Table
    • Release Notifications
      • Overview
      • Upgrade to 0.2.0

    • Install
    • Externally Built Images
    • Building Container Images
    • Helm Deployment
    • YAML-Free Deployment
    • YAML Directory Deployment
    • Resource Status
    • ConfigMaps and Secrets

    • Overview
    • Git Integration
    • Remote Operations
    • Overview
    • Build
    • Deploy
    • Release
    • Hooks
    • Labels
    • Workspace and Label Scoping
    • Overview
      • Overview
      • Input Variables
      • External Data
      • artifact
      • deploy
      • entrypoint
      • labels
      • path
      • workspace
      • Overview
      • Full Reference
      • Templating
      • Overview
      • Expressions
      • JSON Syntax
    • app
    • build
    • config
    • deploy
    • hook
    • plugin
    • registry
    • release
    • runner
    • url
    • use
    • variable
  • URL Service
  • Logs
  • Exec
    • Overview
    • Dynamic Values
    • Files
    • Internal Values
    • Workspace and Label Scoping
    • Overview
      • Overview
      • OIDC
      • Overview
      • Maintenance
      • Production
      • Security
    • Express Server Install
    • Overview
    • Configuration
    • Profiles
    • On-Demand Runner
    • Additional Runners
  • Workspaces
  • Plugins
  • Triggers

    • Overview
      • Overview
      • Registering Plugin Components
      • Handling Configuration
      • Implementing the Builder Interface
      • Compiling the Plugin
      • Creating an Example Application
      • Testing the Plugin
    • Initializing the SDK
    • Passing Values Between Components
      • Overview
      • Authenticator
      • Configurable
      • ConfigurableNotify
      • Builder
      • Registry
      • Platform
      • ReleaseManager
      • Destroy
      • Status
      • Default Parameters
      • Overview
    • Overview
    • Disable
    • Overview
    • GitHub Actions
    • GitLab CI/CD
    • CircleCI
    • Jenkins
  • Troubleshooting
  • Glossary

    • Overview
    • Architecture
    • Operation Execution
  • Roadmap
Type '/' to Search

»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.

Prefer writing YAML? That's okay! Waypoint supports Helm and raw kubectl apply as first-class deployment plugins, too.

»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.

Common mistake: your application must be written to listen on the PORT environment variable for this to just work. If you want to change the port to something else, specify it using the ports configuration shown below.

»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
          }
        }
      }
    }
  }
}

Important! The first port is special. The first port is used as the expected HTTP listening port (regardless of name or any other settings).

»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.

Be careful! This section is configuring the release stanza, not the deploy stanza. If you're scrolling down this will be a very subtle difference.

»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      = "/"
      }
    }
  }
}

This requires that you have an Ingress controller configured. Kubernetes does not do this by default. See the official Kubernetes documentation for more information.

»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.

github logoEdit this page

Using Waypoint

The best way to understand what Waypoint can enable for your projects is to give it a try.

Waypoint tutorials
Waypoint documentation
Tutorial

Get Started - Kubernetes

Build, deploy, and release applications to a Kubernetes cluster.

View
Tutorial

Introduction to Waypoint

Waypoint enables you to publish any application to any platform with a single file and a single command.

View

Waypoint is maintained by HashiCorp, Inc.

View Code of Conduct
DocumentationCLI ReferenceTutorialsIntegrations
All systems normal