Using an EC2 instance to do development allows numerous scenarios, like doing vanilla Linux/Unix development on a Windows host machine. Wouldn’t it be great to use amazing tools like Visual Studio Code to develop on an EC2 instance too, right from the device at your desk?
Visual Studio Code has a very nice feature to allow this, using the Remote-SSH extension. It can SSH into the EC2 instance, install the Visual Studio Code agent, and give you the shell prompt on the EC2 instance. Further, the development folder on the EC2 instance can be opened in Visual Studio, so that the whole application context appears to be on the EC2 instance.
Let’s set this up.
When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS, including Amazon EC2. You're charged only for the services that you use.
With Amazon EC2, you pay only for the resources you use. If you're a new AWS customer, you can get started with Amazon EC2 for free. For more information, see AWS Free Usage Tier.
If you already have an AWS account, skip to the next task. If you don't have an AWS account, perform the steps in the following procedure to create one.
-
Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.
Note your AWS account ID because you'll need it for the next task.
Services in AWS, such as Amazon EC2, require that you provide credentials when you access them. This is so that the service can determine whether you have permissions to access the resources owned by that service. The console requires your password. You can create access keys for your AWS account to access the AWS CLI or API. However, we don't recommend that you access AWS by using the credentials for your AWS account root user. Instead, we recommend that you:
- Use AWS Identity and Access Management (IAM) to create an IAM user.
- Add the user to an IAM group with administrative permissions.
You can then access AWS by using a special URL and that IAM user's credentials.
If you signed up for AWS, but you haven't created an IAM user for yourself, you can create one by using the IAM console. Follow the procedure to create an IAM user in your account.
- Create an IAM user with administrator permissions in your AWS account. For instructions, see Creating Your First IAM User and Administrators Group in the IAM User Guide.
- As the IAM user, sign in to the AWS Management Console by using a special URL. For more information, see How Users Sign In to Your Account in the IAM User Guide.
For more information about IAM, see the following:
Before you can launch and connect to an Amazon EC2 instance, you need to create a key pair, unless you already have one. You can create a key pair using the Amazon EC2 console, and then you can launch your EC2 instance.
Follow the steps in Setting up with Amazon EC2 in the Amazon EC2 User Guide for Linux Instances to create a key pair. If you already have a key pair, you don't need to create a new one. You can use your existing key pair for this exercise.
You will download the .pem keypair file to the local machine, and save it somewhere that you will be able to locate it.
-
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
-
In the top right of the console, we will select a region. I used us-west-2. Adjust accordingly.
-
Choose Launch Instance.
-
In Step 1: Choose an Amazon Machine Image (AMI), find an Amazon Linux 2 AMI at the top of the list and choose Select.
-
In Step 2: Choose an Instance Type, choose Next: Configure Instance Details.
-
In Step 3: Configure Instance Details, provide the following information:
- Leave Number of instances at one.
- Leave Purchasing option at the default setting.
- For Subnet, choose a default subnet in any Availability Zone.
-
Choose Next: Add Storage.
-
Choose Next: Add Tags.
-
Name your instance and choose Next: Configure Security Group.
-
In Step 6: Configure Security Group, set Assign a security group to ‘Create a new security group’. By default, there is an SSH Rule included as a part of the security group, with the following properties.
- Type: SSH
- Protocol: TCP
- Port Range: 22
- Source: Anywhere 0.0.0.0/0
-
Choose Review and Launch.
-
Choose Launch.
-
Select the check box for the key pair that you created, and then choose Launch Instances.
-
View your instance and make a note of the Public IPv4 DNS for later. It should look something like this:
Visual Studio Code must be installed on the local device. Download and install the application.
Start the application.
The extension to Visual Studio Code for Remote – SSH must be installed.
Select the extensions browser from the icons on the left. It is the bottom icon in the figure below.
Type remote into the search box and it will appear in the results.
Click install. The extension installs itself in a second or two.
Next, we will provide information on how we want Visual Studio Code to connect to our EC2 instance.
Click on the green remote icon in the bottom left corner of the application.
Pick Remote-SSH: Open Configuration File…
Pick the one under the home directory (user folder in Windows) for user setup or the one in /etc/ssh (C:\ProgramData\ssh in Windows) for all users.
This file will be created and opened in the editor for you.
Edit it as follows:
- Set the alias to whatever friendly name you like, e.g.
player-auth(only because that's the project I am using my EC2 instance for) - Set the hostname to the Public IPv4 DNS name we were given for our EC2 instance, visible in the list of running instances in the AWS console.
- Set the user to
ec2-userfor Amazon Linux 2 (other OS may need a different user) - Add an indented line 5, with the label IdentityFile and the location of the keypair file. Especially if there are spaces in a Windows path, the filepath will need to be delimited in quotes.
Don’t forget to save the file when you have finished editing.
This will then enable Remote-SSH to find the credentials for your EC2 instance.
Next, we will connect to our EC2 instance.
Click on the green remote icon in the bottom left corner of the application.
Pick Remote-SSH: Connect Current Window to Host…
Select the friendly host name for the EC2 instance.
And pick the operating system on the EC2 instance.
You will be prompted to accept the fingerprint of the server, pick Continue.
The connection will be completed, as shown in the green corner icon.
If you get an error about an invalid pipeline, then the connection failed and you should check the SSH config file.
If you are connected, you will be able to open the bash terminal with the shortcut CTRL+`
At this point I like to create a dev directory, by issuing the command
Open the sidebar by clicking on the folder tool or with the shortcut CTRL+B and click on Open Folder.
(Alternatively use the shortcut CTRL+K, CTRL+O get there directly).
Choose the folder on the EC2 instance to open. I will click on dev and open that one.
There are no files there, so create a new test file. Click on the new file icon.
Give it a name.
Put in something interesting, and save the file.
Run the file. The chmod +x command makes the script file executable. ./test.sh runs the script.
And the script outputs the EC2 instance ID, i-069663daf9a647373. Perfect.
To allow the SSH user the ability to run AWS CLI commands over Remote-SSH, we should give the EC2 instance the ability to use a service role. In our case, since we are going to be developing an application that uses the EC2 service role to deploy a CloudFormation template, all the activities in the deployment and operation must be permitted. However, this shouldn't be an administrator role, because then the EC2 instance could access things like billing and such in the AWS account, so we will restrict the actions using the principle of least privilege.
We will create a permissions policy, apply it to a service role, then apply the service role to the EC2 instance, and finally test the role works as expected.
An example EC2 permissions policy file shows what you might need.
The exact permissions depend on what you want your EC2 instance be able to do. Typically, avoid giving your EC2 instance administrator rights in the permissions policy. That would mean an attacker that took control of your EC2 instance would be able to to do anything in your AWS account, including viewing billing details and creating users with administrative roles, and creating new infrastructure. Use the principle of least privilege.
Sometimes you will receive a policy from elsewhere. In that case, to use the policy, you may have to customize it, by replacing another account ID in the policy with your own. You will also need your 12-digit AWS account ID for this, which you can find using these instructions.
Using the editor, replace all occurrences of the text “YOUR_12_DIGIT_ACCOUNT_ID” with your 12-digit AWS account ID. That will personalize the policy to your account.
Review the functionality of the policy and ensure it is functionally correct and suited to your application. This policy was developed for the player authentication sample, and is tailored to that.
In your AWS console (https://console.aws.amazon.com/iam/home?#/policies$new), pick the JSON tab, and paste the modified policy into the text box, replacing the text already in there. Skip through the tags screen in step 2 and on step 3 (review policy), name the policy “ec2devpolicy”.
In the AWS console (https://console.aws.amazon.com/iam/home?#/roles$new?step=type), create the role. Make sure AWS service is the trusted entity and select EC2. Click Next.
Click Next to go to the next screen. Find the permissions policy by typing part of its name in the search box, and check the permissions policy to apply it.
Skip adding tags and continue to the review screen. On the review screen, name the new EC2 service role ec2dev. Verify that the policy set and click on the create role button.
In the AWS Console (https://console.aws.amazon.com/ec2/v2/home?#Instances:instanceState=running), find the the EC2 instance you created earlier, and check its box.
Select the Actions > Security > Modify IAM role menu item. Choose the ec2dev role that you just created, and Save.
Then check that the attachment was successful.
Do a quick test to make sure that the policy has taken effect. Run aws sts get-caller-identity at the command line:
This shows us distinctly using the ec2dev service linked role. If you do not have valid credentials, you will see this instead.
To check permissions for a particular operation, without executing the operation itself, the AWS CLI supports the --auth-dry-run switch. This shows whether the operation is permitted with the current credentials. Use this if you experience difficulty executing a command.
Visual Studio Code may issue a message, “Unable to watch for file changes in this large workspace folder”. This is because we added a lot of files to the EC2 host.
We can tell it that we don’t need it to watch for changes in all these files. The instructions are accessible from the box. On the local machine, go to settings and type in watcher, to find the setting "files.watcherExclude". Add the following paths:
**/.local/**
**/.npm/**
**/.nvm/**
**/aws-sam-cli-src/**
This reduces the burden on the file watcher again. The message can be dismissed.
When an Amazon Linux 2 AMI is started, it may be on an old version of the AWS CLI and Python, such as the following.
aws-cli/1.18.147 Python/2.7.18 Linux/4.14.225-169.362.amzn2.x86_64 botocore/1.18.6Upgrade by pasting the following command block at the EC2 command prompt.
aws --version
sudo rm -rf /usr/lib/python2.7/site-packages/awscli/
sudo rm -rf /usr/lib/python2.7/site-packages/botocore/
sudo rm /usr/bin/aws
sudo rm /usr/bin/aws_completer
sudo rm /usr/share/zsh/site-functions/aws_zsh_completer.sh
sudo rm /etc/bash_completion.d/aws_bash_completer
sudo yum update -y
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip -q -o awscliv2.zip
sudo ./aws/install --update
bash
aws --versionYou should expect to see the output look a bit like this, with the last line of the output showing updated versions:
aws-cli/2.1.38 Python/3.8.8 Linux/4.14.225-169.362.amzn2.x86_64 exe/x86_64.amzn.2 prompt/offI have experienced a condition where Visual Studio Code 1.55.2 updated Remote-SSH to 0.65.3, and then I was able to connect to the terminal on a remote instance, but opening a folder would not work. After trying to connect for a minute or so, the attempt would be abandoned with a message box. The Remote-SSH output in the Terminal Output window (use the dropdown in the Output window to pick Remote-SSH) reported wget: unrecognized option '--no-hsts'.
To fix, I reinstalled an older version of the Remote-SSH plugin (0.65.1), reloaded VSCode and then opened the folder again. [Look in the extension settings menu for 'Install another version'.] Once it worked, I was able to install the later (0.65.3) version again, and it would work just fine. My theory is the VSCode server on the remote got out of sync with the local, but I didn't diagnose further as I was unable to repro the issue again.