docs(ansible): add documentation and examples for Ansible integration#2108
docs(ansible): add documentation and examples for Ansible integration#2108
Conversation
- Add demo-ansible example with hello-world playbook, catalog, and dev/prod stacks - Add test cases for stack listing, describe component, and dry-run - Add new doc pages: Ansible components, CLI configuration, stack configuration - Update existing docs to consistently include Ansible alongside Terraform, Helmfile, and Packer - Add Ansible feature card to features overview - Add EmbedFile/EmbedExample usage in playbook command docs - Update file-browser plugin with demo-ansible tags and docs mapping - Remove accidentally committed build artifacts (.docusaurus/, package-lock.json)
|
Important Cloud Posse Engineering Team Review RequiredThis pull request modifies files that require Cloud Posse's review. Please be patient, and a core maintainer will review your changes. To expedite this process, reach out to us on Slack in the |
Dependency Review✅ No vulnerabilities or license issues found.Scanned FilesNone |
📝 WalkthroughWalkthroughAdds first-class Ansible component support: demo example, tests, CLI dry-run plumbing, describe/stack processing, executor dry-run behavior, extensive docs and website updates, and minor .gitignore updates. Changes
Sequence Diagram(s)sequenceDiagram
participant CLI as CLI
participant Describe as DescribeStacks
participant Executor as AnsibleExecutor
participant FS as Filesystem
CLI->>Describe: request describe/list (includes ansible)
Describe->>FS: read stack manifests & component files
Describe->>Describe: process templates / yaml functions
Describe->>CLI: return configAndStacksInfo (includes DryRun flag)
CLI->>Executor: run ansible-playbook (with config)
Executor->>FS: read playbook / inventory
alt Dry-run
Executor->>CLI: print constructed command and exit
else Execute
Executor->>CLI: spawn ansible-playbook process
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (3)
website/docs/components/ansible.mdx (1)
1-6:descriptionfrontmatter field is missing.Other component docs (e.g.,
components.mdx) include adescriptionfor SEO and sidebar tooltips. Worth adding for consistency.✏️ Proposed addition
--- title: Using Ansible sidebar_position: 6 sidebar_label: Ansible id: ansible +description: Run Ansible playbooks with the same stack-based configuration used for Terraform and Helmfile. Stack variables are automatically passed via --extra-vars. ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/docs/components/ansible.mdx` around lines 1 - 6, The Ansible docs frontmatter is missing the SEO/tooltip `description` field; add a `description: "..."` entry to the MDX frontmatter block at the top of ansible.mdx (alongside title, sidebar_position, sidebar_label, id) with a short summary of the page (a one-sentence description) so it matches other component docs like components.mdx and enables consistent SEO and sidebar tooltips.website/docs/cli/configuration/components/ansible.mdx (1)
68-87: "Example Configuration" section duplicates the "Configuration" section above.The YAML block on lines 70-77 is byte-for-byte identical to lines 19-29. One of these sections should be removed or the "Example Configuration" block should show a more realistic/extended example.
♻️ Suggested cleanup
-## Example Configuration - -<File title="atmos.yaml"> -```yaml -components: - ansible: - command: ansible - base_path: components/ansible -``` -</File> - -With this configuration, you can run Ansible commands through Atmos: +With this configuration, you can run Ansible commands through Atmos:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/docs/cli/configuration/components/ansible.mdx` around lines 68 - 87, The "Example Configuration" section duplicates the earlier "Configuration" YAML for the ansible component; remove the duplicate YAML block under the "Example Configuration" heading or replace it with a more realistic/extended example. Locate the ansible component YAML (the block showing components: ansible: command: ansible base_path: components/ansible) and either delete the repeated block or expand it to show additional realistic keys (e.g., env vars, inventory path, extra_args) and adjust the subsequent example commands (the atmos ansible playbook/version snippets) to match the extended example. Ensure only one authoritative configuration example for the ansible component remains and the headings remain consistent.website/docs/stacks/components/ansible.mdx (1)
11-11:EmbedFileis imported but never used.The import at line 11 can be dropped since no
<EmbedFile>element appears anywhere in the file.♻️ Proposed fix
import File from '@site/src/components/File' import Intro from '@site/src/components/Intro' -import EmbedFile from '@site/src/components/EmbedFile'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/docs/stacks/components/ansible.mdx` at line 11, Remove the unused import of the EmbedFile component by deleting the line that imports EmbedFile (the "import EmbedFile from '@site/src/components/EmbedFile'" statement) since no <EmbedFile> element is used in the document; if you intended to embed a file, instead add the corresponding <EmbedFile .../> usage where required, otherwise simply remove the import to clean up the module.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@website/docs/components/ansible.mdx`:
- Line 72: Update the sentence "Command line flags take precedence over stack
manifest settings:" to hyphenate "command-line" (i.e., change it to
"Command-line flags take precedence over stack manifest settings:") to fix the
minor grammar issue in the ansible.mdx content.
- Around line 28-32: The docs show "command: ansible" but the ansible playbook
flow delegates to the ansible-playbook binary; update the example and any
schema/defaults to "command: ansible-playbook" to match the actual delegated
binary used by the playbook runner (verify references such as the ansible
playbook handler in code like AnsiblePlaybook, any ansible.go execution strings,
and the other docs file command.mdx) so examples and defaults align with the
real binary.
In `@website/docs/stacks/command.mdx`:
- Around line 165-172: The docs currently imply ansible.command in
_defaults.yaml applies to all Ansible invocations but the code path that runs
playbooks hardcodes the binary name (the playbook execution in executor.go that
invokes "ansible-playbook"), so update the documentation to state that
ansible.command only affects non-playbook subcommands and does not change the
binary used for atmos ansible playbook; advise two practical remedies: set
ansible.command to the full path of the ansible-playbook binary (e.g.,
/opt/venv/bin/ansible-playbook), or use a wrapper/symlink inside the virtualenv
to expose ansible-playbook at the expected name, or note that changing the
playbook behavior requires modifying the playbook invocation in executor.go to
use the configured ansible.command.
In `@website/docs/stacks/components/ansible.mdx`:
- Around line 196-200: Update the example and/or explanatory text around the
`<context>-<component>.ansible.vars.yaml` naming line to clarify that
`<context>` is the full Atmos context string (e.g., `acme-plat-prod-us-east-1`),
not just the short stack name; either change the example
`prod-webserver.ansible.vars.yaml` to a representative one like
`acme-plat-prod-us-east-1-webserver.ansible.vars.yaml` or add a parenthetical
explaining what `<context>` resolves to, and ensure the doc line referencing
`<context>-<component>.ansible.vars.yaml` is updated accordingly.
---
Nitpick comments:
In `@website/docs/cli/configuration/components/ansible.mdx`:
- Around line 68-87: The "Example Configuration" section duplicates the earlier
"Configuration" YAML for the ansible component; remove the duplicate YAML block
under the "Example Configuration" heading or replace it with a more
realistic/extended example. Locate the ansible component YAML (the block showing
components: ansible: command: ansible base_path: components/ansible) and either
delete the repeated block or expand it to show additional realistic keys (e.g.,
env vars, inventory path, extra_args) and adjust the subsequent example commands
(the atmos ansible playbook/version snippets) to match the extended example.
Ensure only one authoritative configuration example for the ansible component
remains and the headings remain consistent.
In `@website/docs/components/ansible.mdx`:
- Around line 1-6: The Ansible docs frontmatter is missing the SEO/tooltip
`description` field; add a `description: "..."` entry to the MDX frontmatter
block at the top of ansible.mdx (alongside title, sidebar_position,
sidebar_label, id) with a short summary of the page (a one-sentence description)
so it matches other component docs like components.mdx and enables consistent
SEO and sidebar tooltips.
In `@website/docs/stacks/components/ansible.mdx`:
- Line 11: Remove the unused import of the EmbedFile component by deleting the
line that imports EmbedFile (the "import EmbedFile from
'@site/src/components/EmbedFile'" statement) since no <EmbedFile> element is
used in the document; if you intended to embed a file, instead add the
corresponding <EmbedFile .../> usage where required, otherwise simply remove the
import to clean up the module.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (27)
.gitignoreexamples/demo-ansible/.gitignoreexamples/demo-ansible/README.mdexamples/demo-ansible/atmos.yamlexamples/demo-ansible/components/ansible/hello-world/inventory.iniexamples/demo-ansible/components/ansible/hello-world/site.ymlexamples/demo-ansible/stacks/catalog/hello-world.yamlexamples/demo-ansible/stacks/deploy/dev.yamlexamples/demo-ansible/stacks/deploy/prod.yamltests/test-cases/demo-ansible.yamlwebsite/docs/cli/commands/ansible/ansible-playbook.mdxwebsite/docs/cli/configuration/components/ansible.mdxwebsite/docs/cli/configuration/components/index.mdxwebsite/docs/components/ansible.mdxwebsite/docs/components/components-overview.mdxwebsite/docs/components/components.mdxwebsite/docs/intro/features.mdxwebsite/docs/stacks/command.mdxwebsite/docs/stacks/components/ansible.mdxwebsite/docs/stacks/components/index.mdxwebsite/docs/stacks/dependencies.mdxwebsite/docs/stacks/env.mdxwebsite/docs/stacks/settings/index.mdxwebsite/docs/stacks/stacks.mdxwebsite/docs/stacks/vars.mdxwebsite/plugins/file-browser/index.jswebsite/sidebars.js
|
@aknysh Does this PR look good? Just adding some documentation for the Atmos Ansible integration work |
|
@RoseSecurity the tests are failing: |
b151796
|
Warning This PR exceeds the recommended limit of 1,000 lines.Large PRs are difficult to review and may be rejected due to their size. Please verify that this PR does not address multiple issues. |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #2108 +/- ##
========================================
Coverage 76.49% 76.49%
========================================
Files 831 831
Lines 79088 79254 +166
========================================
+ Hits 60497 60625 +128
- Misses 14819 14835 +16
- Partials 3772 3794 +22
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@internal/exec/describe_component.go`:
- Around line 447-459: The code currently only falls back to Ansible when Packer
returns errUtils.ErrInvalidComponent; change the gate so any Packer failure will
attempt the Ansible path. In the block around tryProcessWithComponentType use
baseParams (baseParams.configAndStacksInfo/result and baseParams.componentType =
cfg.AnsibleComponentType) and call tryProcessWithComponentType(&baseParams)
regardless of whether errors.Is(err, errUtils.ErrInvalidComponent) (i.e., remove
or invert that conditional); keep the existing handling that on an Ansible error
you set result.ComponentSection[cfg.ComponentTypeSectionName] = "" and return
the error.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
cmd/ansible/ansible.gointernal/exec/describe_component.gointernal/exec/describe_stacks.gopkg/component/ansible/executor.go
There was a problem hiding this comment.
🧹 Nitpick comments (1)
internal/exec/describe_stacks_test.go (1)
226-243: Add the missing devapp_portassertion.The test validates dev
app_name/app_versionbut skips devapp_port(expected in PR goals and failing CLI cases). Adding it strengthens regression coverage.Suggested patch
val, err = u.EvaluateYqExpression(&atmosConfig, stacksMap, ".dev.components.ansible.hello-world.vars.app_version") assert.Nil(t, err) assert.Equal(t, "1.0.0-dev", val) + + val, err = u.EvaluateYqExpression(&atmosConfig, stacksMap, ".dev.components.ansible.hello-world.vars.app_port") + assert.Nil(t, err) + assert.Equal(t, 8080, val)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@internal/exec/describe_stacks_test.go` around lines 226 - 243, Test is missing an assertion for the dev component's app_port; add a call to u.EvaluateYqExpression(&atmosConfig, stacksMap, ".dev.components.ansible.hello-world.vars.app_port"), assert the error is nil, and assert the returned value equals the expected dev port (e.g. 80) using the same pattern as the existing dev and prod assertions to mirror the prod app_port check.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@internal/exec/describe_stacks_test.go`:
- Around line 226-243: Test is missing an assertion for the dev component's
app_port; add a call to u.EvaluateYqExpression(&atmosConfig, stacksMap,
".dev.components.ansible.hello-world.vars.app_port"), assert the error is nil,
and assert the returned value equals the expected dev port (e.g. 80) using the
same pattern as the existing dev and prod assertions to mirror the prod app_port
check.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
internal/exec/describe_component_test.gointernal/exec/describe_stacks_test.go
|
@osterman Fixed the outputs and such! |
|
These changes were released in v1.208.0. |
what
demo-ansibleexample, including stack manifests, catalog defaults, Ansible playbook, inventory, Atmos configuration, and.gitignoreentries for Ansible artifacts. This demonstrates variable handling, catalog pattern, and per-environment overrides for Ansible components. [1] [2] [3] [4] [5] [6] [7] [8]atmos.yamland stack manifests. [1] [2]ansible-playbookcommand reference with embedded example files and an interactive demo, improving clarity and real-world applicability. [1] [2] [3]\why
Summary by CodeRabbit
New Features
Documentation
Tests
Chores