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. The following information describes the types of changes AWS CodeStar supports.

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 related IAM role, or its related 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, then 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 dashboard for the project. 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, revoke access using the Authorized OAuth Apps section of the settings page for your GitHub account profile.

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, then 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 related IAM role or API Gateway API, that AWS CodeStar creates in a project. To do this, we recommend 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, related IAM role, and related 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 the file /template.yml.

You can modify this file to add tracing by adding the AWS X-Ray resource to the Resources section in the template.yml file. You then modify the IAM permissions for your project to allow AWS CloudFormation to create the resource. To learn more 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. Click 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. Paste the resource into the Properties section under the Resources.

    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, select 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.

  3. After the successful completion of your pipeline, tracing is enabled on your application. You can verify tracing is enabled by viewing the details for your function in the Lambda console.

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

Add a Resource to a Project

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

You can modify this file by adding AWS CloudFormation resources to the Resources section in the template.yml file. Modifying the project template.yml file allows AWS CodeStar and AWS CloudFormation to add the new resource to your project. Certain resources require additional permissions to be added to the policy created for your project's CloudFormation Worker role. To learn more 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 in JSON format.

    Note

    The policy attached to the worker role is CodeStarWorkerCloudFormationRolePolicy.

  6. In the JSON field, add the following policy statement within 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. When the policy is error-free, 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 existing serverless project and then open the Code page. In the top level of your repository, note the location of the template to be modified, 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, restart your pipeline after permissions have been corrected.

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 select the AWS CloudFormation stage in your pipeline on your AWS CodeStar dashboard to see the stack update notice when deployment is started.

    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.

    Select the CloudFormation link in your pipeline's Deploy stage to troubleshoot the failure in the AWS CloudFormation console. In the console, select your project in the Events list 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 successful completion 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.

  3. 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 associated AdministratorAccess managed policy or equivalent.

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

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

  3. Paste the policy for your new resource on the JSON tab. 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, type 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

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

Shift Traffic for an AWS Lambda Project

AWS CodeDeploy supports function version deployments for AWS Lambda functions in your AWS CodeStar serverless projects. An AWS Lambda deployment shifts incoming traffic from an existing Lambda function to an updated Lambda function version. You might want to test an updated Lambda function by deploying a separate version and then rolling back the deployment to the first version if needed.

Use the steps in this section to modify your AWS CodeStar project template and update your CodeStarWorker role’s IAM permissions. This task starts an automated response in AWS CloudFormation that creates aliased AWS Lambda functions and then instructs AWS CodeDeploy to shift traffic to an updated environment.

AWS CodeDeploy has three deployment options that allow you to shift traffic to versions of your AWS Lambda function in your application:

  • Canary: Traffic is shifted in two increments. You can choose from predefined canary options that specify the percentage of traffic shifted to your updated Lambda function version in the first increment and the interval, in minutes, before the remaining traffic is shifted in the second increment.

  • Linear: Traffic is shifted in equal increments with an equal number of minutes between each increment. You can choose from predefined linear options that specify the percentage of traffic shifted in each incrememnt and the number of minutes between each increment. Traffic is shifted in equal increments with an equal number of minutes between each increment. You can choose from predefined linear options that specify the percentage of traffic shifted in each increment and the number of minutes between each increment.

  • All-at-once: All traffic is shifted from the original Lambda function to the updated Lambda function version at once.

Deployment Preference Type
Canary10Percent30Minutes
Canary10Percent5Minutes
Canary10Percent10Minutes
Canary10Percent15Minutes
Linear10PercentEvery10Minutes
Linear10PercentEvery1Minute
Linear10PercentEvery2Minutes
Linear10PercentEvery3Minutes
AllAtOnce

For more information about AWS CodeDeploy deployments on an AWS Lambda compute platform, see Deployments on an AWS Lambda Compute Platform.

For more information about AWS SAM, see AWS Serverless Application Model (AWS SAM) on GitHub.

Prerequisites:

When you create a serverless project, select any template with the Lambda compute platform. You must be signed in as an administrator to perform steps 4-6.

