This repository has been archived by the owner on Jan 8, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 327
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #858 from hashicorp/f-docs-template
Docs for path vars, template functions, and artifact/deploy variables
- Loading branch information
Showing
12 changed files
with
591 additions
and
148 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 meantime, these | ||
functions are documented elsewhere in context with their purpose. | ||
|
||
@include "funcs.mdx" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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")) | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 fields, see the Docker plugin documentation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" { | ||
# ... | ||
} | ||
} | ||
} | ||
``` |
50 changes: 50 additions & 0 deletions
50
website/content/docs/waypoint-hcl/variables/entrypoint.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Oops, something went wrong.