Remote Access Documentation

View the Live Documentation

The Challenge

Remote Access was the #1 requested feature from SageMaker customers at the time of launch. Data scientists wanted to use their familiar local VS Code environment while leveraging the compute power and managed infrastructure of SageMaker Studio spaces.

This was an incredibly complex feature to document because it involved:

• Multiple connection methods: Deep links from the SageMaker UI, AWS Toolkit for VS Code integration, and direct SSH terminal connections
• Complex security architecture: IAM permissions, session management, least privilege principles, and cross-service authorization
• Multiple audiences: End-users (data scientists) needed simple setup guides, while administrators needed detailed security configuration documentation
• Advanced scenarios: Private subnet configurations with no internet access, auto space filtering, and network-based constraints

My Approach

• Audience-driven structure: Separated administrator setup (IAM, security) from end-user setup (VS Code configuration) to serve each audience's needs without overwhelming them with irrelevant information.
• Security-first documentation: Emphasized least privilege principles throughout, with clear warnings about wildcard permissions and guidance on scoping permissions to specific space ARNs.
• Progressive disclosure: Started with the simplest connection method (deep links) and progressively introduced more complex options (AWS Toolkit, SSH terminal) for users who needed them.
• Hands-on validation: Tested all three connection methods myself, identifying edge cases and prerequisites that weren't obvious from engineering specs.
• Cross-platform considerations: Documented prerequisites for different operating systems and shell environments (bash, PowerShell, cmd.exe).

Documentation Structure

I designed an information architecture that separates concerns while maintaining clear navigation:

• Remote access — Overview and feature introduction
  • Set up remote access — Administrator guide
    • Advanced access control — Resource ARNs, tags, network constraints
    • Set up private subnet with no internet access
    • Set up auto space filtering
  • Set up local Visual Studio Code — End-user guide
    • Connect to private subnet with no internet access
    • Filter your Studio spaces

Technical Depth

The documentation required deep understanding of several AWS services and security concepts:

• IAM policy structure: Documented three distinct permission methods (deep link, AWS Toolkit, SSH terminal), each with different IAM requirements
• Session Manager integration: Explained how the StartSession API enables secure connections without exposing SSH ports
• SSH ProxyCommand configuration: Provided shell-specific examples for routing SSH connections through AWS Session Manager
• Resource-based access control: Showed how to scope permissions using space ARNs, user profile tags, and network-based conditions

Security Documentation

A critical aspect of this documentation was helping administrators understand and implement proper security controls:

Impact

Being trusted with the documentation for the #1 requested feature was a significant responsibility. The documentation was part of the major 2025 AWS Summit New York launch, and needed to:

• Enable successful adoption of a highly anticipated feature
• Reduce support burden by addressing common setup issues proactively
• Maintain AWS's security standards while making the feature accessible
• Serve both technical and less technical audiences effectively