AWS CodeStar
User Guide

Change AWS Resources in an AWS CodeStar Project

After you create a project in AWS CodeStar, you can change the default set of AWS resources that AWS CodeStar adds to the project.

Supported Resource Changes

The following table lists the supported and unsupported changes to default AWS resources in an AWS CodeStar project.

Change Supported? Notes
Add a stage to AWS CodePipeline. Yes See Add a Stage to AWS CodePipeline.
Change Elastic Beanstalk environment settings. Yes See Change AWS Elastic Beanstalk Environment Settings.
Change an AWS Lambda function's code or settings, its IAM role, or its API in Amazon API Gateway. Yes See Change an AWS Lambda Function in Source Code.
Add a resource to an AWS Lambda project and expand permissions to create and access the new resource. Yes See Add a Resource to a Project.
Add traffic shifting with AWS CodeDeploy for an AWS Lambda function. Yes See Shift Traffic for an AWS Lambda Project.
Add AWS X-Ray support Yes See Enable Tracing for a Lambda Project.
Switch to a different deployment target (for example, deploy to AWS Elastic Beanstalk instead of AWS CodeDeploy). No
Change an IAM role definition. No
Add a friendly web endpoint name. No
Change the AWS CodeCommit repository name (for an AWS CodeStar project connected to AWS CodeCommit). No
Disconnect the GitHub repository (for an AWS CodeStar project connected to GitHub) and then reconnect the repository to that project, or connect any other repository to that project. No

You can use the AWS CodePipeline console (not the AWS CodeStar console) to disconnect and reconnect to GitHub in a pipeline's Source stage. However, if you reconnect the Source stage to a different GitHub repository, in the AWS CodeStar dashboard for the project, the information in the Application endpoints, Commit history, and GitHub Issues tiles might be wrong or out of date.

Disconnecting the GitHub repository does not remove that repository's information from the commit history and GitHub issues tiles in the AWS CodeStar project dashboard. To remove this information, use the GitHub website to disable access to GitHub from the AWS CodeStar project. To do this, on the GitHub website, use the Authorized OAuth Apps section of the settings page for your GitHub account profile to revoke access.

Disconnect the AWS CodeCommit repository (for an AWS CodeStar project connected to AWS CodeCommit) and then reconnect the repository to that project, or connect any other repository to that project. No
Modify the buildspec.yml file for your project to add a unit test build phase AWS CodeBuild runs. Yes See Step 7: Add a Unit Test to the Web Service.

Add a Stage to AWS CodePipeline

You can add a new stage to a pipeline that AWS CodeStar creates in a project. For more information, see Edit a Pipeline in AWS CodePipeline in the AWS CodePipeline User Guide.

Note

If the new stage depends on any AWS resources that AWS CodeStar did not create, the pipeline might break. This is because the IAM role that AWS CodeStar created for AWS CodePipeline might not have access to those resources by default.

To attempt to give AWS CodePipeline access to AWS resources that AWS CodeStar did not create, you might want to change the IAM role that AWS CodeStar created. This is not supported because AWS CodeStar might remove your IAM role changes when it performs regular update checks on the project.

Change AWS Elastic Beanstalk Environment Settings

You can change the settings of an Elastic Beanstalk environment that AWS CodeStar creates in a project. For more information, see AWS Elastic Beanstalk Environment Management Console in the AWS Elastic Beanstalk Developer Guide.

Change an AWS Lambda Function in Source Code

You can change the code or settings of a Lambda function, or its IAM role or API Gateway API, that AWS CodeStar creates in a project. To do this, we recommend that you use the AWS Serverless Application Model (AWS SAM) along with the template.yaml file in your project's AWS CodeCommit repository. This template.yaml file defines your function's name, handler, runtime, IAM role, and API in API Gateway. For more information, see How to Create Serverless Applications Using AWS SAM on the GitHub website.

Enable Tracing for a Lambda Project

AWS X-Ray offers tracing, which you can use to analyze performance behavior of distributed applications (for example, latencies in response times). After you add traces to your AWS CodeStar project, you can use the AWS X-Ray console to view application views and response times.

Each AWS CodeStar template for Lambda-based projects includes an AWS CloudFormation file that models your application's AWS runtime dependencies, such as database tables and Lambda functions. This file is stored in your source repository in /template.yml.

