docs: add example for complex usage of !include with triple quotes #1086
Conversation
📝 WalkthroughWalkthroughThe changes introduce enhancements to the documentation and configuration files related to the Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
website/docs/core-concepts/stacks/yaml-functions/include.mdx (1)
173-179: Clarify Triple Quotes ExampleThe new example clearly demonstrates how to handle cases that require triple double quotes when combining file paths and complex YQ expressions. For extra clarity, consider adding a brief inline comment or expanding the surrounding text to explain when and why the triple quotes are necessary (for instance, when the YQ expression itself contains syntax that could be misinterpreted by YAML). This extra detail could help users quickly understand the rationale behind this syntax choice.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
website/docs/core-concepts/stacks/yaml-functions/include.mdx(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (4)
- GitHub Check: Build (windows-latest, windows)
- GitHub Check: website-deploy-preview
- GitHub Check: Analyze (go)
- GitHub Check: Summary
| @@ -170,3 +170,9 @@ On macOS and Linux: | |||
| values: !include './values.yaml "<yq-expression-with-spaces>"' | |||
| description: !include '"component description.md"' | |||
| ``` | |||
|
|
|||
| Sometimes for more complex cases you may need to utilize 3x double quotes, for examples: | |||
There was a problem hiding this comment.
I rather we address the root cause. This is absurd. This is a hack, a workaround. This is not the solution.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
tests/fixtures/scenarios/atmos-include-yaml-function/config/vars.yaml (1)
11-19: Fix YAML formatting issues.The YAML linter reports trailing spaces and incorrect indentation.
Apply this diff to fix the formatting:
-other_list_var: +other_list_var: - d - e - f list_objects: - hyphenated-list-var: - - x - - y - - z + - x + - y + - z🧰 Tools
🪛 YAMLlint (1.35.1)
[error] 11-11: trailing spaces
(trailing-spaces)
[warning] 17-17: wrong indentation: expected 6 but found 4
(indentation)
tests/fixtures/scenarios/atmos-include-yaml-function/atmos.yaml (1)
24-30: Document template settings and consider security implications.While enabling template features enhances functionality, it's important to document:
- The purpose and impact of each template setting
- Security considerations when enabling template engines
- Best practices for using these features safely
Consider adding documentation about these settings and their security implications. Would you like me to help draft this documentation?
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
tests/fixtures/scenarios/atmos-include-yaml-function/atmos.yaml(1 hunks)tests/fixtures/scenarios/atmos-include-yaml-function/config/vars.json(1 hunks)tests/fixtures/scenarios/atmos-include-yaml-function/config/vars.tfvars(1 hunks)tests/fixtures/scenarios/atmos-include-yaml-function/config/vars.yaml(1 hunks)tests/fixtures/scenarios/atmos-include-yaml-function/stacks/deploy/nonprod.yaml(1 hunks)
🧰 Additional context used
🪛 YAMLlint (1.35.1)
tests/fixtures/scenarios/atmos-include-yaml-function/config/vars.yaml
[error] 11-11: trailing spaces
(trailing-spaces)
[warning] 17-17: wrong indentation: expected 6 but found 4
(indentation)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: Build (windows-latest, windows)
- GitHub Check: Summary
🔇 Additional comments (6)
tests/fixtures/scenarios/atmos-include-yaml-function/config/vars.json (1)
9-22: LGTM! JSON structure is well-formed and consistent.The new variables are properly formatted and maintain consistency with other configuration files.
tests/fixtures/scenarios/atmos-include-yaml-function/stacks/deploy/nonprod.yaml (5)
17-17: Clarify the relative path comment.The comment on this line clearly reminds users that relative paths are based on the location of the file with the
!includedirective, which is helpful for avoiding confusion when referencing files.
18-18: Validate the complex YQ expression.The inclusion syntax for
complex_yq_var—combining.list_varand.other_list_varfrom"../../config/vars.json"—is a neat way to demonstrate advanced usage. Please verify that concatenating these variables produces the intended result and that the referenced keys are available in all relevant configurations.
19-19: Review handling of hyphenated keys.The
hyphenated_list_varincludes a hyphenated key (hyphenated-list-var), and the expression concatenating.list_var,.other_list_var, and.list_objects[0].hyphenated-list-varis interesting. Confirm that the parser correctly processes hyphenated keys within this context.
20-20: Affirm the triple quotes note.The inline comment explaining that the HTTP include requires triple quotes due to the space in the jq filter is clear and beneficial for users who might run into similar issues.
21-21: Confirm triple quotes usage in HTTP include.The
http_varcorrectly demonstrates how to use triple double quotes to wrap a complex filter with spaces. Please ensure that this syntax is compliant with your YAML parser and that it functions as expected in practice.
| other_list_var : [ | ||
| "d", | ||
| "e", | ||
| "f" | ||
| ] |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Standardize variable assignment syntax and avoid hyphens in Terraform variable names.
The new variables use : for assignment while existing variables use =. Additionally, the hyphenated key name might cause issues in Terraform.
Apply this diff to maintain consistency and Terraform compatibility:
-other_list_var : [
+other_list_var = [
"d",
"e",
"f"
]
-list_objects : [
+list_objects = [
{
- hyphenated-list-var : [
+ hyphenated_list_var = [
"x",
"y",
"z"
]
}
]Also applies to: 14-22
| complex_yq_var: !include '"../../config/vars.json" ".list_var + .other_list_var"' | ||
| hyphenated_list_var: !include '"../../config/vars.json" ".list_var + .other_list_var + .list_objects[0].hyphenated-list-var"' | ||
| ### http include with space based jq filter requires triple quotes. | ||
| http_var: !include '"https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json" """.definitions.backend_type.enum + .definitions.metadata.properties.type.enum"""' |
There was a problem hiding this comment.
Can we test what we discussed on Friday ARB?
| @@ -19,3 +19,12 @@ stacks: | |||
| logs: | |||
| file: "/dev/stderr" | |||
| level: Info | |||
|
|
|||
| vars: | ||
| my_array: !include '"https://foo.com/bar.json" """.some_key.array_one + .some_key.hyphenated-field.array_two"""' |
There was a problem hiding this comment.
Please try this instead
| vars: | |
| my_array: !include '"https://foo.com/bar.json" """.some_key.array_one + .some_key.hyphenated-field.array_two"""' | |
| vars: | |
| my_array: !include > | |
| https://foo.com/bar.json | |
| ".some_key.array_one + .some_key.hyphenated-field.array_two" |
what
!includeYAML function in Atmos.why
!includefunction in their Atmos stack manifests.references
Summary by CodeRabbit
Documentation
New Features
templatessection in the YAML configuration, enabling new template settings.