add: Orka on AWS upgrade guide (DI-623)

[celanthe]

Summary

• Adds upgrading-orka-on-aws.mdx covering the 3.5 to 3.6 upgrade path for AWS customers
• Documents the new Ansible-based ARM node tooling update (replaces AMI replacement approach)
• Covers SSH requirements, node tagging, what's preserved vs. cleared, and post-upgrade steps
• Adds hybrid deployment section (EKS control plane on AWS + Mac nodes on-premises)
• Wires the new page into the Upgrade Guides nav in docs.json

Status

• Hybrid section: Added and pushed. Engineering questions answered by Ivan Spasov via Slack (June 16). See PR comment for full Q&A.
• Deployment model: Waiting on Vandair to confirm whether this doc covers the right deployment model for the support case that opened DI-623, or whether those customers should be pointed to PR add: AWS ARM node tooling upgrade guide for Orka 3.6 (OK-5476) #260 instead.

Test plan

• Preview renders correctly in Mintlify
• Nav link works from Upgrade Guides section
• Vandair confirms deployment model
• Engineering SSH/tag requirements verified (covered by Ivan's Slack confirmation)

Closes DI-623

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
macstadiuminc	🟢 Ready	View Preview	Jun 9, 2026, 5:16 PM

[celanthe]

Hybrid deployment gap (EKS control plane + on-prem Mac nodes)

Flagging a gap before this merges. Zendesk ticket 9626 (via Vandair) describes a customer whose control plane and EKS are on AWS but whose Mac nodes are on-premises -- a hybrid topology this doc doesn't currently cover.

The TODO at the bottom of the file was placeholder for this. Here are the specific questions that need engineering confirmation before this section can be written:

1. Ansible inventory: The current doc describes node discovery via EC2 instance tags. On-prem nodes don't have EC2 tags. How does the Ansible dynamic inventory identify them in a hybrid setup?
2. SSH access path: On-prem Mac nodes need to be reachable over SSH for the Ansible-based upgrade. What's the network path -- does MacStadium's Ansible reach the on-prem nodes directly, or does it go through the EKS control plane?
3. Upgrade process: Is the Ansible-based in-place tooling update the same for on-prem nodes, or does the hybrid case still require a different approach?
4. Upgrade Service: Does the Upgrade Service deploy identically when the control plane is EKS but nodes are on-prem?
5. IAM credential scoping: The credential scoping changes are AWS-specific. Do any equivalent changes apply to the on-prem node side of a hybrid deployment?

Holding this PR as draft until these are confirmed. Tagging for engineering input.

[celanthe]

Engineering questions resolved via Slack (orka-dev thread, June 16).

Ivan Spasov confirmed:

1. Ansible inventory for on-prem nodes: Not related to the AWS flow. On-prem nodes use the on-prem installation flow for both install and upgrade.
2. SSH access path: Same network path used during installation.
3. Upgrade process: On-prem nodes use the on-prem workflow, same as installation.
4. Upgrade Service: Deploys identically regardless of whether nodes are on AWS or on-premises.
5. Credential scoping: Not applicable. Section was already removed from this doc earlier based on Ivan's feedback.

Hybrid section added and em-dash fix pushed. Doc is unblocked on the engineering side. Remaining question is how this PR reconciles with PR #260, which has the fully rewritten self-service content for the same file.