Topics

    Step 1: Modify the SAM template to add AWS Lambda version deployment parameters

    1. 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 Code page. In the top level of your repository, note the location of the SAM template named template.yml to be modified.

    3. Open the template.yml file in your IDE or local repository. Copy the following text to add a Globals section to the file. The sample text in this tutorial chooses the Canary10Percent5Minutes option.

      Globals: Function: AutoPublishAlias: live DeploymentPreference: Enabled: true Type: Canary10Percent5Minutes

      This example shows a modified template after the Globals section has been added:

      For more information, see the Globals Section reference guide for SAM templates.

    Step 2: Edit the AWS CloudFormation role to add permissions

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

      Note

      You must sign in to the AWS Management Console using credentials associated with the IAM user you created or identified in Setting Up AWS CodeStar. This user must have the AWS managed policy named AWSCodeStarFullAccess attached.

    2. Choose your existing serverless project and then open the Project resources page.

    3. Under Resources, choose the IAM role created for the CodeStarWorker/AWS CloudFormation role. The role opens in the IAM console.

    4. On the Permissions tab, in Inline Policies, in the row for your service role policy, choose Edit Policy. Choose the JSON tab to edit the policy in JSON format.

      Note

      Your service role is named CodeStarWorkerCloudFormationRolePolicy.

    5. In the JSON field, add the following policy statements within the Statement element. Replace the region and id placeholders with your region and account ID.

      { "Action": [ "s3:GetObject", "s3:GetObjectVersion", "s3:GetBucketVersioning" ], "Resource": "*", "Effect": "Allow" }, { "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws:s3:::codepipeline*" ], "Effect": "Allow" }, { "Action": [ "lambda:*" ], "Resource": [ "arn:aws:lambda:region:id:function:*" ], "Effect": "Allow" }, { "Action": [ "apigateway:*" ], "Resource": [ "arn:aws:apigateway:region::*" ], "Effect": "Allow" }, { "Action": [ "iam:GetRole", "iam:CreateRole", "iam:DeleteRole", "iam:PutRolePolicy" ], "Resource": [ "arn:aws:iam::id:role/*" ], "Effect": "Allow" }, { "Action": [ "iam:AttachRolePolicy", "iam:DeleteRolePolicy", "iam:DetachRolePolicy" ], "Resource": [ "arn:aws:iam::id:role/*" ], "Effect": "Allow" }, { "Action": [ "iam:PassRole" ], "Resource": [ "*" ], "Effect": "Allow" }, { "Action": [ "codedeploy:CreateApplication", "codedeploy:DeleteApplication", "codedeploy:RegisterApplicationRevision" ], "Resource": [ "arn:aws:codedeploy:region:id:application:*" ], "Effect": "Allow" }, { "Action": [ "codedeploy:CreateDeploymentGroup", "codedeploy:CreateDeployment", "codedeploy:DeleteDeploymentGroup", "codedeploy:GetDeployment" ], "Resource": [ "arn:aws:codedeploy:region:id:deploymentgroup:*" ], "Effect": "Allow" }, { "Action": [ "codedeploy:GetDeploymentConfig" ], "Resource": [ "arn:aws:codedeploy:region:id:deploymentconfig:*" ], "Effect": "Allow" }
    6. Choose Review policy to ensure the policy contains no errors. When the policy is error-free, choose Save changes.

    Step 3: Commit and push your template change to start the AWS Lambda version shift

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

      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 that roll back the stack update. If this happens, restart your pipeline after permissions have been corrected.

    2. The AWS CloudFormation stack update starts when the pipeline for your project starts the Deploy stage. To see the stack update notification when the deployment starts, on your AWS CodeStar dashboard, select the AWS CloudFormation stage in your pipeline.

      During stack update, AWS CloudFormation automatically updates the project resources as follows:

      • AWS CloudFormation processes the template.yml file by creating aliased Lambda functions, event hooks, and resources.

      • AWS CloudFormation calls Lambda to create the new version of the function.

      • AWS CloudFormation creates an AppSpec file and calls AWS CodeDeploy to shift the traffic.

      For more information about publishing aliased Lambda functions in SAM, see the AWS Serverless Application Model (SAM) template reference. For more information about event hooks and resources in the AWS CodeDeploy AppSpec file, see AppSpec 'resources' Section (AWS Lambda Deployments Only) and AppSpec 'hooks' Section for an AWS Lambda Deployment.

    3. After successful completion of your pipeline, the resources are created in your AWS CloudFormation stack. On the Project page, in the Project Resources list, view the AWS CodeDeploy application, the AWS CodeDeploy deployment group, and the AWS CodeDeploy service role resources created for your project.

    4. To create a new version, make a change to the Lambda function in your repository. The new deployment starts and shifts traffic according to the deployment type indicated in the SAM template. To view the status of the traffic that is being shifted to the new version, on the Project page, in the Project Resources list, choose the link to the AWS CodeDeploy deployment.

    5. To view details about each revision, under Revisions, choose the link to the AWS CodeDeploy deployment group.

    6. In your local working directory, you can make changes to your AWS Lambda function and commit the change to your project repository. AWS CloudFormation supports AWS CodeDeploy in managing the next revision in the same way. For more information about redeploying, stopping, or rolling back a Lambda deployment, see Deployments on an AWS Lambda Compute Platform.