AWS Toolkit for JetBrains IDEsUser Guide

AWS Toolkit for JetBrains IDEs User Guide

AWS Toolkit for JetBrains IDEs: User GuideCopyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any mannerthat is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks notowned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored byAmazon.

AWS Toolkit for JetBrains IDEs User Guide

Table of ContentsWhat Is the AWS Toolkit for JetBrains IDEs? .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Additional Resources .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Getting Started .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

AWS Toolkit for JetBrains Features by Programming Language .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Setting Up the AWS Toolkit for JetBrains .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Prerequisites ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Install the AWS Toolkit for JetBrains on the JetBrains IDEs .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Setting Up Your AWS Credentials ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Get Your AWS Access Keys .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Add Your AWS Access Keys to the AWS Toolkit for JetBrains .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Use Multiple AWS Accounts with the AWS Toolkit for JetBrains .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Changing AWS Regions .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Working with AWS Services .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Working with AWS Lambda .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Creating and Deploying a Serverless Application .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Creating a Lambda function .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Invoking and Debugging a Lambda Function .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Document History .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

iii

AWS Toolkit for JetBrains IDEs User GuideAdditional Resources

What Is the AWS Toolkit forJetBrains IDEs?

The AWS Toolkit for JetBrains IDEs is an open source plug-in for the integrated developmentenvironments (IDEs) from Jetbrains that makes it easier for developers to develop, debug, and deployserverless applications that use Amazon Web Services. It includes features like credentials managementand AWS Region management that simplify writing applications for Amazon Web Services.

Topics

• Getting Started with the AWS Toolkit for JetBrains (p. 2)• Working with AWS Services (p. 8)

Additional ResourcesUse the following resources to access the source code for the toolkit or view currently open issues.

• Source Code• Issue Tracker

1

AWS Toolkit for JetBrains IDEs User GuideAWS Toolkit for JetBrains Features

by Programming Language

Getting Started with the AWSToolkit for JetBrains

This section provides information for getting started with the AWS Toolkit for JetBrains IDEs, includinginformation about how to install and configure the AWS Toolkit for JetBrains.

Topics

• AWS Toolkit for JetBrains Features by Programming Language (p. 2)

• Setting Up the AWS Toolkit for JetBrains on JetBrains IDEs (p. 2)

• Setting Up Your AWS Credentials (p. 3)

• Changing AWS Regions (p. 6)

AWS Toolkit for JetBrains Features byProgramming Language

Before you begin, note the toolkit features supported for each language.

Language ResourceExplorer

NewServerlessProject

Local Run/Debug

DeployLambdaFunction

DeployServerlessApplication

InvokeRemoteLambdaFunction

Python Yes Yes Yes Yes Yes Yes

Java Yes Yes Yes Yes No Yes

All Others Yes No No No No Yes

Setting Up the AWS Toolkit for JetBrains onJetBrains IDEs

This section describes how to install or upgrade the AWS Toolkit for JetBrains.

PrerequisitesBefore you can install the AWS Toolkit for JetBrains, you must have the following:

• An Amazon Web Services account – To obtain an AWS account, go to the AWS home page, and chooseSign Up Now. Signing up enables you to use all of the services offered by AWS.

2

AWS Toolkit for JetBrains IDEs User GuideInstall the AWS Toolkit for JetBrains on the JetBrains IDEs

• A supported operating system – The AWS Toolkit for JetBrains is supported on Windows, Linux,macOS, or Unix.

• JetBrains IDEs version 2018.3.x or later – We try to keep the AWS Toolkit for JetBrains current withthe default version that's available on the JetBrains download page.

• AWS SAM CLI – This is an AWS CLI tool that helps you to develop, test, and analyze your serverlessapplications locally. This isn't required for installing the toolkit, but we recommend you install itbecause it's required for any AWS Lambda functionality. See Installing the AWS SAM CLI in the AWSServerless Application Model Developer Guide

• Docker – This open-source software container platform is required by the AWS SAM CLI. For moreinformation and download instructions, see Docker.

Install the AWS Toolkit for JetBrains on the JetBrainsIDEs1. Start one of the JetBrains IDEs.2. In the Preference menu, choose Plugins.3. In the search box for Plugins, start typing AWS until the entry AWS Toolkit is visible in the list.

