Added note on ansible known issues

[juanmatias]

What?

• Added a note on two known issues for Ansible

Why?

• To provide a quick fix for these issues

Summary by CodeRabbit

• Documentation
  • Added a Known Issues guide for Ansible covering SSH key handling in containerized runs, two common failure modes (key location mismatch, keys protected by passphrase), and recommended workarounds including key placement and using unencrypted keys when ssh-agent forwarding is unavailable.
  • Updated site navigation to add the new Known Issues entry under the Reference Architecture for Ansible.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a new documentation page describing SSH key handling and common failure modes when running Ansible inside the leverage run apply container, and updates MkDocs navigation to include the new "Known issues" page under the Reference Architecture for Ansible sections.

Changes

Cohort / File(s)	Summary
Documentation docs/user-guide/ref-architecture-ansible/known-issues.md	New page detailing SSH key handling for Ansible in containerized leverage run apply, including failure modes (key location mismatch, passphrase-protected keys), example inventory snippet, and recommended solutions (mounting keys, path adjustments, use of unencrypted keys).
Navigation Configuration mkdocs.yml	Added "Known issues" entry under the Reference Architecture for Ansible in the site navigation (both main and User Guide locations).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify the documentation accurately reflects container SSH key mounting behavior and the example inventory paths.
• Confirm mkdocs.yml entries are correctly formatted and the new page path resolves in the generated site.

Suggested reviewers

• martingaleano
• exequielrafaela

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: adding documentation about Ansible known issues for the leverage run apply command.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch kungfoo/ansible-known-issues

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2ed31fd and 7f15a0a.

📒 Files selected for processing (1)

• docs/user-guide/ref-architecture-ansible/known-issues.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

docs/**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

Edit and maintain documentation content as Markdown files under docs/

Files:

• docs/user-guide/ref-architecture-ansible/known-issues.md

{docs/**/*.md,*.md}

📄 CodeRabbit inference engine (.cursor/rules/doc-binbash-leverage.mdc)

{docs/**/*.md,*.md}: Follow binbash Leverage terminology and architectural concepts as defined in this rule file across all documentation content
Always reference official sources (linked docs and repositories) as the primary truth
Align recommendations with the AWS Well-Architected Framework
Consider the multi-layer architecture (Network, Security, Shared, Apps) when providing guidance
Account for the multi-account organizational structure (Management, Security, Shared, Apps/Workloads)
Prefer using existing Terraform/OpenTofu modules from the Leverage library before custom solutions (Module-First)
Emphasize security by design, compliance, and governance in recommendations
Provide practical, actionable, and tested implementation guidance
Show concrete Leverage CLI commands for operations and workflows
For architecture topics, reference specific documentation sections and established patterns from the reference architecture
For architecture topics, consider layer dependencies and account boundaries
For module usage, reference module documentation, examples, and the Makefile module list for versions
For module usage, follow established naming and tagging conventions
For CLI operations, reference credential management and Docker-based execution context, and include troubleshooting tips
For troubleshooting, cover common credential/config issues, layer dependencies, account setup, and CLI version compatibility
Reference the provided essential resources and repositories when guiding users (Leverage docs site, core repos, PyPI package)

Files:

• docs/user-guide/ref-architecture-ansible/known-issues.md

{mkdocs.yml,docs/**/*.md}

📄 CodeRabbit inference engine (.cursor/rules/doc-binbash-leverage.mdc)

{mkdocs.yml,docs/**/*.md}: Maintain consistency with existing documentation structure and navigation
Organize content according to the documented sections (Concepts, Try Leverage, User Guide, How It Works, Work With Us, Key Feature Documentation)

Files:

• docs/user-guide/ref-architecture-ansible/known-issues.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to {docs/**/*.md,*.md} : For CLI operations, reference credential management and Docker-based execution context, and include troubleshooting tips

🪛 LanguageTool

docs/user-guide/ref-architecture-ansible/known-issues.md

[style] ~33-~33: Using many exclamation marks might seem excessive (in this case: 6 exclamation marks for a text that’s 1806 characters long)
Context: ... container, and Ansible cannot use it. !!! idea "Solution" For SSH keys inte...

