ESC Environments reference (#14634)

These changes add a more complete reference section to the ESC documentation.

This reference content covers the contents of ESC environment definitions, including:

- Document structure
- Interpolation and reference syntax
- Built-in functions
- Built-in values
- Providers
- Rotators
- Reserved properties
- Sample environment definitions

Fixes #14289

Author: pgavlin

content/docs/esc/reference/_index.md

@@ -0,0 +1,30 @@
+---
+title: Environment Definition Reference
+title_tag: Environment Definition Reference
+h1: Environment Definition Reference
+meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
+menu:
+  esc:
+    parent: esc-home
+    identifier: esc-reference
+    weight: 5
+aliases:
+  - /docs/esc/syntax-reference
+---
+
+This is a reference for the various constructs defined by ESC.
+
+## Reference summary
+
+The ESC Environment reference is divided into the following sections:
+
+- __Top-level keys__: These are the different top-level document keys defined by the ESC language. Each key has its own well-defined semantics. For more information, see the [top-level key reference](/docs/esc/reference/top-level-keys).
+- __Interpolations and references__: Interpolations and references are additional syntactical constructs ESC layers on top of YAML to enable users to reuse property values. For more information, see the [interpolation and references syntax reference](/docs/esc/reference/interpolations-and-references).
+- __Built-in functions__: These are the different built-in functions defined by the ESC language. These functions allow you to perform common tasks such as encoding and decoding values and manipulating strings. For more information, see the [built-in functions reference](/docs/esc/reference/builtin-functions).
+- __Built-in properties__: These are the different predefined properties available to [interpolations and references](/docs/esc/reference/interpolations-and-references). For more information, see the [built-in values reference](/docs/esc/reference/builtin-values).
+- __Providers__: These are the different providers that allow dynamic access to credentials, configuration, and secrets stored outside of ESC. Each provider has its own set of inputs that affect its behavior. For more information, see the [providers reference](/docs/esc/reference/providers).
+- __Rotators__: These are the different rotators that allow ESC to rotate credentials, configuration, and secrets stored outside of ESC. Each rotator has its own set of inputs that affect its behavior. For more information, see the [rotators reference](/docs/esc/reference/rotators).
+- __Reserved properties__: These are the different environment properties that are interpreted by the [`esc` CLI](/docs/install/esc/) and other ESC consumers (e.g. the [`pulumi` CLI](/docs/install/)). The semantics of these properties are defined by conventions amongst consumers of ESC environments. For more information, see the [reserved property reference](/docs/esc/reference/reserved-properties).
+- __Sample environment definition__: This is a sample environment definition that demonstrates many of the constructs described in the other reference sections. For more information, see the [sample environment definition reference](/docs/esc/reference/sample-environment-definition).
+
+Each ESC environment is a YAML document that defines the structure and values produced when the environment is evaluated (also referred to as _opened_). For more information see the [high-level Environments documentation](/docs/esc/environments).

content/docs/esc/reference/builtin-functions/_index.md

@@ -0,0 +1,51 @@
+---
+title: Built-in Functions
+title_tag: Built-in Functions
+h1: Built-in Functions
+meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
+menu:
+  esc:
+    parent: esc-reference
+    identifier: esc-ref-builtin-functions
+    weight: 3
+---
+
+ESC provides a number of built-in functions to help perform common value manipulations and to help access information stored outside of ESC.
+
+All function invocations take the form of an object with a single key that names the function to invoke. The value of the key is the argument passed to the function. It is an error to attempt to invoke an unknown function, or for an object literal with multiple entries to contain a key with the prefix `fn::`.
+
+## Functions
+
+- [`fn::fromJSON`](/docs/esc/reference/builtin-functions/fn-from-json)
+- [`fn::fromBase64`](/docs/esc/reference/builtin-functions/fn-from-base64)
+- [`fn::join`](/docs/esc/reference/builtin-functions/fn-join)
+- [`fn::open`](/docs/esc/reference/builtin-functions/fn-open)
+- [`fn::rotate`](/docs/esc/reference/builtin-functions/fn-rotate)
+- [`fn::secret`](/docs/esc/reference/builtin-functions/fn-secret)
+- [`fn::toBase64`](/docs/esc/reference/builtin-functions/fn-to-base64)
+- [`fn::toJSON`](/docs/esc/reference/builtin-functions/fn-to-json)
+- [`fn::toString`](/docs/esc/reference/builtin-functions/fn-to-string)
+
+## Examples
+
+### Valid function invocation
+
+```yaml
+valid:
+  fn::join: [ " ", [ "hello", "world" ] ]
+```
+
+### Too many keys
+
+```yaml
+tooManyKeys:
+  fn::join: [ " ", [ "hello", "world" ] ]
+  fn::toString: { "hello": "world" }
+```
+
+### Unknown function
+
+```yaml
+unknownFunction:
+  fn::undefined: {}
+```

content/docs/esc/reference/builtin-functions/fn-from-base64.md

@@ -0,0 +1,47 @@
+---
+title: fn::fromBase64
+title_tag: fn::fromBase64
+h1: fn::fromBase64
+meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
+menu:
+  esc:
+    parent: esc-ref-builtin-functions
+    identifier: esc-ref-fn-from-base64
+    weight: 2
+---
+
+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` well-known property](/docs/esc/reference/well-known-properties/files). If the input to `fn::fromBase64` is a secret, the decoded value is also a secret.
+
+## Declaration
+
+```yaml
+fn::fromBase64: value-to-decode
+```
+
+### Parameters
+
+| Property          | Type   | Description                                                       |
+|-------------------|--------|-------------------------------------------------------------------|
+| `value-to-decode` | string | The base64-encoded value.
+
+### Returns
+
+The decoded data.
+
+## Example
+
+### Definition
+
+```yaml
+values:
+  binary-data:
+    fn::fromBase64: aGVsbG8sIHdvcmxkIQo=
+```
+
+### Evaluated result
+
+```json
+{
+  "binary-data": "hello, world!"
+}
+```

content/docs/esc/reference/builtin-functions/fn-from-json.md

@@ -0,0 +1,49 @@
+---
+title: fn::fromJSON
+title_tag: fn::fromJSON
+h1: fn::fromJSON
+meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
+menu:
+  esc:
+    parent: esc-ref-builtin-functions
+    identifier: esc-ref-fn-from-json
+    weight: 1
+---
+
+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.
+
+## Declaration
+
+```yaml
+fn::fromJSON: value-to-decode
+```
+
+### Parameters
+
+| Property          | Type   | Description                                                       |
+|-------------------|--------|-------------------------------------------------------------------|
+| `value-to-decode` | string | The JSON value to decode.
+
+### Returns
+
+The decoded value.
+
+## Example
+
+### Definition
+
+```yaml
+values:
+  json-object:
+    fn::fromJSON: "{\"hello\": \"world\"}"
+```
+
+### Evaluated result
+
+```json
+{
+  "json-object": {
+    "hello": "world"
+  }
+}
+```

content/docs/esc/reference/builtin-functions/fn-join.md

@@ -0,0 +1,57 @@
+---
+title: fn::join
+title_tag: fn::join
+h1: fn::join
+meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
+menu:
+  esc:
+    parent: esc-ref-builtin-functions
+    identifier: esc-ref-fn-join
+    weight: 3
+---
+
+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.
+
+## Declaration
+
+```yaml
+fn::join: [ delimiter, values ]
+```
+
+### Parameters
+
+| Property    | Type         | Description                                                       |
+|-------------|--------------|-------------------------------------------------------------------|
+| `delimiter` | string       | The delimiter to use when joining values
+| `values`    | List<string> | The list of strings to join
+
+### Returns
+
+The elements of `values` joined by `delimiter`.
+
+## Example
+
+### Definition
+
+```yaml
+values:
+  list-of-strings:
+    - one
+    - two
+    - three
+  joined:
+    fn::join: [ ", ", ${list-of-strings} ]
+```
+
+### Evaluated result
+
+```json
+{
+  "list-of-strings": [
+    "one",
+    "two",
+    "three"
+  ],
+  "joined": "one, two, three"
+}
+```

content/docs/esc/reference/builtin-functions/fn-open.md

@@ -0,0 +1,80 @@
+---
+title: fn::open
+title_tag: fn::open
+h1: fn::open
+meta_desc: Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways.
+menu:
+  esc:
+    parent: esc-ref-builtin-functions
+    identifier: esc-ref-fn-open
+    weight: 4
+---
+
+The `fn::open` built-in function invokes a [provider](/docs/esc/reference/providers/) to fetch values from outside of ESC.
+
+## Declaration
+
+```yaml
+fn::open:
+  provider: name
+  inputs: inputs
+```
+
+### Short form
+
+In addition to the long form syntax, `fn::open` can be invoked using the short form `fn::open::name` with the inputs provided directly:
+
+```yaml
+fn::open::name: inputs
+```
+
+### Parameters
+
+| Property    | Type         | Description                                                       |
+|-------------|--------------|-------------------------------------------------------------------|
+| `name`      | string       | The name of the provider to open.
+| `inputs`    | any          | The inputs to the provider. The exact type is provider-dependent.
+
+### Returns
+
+The return value of `fn::open` is dependent on the provider being opened.
+
+## Example
+
+### Long form
+
+```yaml
+values:
+  aws:
+    login:
+      fn::open:
+        provider: aws-login
+        inputs:
+          oidc:
+            ...
+```
+
+### Short form
+
+```yaml
+values:
+  aws:
+    login:
+      fn::open::aws-login:
+        oidc:
+          ...
+```
+
+### Evaluated result
+
+```json
+{
+  "aws": {
+    "login": {
+      "AWS_ACCESS_KEY_ID": ...,
+      "AWS_SECRET_ACCESS_KEY": ...,
+      "AWS_SESSION_TOKEN": ...
+    }
+  }
+}
+```