The Waypoint website is being redesigned to help you find what you are looking for more effectively.
»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
»Required Parameters
These parameters are used in the use
stanza for this plugin.
»autoscale (category)
Sets up a horizontal pod autoscaler to scale deployments automatically.
This configuration will automatically set up and associate the current deployment with a horizontal pod autoscaler in Kuberentes. Note that for this to work, you must also define resource limits and requests for a deployment otherwise the metrics-server will not be able to properly determine a deployments target CPU utilization.
»autoscale.cpu_percent
The target CPU percent utilization before the horizontal pod autoscaler scales up a deployments replicas.
- Type: int32
- Optional
»autoscale.max_replicas
The maximum amount of pods to scale to for a deployment.
- Type: int32
- Optional
»autoscale.min_replicas
The minimum amount of pods to have for a deployment.
- Type: int32
- Optional
»cpu (category)
Cpu resource configuration.
CPU lets you define resource limits and requests for a container in a deployment.
»cpu.limit
Maximum amount of cpu to give the container. Supports m to indicate milli-cores.
- Type: string
- Optional
»cpu.request
How much cpu to give the container in cpu cores. Supports m to indicate milli-cores.
- Type: string
- Optional
»memory (category)
Memory resource configuration.
Memory lets you define resource limits and requests for a container in a deployment.
»memory.limit
Maximum amount of memory to give the container. Supports k for kilobytes, m for megabytes, and g for gigabytes.
- Type: string
- Optional
»memory.request
How much memory to give the container in bytes. Supports k for kilobytes, m for megabytes, and g for gigabytes.
- Type: string
- Optional
»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.
- Type: list of string
- Optional
»pod.container.command
An array of strings to run for the container.
- Type: list of string
- Optional
»pod.container.cpu (category)
Cpu resource configuration.
CPU lets you define resource limits and requests for a container in a deployment.
»pod.container.cpu.limit
Maximum amount of cpu to give the container. Supports m to indicate milli-cores.
- Type: string
- Optional
»pod.container.cpu.request
How much cpu to give the container in cpu cores. Supports m to indicate milli-cores.
- Type: string
- Optional
»pod.container.memory (category)
Memory resource configuration.
Memory lets you define resource limits and requests for a container in a deployment.
»pod.container.memory.limit
Maximum amount of memory to give the container. Supports k for kilobytes, m for megabytes, and g for gigabytes.
- Type: string
- Optional
»pod.container.memory.request
How much memory to give the container in bytes. Supports k for kilobytes, m for megabytes, and g for gigabytes.
- Type: string
- Optional
»pod.container.name
Name of the container.
- Type: string
- Optional
»pod.container.port (category)
A port and options that the application is listening on.
Used to define and expose multiple ports that the application or process is listening on for the container in use. Can be specified multiple times for many ports.
»pod.container.port.host_ip
What host IP to bind the external port to.
- Type: string
- Optional
»pod.container.port.host_port
The corresponding worker node port.
Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this.
- Type: uint
- Optional
»pod.container.port.name
Name of the port.
If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services.
- Type: string
»pod.container.port.port
The port number.
Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536.
- Type: uint
»pod.container.port.protocol
Protocol for port. Must be UDP, TCP, or SCTP.
- Type: string
- Optional
- Default: TCP
»pod.container.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.
»pod.container.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
»pod.container.probe.initial_delay
Time in seconds to wait before performing the initial liveness and readiness probes.
- Type: uint
- Optional
- Default: 5
»pod.container.probe.timeout
Time in seconds before the probe fails.
- Type: uint
- Optional
- Default: 5
»pod.container.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
»pod.container.resources
A map of resource limits and requests to apply to a container on deploy.
Resource limits and requests for a container. This exists to allow any possible resources. For cpu and memory, use those relevant settings instead. Keys must start with either limits_
or requests_
. Any other options will be ignored.
- Type: map of string to string
- Optional
»pod.container.static_environment
Environment variables to control broad modes of the application.
Environment variables that are meant to configure the container 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
»pod.security_context (category)
Holds pod-level security attributes and container settings.
»pod.security_context.fs_group
A special supplemental group that applies to all containers in a pod.
- Type: int64
»pod.security_context.run_as_non_root
Indicates that the container must run as a non-root user.
- Type: bool
»pod.security_context.run_as_user
The UID to run the entrypoint of the container process.
- Type: int64
»pod.sidecar (category)
A sidecar container within the same pod.
Another container to run alongside the app container in the kubernetes pod. Can be specified multiple times for multiple sidecars.
»pod.sidecar.container (category)
Container describes the commands and arguments for a container config.
»pod.sidecar.container.args
An array of string arguments to pass through to the container.
- Type: list of string
- Optional
»pod.sidecar.container.command
An array of strings to run for the container.
- Type: list of string
- Optional
»pod.sidecar.container.cpu (category)
Cpu resource configuration.
CPU lets you define resource limits and requests for a container in a deployment.
»pod.sidecar.container.cpu.limit
Maximum amount of cpu to give the container. Supports m to indicate milli-cores.
- Type: string
- Optional
»pod.sidecar.container.cpu.request
How much cpu to give the container in cpu cores. Supports m to indicate milli-cores.
- Type: string
- Optional
»pod.sidecar.container.memory (category)
Memory resource configuration.
Memory lets you define resource limits and requests for a container in a deployment.
»pod.sidecar.container.memory.limit
Maximum amount of memory to give the container. Supports k for kilobytes, m for megabytes, and g for gigabytes.
- Type: string
- Optional
»pod.sidecar.container.memory.request
How much memory to give the container in bytes. Supports k for kilobytes, m for megabytes, and g for gigabytes.
- Type: string
- Optional
»pod.sidecar.container.name
Name of the container.
- Type: string
- Optional
»pod.sidecar.container.port (category)
A port and options that the application is listening on.
Used to define and expose multiple ports that the application or process is listening on for the container in use. Can be specified multiple times for many ports.
»pod.sidecar.container.port.host_ip
What host IP to bind the external port to.
- Type: string
- Optional
»pod.sidecar.container.port.host_port
The corresponding worker node port.
Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this.
- Type: uint
- Optional
»pod.sidecar.container.port.name
Name of the port.
If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services.
- Type: string
»pod.sidecar.container.port.port
The port number.
Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536.
- Type: uint
»pod.sidecar.container.port.protocol
Protocol for port. Must be UDP, TCP, or SCTP.
- Type: string
- Optional
- Default: TCP
»pod.sidecar.container.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.
»pod.sidecar.container.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
»pod.sidecar.container.probe.initial_delay
Time in seconds to wait before performing the initial liveness and readiness probes.
- Type: uint
- Optional
- Default: 5
»pod.sidecar.container.probe.timeout
Time in seconds before the probe fails.
- Type: uint
- Optional
- Default: 5
»pod.sidecar.container.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
»pod.sidecar.container.resources
A map of resource limits and requests to apply to a container on deploy.
Resource limits and requests for a container. This exists to allow any possible resources. For cpu and memory, use those relevant settings instead. Keys must start with either limits_
or requests_
. Any other options will be ignored.
- Type: map of string to string
- Optional
»pod.sidecar.container.static_environment
Environment variables to control broad modes of the application.
Environment variables that are meant to configure the container 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
»pod.sidecar.image
Image of the sidecar container.
- Type: string
»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: 30
»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
»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 container on deploy.
Resource limits and requests for a container. This exists to allow any possible resources. For cpu and memory, use those relevant settings instead. Keys 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 container 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: opaqueany.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
»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
These parameters are used in the use
stanza for this plugin.
»ingress (category)
Configuration to set up an ingress resource to route traffic to the given application from an ingress controller.
An ingress resource can be created on release that will route traffic to the Kubernetes service. Note that before this happens, the Kubernetes cluster must already be configured with an Ingress controller. Otherwise there won't be a way for inbound traffic to be routed to the ingress resource.
»ingress.annotations
Annotations to be applied to the ingress resource.
- Type: map of string to string
- Optional
»ingress.default
Sets the ingress resource to be the default backend for any traffic that doesn't match existing ingress rule paths.
- Type: bool
- Optional
- Default: false
»ingress.host
If set, will configure the ingress resource to have the ingress controller route traffic for any inbound requests that match this host. IP addresses are not allowed, nor are ':' delimiters. Wildcards are allowed to a certain extent. For more details check out the Kubernetes documentation.
- Type: string
- Optional
»ingress.path
The route rule that should be used to route requests to this ingress resource. A path must begin with a '/'.
- Type: string
- Optional
- Default: /
»ingress.path_type
Defines the kind of rule the path will be for the ingress controller. Valid path types are 'Exact', 'Prefix', and 'ImplementationSpecific'.
- Type: string
- Optional
- Default: Prefix
»ingress.tls (category)
A stanza of TLS configuration options for traffic to the ingress resource.
»ingress.tls.hosts
A list of hosts included in the TLS certificate.
»ingress.tls.secret_name
The Kubernetes secret name that should be used to look up or store TLS configs.
»Optional Parameters
These parameters are used in the use
stanza for this plugin.
»annotations
Annotations to be applied to the kube service.
- 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. Note that to read a config value from a Secret, you must set secret = true
. Otherwise Waypoint will load a dynamic value from a ConfigMap.
»Examples
»Required Parameters
These parameters are used in dynamic
for sourcing configuration values or input variable values.
»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 dynamic
for sourcing configuration values or input variable values.
»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
»kubernetes (task)
Launch a Kubernetes pod for on-demand tasks from the Waypoint server.
This will use the standard Kubernetes environment variables to source authentication information for Kubernetes. If this is running within Kubernetes itself (typical for a Kubernetes-based installation), it will use the pod's service account unless other auth is explicitly given. This allows the task launcher to work by default.
»Interface
»Examples
»Required Parameters
These parameters are used in the use
stanza for this plugin.
»cpu
Cpu resource request to be added to the task container.
- Type: k8s.ResourceConfig
»memory
Memory resource request to be added to the task container.
- Type: k8s.ResourceConfig
»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
»image_pull_policy
Pull policy to use for the task container image.
- Type: string
- Optional
»image_secret
Name of the Kubernetes secret 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
»namespace
Namespace in which to launch task.
- Type: 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
»Output Attributes
Output attributes can be used in your waypoint.hcl
as variables via artifact
or deploy
.
»id
- Type: string