Merge pull request #2466 from hashicorp/website/k8s2

More K8S docs

builtin/k8s/helm/platform.go

@@ -266,6 +266,9 @@ environment variables using the [templating feature](/docs/waypoint-hcl/function
 These must be passed in using Helm values (i.e. the chart must make
 environment variables configurable).
 
+This is documented in more detail with a full example in the
+[Kubernetes Helm Deployment documentation](/docs/kubernetes/helm-deploy).
+
 #### URL Service
 
 If you want your workload to be accessible by the

website/content/docs/getting-started.mdx

@@ -10,10 +10,13 @@ description: |-
 It only takes a few minutes to get started with Waypoint on your local
 development environment. This quick start example uses Docker, either on Linux
 or with [Docker Desktop](https://www.docker.com/products/docker-desktop) for
-Windows and macOS.
+Windows and macOS. This will introduce you to the basics of Waypoint, even
+if your target environment is not Docker.
 
 Afterwards, go in-depth with tutorials for AWS, Azure, GCP, Kubernetes, and
-Nomad at [HashiCorp Learn](https://learn.hashicorp.com/waypoint).
+Nomad at [HashiCorp Learn](https://learn.hashicorp.com/waypoint). For detailed
+Kubernetes-focused documentation, see the
+[dedicated Kubernetes section](/docs/kubernetes/install).
 
 ## Installing Waypoint
 

website/content/docs/kubernetes/config.mdx

@@ -0,0 +1,123 @@
+---
+layout: docs
+page_title: Kubernetes - ConfigMaps and Secrets
+description: |-
+ Waypoint provides multiple options for accessing ConfigMap and Secret resources within your deployed application. This can be used or instead of Waypoint's native application configuration.
+---
+
+# ConfigMaps and Secrets
+
+Waypoint provides multiple options for accessing ConfigMap and Secret resources
+within your deployed application. This can be used or instead of Waypoint's native
+[application configuration](/docs/app-config) functionality.
+
+This page will focus on Waypoint-specific mechanisms for injecting
+configuration into your application, and it all requires the
+[Waypoint Entrypoint](/docs/entrypoint) to be injected and configured.
+Please note that **if you're using the [Helm](/docs/kubernetes/helm-deploy) or
+[`kubernetes-apply`](/docs/kubernetes/kubectl-deploy) deployment plugins,
+you do not need to use the Waypoint entrypoint** and you can access
+ConfigMaps and Secrets using
+[standard Kubernetes practices](https://kubernetes.io/docs/concepts/configuration/configmap/).
+Even if you are using Helm or raw YAML, you can also mix in any of the
+techniques noted below as well.
+
+## Environment Variables
+
+You can set environment variables for your application directly
+in the `waypoint.hcl` file using the [`config` stanza](/docs/waypoint-hcl/config).
+Static environment variables like this can also be set using the
+[web UI or CLI](/docs/app-config).
+
+```hcl
+config {
+ env = {
+ MY_API_KEY = "abcd1234"
+ }
+}
+
+app "my-app" {
+ // ...
+}
+```
+
+But, it's not a good idea to put something like an API key directly
+in your Waypoint configuration. A better idea would be to use a Kubernetes
+Secret and access it from there. Waypoint lets you do this with
+[dynamic configuration](/docs/app-config/dynamic):
+
+```hcl
+config {
+ env = {
+ MY_API_KEY = configdynamic("kubernetes", {
+ name = "my-secret" # Secret name
+ key = "apiKey"
+ secret = true
+ })
+ }
+}
+
+app "my-app" {
+ // ...
+}
+```
+
+## Files
+
+You can also create files from configuration values. For example, if we
+wanted to create a JSON file with our API key from the environment variable
+example above, we can do the following:
+
+```hcl
+config {
+ internal = {
+ MY_API_KEY = configdynamic("kubernetes", {
+ name = "my-secret" # Secret name
+ key = "apiKey"
+ secret = true
+ })
+ }
+
+ file = {
+ "config/config.json" = templatefile("${path.project}/config.json", {
+ api_key = config.internal.MY_API_KEY,
+ })
+ }
+}
+
+app "my-app" {
+ // ...
+}
+```
+
+```json
+{
+ "api_key": "${api_key}"
+}
+```
+
+This example shows two new concepts: [internal variables](/docs/app-config/internal)
+for creating intermediary values that can be used in other configuration
+values and [files](/docs/app-config/files) for creating configuration files.
+
+The file `config/config.json` will be written relative to your application
+deployment path. You could also specify an absolute path if you want the
+file to be written in an exact location. The files are written by a user with
+the same permissions as the running application when deployed, so ensure it is
+a path you have permission to write to.
+
+### File Change Notification
+
+If an input to a configuration file changes while the application is deployed,
+Waypoint will send a signal to the deployed application (by default `SIGUSR2`).
+The application can listen for this signal to reload configuration.
+
+For example, if you change the `my-secret` secret (as used in the example above)
+_after_ you had already deployed your application, Waypoint would detect
+the change, update the file, and then send a `SIGUSR2` signal to your
+running application.
+
+This is a big improvement over native Kubernetes mechanisms which update the
+file but depend on the running application to watch the filesystem for changes.
+For more information, including how to change the signal Waypoint sends,
+see [the reference documentation](/docs/app-config/files#file-change-signal).

website/content/docs/kubernetes/deploy.mdx

@@ -0,0 +1,206 @@
+---
+layout: docs
+page_title: Kubernetes - YAML-Free Deployment
+description: |-
+ 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.
+---
+
+# 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](/docs/kubernetes/helm-deploy) and raw
+[`kubectl apply`](/docs/kubernetes/kubectl-deploy) as first-class
+deployment plugins, too.
+
+## A Simple Application
+
+For a simple web application, you can get started with almost zero configuration:
+
+```hcl
+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:
+
+```hcl
+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.
+
+```hcl
+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`:
+
+```hcl
+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).
+
+```hcl
+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](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
+in just a few lines:
+
+```hcl
+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](https://kubernetes.io/docs/tasks/debug-application-cluster/resource-metrics-pipeline/#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](/docs/waypoint-hcl/release),
+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:
+
+```hcl
+app "my-app" {
+ release {
+ use "kubernetes" {
+ load_balancer = true
+ }
+ }
+}
+```
+
+### Ingress
+
+You can expose your application through a
+[Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/):
+
+```hcl
+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](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+for more information.
+
+## Reference Documentation
+
+To view a full list of the available options for the Kubernetes plugin,
+please see the [plugin reference documentation](/plugins/kubernetes).
+This documentation is more dense and has less examples, but is an
+exhaustive list of the available options.