diff --git a/content/docs/esc/environments/syntax/builtin-functions/_index.md b/content/docs/esc/environments/syntax/builtin-functions/_index.md index 92adf7a65807..f81f3bc28f8a 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/_index.md +++ b/content/docs/esc/environments/syntax/builtin-functions/_index.md @@ -20,6 +20,7 @@ All function invocations take the form of an object with a single key that names ## Functions - [`fn::concat`](/docs/esc/environments/syntax/builtin-functions/fn-concat) +- [`fn::eval`](/docs/esc/environments/syntax/builtin-functions/fn-eval) - [`fn::final`](/docs/esc/environments/syntax/builtin-functions/fn-final) - [`fn::fromBase64`](/docs/esc/environments/syntax/builtin-functions/fn-from-base64) - [`fn::fromJSON`](/docs/esc/environments/syntax/builtin-functions/fn-from-json) @@ -28,6 +29,7 @@ All function invocations take the form of an object with a single key that names - [`fn::rotate`](/docs/esc/environments/syntax/builtin-functions/fn-rotate) - [`fn::secret`](/docs/esc/environments/syntax/builtin-functions/fn-secret) - [`fn::split`](/docs/esc/environments/syntax/builtin-functions/fn-split) +- [`fn::template`](/docs/esc/environments/syntax/builtin-functions/fn-template) - [`fn::toBase64`](/docs/esc/environments/syntax/builtin-functions/fn-to-base64) - [`fn::toJSON`](/docs/esc/environments/syntax/builtin-functions/fn-to-json) - [`fn::toString`](/docs/esc/environments/syntax/builtin-functions/fn-to-string) diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-eval.md b/content/docs/esc/environments/syntax/builtin-functions/fn-eval.md new file mode 100644 index 000000000000..06f7a51b4829 --- /dev/null +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-eval.md @@ -0,0 +1,92 @@ +--- +title: fn::eval +title_tag: fn::eval +h1: fn::eval +meta_desc: The fn::eval built-in function evaluates a template expression in the context of the current environment. +menu: + esc: + parent: esc-syntax-builtin-functions + identifier: esc-syntax-fn-eval + weight: 2 +--- + +The `fn::eval` built-in function evaluates a [template expression](/docs/esc/environments/syntax/builtin-functions/fn-template/) in the context of the current environment. Together with `fn::template`, it enables late binding — the ability to define reusable expressions in one environment and evaluate them with different values in another. + +## Declaration + +```yaml +fn::eval: template-reference +``` + +### Parameters + +| Property | Type | Description | +|----------------------|------|----------------------------------------------------------------------------------------------------------| +| `template-reference` | any | A reference to a value defined with `fn::template`. Typically an interpolation like `${environments.org.defn.my-template}`. | + +### Returns + +The result of evaluating the referenced template in the context of the calling environment. The template's interpolations are resolved using the values available in the environment where `fn::eval` is called, not where the template is defined. + +## Example + +### Reusable greeting template + +This example shows how to define a template in one environment and evaluate it in multiple environments with different values. + +#### Template environment (example/defn) + +```yaml +values: + hello: + fn::template: Hello ${name}! +``` + +The `fn::template` expression defines a template that references `${name}`. The interpolation is not resolved in this environment — it is deferred until a consumer evaluates it with `fn::eval`. + +#### Consumer environment A (example/a) + +```yaml +values: + name: "foo" + example: + fn::eval: ${environments.example.defn.hello} +``` + +#### Consumer environment B (example/b) + +```yaml +values: + name: "bar" + example: + fn::eval: ${environments.example.defn.hello} +``` + +#### Parent environment + +```yaml +values: + a: ${environments.example.a} + b: ${environments.example.b} +``` + +#### Evaluated result + +```json +{ + "a": { + "example": "Hello foo!", + "name": "foo" + }, + "b": { + "example": "Hello bar!", + "name": "bar" + } +} +``` + +Environment A resolves the template with `name: "foo"`, producing `"Hello foo!"`. Environment B resolves the same template with `name: "bar"`, producing `"Hello bar!"`. + +## Related functions + +- [`fn::template`](/docs/esc/environments/syntax/builtin-functions/fn-template/) — defines a template expression for deferred evaluation. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-final.md b/content/docs/esc/environments/syntax/builtin-functions/fn-final.md index 6229f745511c..ee9fc1d64726 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-final.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-final.md @@ -7,7 +7,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-final - weight: 2 + weight: 3 --- The `fn::final` built-in function marks a value as final, preventing child environments from overriding it. If a child environment attempts to override a final value, the value is not overridden and a validation warning is raised. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-from-base64.md b/content/docs/esc/environments/syntax/builtin-functions/fn-from-base64.md index 6c8e218e4c95..83f8374db94f 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-from-base64.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-from-base64.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-from-base64 - weight: 3 + weight: 4 --- The `fn::fromBase64` built-in function decodes its input into a binary value. This can be used to realize binary values that are stored as Base64-encoded (often for use with the [`files` reserved property](/docs/esc/environments/syntax/reserved-properties/files). If the input to `fn::fromBase64` is a secret, the decoded value is also a secret. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-from-json.md b/content/docs/esc/environments/syntax/builtin-functions/fn-from-json.md index e460b62099a7..397f4a77748b 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-from-json.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-from-json.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-from-json - weight: 4 + weight: 5 --- The `fn::fromJSON` built-in function decodes a value from its JSON representation. This can be used to expand JSON values that are stored as scalar strings into complex values. If the input to `fn::fromJSON` is a secret, all of the decoded values are also secrets. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-join.md b/content/docs/esc/environments/syntax/builtin-functions/fn-join.md index 2bbcd6700c8c..fb7583f80f54 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-join.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-join.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-join - weight: 5 + weight: 6 --- The `fn::join` built-in function joins the elements of a list of strings using a given delimiter. If any input to `fn::join` is a secret, the result is also a secret. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-open.md b/content/docs/esc/environments/syntax/builtin-functions/fn-open.md index a48656203081..c1c7d645b38c 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-open.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-open.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-open - weight: 6 + weight: 7 --- The `fn::open` built-in function invokes a [provider](/docs/esc/environments/syntax/providers/) to fetch values from outside of ESC. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-rotate.md b/content/docs/esc/environments/syntax/builtin-functions/fn-rotate.md index d0ea175a6e00..b0957eecb901 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-rotate.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-rotate.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-rotate - weight: 7 + weight: 8 --- The `fn::rotate` built-in function invokes a [rotator](/docs/esc/environments/syntax/rotators) to rotate secrets. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-secret.md b/content/docs/esc/environments/syntax/builtin-functions/fn-secret.md index 3a8f86f877d5..c3842ebef352 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-secret.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-secret.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-secret - weight: 8 + weight: 9 --- The `fn::secret` built-in function decrypts a ciphertext literal into a secret string value. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-split.md b/content/docs/esc/environments/syntax/builtin-functions/fn-split.md index 29e1288ddfd2..7fd92ac8c912 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-split.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-split.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-split - weight: 9 + weight: 10 --- The `fn::split` built-in function splits a string into a list of strings using a given delimiter. If any input to `fn::split` is a secret, the result is also a secret. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-template.md b/content/docs/esc/environments/syntax/builtin-functions/fn-template.md new file mode 100644 index 000000000000..85d22bf92298 --- /dev/null +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-template.md @@ -0,0 +1,101 @@ +--- +title: fn::template +title_tag: fn::template +h1: fn::template +meta_desc: The fn::template built-in function defines a template expression with deferred evaluation for use with fn::eval. +menu: + esc: + parent: esc-syntax-builtin-functions + identifier: esc-syntax-fn-template + weight: 11 +--- + +The `fn::template` built-in function defines a template expression whose interpolations are not resolved immediately. Instead, the template is evaluated later when a consumer environment references it with [`fn::eval`](/docs/esc/environments/syntax/builtin-functions/fn-eval/). This enables late binding — defining reusable expressions in one environment and evaluating them with different values in another. + +## Declaration + +```yaml +fn::template: expression +``` + +### Parameters + +| Property | Type | Description | +|--------------|--------|---------------------------------------------------------------------------------------------------| +| `expression` | any | An expression containing interpolations (e.g., `Hello ${name}!`). The interpolations are not resolved in the defining environment — they are deferred until evaluation with `fn::eval`. | + +### Returns + +A template value that can be referenced by other environments. The template is not evaluated in the defining environment. It produces a result only when consumed via `fn::eval`. + +## Example + +### Defining a reusable template + +#### Template environment (example/defn) + +```yaml +values: + hello: + fn::template: Hello ${name}! +``` + +This defines a template that references `${name}`. The value of `name` is determined by the environment that evaluates the template. + +#### Consumer environment (example/a) + +```yaml +values: + name: "foo" + example: + fn::eval: ${environments.example.defn.hello} +``` + +#### Evaluated result + +```json +{ + "example": "Hello foo!", + "name": "foo" +} +``` + +The template resolves `${name}` to `"foo"` because that is the value of `name` in the consumer environment. + +### Using templates for standardized configuration + +Templates are useful for enforcing consistent patterns across environments. For example, you can define a naming convention template and have all environments evaluate it with their own values: + +#### Template environment (org/templates) + +```yaml +values: + resource-name: + fn::template: ${project}-${environment}-${region} +``` + +#### Consumer environment (org/prod-us) + +```yaml +values: + project: "myapp" + environment: "prod" + region: "us-east-1" + name: + fn::eval: ${environments.org.templates.resource-name} +``` + +#### Evaluated result + +```json +{ + "project": "myapp", + "environment": "prod", + "region": "us-east-1", + "name": "myapp-prod-us-east-1" +} +``` + +## Related functions + +- [`fn::eval`](/docs/esc/environments/syntax/builtin-functions/fn-eval/) — evaluates a template expression in the context of the current environment. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-to-base64.md b/content/docs/esc/environments/syntax/builtin-functions/fn-to-base64.md index fadcd1dc672f..63508ad99477 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-to-base64.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-to-base64.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-toBase64 - weight: 10 + weight: 12 --- The `fn::toBase64` built-in function encodes a binary value using Base64. If the input to `fn::toBase64` is a secret, the encoded value is also a secret. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-to-json.md b/content/docs/esc/environments/syntax/builtin-functions/fn-to-json.md index 1d53994ab9c8..40ed50cfdcda 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-to-json.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-to-json.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-toJSON - weight: 11 + weight: 13 --- The `fn::toJSON` built-in function encodes a value as its JSON representation. This can be used to encode values for use in positions that only accept strings. If any input to `fn::toJSON` is a secret, the encoded values is also a secret. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-to-string.md b/content/docs/esc/environments/syntax/builtin-functions/fn-to-string.md index 438f7ec7ede0..064f8dda624b 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-to-string.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-to-string.md @@ -10,7 +10,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-toString - weight: 12 + weight: 14 --- The `fn::toString` built-in function encodes a value as its string representation. This can be used to encode values for use in positions that only accept strings. If any input to `fn::toString` is a secret, the encoded values is also a secret. diff --git a/content/docs/esc/environments/syntax/builtin-functions/fn-validate.md b/content/docs/esc/environments/syntax/builtin-functions/fn-validate.md index 6a48fca9d7e5..c370d284d419 100644 --- a/content/docs/esc/environments/syntax/builtin-functions/fn-validate.md +++ b/content/docs/esc/environments/syntax/builtin-functions/fn-validate.md @@ -9,7 +9,7 @@ menu: esc: parent: esc-syntax-builtin-functions identifier: esc-syntax-fn-validate - weight: 13 + weight: 15 --- The `fn::validate` built-in function validates a value against a JSON Schema. If the value does not conform to the schema, a validation error is raised and the environment cannot be saved until the issues are resolved.