Docs for path vars, template functions, and artifact/deploy variables

internal/cli/app_docs.go

@@ -447,7 +447,7 @@ func (c *AppDocsCommand) funcsMDX() int {
  for _, k := range keys {
  fn := all[k]
 
- fmt.Fprintf(w, "# `%s` Function\n\n", k)
+ fmt.Fprintf(w, "## `%s`\n\n", k)
 
  var (
  args []string
@@ -478,7 +478,7 @@ func (c *AppDocsCommand) funcsMDX() int {
 
  fmt.Fprintf(w, "```hcl\n%s(%s) %s\n```\n\n", k, strings.Join(args, ", "), rt.FriendlyName())
  if d, ok := docs[k]; ok {
- fmt.Fprintf(w, "`%s`: %s\n\n", k, d)
+ fmt.Fprintf(w, "%s\n\n", d)
  }
  }
 

website/content/docs/waypoint-hcl/functions/all.mdx

@@ -0,0 +1,21 @@
+---
+layout: docs
+page_title: Full List - Functions - waypoint.hcl
+sidebar_title: Full Reference
+description: |-
+ This page contains an automatically generated list of all the available functions within the Waypoint configuration file.
+---
+
+# Full Function Reference
+
+This page contains an automatically generated list of all the available
+functions within the Waypoint configuration file. To navigate this page
+more easily, we recommend using your browser's find feature
+(`Cmd-F` or `Ctrl-F`) along with the "Jump to Section" dropdown above.
+
+-> **Note:** This page is currently missing some functions such as
+the template functions (`templatedir`, etc.) and configuration functions
+(`configdynamic`). We are working to fix this. In the mean time, these
+functions are documented elsewhere in context with their purpose.
+
+@include "funcs.mdx"

website/content/docs/waypoint-hcl/functions/index.mdx

@@ -0,0 +1,52 @@
+---
+layout: docs
+page_title: Functions - waypoint.hcl
+sidebar_title: Functions
+description: |-
+ The `waypoint.hcl` file uses HCL which is able to call predefined functions. Functions enable Waypoint configurations to represent complex configurations using programming techniques.
+---
+
+# Functions in `waypoint.hcl`
+
+The `waypoint.hcl` file uses [HCL](https://github.com/hashicorp/hcl) which
+is able to call predefined functions. Functions enable Waypoint configurations
+to represent complex configurations using programming techniques.
+
+Most functions can be used anywhere in the Waypoint configuration file.
+Some functions are context-specific and are only valid when called from the correct locations.
+Function documentation pages may use [placement tables](/docs/waypoint-hcl#placement-tables)
+to document where functions are valid. If a placement table is not present
+for a function, it is safe to assume that it can be used anywhere.
+
+## Calling Functions
+
+Function usage is similar to many mainstream programming languages such
+as Javascript, Ruby, or Python. Functions can be called directly and
+assigned to values:
+
+```hcl
+port = floor(8080.4)
+```
+
+Functions can be composed:
+
+```hcl
+port = floor(abs(-8080.4))
+```
+
+Functions arguments can be any expressions: variables, mathematical operations, etc.:
+
+```hcl
+port = floor(abs(artifact.port) + 42)
+```
+
+Functions can be used as part of string interpolations. Regardless of the
+return value HCL will attempt to coerce it into a string:
+
+```hcl
+port = "80${floor(80.4)}" // 8080
+```
+
+## Custom Functions
+
+Waypoint does not support custom defined functions.

website/content/docs/waypoint-hcl/functions/template.mdx

@@ -0,0 +1,87 @@
+---
+layout: docs
+page_title: Templating - Functions - waypoint.hcl
+sidebar_title: Templating
+description: |-
+ Waypoint has a set of functions for templating strings, files, and directories with both predefined and custom variable values. These templates can use conditionals, loops, and more to dynamically generate content.
+---
+
+# Templating Functions
+
+Waypoint has a set of functions for templating strings, files, and directories
+with both predefined and custom variable values. These templates can use
+conditionals, loops, and more to dynamically generate content.
+
+Waypoint has three templating functions documented below: `templatefile`,
+`templatedir`, and `templatestring`. All of these functions use the same
+templating syntax. The templates have access to all the same variables
+and functions that are available at the function call-site (where the
+function such as `templatedir` is called). Custom variables can also
+be provided to the template.
+
+## `templatefile`
+
+```hcl
+templatefile(path[, vars...]) path
+```
+
+`templatefile` takes a path to a file and optionally one or more maps of variables
+for the template, renders the template at `path`, and returns the path to
+the rendered template. The returned path is a copy of the original template
+in a temporary location. This function _does not modify the original file_.
+
+**Reminder:** This function returns a file path, not the rendered contents of the file.
+If you want the contents of the rendered file, you can wrap this function
+with [`file`](/docs/waypoint-hcl/functions/all#file).
+
+This function is useful for parameters that expect file paths. The example
+below shows using this function with Docker to template the Dockerfile:
+
+```hcl
+app "web" {
+ build {
+ use "docker" {
+ dockerfile = templatefile("${path.app}/Dockerfile.tpl", {
+ theme = "rainbow"
+ })
+ }
+ }
+}
+```
+
+## `templatedir`
+
+```hcl
+templatedir(path[, vars...]) path
+```
+
+`templatedir` is similar to `templatefile`, except it takes a path to
+a directory, treats all files within that directory as a template, copies
+the results to a new temporary directory, and returns the temporary
+directory path.
+
+This function will recursively render all files in `path`.
+
+This function is useful for parameters that expect directory paths, such
+as specifying a directory of YAML files for Kubernetes.
+
+## `templatestring`
+
+```hcl
+templatestring(string[, vars...]) string
+```
+
+`templatestring` renders a string as a template directly and returns
+the rendered contents.
+
+-> **If you have a static template string, you probably want to use
+string literals instead.** This function is primarily for dynamically
+sourced templates (such as reading a file or the contents of some
+other variable). If you have a static string you can use HCL interpolations
+directly, for example: `"Port: ${deploy.port}"`
+
+Example, rendering a template file and returning the contents directly:
+
+```hcl
+userdata = templatestring(file("${path.app}/userdata.tpl"))
+```

website/content/docs/waypoint-hcl/index.mdx

@@ -50,6 +50,19 @@ plugin "plugin-name" {
 }
 ```
 
+## Placement Tables
+
+Many pages within the `waypoint.hcl` documentation section will have
+a _placement table_ just beneath the header. This table documents where
+a configuration, function, or variable may be used. An example placement
+table is shown below.
+
+If the example below were present on the documentation page, the documented
+feature is only valid within the context of an `app` stanza. It is not valid
+at the top-level, or any further nested locations.
+
+<Placement groups={[['app', 'build']]} />
+
 ## Top-level
 
 The "top-level" refers to the objects that are not nested in any other
@@ -71,6 +84,13 @@ and `release`. These are documented further in their respective pages.
 
 A stanza is a parameter, but not all parameters are stanzas.
 
+## Variables
+
+Waypoint configuration files have access to a number of predefined variables.
+Using variables helps make a Waypoint configuration more robust by more
+explicitly specifying paths, reducing duplication, etc. You can learn more about
+variables in the dedicated [variables section](/docs/waypoint-hcl/variables).
+
 ## Top-level Parameters
 
 ### Required

website/content/docs/waypoint-hcl/variables/artifact.mdx

@@ -0,0 +1,54 @@
+---
+layout: docs
+page_title: artifact - Variables - waypoint.hcl
+sidebar_title: <code>artifact</code>
+description: |-
+ The `artifact` variable can be used to reference information about built artifacts. This can be used to access information such as the name and tag of a built Docker image, or the AMI of a built EC2 machine image.
+---
+
+# `artifact` Variable
+
+<Placement
+ groups={[
+ ['app', 'build', 'registry'],
+ ['app', 'deploy'],
+ ['app', 'release'],
+ ]}
+/>
+
+The `artifact` variable can be used to reference information about
+built artifacts. This can be used to access information such as
+the name and tag of a built Docker image, or the AMI of a built
+EC2 machine image.
+
+The exact fields within an `artifact` variable are dependent on the
+[plugin used for the build](/plugins) and the available fields are
+documented alongside plugins.
+
+## Example: Docker
+
+The example below uses the `artifact` variable to reuse the
+Docker image name from the build when pushing it to a registry. This
+configuration makes it so that if the build name is changed, it will
+also automatically change for the registry without having to modify
+the configuration.
+
+```hcl
+app "web" {
+ build {
+ use "docker" {}
+
+ registry {
+ use "docker" {
+ image = artifact.image
+ tag = gitrefpretty()
+ }
+ }
+ }
+}
+```
+
+The example uses the `artifact.image` value which is the image name
+(without a tag). Other fields such as `artifact.tag` and
+`artifact.name` (the full name with the tag) are also available.
+For the full list of available field, see the Docker plugin documentation.

website/content/docs/waypoint-hcl/variables/deploy.mdx

@@ -0,0 +1,46 @@
+---
+layout: docs
+page_title: deploy - Variables - waypoint.hcl
+sidebar_title: <code>deploy</code>
+description: |-
+ The `deploy` variable can be used to reference information about the deployment within a release. This can be used to access information such as the resulting instance ID, IP address, etc.
+---
+
+# `deploy` Variable
+
+<Placement groups={[['app', 'release']]} />
+
+The `deploy` variable can be used to reference information about
+the deployment within a release. This can be used to access information
+such as the resulting instance ID, IP address, etc.
+
+The exact fields within a `deploy` variable are dependent on the
+[plugin used for the build](/plugins) and the available fields are
+documented alongside plugins.
+
+## Example: AWS ECS
+
+The example below uses the `deploy` variable to store the ECS Task ARN
+as a label as part of the release operation. While Waypoint keeps track
+of the backlinks of what deployment created a release, this information
+may be useful to have directly in a label:
+
+```hcl
+app "web" {
+ deploy {
+ use "aws-ecs" {
+ # ...
+ }
+ }
+
+ release {
+ labels = {
+ "example.com/task-arn": deploy.task_arn,
+ }
+
+ use "aws-ecs" {
+ # ...
+ }
+ }
+}
+```

website/content/docs/waypoint-hcl/variables/entrypoint.mdx

@@ -0,0 +1,50 @@
+---
+layout: docs
+page_title: entrypoint - Variables - waypoint.hcl
+sidebar_title: <code>entrypoint</code>
+description: |-
+ The `entrypoint` variable contains important information about the Waypoint Entrypoint, such as the required environment variables that must be set for proper entrypoint behavior.
+---
+
+# `entrypoint` Variable
+
+<Placement groups={[['app', 'deploy']]} />
+
+The `entrypoint` variable contains important information about
+the [Waypoint Entrypoint](/docs/entrypoint), such as the required
+environment variables that must be set for proper entrypoint behavior.
+
+## `entrypoint.env`
+
+**Type: `map<string,string>`**
+
+These are the environment variables that must be set on startup
+for the entrypoint to function properly. **You do not normally need
+to use this** because deployment plugins will automatically set these
+environment variables in most cases.
+
+This is useful for manual configuration in cases where the platform
+may not do it automatically (for example, if you specify a custom set
+of YAML files for Kubernetes).
+
+### Example: Kubernetes
+
+The example below shows how we can configure the Kubernetes plugin
+with the required environment variables. **Note: this is not necessary
+since the Kubernetes plugin automatically does this.** This is just
+shown as an example for illustrative purposes.
+
+```hcl
+app "web" {
+ deploy {
+ use "kubernetes" {
+ static_environment = merge({
+ MY_CUSTOM_VAR = "hello, world"
+ }, entrypoint.env)
+ }
+ }
+}
+```
+
+This example sets some custom variables and uses the `merge` function
+to merge in the Waypoint Entrypoint environment variables as well.