(EN_EXCESSIVE_EXCLAMATION)

🔇 Additional comments (1)

docs/user-guide/ref-architecture-ansible/known-issues.md (1)

1-37: Documentation is clear, practical, and well-structured.

The page effectively explains two common SSH key issues when running Ansible inside containers and provides actionable solutions with a concrete inventory example. The content correctly references credential management in the Docker-based execution context as aligned with learnings.

Minor suggestions for consideration:

1. Static analysis note: LanguageTool flagged 6 exclamation marks across the text. This is acceptable documentation tone, but consider if the current count feels natural when reading aloud.

2. Optional enhancement: Per the learnings on CLI operations, consider adding a brief line linking to Leverage credential setup documentation or explicitly mentioning the ~/.ssh/bb directory as part of the standard credential layout. This would strengthen the connection to the broader credential management context.

3. Verification needed: The AI summary mentions mkdocs.yml was updated to include navigation entries for "Known issues" under Reference Architecture for Ansible. Please confirm this navigation is included so readers can discover this page.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

docs/user-guide/ref-architecture-ansible/known-issues.md (2)

28-36: Discuss security trade-offs regarding passphrase-less keys.

The recommendation to avoid passphrases pragmatically solves the ssh-agent forwarding limitation in containers, but this may weaken key security posture. Consider noting that users should apply compensating controls elsewhere (e.g., restricted key permissions, limited scope, secure storage of ~/.ssh/bb).

Example addition:

 !!! idea "Solution"
       For SSH keys intended for use with **EC2 instances** via `leverage run apply`, it is recommended to use keys that **do not have a passphrase**.
+      
+      **Security note:** Passphrase-less keys are less protected if compromised locally. Ensure proper file permissions (e.g., `chmod 600`) and consider limiting key scope to specific instances or roles.

---

1-37: Align documentation with Leverage CLI context and best practices.

The document covers troubleshooting and Docker execution context well, but could strengthen alignment with Leverage guidelines by:

1. Cross-referencing the Leverage CLI run command documentation
2. Explicitly showing the leverage run apply command context
3. Adding a reference to credential management best practices in the Leverage docs

Based on learnings, documentation for CLI operations should reference credential management and Docker-based execution context, which you cover; consider adding links to relevant Leverage documentation sections to provide the "official source of truth."

Consider adding an introductory paragraph or "See also" section:

### See also
- [Leverage CLI `run` command reference](../leverage-cli/reference/run.md)
- [Credentials and Secrets Management](../ref-architecture-aws/features/secrets/secrets.md)

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 98d30eb and 2ed31fd.

📒 Files selected for processing (2)

• docs/user-guide/ref-architecture-ansible/known-issues.md (1 hunks)
• mkdocs.yml (1 hunks)

🧰 Additional context used

📓 Path-based instructions (4)

docs/**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

Edit and maintain documentation content as Markdown files under docs/

Files:

• docs/user-guide/ref-architecture-ansible/known-issues.md

{docs/**/*.md,*.md}

📄 CodeRabbit inference engine (.cursor/rules/doc-binbash-leverage.mdc)

{docs/**/*.md,*.md}: Follow binbash Leverage terminology and architectural concepts as defined in this rule file across all documentation content
Always reference official sources (linked docs and repositories) as the primary truth
Align recommendations with the AWS Well-Architected Framework
Consider the multi-layer architecture (Network, Security, Shared, Apps) when providing guidance
Account for the multi-account organizational structure (Management, Security, Shared, Apps/Workloads)
Prefer using existing Terraform/OpenTofu modules from the Leverage library before custom solutions (Module-First)
Emphasize security by design, compliance, and governance in recommendations
Provide practical, actionable, and tested implementation guidance
Show concrete Leverage CLI commands for operations and workflows
For architecture topics, reference specific documentation sections and established patterns from the reference architecture
For architecture topics, consider layer dependencies and account boundaries
For module usage, reference module documentation, examples, and the Makefile module list for versions
For module usage, follow established naming and tagging conventions
For CLI operations, reference credential management and Docker-based execution context, and include troubleshooting tips
For troubleshooting, cover common credential/config issues, layer dependencies, account setup, and CLI version compatibility
Reference the provided essential resources and repositories when guiding users (Leverage docs site, core repos, PyPI package)

