SHIFT-WIKI

--- Sjoerd Hooft's InFormation Technology ---

User Tools

Site Tools


awstoolkitforvsc

AWS Toolkit for VS Code

Goal: Start working with AWS Toolkit for VS Code

  • to use with Lambda and Step Functions
  • Reason: Keep everything in source control
  • Target: Create, Update and Deploy Lambda functions and step functions from VS Code
    • Data must be in a Azure DevOps project
    • View Cloudwatch logs
  • How: Use the 10 minute tutorial for Step Functions
  • Note that this page gets continued in SAM - Combining Lambda and Step Functions in AWS Toolkit for VS Code in which we also deploy the step function from the SAM.

Requirements

I will be using Lambda functions in both PowerShell (.NET) and Node.js so I'll be needing both the SDK's:

As I'll be also creating Serverless Applications (as that's the way to deploy Lambda Functions) I'm also installing the AWS SAM CLI and as I don't plan on testing the applications locally I won't need Docker:

Install the AWS Toolkit

Inside VS Code, go to extensions and search for the AWS Toolkit, and click install. Once the install is done restart VS Code.

Configure Profiles

To connect to AWS you need to have a profile with AWS access keys. In my case I have multiple accounts, so I need multiple profiles.

Test Account

First we'll create AWS Access keys and a profile for my test account:

  • Log into the AWS console of the specific account and go to IAM
  • Go to Users → Add user
    • User name: VSCodeTestUser
    • Access type: Programmatic Access
    • Permissions:
      • Attach existing policies directly:
        • AWSLambdaFullAccess
        • AWSStepFunctionsFullAccess
        • AWSCloudFormationFullAccess
        • IAMFullAccess –> not needed for just lambda?
        • AmazonAPIGatewayAdministrator –> not needed for just lambda?
Note that these permissions are a bit extensive, for production you should tailor the permissions to what really is required.

This provides a Access key ID and Secret access key that you should store securely.

Now go back to VS Code to add the keys to a profile:

  • Open the command palette and search for AWS
  • Choose AWS: Create Credentials Profile:
    • Name: testaccount
    • Provide the Access key ID and the Secret access key when prompted
Note that the name of the profile must be in lowercase characters, to prevent an error like “Command 'AWS: Create Credentials Profile' resulted in an error (Unexpected credentialsProviderId format: TestAccount)”

Now the profile is created which you can check by checking “AWS: Create Credentials Profile” again, which will show the file.

You can test the credentials by chossing “AWS: Connect to AWS”. If this is successful you'll see a message in the right bottom corner telling you with what profile AWS Toolkit is connected.

Production Account

You can fully repeat the above steps for additional AWS accounts, except for the AWS Create Credentials Step. If you select this the profile file is opened and you can add additional accounts like this:

# Amazon Web Services Credentials File used by AWS CLI, SDKs, and tools
# This file was created by the AWS Toolkit for Visual Studio Code extension.
#
# Your AWS credentials are represented by access keys associated with IAM users.
# For information about how to create and manage AWS access keys for a user, see:
# https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html
#
# This credential file can store multiple access keys by placing each one in a
# named "profile". For information about how to change the access keys in a
# profile or to add a new profile with a different access key, see:
# https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html
#
[testaccount]
# The access key and secret key pair identify your account and grant access to AWS.
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
# Treat your secret key like a password. Never share your secret key with anyone. Do
# not post it in online forums, or store it in a source control system. If your secret
# key is ever disclosed, immediately use IAM to delete the access key and secret key
# and create a new key pair. Then, update this file with the replacement key details.
aws_secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
[prodaccount]
# The access key and secret key pair identify your account and grant access to AWS.
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
# Treat your secret key like a password. Never share your secret key with anyone. Do
# not post it in online forums, or store it in a source control system. If your secret
# key is ever disclosed, immediately use IAM to delete the access key and secret key
# and create a new key pair. Then, update this file with the replacement key details.
aws_secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Add a Region

  • Connect to AWS and go to the AWS Explorer icon on the left menu bar
  • Click on Add a region to AWS Explorer and select the region from the list (Europe (Ireland)
  • Now the supported objects in that region are shown in the AWS Explorer

Add a Azure DevOps Project for File Versioning

In the next part we will run an AWS tutorial, and creating several files in the process. Obviously we want to keep these files in a git repository and my favorite tooling for that is Azure DevOps. As we will be working in the AWS TestAccount we will use my test project in my Azure DevOps Test Organization:

  • Log into Azure DevOps and navigate to the project you want to use.
  • Go to Repos → Files
  • From the root in the repository, click “Clone” and select “Clone in VS Code” under the IDE section in the new “Clone Repository” popup.
  • VS Code will open and will ask you for a folder to store the repository
  • In the VS Code Exlorer you'll now a new folder in your workspace representing your project in Azure DevOps
  • Add a new folder under the project called AWSToolkit (or any name you want)

We now have a place to store the files we will create in the next part.

Run the StepFunction Tutorial

AWS provides a 10 minute tutorial for Step Functions, which is the tutorial we are going to try out for working with AWS Toolkit for VS Code.

Create State Machine

  • The first step is to create a State Machine:
    • The tutorial provides the definition code, so copy the code to your clipboard
    • Now, select Step Functions in the AWS Explorer and select “AWS: Create a new Step Functions State Machine”
    • Select the Hello World template and replace all the text with the content of your clipboard
    • Save the file under the directory you assigned as the project folder in the previous step as CallCenterStateMachine.asl.json
    • Now select “Publish to Step Functions” from the top of the file
      • Select Quick Create
      • Select the STEP FUNCTION BASIC EXECUTE ROLE
      • Name: CallCenterStateMachine

This provides the following output:

Creating state machine 'CallCenterStateMachine' in us-east-1...
Successfully created state machine 'CallCenterStateMachine'
arn:aws:states:us-east-1:952941930635:stateMachine:CallCenterStateMachine
Note that it gets deployed to us-east-1 instead of my opened region Ireland.

Solution: Add region=eu-west-1 to the profile file:

Creating state machine 'CallCenterStateMachine' in eu-west-1...
Successfully created state machine 'CallCenterStateMachine'
arn:aws:states:eu-west-1:952941930635:stateMachine:CallCenterStateMachine

You can verify the existence of the state machine in the AWS console for Step Functions.

Profile

Just for reference, this is now my profile:

# Amazon Web Services Credentials File used by AWS CLI, SDKs, and tools
# This file was created by the AWS Toolkit for Visual Studio Code extension.
#
# Your AWS credentials are represented by access keys associated with IAM users.
# For information about how to create and manage AWS access keys for a user, see:
# https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html
#
# This credential file can store multiple access keys by placing each one in a
# named "profile". For information about how to change the access keys in a
# profile or to add a new profile with a different access key, see:
# https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html
#
[testaccount]
region=eu-west-1
# The access key and secret key pair identify your account and grant access to AWS.
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
# Treat your secret key like a password. Never share your secret key with anyone. Do
# not post it in online forums, or store it in a source control system. If your secret
# key is ever disclosed, immediately use IAM to delete the access key and secret key
# and create a new key pair. Then, update this file with the replacement key details.
aws_secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
[prodaccount]
region=eu-west-1
# The access key and secret key pair identify your account and grant access to AWS.
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
# Treat your secret key like a password. Never share your secret key with anyone. Do
# not post it in online forums, or store it in a source control system. If your secret
# key is ever disclosed, immediately use IAM to delete the access key and secret key
# and create a new key pair. Then, update this file with the replacement key details.
aws_secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Create Lambda Functions

To create Lambda functions using the AWS Toolkit for VS Code we need to create a serverless application. There are templates available which are easy to start with but also complicated as in that they create quite a few resources we don't need for now. So for now, we will create our own:

  • Inside of the directory we created before, create the following folder and file structure:
- SAM-CallCenterLambdas
-- functions
--- assign-case
---- app.js
---- package.json
--- close-case
---- app.js
---- package.json
--- escalate-case
---- app.js
---- package.json
--- open-case
---- app.js
---- package.json
--- work-on-case
---- app.js
---- package.json
-- template.yaml

Now edit the app.js, package.json and template.yaml file as:

  • for each of the app.js files, copy paste the javascript for the corresponding function from the Step Functions Tutorial
  • for each of the package.json files, copy paste the following code and adjust accordingly:
{
    "name": "assign_case",
    "version": "1.0.0",
    "description": "Assign Case Lambda Function for 10 minute tutoral Step Functions",
    "main": "app.js",
    "author": "AWS",
    "license": "MIT"
}
  • Use the following code for the template.yaml:
AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: >
  SAM-CallCenterLambdas
 
  SAM to deploy Lambdas as described in https://aws.amazon.com/getting-started/hands-on/create-a-serverless-workflow-step-functions-lambda/

Resources:
  OpenCaseFunction:
    Type: AWS::Serverless::Function # More info about Function Resource: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html
    Properties:
      CodeUri: functions/open-case/
      Handler: app.handler #app.lambdaHandler
      Runtime: nodejs12.x
      Role: arn:aws:iam::111111111:role/service-role/OpenCaseFunction-role-xxxxxxx

  AssignCaseFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/assign-case/
      Handler: app.handler #app.lambdaHandler
      Runtime: nodejs12.x
      Role: arn:aws:iam::111111111:role/service-role/OpenCaseFunction-role-xxxxxxx

  WorkOnCaseFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/work-on-case/
      Handler: app.handler #app.lambdaHandler
      Runtime: nodejs12.x
      Role: arn:aws:iam::111111111:role/service-role/OpenCaseFunction-role-xxxxxxx

  CloseCaseFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/close-case/
      Handler: app.handler #app.lambdaHandler
      Runtime: nodejs12.x
      Role: arn:aws:iam::111111111:role/service-role/OpenCaseFunction-role-xxxxxxx

  EscalateCaseFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: functions/escalate-case/
      Handler: app.handler #app.lambdaHandler
      Runtime: nodejs12.x
      Role: arn:aws:iam::111111111:role/service-role/OpenCaseFunction-role-xxxxxxx
Please notice the roles, if you don't add a role one will be created automatically for you per function. If you need specific permissions, or want them all to use the same role you you need to list it as shown above.

Create S3 Bucket

Before we can deploy the Serverless Application containing our Lambdas we need to create an S3 bucket as a staging area from which the actual deployment can take place:

  • In VS Code, in the AWS Explorer, go to the S3 section
  • Your current buckets are displayed, if there is none you can use right-click on S3 and click on Create Bucket
    • Provide a name and your bucket is created with all the default settings

Deploy Lambda Functions

Now that we've prepared everything all we need to do is deploy the Serverless Application, and as part of that the Lambda functions will be deployed as well:

  • Open the command palette and search for AWS and select AWS: Deploy Serverless Application
    • Select the just created template.yaml from the list
    • Select the region to deploy to: Europe (Ireland) - eu-west-1
    • Provide the name of the S3 bucket we created earlier: vscode-awstoolkitsam
    • Provide the name of the (CloudFormation) stack. Notice that all resources will be created with this name as a prefix, so keep the name short and simple: sam-callcenter

Now the deployment starts which you can monitor using the output in VS Code and if everything was configured correctly you now have 5 new Lambdas functions.

Update State Machine

Unfortunately, the Step Functions State Machine does not work yet, as we created it with placeholders for the Lambda functions. The newly create Lambda functions are available now in the AWS Explorer (maybe after a refresh) so you can edit the original CallCenterStateMachine.asl.json, and replace the placeholders with the ARN, which you can get by rightclicking the Lambda function in the AWS explorer and selecting Copy ARN. Once you done that, at the top of the file, click “Publish to Step Functions”. Select Quick Update and select CallCenterStateMachine from the list.

Test

Now everything should work, and to test:

  • In the AWS Explorer, navigate to the CallCenterStateMachine
  • Right click the state machine and select Start Execution
  • As explained in the tutorial, provide the json input below and click Execute
{ "inputCaseID": "001" }

Unfortunately, in the output you can only see that the execution started, not the result, and as the State Machine is also not configured for CloudWatch logging we can only check in the AWS Console what the result is. You could check the CloudWatch Lambda loggroup, but that lacks the overview of the entire Step Function:

  • In the AWS Console, go to the Step Functions console
  • Click on the CallCenterStateMachine
  • You can now check the status of the executions, and click on the execution to go to the Graph Inspector to get a visual overview.

To check the individual Lambda Cloudwatch logs check in AWS Explorer the Cloudwatch Logs. Notice that it could take a while for the logs to show.

Resources

awstoolkitforvsc.txt · Last modified: 2021/09/24 08:07 by sjoerd