You can modify this file to add tracing by adding the AWS X-Ray resource to the Resources section. You then modify the IAM permissions for your project to allow AWS CloudFormation to create the resource. For information about template elements and formatting, see AWS Resource Types Reference.

These are the high-level steps to follow to customize your template.

Step 1: Edit the Lambda Worker Role in IAM for Tracing

You must be signed in as an administrator to perform steps 1 and 4.

  1. Sign in to the AWS Management Console and open the AWS CodeStar console at https://console.aws.amazon.com/codestar/.

  2. Create a project or choose an existing project with a template.yml file, and then open the Project resources page.

  3. Under Project Resources, locate the IAM role created for the CodeStarWorker/Lambda role in the resource list. The role name follows this format: role/CodeStarWorker-Project_name-lambda-Function_name. Choose the ARN for the role.

  4. The role opens in the IAM console. Choose Attach policies. Search for the AWSXrayWriteOnlyAccess policy, select the box next to it, and then choose Attach Policy.

Step 2: Modify the template.yml File for Tracing

  1. Open the AWS CodeStar console at https://console.aws.amazon.com/codestar/.

  2. Choose your serverless project and then open the Code page. In the top level of your repository, locate and edit the template.yml file. Under Resources, paste the resource into the Properties section .

    Tracing: Active

    This example shows a modified template:

Step 3: Commit and Push Your Template Change for Tracing

  • Commit and push the changes in the template.yml file.

    Note

    This starts your pipeline. If you commit the changes before you update IAM permissions, your pipeline starts, the AWS CloudFormation stack update encounters errors, and the stack update is rolled back. If this happens, correct the permissions and then restart your pipeline.

Step 4: Monitor the AWS CloudFormation Stack Update for Tracing

  1. The AWS CloudFormation stack update starts when the pipeline for your project starts the Deploy stage. To see the status of the stack update, on your AWS CodeStar dashboard, choose the AWS CloudFormation stage in your pipeline.

    If the stack update in AWS CloudFormation returns errors, see troubleshooting guidelines in AWS CloudFormation: Stack Creation Rolled Back for Missing Permissions. If permissions are missing from the worker role, edit the policy attached to your project's Lambda worker role. See Step 1: Edit the Lambda Worker Role in IAM for Tracing.

  2. Use the dashboard to view the successful completion of your pipeline. Tracing is now enabled on your application.

  3. Verify that tracing is enabled by viewing the details for your function in the Lambda console.

  4. Choose the application endpoint for your project. This interaction with your application is traced. You can view tracing information in the AWS X-Ray console.

Add a Resource to a Project

Each AWS CodeStar project template includes an AWS CloudFormation file that models your application's AWS runtime dependencies, such as database tables and Lambda functions. This file is stored in your source repository in /template.yml.

You can modify this file by adding AWS CloudFormation resources to the Resources section. Modifying the template.yml file allows AWS CodeStar and AWS CloudFormation to add the new resource to your project. Some resources require you to add other permissions to the policy for your project's CloudFormation worker role. For information about template elements and formatting, see AWS Resource Types Reference.

After you determine which resources you must add to your project, these are the high-level steps to follow to customize a template. For a list of AWS CloudFormation resources and their required properties, see AWS Resource Types Reference.

Use the steps in this section to modify your AWS CodeStar project template to add a resource and then expand the project's CloudFormation worker role's permissions in IAM. In this example, the AWS::SQS::Queue resource is added to the template.yml file. The change starts an automated response in AWS CloudFormation that adds an Amazon Simple Queue Service queue to your project.

Step 1: Edit the CloudFormation Worker Role in IAM