Files:

• docs/user-guide/ref-architecture-ansible/known-issues.md

{mkdocs.yml,docs/**/*.md}

📄 CodeRabbit inference engine (.cursor/rules/doc-binbash-leverage.mdc)

{mkdocs.yml,docs/**/*.md}: Maintain consistency with existing documentation structure and navigation
Organize content according to the documented sections (Concepts, Try Leverage, User Guide, How It Works, Work With Us, Key Feature Documentation)

Files:

• docs/user-guide/ref-architecture-ansible/known-issues.md
• mkdocs.yml

mkdocs.yml

📄 CodeRabbit inference engine (CLAUDE.md)

Maintain site structure and navigation in mkdocs.yml and keep it in sync with content

Keep mkdocs.yml aligned with the documentation structure and navigation defined for the project

Files:

• mkdocs.yml

🧠 Learnings (8)

📓 Common learnings

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to {docs/**/*.md,*.md} : For CLI operations, reference credential management and Docker-based execution context, and include troubleshooting tips

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to {docs/**/*.md,*.md} : For troubleshooting, cover common credential/config issues, layer dependencies, account setup, and CLI version compatibility

📚 Learning: 2025-10-06T20:21:51.595Z

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to {docs/**/*.md,*.md} : For CLI operations, reference credential management and Docker-based execution context, and include troubleshooting tips

Applied to files:

• docs/user-guide/ref-architecture-ansible/known-issues.md
• mkdocs.yml

📚 Learning: 2025-10-06T20:21:51.595Z

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to {mkdocs.yml,docs/**/*.md} : Maintain consistency with existing documentation structure and navigation

Applied to files:

• mkdocs.yml

📚 Learning: 2025-10-06T20:21:51.595Z

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to mkdocs.yml : Keep mkdocs.yml aligned with the documentation structure and navigation defined for the project

Applied to files:

• mkdocs.yml

📚 Learning: 2025-10-06T20:21:03.832Z

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-10-06T20:21:03.832Z
Learning: Applies to mkdocs.yml : Maintain site structure and navigation in mkdocs.yml and keep it in sync with content

Applied to files:

• mkdocs.yml

📚 Learning: 2025-10-06T20:21:51.595Z

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to {mkdocs.yml,docs/**/*.md} : Organize content according to the documented sections (Concepts, Try Leverage, User Guide, How It Works, Work With Us, Key Feature Documentation)

Applied to files:

• mkdocs.yml

📚 Learning: 2025-10-06T20:21:51.595Z

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to {docs/**/*.md,*.md} : For architecture topics, reference specific documentation sections and established patterns from the reference architecture

Applied to files:

• mkdocs.yml

📚 Learning: 2025-10-06T20:21:51.595Z

Learnt from: CR
Repo: binbashar/le-ref-architecture-doc PR: 0
File: .cursor/rules/doc-binbash-leverage.mdc:0-0
Timestamp: 2025-10-06T20:21:51.595Z
Learning: Applies to {docs/**/*.md,*.md} : Show concrete Leverage CLI commands for operations and workflows

Applied to files:

• mkdocs.yml

🪛 LanguageTool

docs/user-guide/ref-architecture-ansible/known-issues.md

[style] ~33-~33: Using many exclamation marks might seem excessive (in this case: 6 exclamation marks for a text that’s 1807 characters long)
Context: ... container, and Ansible cannot use it. !!! idea "Solution" For SSH keys inte...

(EN_EXCESSIVE_EXCLAMATION)

🔇 Additional comments (1)

mkdocs.yml (1)

261-265: Navigation update is properly structured.

The new entry is correctly positioned in the "Reference Architecture for Ansible" section with consistent indentation and follows the established pattern. The file path aligns with the documentation file location.