Skip to content

Refactor Leapp migration docs for clarity#1668

Merged
osterman merged 3 commits intodocs/leapp-atmosauth-migrationfrom
osterman/simplify-leapp-migration
Oct 19, 2025
Merged

Refactor Leapp migration docs for clarity#1668
osterman merged 3 commits intodocs/leapp-atmosauth-migrationfrom
osterman/simplify-leapp-migration

Conversation

@osterman
Copy link
Member

what

  • Moved the "Quick Migration Example" section to be more prominent, appearing immediately after the overview.
  • Encapsulated the detailed "Understanding Leapp Components" section within a collapsible <details> block, making it optional for users who need more context.
  • Simplified the "Using with Geodesic" section by reducing its length and directly linking to the dedicated Geodesic configuration guide.
  • Removed specific reference architecture terminology and concepts to provide a more general guide.

why

  • To address feedback that the migration page was too verbose and conflated general Atmos concepts with specific reference architectures.
  • The goal is to make it easier for users to quickly understand what they need to change and how to log in when migrating from Leapp to Atmos Auth.
  • Collapsing detailed explanations and linking to dedicated guides improves scannability and focuses the primary content on the migration itself.

references

  • closes #

@codecov
Copy link

codecov bot commented Oct 19, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 65.97%. Comparing base (b9a6176) to head (c6c72e3).
⚠️ Report is 1 commits behind head on docs/leapp-atmosauth-migration.

Additional details and impacted files

Impacted file tree graph

@@                        Coverage Diff                         @@
##           docs/leapp-atmosauth-migration    #1668      +/-   ##
==================================================================
- Coverage                           66.02%   65.97%   -0.06%     
==================================================================
  Files                                 343      343              
  Lines                               38686    38686              
==================================================================
- Hits                                25543    25523      -20     
- Misses                              11151    11169      +18     
- Partials                             1992     1994       +2     
Flag Coverage Δ
unittests 65.97% <ø> (-0.06%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@osterman osterman merged commit a5798c3 into docs/leapp-atmosauth-migration Oct 19, 2025
47 checks passed
@osterman osterman deleted the osterman/simplify-leapp-migration branch October 19, 2025 14:02
@mergify mergify bot removed the triage Needs triage label Oct 19, 2025
osterman added a commit that referenced this pull request Oct 20, 2025
* initial migration guide

* remove extra image

* update docs

* bugfix build and update docs a bit for makefile and source profiles

* fix links

* Update image and guide

* update guide

* Add Atmos Auth guides and blog post (#1659)

* Fix AWS region inconsistency in Leapp migration docs

Updated provider region from us-east-2 to us-east-1 to match the Leapp
session example shown in the documentation (US-EAST-1). This ensures
users copying the example will use the correct region that corresponds
to their Leapp configuration reference.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix AWS_CONFIG_FILE redefinition in Geodesic Dockerfile

Changed the second AWS_CONFIG_FILE assignment to use AWS_CONFIG_TEAMS
to avoid clobbering the Atmos-managed config path. This ensures that:

- AWS_CONFIG_FILE points to Atmos auth config (required for authentication)
- AWS_CONFIG_TEAMS points to teams config (for assume-role utilities)

Added a note explaining the separation and how to update Geodesic
utilities that reference the teams config.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add Geodesic guide and blog post for auth tutorials

Created comprehensive documentation for configuring Geodesic with
Atmos Auth and introduced both guides with a blog post:

New Files:
- website/docs/cli/commands/auth/tutorials/configuring-geodesic-with-atmos-auth.mdx
  Complete guide for integrating Geodesic with Atmos Auth, including:
  - Dockerfile environment variable configuration
  - Makefile automatic login setup
  - Source profile configuration for assume-role
  - Complete working examples and troubleshooting

- website/blog/2025-10-18-auth-tutorials-geodesic-leapp.md
  Blog post announcing the new auth guides with:
  - Overview of what's new
  - Key benefits of using Atmos Auth
  - Getting started instructions
  - Links to detailed guides

Modified Files:
- website/docs/cli/commands/auth/tutorials/migrating-from-leapp.mdx
  Replaced inline Geodesic integration section with reference to
  the new dedicated guide, keeping Leapp migration guide focused

This reorganization provides better separation of concerns and makes
it easier to maintain and discover each guide independently.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Remove unnecessary sections from blog post

Dropped "Why These Guides Matter" and "What's Next" sections to
keep the blog post more focused and concise.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Changes auto-committed by Conductor

* Rename Geodesic guide to remove redundant suffix

Renamed configuring-geodesic-with-atmos-auth.mdx to
configuring-geodesic.mdx for a cleaner, more concise filename.

Updated all references in:
- migrating-from-leapp.mdx
- blog post
- internal document id

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Clarify authentication flow for Geodesic integration

Added explicit clarification that authentication happens on the host
machine (laptop), not inside the Geodesic container:

- New "How Authentication Works" section explaining the flow
- Expanded workflow with clear host vs container context
- Updated troubleshooting to emphasize host-based re-authentication
- Added keychain integration note explaining limitations in containers
- Clarified that browser-based SSO requires host machine access

This addresses confusion about where atmos auth login runs and when
keychain integration is available.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Update blog post to clarify host-based authentication

Updated Geodesic section in blog post to emphasize:
- Authentication happens on host machine (laptop)
- Authentication occurs before container starts, not inside it
- Keychain integration limitations with containers

This aligns with the detailed clarifications added to the guide itself.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Remove change-oriented language from blog post

Changed "clarifies" to "covers" and "explains" - the blog post
should describe what the guide contains, not frame it as fixing
or clarifying previous documentation since this is net-new content.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Update Geodesic env vars to follow Atmos conventions

Changed Dockerfile variables to use proper Atmos naming:
- DEFAULT_ATMOS_PROVIDER → ATMOS_AUTH_PROVIDER
- DEFAULT_ATMOS_IDENTITY → ATMOS_AUTH_IDENTITY

Also added ATMOS_IDENTITY env var which Atmos actually reads to
determine the default identity (as documented in auth env docs).

The previous naming (DEFAULT_*) didn't follow Atmos conventions and
could be confused with actual Atmos environment variables. The new
names make it clear these are Geodesic-specific build args used to
construct credential paths, while ATMOS_IDENTITY is the actual env
var that Atmos reads.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add blog post introducing atmos auth feature

Created comprehensive announcement post for atmos auth release,
backdated to v1.194.1 release (Oct 13, 2025).

The post covers:
- The authentication problem platform teams face
- Why existing solutions (Leapp, aws-vault, etc.) fall short
- How atmos auth solves these problems
- That it can be used standalone, not just with full Atmos
- Configuration as code approach vs wiki-ops
- Getting started guide and examples

Emphasizes that this solves a problem teams face repeatedly,
inspired by aws-vault and aws2saml, but built natively into
Atmos for better integration and shared configuration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

* Update website/docs/cli/commands/auth/tutorials/configuring-geodesic.mdx

Co-authored-by: Dan Miller <miller0daniel@gmail.com>

* Refactor Leapp migration docs for clarity (#1668)

* Changes auto-committed by Conductor

* Changes auto-committed by Conductor

* Changes auto-committed by Conductor

* Update website/docs/cli/commands/auth/tutorials/configuring-geodesic.mdx

Co-authored-by: Dan Miller <miller0daniel@gmail.com>

---------

Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Dan Miller <miller0daniel@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

stacked Stacked

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant