cloudx-proxy 0.3.3__tar.gz → 0.3.5__tar.gz

{cloudx_proxy-0.3.3 → cloudx_proxy-0.3.5}/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.3.5](https://github.com/easytocloud/cloudX-proxy/compare/v0.3.4...v0.3.5) (2025-02-11)
+
+
+### Bug Fixes
+
+* repaired 1Password integration and ssh perms ([69f6a24](https://github.com/easytocloud/cloudX-proxy/commit/69f6a249c941044c4dc689c787c12c1a0d0e093a))
+
+## [0.3.4](https://github.com/easytocloud/cloudX-proxy/compare/v0.3.3...v0.3.4) (2025-02-09)
+
 ## [0.3.3](https://github.com/easytocloud/cloudX-proxy/compare/v0.3.2...v0.3.3) (2025-02-09)
 
 ## [0.3.2](https://github.com/easytocloud/cloudX-proxy/compare/v0.3.1...v0.3.2) (2025-02-09)

{cloudx_proxy-0.3.3 → cloudx_proxy-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cloudx-proxy
-Version: 0.3.3
+Version: 0.3.5
 Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
 Author-email: easytocloud <info@easytocloud.com>
 License: MIT License
@@ -95,14 +95,9 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
    - Uses the SSH configuration to connect to instances
    - Handles file synchronization and terminal sessions
 
-## AWS Credentials Setup
+## Installation
 
-The proxy expects to find AWS credentials in a profile named 'vscode' by default. These credentials should be the Access Key and Secret Key that were created by deploying the cloudX-user stack in your AWS account. The cloudX-user stack creates an IAM user with the minimal permissions required for:
-- Starting/stopping EC2 instances
-- Establishing SSM sessions
-- Pushing SSH keys via EC2 Instance Connect
-
-The proxy supports easytocloud's AWS profile organizer for managing multiple AWS environments. You can store your AWS configuration and credentials in `~/.aws/aws-envs/<environment>` directories and use the `--aws-env` option to specify which environment to use.
+The cloudX-proxy package is available on PyPI and can run using uvx without explicit installation.
 
 ## Setup
 
@@ -122,7 +117,7 @@ uvx cloudx-proxy setup --aws-env prod
 The setup command will:
 
 1. Configure AWS Profile:
-   - Creates/validates AWS profile with cloudX-{env}-{user} format
+   - Creates/validates AWS profile for IAM user in cloudX-{env}-{user} format
    - Supports AWS environment directories via --aws-env
    - Uses aws configure for credential input
 
@@ -145,7 +140,40 @@ The setup command will:
 
 ### SSH Configuration
 
-The setup command configures SSH to use cloudX-proxy as a ProxyCommand, enabling seamless connections through AWS Systems Manager. It creates:
+The setup command configures SSH to use cloudX-proxy as a ProxyCommand, enabling seamless connections through AWS Systems Manager. For example, running:
+
+```bash
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
+```
+
+Will create a configuration like this:
+
+```
+# Base environment config (created once per environment)
+Host cloudx-dev-*
+    User ec2-user
+    IdentityFile ~/.ssh/vscode/mykey
+    ProxyCommand uvx cloudx-proxy connect %h %p --profile myprofile --ssh-key mykey
+
+# Host entry (added for specific instance)
+Host cloudx-dev-myserver
+    HostName i-0123456789abcdef0
+```
+
+Allowing the user to:
+
+```bash
+ssh cloudx-dev-myserver
+scp cloudx-dev-myserver:/path/to/file /local/path/to/file
+```
+without the need to provide any further credentials.
+
+In these examples, ssh will use cloudx-proxy to connect to AWS with the `myprofile` credentials, allowing it to check the instance state and start the instance if it's stopped. Next cloudx-proxy will use `myprofile` to push the public part of the key `mykey` to the instance using SSM. Finally a tunnel is created between the local machine and the instance, using the SSM plugin, allowing SSH to connect to the instance using the private part of the `mykey` key. 
+
+VSCode will be able to connect to the instance using the same SSH configuration.
+
+### SSH Configuration Details
+The setup command creates:
 
 1. A base configuration for each environment (cloudx-{env}-*) with:
    - User and key settings
@@ -171,7 +199,7 @@ When adding new instances to an existing environment, you can choose to:
        "remote.SSH.connectTimeout": 90
    }
    ```
-
+This extra long timeout is necessary to account for the time it takes to start the instance and establish the connection.
 ## Usage
 
 ### Command Line Options
@@ -239,28 +267,28 @@ Note: The connect command is typically used through the SSH ProxyCommand configu
 5. VSCode will handle the rest, using cloudX-proxy to establish the connection
 
 ## AWS Permissions
+### IAM User Permissions
 
-The AWS user needs these permissions:
-
-```json
-{
-    "Version": "2012-10-17",
-    "Statement": [
-        {
-            "Effect": "Allow",
-            "Action": [
-                "ec2:StartInstances",
-                "ec2:DescribeInstances",
-                "ssm:StartSession",
-                "ssm:DescribeInstanceInformation",
-                "ec2-instance-connect:SendSSHPublicKey"
-            ],
-            "Resource": "*"
-        }
-    ]
-}
-```
-Note: This user should be created using the cloudX-user product from Service Catalog in the AWS Console. This assures proper permissions and naming conventions.
+The AWS IAM user has to be member of the AWS IAM Group that is created as part of the cloudX environment.
+The group uses ABAC (Attribute Based Access Control) to allow access to the instances based on the tags.
+The ABAC tag defaults to `cloudxuser` and should have the value of the username of the user that owns the instance.
+
+Example:
+- AWS IAM User `cloudx-dev-user1` is connecting to an instance with the tag `cloudxuser=cloudx-dev-user1`
+
+Note: This user should be created using the cloudX-user product from Service Catalog in the AWS Console. This assures proper permissions and naming conventions. The user in the example is member of the `dev` group, part as part of the `cloudx-dev` environment.
+
+The EC2 instance should have the tag `cloudxuser` with the value of the username of the user that is connecting to the instance. This is automatically set when the instance is created using the cloudX-instance product from Service Catalog in the AWS Console.
+
+### EC2 Instance Permissions
+
+The EC2 instance has a profile/role that provides enough permissions to allow the AWS SSM agent to connect to the instance, as well as
+- CodeArtifact read only access, to use as a source for pip
+- CodeCommit read only access, to pull code from the repository for installation
+- Organizations read only access, to create aws sso configuration
+- EC2 basic access, to allow the instance to introspect for tags and other metadata
+
+These permissions are required to bootstrap the instance, so that after creation the instance can perform software installation and configuration without a user being present.
 
 ## Troubleshooting
 

{cloudx_proxy-0.3.3 → cloudx_proxy-0.3.5}/README.md

@@ -45,14 +45,9 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
    - Uses the SSH configuration to connect to instances
    - Handles file synchronization and terminal sessions
 
-## AWS Credentials Setup
+## Installation
 
-The proxy expects to find AWS credentials in a profile named 'vscode' by default. These credentials should be the Access Key and Secret Key that were created by deploying the cloudX-user stack in your AWS account. The cloudX-user stack creates an IAM user with the minimal permissions required for:
-- Starting/stopping EC2 instances
-- Establishing SSM sessions
-- Pushing SSH keys via EC2 Instance Connect
-
-The proxy supports easytocloud's AWS profile organizer for managing multiple AWS environments. You can store your AWS configuration and credentials in `~/.aws/aws-envs/<environment>` directories and use the `--aws-env` option to specify which environment to use.
+The cloudX-proxy package is available on PyPI and can run using uvx without explicit installation.
 
 ## Setup
 
@@ -72,7 +67,7 @@ uvx cloudx-proxy setup --aws-env prod
 The setup command will:
 
 1. Configure AWS Profile:
-   - Creates/validates AWS profile with cloudX-{env}-{user} format
+   - Creates/validates AWS profile for IAM user in cloudX-{env}-{user} format
    - Supports AWS environment directories via --aws-env
    - Uses aws configure for credential input
 
@@ -95,7 +90,40 @@ The setup command will:
 
 ### SSH Configuration
 
-The setup command configures SSH to use cloudX-proxy as a ProxyCommand, enabling seamless connections through AWS Systems Manager. It creates:
+The setup command configures SSH to use cloudX-proxy as a ProxyCommand, enabling seamless connections through AWS Systems Manager. For example, running:
+
+```bash
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
+```
+
+Will create a configuration like this:
+
+```
+# Base environment config (created once per environment)
+Host cloudx-dev-*
+    User ec2-user
+    IdentityFile ~/.ssh/vscode/mykey
+    ProxyCommand uvx cloudx-proxy connect %h %p --profile myprofile --ssh-key mykey
+
+# Host entry (added for specific instance)
+Host cloudx-dev-myserver
+    HostName i-0123456789abcdef0
+```
+
+Allowing the user to:
+
+```bash
+ssh cloudx-dev-myserver
+scp cloudx-dev-myserver:/path/to/file /local/path/to/file
+```
+without the need to provide any further credentials.
+
+In these examples, ssh will use cloudx-proxy to connect to AWS with the `myprofile` credentials, allowing it to check the instance state and start the instance if it's stopped. Next cloudx-proxy will use `myprofile` to push the public part of the key `mykey` to the instance using SSM. Finally a tunnel is created between the local machine and the instance, using the SSM plugin, allowing SSH to connect to the instance using the private part of the `mykey` key. 
+
+VSCode will be able to connect to the instance using the same SSH configuration.
+
+### SSH Configuration Details
+The setup command creates:
 
 1. A base configuration for each environment (cloudx-{env}-*) with:
    - User and key settings
@@ -121,7 +149,7 @@ When adding new instances to an existing environment, you can choose to:
        "remote.SSH.connectTimeout": 90
    }
    ```
-
+This extra long timeout is necessary to account for the time it takes to start the instance and establish the connection.
 ## Usage
 
 ### Command Line Options
@@ -189,28 +217,28 @@ Note: The connect command is typically used through the SSH ProxyCommand configu
 5. VSCode will handle the rest, using cloudX-proxy to establish the connection
 
 ## AWS Permissions
+### IAM User Permissions
 
-The AWS user needs these permissions:
-
-```json
-{
-    "Version": "2012-10-17",
-    "Statement": [
-        {
-            "Effect": "Allow",
-            "Action": [
-                "ec2:StartInstances",
-                "ec2:DescribeInstances",
-                "ssm:StartSession",
-                "ssm:DescribeInstanceInformation",
-                "ec2-instance-connect:SendSSHPublicKey"
-            ],
-            "Resource": "*"
-        }
-    ]
-}
-```
-Note: This user should be created using the cloudX-user product from Service Catalog in the AWS Console. This assures proper permissions and naming conventions.
+The AWS IAM user has to be member of the AWS IAM Group that is created as part of the cloudX environment.
+The group uses ABAC (Attribute Based Access Control) to allow access to the instances based on the tags.
+The ABAC tag defaults to `cloudxuser` and should have the value of the username of the user that owns the instance.
+
+Example:
+- AWS IAM User `cloudx-dev-user1` is connecting to an instance with the tag `cloudxuser=cloudx-dev-user1`
+
+Note: This user should be created using the cloudX-user product from Service Catalog in the AWS Console. This assures proper permissions and naming conventions. The user in the example is member of the `dev` group, part as part of the `cloudx-dev` environment.
+
+The EC2 instance should have the tag `cloudxuser` with the value of the username of the user that is connecting to the instance. This is automatically set when the instance is created using the cloudX-instance product from Service Catalog in the AWS Console.
+
+### EC2 Instance Permissions
+
+The EC2 instance has a profile/role that provides enough permissions to allow the AWS SSM agent to connect to the instance, as well as
+- CodeArtifact read only access, to use as a source for pip
+- CodeCommit read only access, to pull code from the repository for installation
+- Organizations read only access, to create aws sso configuration
+- EC2 basic access, to allow the instance to introspect for tags and other metadata
+
+These permissions are required to bootstrap the instance, so that after creation the instance can perform software installation and configuration without a user being present.
 
 ## Troubleshooting
 

{cloudx_proxy-0.3.3 → cloudx_proxy-0.3.5}/cloudx_proxy/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.3.3'
-__version_tuple__ = version_tuple = (0, 3, 3)
+__version__ = version = '0.3.5'
+__version_tuple__ = version_tuple = (0, 3, 5)

{cloudx_proxy-0.3.3 → cloudx_proxy-0.3.5}/cloudx_proxy/setup.py

@@ -2,6 +2,7 @@ import os
 import time
 import json
 import subprocess
+import platform
 from pathlib import Path
 from typing import Optional, Tuple
 import boto3
@@ -142,16 +143,17 @@ class CloudXSetup:
             
             if key_exists:
                 self.print_status(f"SSH key '{self.ssh_key}' exists", True, 2)
-                self.using_1password = self.prompt("Would you like to use 1Password SSH agent?", "N").lower() == 'y'
-                if self.using_1password:
-                    self.print_status("Using 1Password SSH agent", True, 2)
-                else:
-                    store_in_1password = self.prompt("Would you like to store the private key in 1Password?", "N").lower() == 'y'
-                    if store_in_1password:
-                        if self._store_key_in_1password():
-                            self.print_status("Private key stored in 1Password", True, 2)
-                        else:
-                            self.print_status("Failed to store private key in 1Password", False, 2)
+                if platform.system() != 'Windows':
+                    self.using_1password = self.prompt("Would you like to use 1Password SSH agent?", "N").lower() == 'y'
+                    if self.using_1password:
+                        self.print_status("Using 1Password SSH agent", True, 2)
+                    else:
+                        store_in_1password = self.prompt("Would you like to store the private key in 1Password?", "N").lower() == 'y'
+                        if store_in_1password:
+                            if self._store_key_in_1password():
+                                self.print_status("Private key stored in 1Password", True, 2)
+                            else:
+                                self.print_status("Failed to store private key in 1Password", False, 2)
             else:
                 self.print_status(f"Generating new SSH key '{self.ssh_key}'...", None, 2)
                 subprocess.run([
@@ -162,16 +164,17 @@ class CloudXSetup:
                 ], check=True)
                 self.print_status("SSH key generated", True, 2)
                 
-                self.using_1password = self.prompt("Would you like to use 1Password SSH agent?", "N").lower() == 'y'
-                if self.using_1password:
-                    self.print_status("Using 1Password SSH agent", True, 2)
-                else:
-                    store_in_1password = self.prompt("Would you like to store the private key in 1Password?", "N").lower() == 'y'
-                    if store_in_1password:
-                        if self._store_key_in_1password():
-                            self.print_status("Private key stored in 1Password", True, 2)
-                        else:
-                            self.print_status("Failed to store private key in 1Password", False, 2)
+                if platform.system() != 'Windows':
+                    self.using_1password = self.prompt("Would you like to use 1Password SSH agent?", "N").lower() == 'y'
+                    if self.using_1password:
+                        self.print_status("Using 1Password SSH agent", True, 2)
+                    else:
+                        store_in_1password = self.prompt("Would you like to store the private key in 1Password?", "N").lower() == 'y'
+                        if store_in_1password:
+                            if self._store_key_in_1password():
+                                self.print_status("Private key stored in 1Password", True, 2)
+                            else:
+                                self.print_status("Failed to store private key in 1Password", False, 2)
             
             return True
 
@@ -184,20 +187,51 @@ class CloudXSetup:
             return False
 
     def _store_key_in_1password(self) -> bool:
-        """Store SSH private key in 1Password.
+        """Store SSH private key in 1Password and configure SSH agent.
         
         Returns:
             bool: True if key was stored successfully
         """
         try:
+            # Check if 1Password CLI is available
             subprocess.run(['op', '--version'], check=True, capture_output=True)
-            print("Storing private key in 1Password...")
-            subprocess.run([
-                'op', 'document', 'create',
-                str(self.ssh_key_file),
-                '--title', f'cloudx-proxy SSH Key - {self.ssh_key}'
-            ], check=True)
-            return True
+            
+            # Check if 1Password SSH agent is running
+            agent_sock = Path.home() / ".1password" / "agent.sock"
+            if platform.system() == 'Darwin':
+                agent_sock = Path.home() / "Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
+            
+            if not agent_sock.exists():
+                self.print_status("1Password SSH agent not running. Please enable it in 1Password settings.", False, 2)
+                return False
+            
+            print("Adding SSH key to 1Password SSH agent...")
+            try:
+                # First try to add to SSH agent
+                subprocess.run([
+                    'op', 'ssh-add',
+                    '--name', f'cloudx-proxy-{self.ssh_key}',
+                    str(self.ssh_key_file)
+                ], check=True)
+                
+                # Read private key content before removing
+                with open(self.ssh_key_file, 'r') as f:
+                    private_key = f.read()
+                
+                # Store private key in 1Password as document for backup
+                subprocess.run([
+                    'op', 'document', 'create',
+                    '--title', f'cloudx-proxy SSH Key - {self.ssh_key}',
+                ], input=private_key.encode(), check=True)
+                
+                # Remove private key file but keep public key
+                os.remove(self.ssh_key_file)
+                self.print_status("Private key added to 1Password SSH agent and removed from disk", True, 2)
+                self.print_status("Backup copy stored in 1Password documents", True, 2)
+                return True
+            except subprocess.CalledProcessError as e:
+                self.print_status(f"Failed to add key to SSH agent: {e}", False, 2)
+                return False
         except subprocess.CalledProcessError:
             print("Error: 1Password CLI not installed or not signed in.")
             return False
@@ -229,13 +263,19 @@ Host cloudx-{cloudx_env}-{hostname}
     HostName {instance_id}
     User ec2-user
 """
-            if self.using_1password:
-                host_entry += f"""    IdentityAgent ~/.1password/agent.sock
+            if self.using_1password and platform.system() != 'Windows':
+                # Use platform-specific agent socket path
+                if platform.system() == 'Darwin':  # macOS
+                    agent_sock = "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
+                else:  # Linux
+                    agent_sock = "~/.1password/agent.sock"
+                host_entry += f"""    IdentityAgent {agent_sock}
     IdentityFile {self.ssh_key_file}.pub
     IdentitiesOnly yes
 """
             else:
                 host_entry += f"""    IdentityFile {self.ssh_key_file}
+    IdentitiesOnly yes
 """
             host_entry += f"""    ProxyCommand {proxy_command}
 """
@@ -343,14 +383,22 @@ Host cloudx-{cloudx_env}-{hostname}
 Host cloudx-{cloudx_env}-*
     User ec2-user
 """
-            # Add 1Password or standard key configuration
-            if self.using_1password:
-                base_config += f"""    IdentityAgent ~/.1password/agent.sock
+            # Add key configuration
+            if self.using_1password and platform.system() != 'Windows':
+                # Use platform-specific agent socket path
+                if platform.system() == 'Darwin':  # macOS
+                    agent_sock = "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
+                else:  # Linux
+                    agent_sock = "~/.1password/agent.sock"
+                base_config += f"""    IdentityAgent {agent_sock}
     IdentityFile {self.ssh_key_file}.pub
     IdentitiesOnly yes
+
 """
             else:
                 base_config += f"""    IdentityFile {self.ssh_key_file}
+    IdentitiesOnly yes
+
 """
             # Add ProxyCommand
             base_config += f"""    ProxyCommand {proxy_command}

{cloudx_proxy-0.3.3 → cloudx_proxy-0.3.5}/cloudx_proxy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cloudx-proxy
-Version: 0.3.3
+Version: 0.3.5
 Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
 Author-email: easytocloud <info@easytocloud.com>
 License: MIT License
@@ -95,14 +95,9 @@ cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using
    - Uses the SSH configuration to connect to instances
    - Handles file synchronization and terminal sessions
 
-## AWS Credentials Setup
+## Installation
 
-The proxy expects to find AWS credentials in a profile named 'vscode' by default. These credentials should be the Access Key and Secret Key that were created by deploying the cloudX-user stack in your AWS account. The cloudX-user stack creates an IAM user with the minimal permissions required for:
-- Starting/stopping EC2 instances
-- Establishing SSM sessions
-- Pushing SSH keys via EC2 Instance Connect
-
-The proxy supports easytocloud's AWS profile organizer for managing multiple AWS environments. You can store your AWS configuration and credentials in `~/.aws/aws-envs/<environment>` directories and use the `--aws-env` option to specify which environment to use.
+The cloudX-proxy package is available on PyPI and can run using uvx without explicit installation.
 
 ## Setup
 
@@ -122,7 +117,7 @@ uvx cloudx-proxy setup --aws-env prod
 The setup command will:
 
 1. Configure AWS Profile:
-   - Creates/validates AWS profile with cloudX-{env}-{user} format
+   - Creates/validates AWS profile for IAM user in cloudX-{env}-{user} format
    - Supports AWS environment directories via --aws-env
    - Uses aws configure for credential input
 
@@ -145,7 +140,40 @@ The setup command will:
 
 ### SSH Configuration
 
-The setup command configures SSH to use cloudX-proxy as a ProxyCommand, enabling seamless connections through AWS Systems Manager. It creates:
+The setup command configures SSH to use cloudX-proxy as a ProxyCommand, enabling seamless connections through AWS Systems Manager. For example, running:
+
+```bash
+uvx cloudx-proxy setup --profile myprofile --ssh-key mykey
+```
+
+Will create a configuration like this:
+
+```
+# Base environment config (created once per environment)
+Host cloudx-dev-*
+    User ec2-user
+    IdentityFile ~/.ssh/vscode/mykey
+    ProxyCommand uvx cloudx-proxy connect %h %p --profile myprofile --ssh-key mykey
+
+# Host entry (added for specific instance)
+Host cloudx-dev-myserver
+    HostName i-0123456789abcdef0
+```
+
+Allowing the user to:
+
+```bash
+ssh cloudx-dev-myserver
+scp cloudx-dev-myserver:/path/to/file /local/path/to/file
+```
+without the need to provide any further credentials.
+
+In these examples, ssh will use cloudx-proxy to connect to AWS with the `myprofile` credentials, allowing it to check the instance state and start the instance if it's stopped. Next cloudx-proxy will use `myprofile` to push the public part of the key `mykey` to the instance using SSM. Finally a tunnel is created between the local machine and the instance, using the SSM plugin, allowing SSH to connect to the instance using the private part of the `mykey` key. 
+
+VSCode will be able to connect to the instance using the same SSH configuration.
+
+### SSH Configuration Details
+The setup command creates:
 
 1. A base configuration for each environment (cloudx-{env}-*) with:
    - User and key settings
@@ -171,7 +199,7 @@ When adding new instances to an existing environment, you can choose to:
        "remote.SSH.connectTimeout": 90
    }
    ```
-
+This extra long timeout is necessary to account for the time it takes to start the instance and establish the connection.
 ## Usage
 
 ### Command Line Options
@@ -239,28 +267,28 @@ Note: The connect command is typically used through the SSH ProxyCommand configu
 5. VSCode will handle the rest, using cloudX-proxy to establish the connection
 
 ## AWS Permissions
+### IAM User Permissions
 
-The AWS user needs these permissions:
-
-```json
-{
-    "Version": "2012-10-17",
-    "Statement": [
-        {
-            "Effect": "Allow",
-            "Action": [
-                "ec2:StartInstances",
-                "ec2:DescribeInstances",
-                "ssm:StartSession",
-                "ssm:DescribeInstanceInformation",
-                "ec2-instance-connect:SendSSHPublicKey"
-            ],
-            "Resource": "*"
-        }
-    ]
-}
-```
-Note: This user should be created using the cloudX-user product from Service Catalog in the AWS Console. This assures proper permissions and naming conventions.
+The AWS IAM user has to be member of the AWS IAM Group that is created as part of the cloudX environment.
+The group uses ABAC (Attribute Based Access Control) to allow access to the instances based on the tags.
+The ABAC tag defaults to `cloudxuser` and should have the value of the username of the user that owns the instance.
+
+Example:
+- AWS IAM User `cloudx-dev-user1` is connecting to an instance with the tag `cloudxuser=cloudx-dev-user1`
+
+Note: This user should be created using the cloudX-user product from Service Catalog in the AWS Console. This assures proper permissions and naming conventions. The user in the example is member of the `dev` group, part as part of the `cloudx-dev` environment.
+
+The EC2 instance should have the tag `cloudxuser` with the value of the username of the user that is connecting to the instance. This is automatically set when the instance is created using the cloudX-instance product from Service Catalog in the AWS Console.
+
+### EC2 Instance Permissions
+
+The EC2 instance has a profile/role that provides enough permissions to allow the AWS SSM agent to connect to the instance, as well as
+- CodeArtifact read only access, to use as a source for pip
+- CodeCommit read only access, to pull code from the repository for installation
+- Organizations read only access, to create aws sso configuration
+- EC2 basic access, to allow the instance to introspect for tags and other metadata
+
+These permissions are required to bootstrap the instance, so that after creation the instance can perform software installation and configuration without a user being present.
 
 ## Troubleshooting