Choose the entry to see its details in the right pane.4. In the right pane, choose Install.5. Once installed, when you're prompted to restart the IDE, choose Restart to finish installation.

After you install the AWS Toolkit for JetBrains, you should configure your AWS credentials (p. 3) toenable you to access your AWS resources from within JetBrains.

Setting Up Your AWS CredentialsTo access Amazon Web Services with the AWS Toolkit for JetBrains, you must configure the AWS Toolkitfor JetBrains with your AWS account credentials.

For details about users and credentials that are out of scope for this guide, see the following resources:

• AWS Security Credentials in the Amazon Web Services General Reference• Overview of Identity Management: Users in the IAM User Guide

Get Your AWS Access KeysAccess keys are the credentials that identify you to AWS and enable you to programmatically access AWSservices and resources. Access keys can be associated with your AWS account (the account's "root user")or with users that you create with IAM.

Because the root user is essentially an administrator with full access to services and resources, werecommend that you instead create an IAM user with only those permissions needed to perform therequired tasks. Then, for your credentials, you can use an access key that is associated with that user. Fordetails, see Creating an IAM User in Your AWS Account in the IAM User Guide.

An access key consists of an access key ID, which is analogous to a user name, and a secret access key,which is analogous to a password. This access key is used to sign programmatic requests that you maketo AWS. If you don't have access keys, you can create them by using the AWS Management Console. Werecommend that you use access keys for an IAM user instead of the keys for your account's root user.

3

AWS Toolkit for JetBrains IDEs User GuideAdd Your AWS Access Keys to the AWS Toolkit for JetBrains

NoteTo create access keys, you must have permissions to perform the required IAM actions. For moreinformation, see Granting IAM User Permissions to Manage Password Policy and Credentials inthe IAM User Guide.

To retrieve your access key ID and secret access key

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. On the navigation menu, choose Users.

3. Choose your IAM user name (not the check box) to view its details.

4. Choose the Security Credentials tab, and then choose Create access key.

5. To see the new access key, choose Show. The credentials resemble the following:

• Access key ID: AKIAIOSFODNN7EXAMPLE

• Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

6. To download the key pair, choose Download .csv file. Store the keys in a secure location.

Important

• Keep the keys confidential to protect your AWS account, and never email them. Do notshare them outside of your organization, even if an inquiry appears to come from AWS orAmazon.com. No one who legitimately represents Amazon will ever ask you for your secretkey.

• You can't recover the secret key if you lose it. Instead, for security reasons, you mustcreate a new key pair and delete the old pair.

Add Your AWS Access Keys to the AWS Toolkit forJetBrainsThe AWS Toolkit for JetBrains uses the same system for locating and using AWS access keys as that usedby the AWS CLI and the AWS SDKs. Access keys that you enter in the AWS Toolkit for JetBrains are savedto a shared AWS credentials file (named credentials) in the .aws directory within your home directory.

If you have already set your AWS credentials using the AWS CLI, the AWS Toolkit for JetBrains willautomatically detect and make those credentials available for use.

For more information about using the AWS CLI, see the AWS Command Line Interface User Guide.

To add your access keys to the AWS Toolkit for JetBrains

1. Open one of the JetBrains IDEs.

2. In the AWS Explorer window, choose Configure AWS connection. (If you're opening the IDE for thefirst time, you might need to expand the window from the left edge.)

3. Choose Edit AWS Credential file.

4. If the file doesn't exist, you're prompted to create it. Then choose OK.

4

AWS Toolkit for JetBrains IDEs User GuideUse Multiple AWS Accounts with

the AWS Toolkit for JetBrains

5. The toolkit opens the credentials file in the IDE. Add your access key ID and your secret access key,and then save the file.

Once your credentials are added and saved to the file, you will be prompted to restart the IDE. Whenthe IDE restarts see AWS Lambda listed in the AWS Explorer. Expand the node to see all the Lambdaapplications and functions that are defined in your account.

AWS Credentials File Format

When the toolkit creates an AWS credentials file, it creates a file with the following format.

[default] aws_access_key_id={YOUR_ACCESS_KEY_ID} aws_secret_access_key={YOUR_SECRET_ACCESS_KEY} [profile2] aws_access_key_id={YOUR_ACCESS_KEY_ID} aws_secret_access_key={YOUR_SECRET_ACCESS_KEY}

The profile name is specified in square brackets (for example, [default]), followed by the configurablefields in that profile as key-value pairs. You can have multiple profiles in your credentials file. You add oredit them using aws configure --profile PROFILE_NAME to select the profile to configure.

You can specify additional fields, such as aws_session_token, metadata_service_timeout, andmetadata_service_num_attempts. You can't configure these by using the CLI—you must edit thefile by hand if you want to use them. For more information about the configuration file and its availablefields, see Configuring the AWS Command Line Interface in the AWS Command Line Interface User Guide.

Use Multiple AWS Accounts with the AWS Toolkit forJetBrainsIf the credential file contains more than one AWS account, the toolkit makes it easy for you to choosebetween them. Multiple accounts can be useful, for example, to provide developers and administratorswith separate resources for development and for release or publication.

Separate sets of AWS credentials are stored as profiles within the shared AWS credentials file described inAdd Your AWS Access Keys to the AWS Toolkit for JetBrains (p. 4). You can see all configured profilesby choosing the AWS menu at the bottom right of the IDE, and then choosing All Credentials.

To add a new set of access keys

1. Open the AWS menu at the bottom right of the IDE.

5

AWS Toolkit for JetBrains IDEs User GuideChanging AWS Regions

2. Choose AWS Connection Settings and then choose the All Credentials menu.

3. Choose Edit AWS Credential file. This opens the credentials file in the IDE for editing.

4. Enter additional profiles by following the credentials file format described in AWS Credentials FileFormat (p. 5).

Changing AWS RegionsWhen you set up your credentials, the AWS Toolkit for JetBrains selects the default AWS Regionautomatically. This section describes how to select a different Region.

To select a different Region with the AWS Toolkit for JetBrains

1. Open the AWS Explorer and choose the Options menu.

2. Choose AWS Connection Settings and then choose All Regions.

6

AWS Toolkit for JetBrains IDEs User GuideChanging AWS Regions

3. Choose a Region from the list.

7

AWS Toolkit for JetBrains IDEs User GuideWorking with AWS Lambda

Working with AWS ServicesAWS Explorer gives you a view of the Amazon Web Services that the AWS Toolkit for JetBrains can workwith. This section provides information about how to access and use the AWS Explorer view in JetBrainsIDEs. It assumes that you've already installed the AWS Toolkit for JetBrains on your system.

Working with AWS LambdaThe AWS Toolkit for JetBrains provides support for authoring code for AWS Lambda. Lambda is a fullymanaged compute service that runs your code in response to events generated by custom code or fromvarious AWS services such as Amazon Simple Storage Service (Amazon S3), Amazon DynamoDB, AmazonKinesis, Amazon Simple Notification Service (Amazon SNS), and Amazon Cognito. For more informationabout Lambda, see the AWS Lambda Developer Guide.

This section of the AWS Toolkit for JetBrains User Guide focuses on how you can use features of the AWSToolkit for JetBrains to create, deploy, and debug Lambda functions.

Creating and Deploying a Serverless Application withthe AWS Toolkit for JetBrainsThis example will use the PyCharm IDE to create and deploy a serverless application using the AWSToolkit for JetBrains.

To create a serverless application with the AWS Toolkit for JetBrains

1. When the IDE starts, choose + Create New Project from the welcome window.2. Choose AWS Serverless Application in the New Project dialogue box.3. Fill in the appropriate location for the project to be stored. For this example, accept the default

values for the rest of the fields.

4. The toolkit creates a basic project that includes all the files you need to deploy, including the AWSSAM template file. The AWS SAM template file defines how the application will be deployed. See

8

AWS Toolkit for JetBrains IDEs User GuideCreating and Deploying a Serverless Application

AWS SAM Template Basics in the AWS Serverless Application Model Developer Guide for details aboutthe AWS SAM template syntax.

To deploy a serverless application with the AWS Toolkit for JetBrains

1. Open the context menu on your project and choose Deploy Serverless Application.

9

AWS Toolkit for JetBrains IDEs User GuideCreating and Deploying a Serverless Application

10

AWS Toolkit for JetBrains IDEs User GuideCreating a Lambda function

2. Enter a name for the stack. This is the AWS CloudFormation stack that will be created using the AWSSAM template file.

3. You can also create a new Amazon S3 bucket or select an existing one from your account. Thisbucket is used to store your project.

4. You can see the progress of the deployment in the Deploying Application dialogue box.

5. Once the deployment is complete, you will see your application listed in the AWS Explorer window.See the Invoking and Debugging a Lambda Function (p. 13) to learn how to invoke and debug theLambda function that was created as part of the application.

Creating a Lambda functionTo create a Lambda function using the AWS Toolkit for JetBrains, you must first create the requesthandler in your project. See the AWS Lambda Developer Guide for details on creating handlers. See JavaHandler in the AWS Lambda Developer Guide for details about creating a Java handler.

11

AWS Toolkit for JetBrains IDEs User GuideCreating a Lambda function

Creating a Lambda function Using the AWS Toolkit for JetBrainsFor this example, let's use the following simple handler.

import com.amazonaws.services.lambda.runtime.Context;import com.amazonaws.services.lambda.runtime.RequestHandler;

public class HelloLambda implements RequestHandler<String, String> {

@Override public String handleRequest(String input, Context context) { context.getLogger().log("Input: " + input); String output = "Hello, " + input + "!"; return output; }

}

NoteYou need the AWS SDK for Java for the import statements. See the AWS SDK for JavaDeveloper Guide for steps on setting up dependencies for the SDK for Java.

Once you have this function in your project, you're ready to create the Lambda function in your AWSaccount.

To create a Lambda function using the AWS Toolkit for JetBrains

1. In AWS Explorer, right-click AWS Lambda to open the context menu.2. Choose Create new AWS Lambda.3. In the dialog box, fill in the information for the new function.

You can create a new IAM role or choose an existing role to run your Lambda function. The list showsonly those roles that have permissions to run Lambda functions.

You can create an Amazon S3 bucket to upload the source to, or choose an existing S3 bucket inyour account.

4. After you fill in all the fields, choose Create Function.

12

AWS Toolkit for JetBrains IDEs User GuideInvoking and Debugging a Lambda Function

It will take a few minutes for the process to finish. When the function is created, you'll see a pop-upnotification that indicates your function was created.

You now have a function uploaded to Lambda. AWS Explorer lists your Lambda function underFunctions.

Invoking and Debugging a Lambda Function

Invoke a Lambda Function

You can invoke a Lambda function locally if you have the project that includes the Lambda handlerfunction open. See the Creating a Lambda function (p. 11) for an example of creating a new functionif you don't have one already.

1. Choose the Lambda icon in the code pane gutter to see the context menu.

2. Choose Run '[Local] HelloLambda'.

13

AWS Toolkit for JetBrains IDEs User GuideInvoking and Debugging a Lambda Function

3. Enter the following in the Input field.

"AWS Lambda"

If you don't get the configuration dialog box, choose Run from the IDE menu, and then choose EditConfigurations.

You'll see the output of the Lambda function run just like you would for any other project using the IDE.

14

AWS Toolkit for JetBrains IDEs User GuideInvoking and Debugging a Lambda Function

Debug a Lambda Function

You can also debug the Lambda function locally using the same context menu from the gutter icon.

1. Set a breakpoint for the debugger to look for.

2. Choose the Lambda icon in the code pane gutter to see the context menu.

3. Choose Debug '[Local] HelloLambda'.

15

AWS Toolkit for JetBrains IDEs User GuideInvoking and Debugging a Lambda Function

The debugger will run until it reaches the breakpoint, and then opens the debugger window. Then youcan use the IDE's debugger tools to step through the code.

16

AWS Toolkit for JetBrains IDEs User Guide

Document History for User GuideThe following table describes the documentation for this release of ServiceName.

update-history-change update-history-description update-history-date

Initial Release (p. 17) Initial release of the user guidefor AWS Toolkit for JetBrains.

November 27, 2018

17