ESC Environments reference #14634
ESC Environments reference #14634
Conversation
|
Your site preview for commit 4e95be3 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-14634-4e95be3a.s3-website.us-west-2.amazonaws.com. |
Co-authored-by: James Denyer <[email protected]>
|
Your site preview for commit d9f0fd3 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-14634-d9f0fd37.s3-website.us-west-2.amazonaws.com. |
|
|
||
| ## Properties | ||
|
|
||
| - [`environmentVariables`](/docs/esc/reference/well-known-properties/environment-variables) |
There was a problem hiding this comment.
What about pulumiConfig?
There was a problem hiding this comment.
pulumiConfig is not interpreted by the esc CLI, so I opted to leave it out. It's also already documented in the Pulumi IaC integration reference. I don't feel super strongly about this one, though, so if folks think it should be in here I'll add it.
There was a problem hiding this comment.
I think it would be expected here, they may not have seen the Pulumi IaC reference. You also mentioned "other consumers" like IaC at the top of the file.
There was a problem hiding this comment.
I think it would be expected here, they may not have seen the Pulumi IaC reference.
SG. I'll add some headers to differentiate "always expected" vs. "only expected when integrating with tool x".
You also mentioned "other consumers" like IaC at the top of the file.
Yeah--what I was trying to communicate is that any consumer of an evaluated environment that deals with envvars, etc. should probably interpret these properties.
There was a problem hiding this comment.
pulumiConfigis not interpreted by theescCLI, so I opted to leave it out. It's also already documented in the Pulumi IaC integration reference. I don't feel super strongly about this one, though, so if folks think it should be in here I'll add it.
I would mention it and say exactly that (in so many words) in the docs!
|
Your site preview for commit 38c2ad3 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-14634-38c2ad3d.s3-website.us-west-2.amazonaws.com. |
| weight: 7 | ||
| --- | ||
|
|
||
| The [`esc` CLI](/docs/install/esc/) and other ESC consumers (e.g. the [`pulumi` CLI](/docs/install/)) conventially assign specific semantics to certain top-level properties of evaluated ESC environments. |
There was a problem hiding this comment.
I think this is a slightly subtle point that may be worth elaborating on a bit further, since we're using "top-level properties" in two different slightly ways. We have top level document properties (imports/values) as described in the dedicated top-level-properties section, but here we're referring to top level properties of the evaluated environment, which are the properties under values. I know that's what you said, but it may be worth explicitly telling the user we're talking about top-level values here?
| weight: 6 | ||
| --- | ||
|
|
||
| The `fn::secret` built-in function decrypts a ciphertext literal into a secret string value. |
There was a problem hiding this comment.
do we define what secret means anywhere? maybe we need a vocabulary page?
There was a problem hiding this comment.
Also, doesn't it encrypt it, not decrypt it?
| weight: 6 | ||
| --- | ||
|
|
||
| ESC rotators allow users to rotate credentials and secrets using ESC. These providers are accessed via the `fn::rotate` built-in function. |
There was a problem hiding this comment.
should we mention they remain static until they are triggered by the rotate verb?
content/docs/esc/reference/_index.md
Outdated
| @@ -0,0 +1,30 @@ | |||
| --- | |||
| title: Environment Reference | |||
There was a problem hiding this comment.
Environment is a very overloaded term, I wonder if calling this Environment Definition Reference might be clearer? It's kind of long though
There was a problem hiding this comment.
Suggest "ESC Syntax Reference" or "Environment Syntax Reference" (longer version), "Syntax Reference" for the doc tree since the context is clear
Co-authored-by: Claire <[email protected]>
| @@ -0,0 +1,18 @@ | |||
| --- | |||
| title: Well-Known Properties | |||
There was a problem hiding this comment.
I know that it's more technically correct, but I don't think "well-known" communicates the concept to a practitioner as well as "reserved" (which, if it's technically incorrect, I don't think we should use) or "special" (not very technical, but easy to conceptualize).
Co-authored-by: Claire <[email protected]>
|
Your site preview for commit 1de8af0 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-14634-1de8af06.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit cb0b2cc is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-14634-cb0b2cc9.s3-website.us-west-2.amazonaws.com. |
These changes add a more complete reference section to the ESC documentation.
This reference content covers the contents of ESC environment definitions, including:
Fixes #14289