You must be signed in as an administrator to perform steps 1 and 5.

  1. Sign in to the AWS Management Console and open the AWS CodeStar console, at https://console.aws.amazon.com/codestar/.

  2. Create a project or choose an existing project with a template.yml file, and then open the Project resources page.

  3. Under Project Resources, locate the IAM role created for the CodeStarWorker/AWS CloudFormation role in the resource list. The role name follows this format: role/CodeStarWorker-Project_name-CloudFormation.

  4. The role opens in the IAM console. On the Permissions tab, in Inline Policies, expand the row for your service role policy, and choose Edit Policy.

  5. Choose the JSON tab to edit the policy.

    Note

    The policy attached to the worker role is CodeStarWorkerCloudFormationRolePolicy.

  6. In the JSON field, add the following policy statement in the Statement element.

    { "Action": [ "sqs:CreateQueue", "sqs:DeleteQueue", "sqs:GetQueueAttributes", "sqs:SetQueueAttributes", "sqs:ListQueues", "sqs:GetQueueUrl" ], "Resource": [ "*" ], "Effect": "Allow" }
  7. Choose Review policy to ensure the policy contains no errors, and then choose Save changes.

Step 2: Modify the template.yml File

  1. Open the AWS CodeStar console at https://console.aws.amazon.com/codestar/.

  2. Choose your serverless project and then open the Code page. In the top level of your repository, make a note of the location of template.yml.

  3. Use an IDE, the console, or the command line in your local repository to edit the template.yml file in your repository. Paste the resource into the Resources section. In this example, when the following text is copied, it adds the Resources section.

    Resources: TestQueue: Type: AWS::SQS::Queue

    This example shows a modified template:

Step 3: Commit and Push Your Template Change

  • Commit and push the changes in the template.yml file that you saved in step 2.

    Note

    This starts your pipeline. If you commit the changes before you update IAM permissions, your pipeline starts and the AWS CloudFormation stack update encounters errors, which causes the stack update to be rolled back. If this happens, correct the permissions and then restart your pipeline.

Step 4: Monitor the AWS CloudFormation Stack Update

  1. When the pipeline for your project starts the Deploy stage, the AWS CloudFormation stack update starts. You can choose the AWS CloudFormation stage in your pipeline on your AWS CodeStar dashboard to see the stack update.

    Troubleshooting:

    The stack update fails if required resource permissions are missing. View the failure status in the AWS CodeStar dashboard view for your project's pipeline.

    Choose the CloudFormation link in your pipeline's Deploy stage to troubleshoot the failure in the AWS CloudFormation console. In the console, in the Events list, choose your project to view stack creation details. There is a message with the failure details. In this example, the sqs:CreateQueue permission is missing.

    Add any missing permissions by editing the policy attached to your project's AWS CloudFormation worker role. See Step 1: Edit the CloudFormation Worker Role in IAM.

  2. After a successful run of your pipeline, the resources are created in your AWS CloudFormation stack. In the Resources list in AWS CloudFormation, view the resource created for your project. In this example, the TestQueue queue is listed in the Resources section.

    The queue URL is available in AWS CloudFormation. The queue URL follows this format:

    https://{REGION_ENDPOINT}/queue.|api-domain|/{YOUR_ACCOUNT_NUMBER}/{YOUR_QUEUE_NAME}

    For more information, see Send an Amazon SQS Message, Receive a Message from an Amazon SQS Queue, and Delete a Message from an Amazon SQS Queue.

Step 5: Add Resource Permissions with an Inline Policy

Grant team members access to your new resource by adding the appropriate inline policy to the user's role. Not all resources require that you add permissions. To perform the following steps, you must have signed in to the console either as a root user, an IAM administrator user in the account, or an IAM user or federated user with the AdministratorAccess managed policy or equivalent.

  1. In the IAM console, choose Users, and then choose the user account.

  2. On the Permissions tab, choose Add inline policy. On the Create policy page, choose the JSON tab.

  3. On the JSON tab, paste the policy for your new resource. Use the permissions that are appropriate for the level of access you want to provide. This example provides the view-only policy for the Amazon SQS resource. Copy and paste the JSON policy provided here.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sqs:Get*", "sqs:List*", "sqs:Receive*" ], "Resource": "*" } ] }
  4. Choose Review policy, and then choose Create policy.

  5. In Name, enter a name for your inline policy. To make your policy easier to find and modify, include your AWS CodeStar project name in the policy title.

  6. The updated statement is displayed as attached directly to the user.

  7. If necessary, you can copy the policy to other team members.

    Important

    AWS CodeStar does not manage the inline policy created for an added resource. To remove the user's permissions or clean up deleted resources, you must manually delete the inline policy.