Use the register-on-premises-instance command (IAM user ARN) to register an on-premises instance

To assign permissions (CLI)

1. Create a file with the following policy contents on the Amazon EC2 instance or device you are using to call the AWS CLI. Name the file something like CodeDeploy-OnPrem-Permissions.json, and then save the file.

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Action": [
                   "s3:Get*",
                   "s3:List*"
               ],
               "Effect": "Allow",
               "Resource": "*"
           }
       ]
   }

   Note

   We recommend that you restrict this policy to only those Amazon S3 buckets your on-premises instance needs to access. If you restrict this policy, make sure to also give access to the Amazon S3 buckets that contain the AWS CodeDeploy agent. Otherwise, an error might occur whenever the CodeDeploy agent is installed or updated on the associated on-premises instance.

   For example:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:Get*",
           "s3:List*"
         ],
         "Resource": [
           "arn:aws:s3:::amzn-s3-demo-bucket/*",
           "arn:aws:s3:::aws-codedeploy-us-east-2/*",
           "arn:aws:s3:::aws-codedeploy-us-east-1/*",
           "arn:aws:s3:::aws-codedeploy-us-west-1/*",
           "arn:aws:s3:::aws-codedeploy-us-west-2/*",
           "arn:aws:s3:::aws-codedeploy-ca-central-1/*",
           "arn:aws:s3:::aws-codedeploy-eu-west-1/*",
           "arn:aws:s3:::aws-codedeploy-eu-west-2/*",
           "arn:aws:s3:::aws-codedeploy-eu-west-3/*",
           "arn:aws:s3:::aws-codedeploy-eu-central-1/*",
           "arn:aws:s3:::aws-codedeploy-eu-central-2/*",
           "arn:aws:s3:::aws-codedeploy-eu-north-1/*",
           "arn:aws:s3:::aws-codedeploy-eu-south-1/*",
           "arn:aws:s3:::aws-codedeploy-eu-south-2/*",
           "arn:aws:s3:::aws-codedeploy-il-central-1/*",
           "arn:aws:s3:::aws-codedeploy-ap-east-1/*",
           "arn:aws:s3:::aws-codedeploy-ap-northeast-1/*",
           "arn:aws:s3:::aws-codedeploy-ap-northeast-2/*",
           "arn:aws:s3:::aws-codedeploy-ap-northeast-3/*",
           "arn:aws:s3:::aws-codedeploy-ap-southeast-1/*",        
           "arn:aws:s3:::aws-codedeploy-ap-southeast-2/*",
           "arn:aws:s3:::aws-codedeploy-ap-southeast-3/*",
           "arn:aws:s3:::aws-codedeploy-ap-southeast-4/*",
           "arn:aws:s3:::aws-codedeploy-ap-south-1/*",
           "arn:aws:s3:::aws-codedeploy-ap-south-2/*",
           "arn:aws:s3:::aws-codedeploy-me-central-1/*",
           "arn:aws:s3:::aws-codedeploy-me-south-1/*",
           "arn:aws:s3:::aws-codedeploy-sa-east-1/*"
         ]
       }
     ]
   }

2. Call the put-user-policy command, specifying the name of the IAM user (with the --user-name option), a name for the policy (with the --policy-name option), and the path to the newly created policy document (with the --policy-document option). For example, assuming that the CodeDeploy-OnPrem-Permissions.json file is in the same directory (folder) from which you're calling this command:

   Important

   Be sure to include file:// before the file name. It is required in this command.

   aws iam put-user-policy --user-name CodeDeployUser-OnPrem --policy-name CodeDeploy-OnPrem-Permissions --policy-document file://CodeDeploy-OnPrem-Permissions.json

To assign permissions (console)

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

2. In the navigation pane, choose Policies, and then choose Create Policy. (If a Get Started button appears, choose it, and then choose Create Policy.)

3. Next to Create Your Own Policy, choose Select.

4. In the Policy Name box, type a name for this policy (for example, CodeDeploy-OnPrem-Permissions).

5. In the Policy Document box, type or paste the following permissions expression, which allows AWS CodeDeploy to deploy application revisions from any Amazon S3 bucket specified in the policy to the on-premises instance on behalf of the IAM user:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Action": [
                   "s3:Get*",
                   "s3:List*"
               ],
               "Effect": "Allow",
               "Resource": "*"
           }
       ]
   }

6. Choose Create Policy.

7. In the navigation pane, choose Users.

8. In the list of users, browse to and choose the name of the IAM user you created in Step 1: Create an IAM user for the on-premises instance.

9. On the Permissions tab, in Managed Policies, choose Attach Policy.

10. Select the policy named CodeDeploy-OnPrem-Permissions, and then choose Attach Policy.

To get the credentials (CLI)

1. Call the list-access-keys command, specifying the name of the IAM user (with the --user-name option) and querying for just the access key IDs (with the --query and --output options). For example:

   aws iam list-access-keys --user-name CodeDeployUser-OnPrem --query "AccessKeyMetadata[*].AccessKeyId" --output text

2. If no keys appear in the output or information about only one key appears in the output, call the create-access-key command, specifying the name of the IAM user (with the --user-name option):

   aws iam create-access-key --user-name CodeDeployUser-OnPrem

   In the output of the call to the create-access-key command, note the value of the AccessKeyId and SecretAccessKey fields. You will need this information in Step 4: Add a configuration file to the on-premises instance.

   Important

   This will be the only time you will have access to this secret access key. If you forget or lose access to this secret access key, you will need to generate a new one by following the steps in Step 3: Get the IAM user credentials.

3. If two access keys are already listed, you must delete one of them by calling the delete-access-key command, specifying the name of the IAM user (with the --user-name option), and the ID of the access key to delete (with the --access-key-id option). Then call the create-access-key command, as described earlier in this step. Here's an example of calling the delete-access-key command:

   aws iam delete-access-key --user-name CodeDeployUser-OnPrem --access-key-id access-key-ID

   Important

   If you call the delete-access-key command to delete one of these access keys, and an on-premises instance is already using this access key as described in Step 4: Add a configuration file to the on-premises instance, you will need to follow the instructions in Step 4: Add a configuration file to the on-premises instance again to specify a different access key ID and secret access key associated with this IAM user. Otherwise, any deployments to that on-premises instance might be stuck in a perpetual pending state or fail altogether.

To get the credentials (console)

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

   2. If the list of users is not displayed, in the navigation pane, choose Users.

   3. In the list of users, browse to and choose the name of the IAM user you created in Step 1: Create an IAM user for the on-premises instance.

2. On the Security credentials tab, if no keys or only one key is listed, choose Create access key.

   If two access keys are listed, you must delete one of them. Choose Delete next to one of the access keys, and then choose Create access key.

   Important

   If you choose Delete next to one of these access keys, and an on-premises instance is already using this access key as described in Step 4: Add a configuration file to the on-premises instance, you will need to follow the instructions in Step 4: Add a configuration file to the on-premises instance again to specify a different access key ID and secret access key associated with this IAM user. Otherwise, deployments to that on-premises instance might be stuck in a perpetual pending state or fail altogether.

3. Choose Show and note the access key ID and secret access key. You will need this information for the next step. Alternatively, you can choose Download .csv file to save a copy of the access key ID and the secret access key.

   Important

   Unless you make a note of or download the credentials, this will be the only time you will have access to this secret access key. If you forget or lose access to this secret access key, you will need to generate a new one by following the steps in Step 3: Get the IAM user credentials.

4. Choose Close to return to the Users > IAM User Name page.

1. Create a file named codedeploy.onpremises.yml (for an Ubuntu Server or RHEL on-premises instance) or conf.onpremises.yml (for a Windows Server on-premises instance) in the following location on the on-premises instance:

   • For Ubuntu Server: /etc/codedeploy-agent/conf

   • For Windows Server: C:\ProgramData\Amazon\CodeDeploy

2. Use a text editor to add the following information to the newly created codedeploy.onpremises.yml or conf.onpremises.yml file:

   ---
   aws_access_key_id: secret-key-id
   aws_secret_access_key: secret-access-key
   iam_user_arn: iam-user-arn
   region: supported-region

   Where:

   • secret-key-id is the corresponding IAM user's secret key ID you noted in Step 1: Create an IAM user for the on-premises instance or Step 3: Get the IAM user credentials.

   • secret-access-key is the corresponding IAM user's secret access key you noted in Step 1: Create an IAM user for the on-premises instance or Step 3: Get the IAM user credentials.

   • iam-user-arn is the IAM user's ARN you noted earlier in Step 1: Create an IAM user for the on-premises instance.

   • supported-region is the identifier of a region supported by CodeDeploy where your CodeDeploy applications, deployment groups, and application revisions are located (for example, us-west-2). For a list of regions, see Region and endpoints in the AWS General Reference.

   Important

   If you chose Delete next to one of the access keys in Step 3: Get the IAM user credentials, and your on-premises instance is already using the associated access key ID and secret access key, you will need to follow the instructions in Step 4: Add a configuration file to the on-premises instance to specify a different access key ID and secret access key associated with this IAM user. Otherwise, any deployments to your on-premises instance might be stuck in a perpetual pending state or fail altogether.

1. To install the AWS CLI on the on-premises instance, follow the instructions in Getting set up with the AWS CLI in the AWS Command Line Interface User Guide.

   Note

   CodeDeploy commands for working with on-premises instances became available in version 1.7.19 of the AWS CLI. If you have a version of the AWS CLI already installed, you can check its version by calling aws --version.

2. To configure the AWS CLI on the on-premises instance, follow the instructions in Configuring the AWS CLI in the AWS Command Line Interface User Guide.

   Important

   As you configure the AWS CLI (for example, by calling the aws configure command), be sure to specify the secret key ID and secret access key of an IAM user that has, at minimum, the following AWS access permissions in addition to the access permissions specified in the Prerequisites for configuring an on-premises instance. This makes it possible for you to download and install the CodeDeploy agent on the on-premises instance:

   {
     "Version": "2012-10-17",
     "Statement" : [
       {
         "Effect" : "Allow",
         "Action" : [
           "codedeploy:*"
         ],
         "Resource" : "*"
       },
       {
         "Effect" : "Allow",
         "Action" : [
           "s3:Get*",
           "s3:List*"
         ],
         "Resource" : [
           "arn:aws:s3:::aws-codedeploy-us-east-2/*",
           "arn:aws:s3:::aws-codedeploy-us-east-1/*",
           "arn:aws:s3:::aws-codedeploy-us-west-1/*",
           "arn:aws:s3:::aws-codedeploy-us-west-2/*",
           "arn:aws:s3:::aws-codedeploy-ca-central-1/*",
           "arn:aws:s3:::aws-codedeploy-eu-west-1/*",
           "arn:aws:s3:::aws-codedeploy-eu-west-2/*",
           "arn:aws:s3:::aws-codedeploy-eu-west-3/*",
           "arn:aws:s3:::aws-codedeploy-eu-central-1/*",
           "arn:aws:s3:::aws-codedeploy-il-central-1/*",
           "arn:aws:s3:::aws-codedeploy-ap-east-1/*",
           "arn:aws:s3:::aws-codedeploy-ap-northeast-1/*",
           "arn:aws:s3:::aws-codedeploy-ap-northeast-2/*",
           "arn:aws:s3:::aws-codedeploy-ap-southeast-1/*",
           "arn:aws:s3:::aws-codedeploy-ap-southeast-2/*",
           "arn:aws:s3:::aws-codedeploy-ap-southeast-4/*",
           "arn:aws:s3:::aws-codedeploy-ap-south-1/*",
           "arn:aws:s3:::aws-codedeploy-sa-east-1/*"
         ]
       }     
     ]
   }

   These access permissions can be assigned to either the IAM user you created in Step 1: Create an IAM user for the on-premises instance or to a different IAM user. To assign these permissions to an IAM user, follow the instructions in Step 1: Create an IAM user for the on-premises instance, using these access permissions instead of the ones in that step.

1. Before you can use the AWS CLI, you will need the user ARN of the IAM user you created in Step 1: Create an IAM user for the on-premises instance. If you don't already have the user ARN, call the get-user command, specifying the name of the IAM user (with the --user-name option) and querying for just the user ARN (with the --query and --output options):

   aws iam get-user --user-name CodeDeployUser-OnPrem --query "User.Arn" --output text

2. Call the register-on-premises-instance command, specifying:

   • A name that uniquely identifies the on-premises instance (with the --instance-name option).

     Important

     To help identify the on-premises instance, especially for debugging purposes, we strongly recommend that you specify a name that maps to some unique characteristic of the on-premises instance (for example, the serial number or an internal asset identifier, if applicable). If you specify a MAC address as a name, be aware that MAC addresses contain characters that CodeDeploy does not allow, such as colon (:). For a list of allowed characters, see CodeDeploy quotas.

   • The user ARN of the IAM user you created in Step 1: Create an IAM user for the on-premises instance (with the --iam-user-arn option).

     For example:

     aws deploy register-on-premises-instance --instance-name AssetTag12010298EX --iam-user-arn arn:aws:iam::444455556666:user/CodeDeployUser-OnPrem

To tag the on-premises instance (CLI)

• Call the add-tags-to-on-premises-instances command, specifying:

  • The name that uniquely identifies the on-premises instance (with the --instance-names option).

  • The name of the on-premises instance tag key and tag value you want to use (with the --tags option). You must specify both a name and value. CodeDeploy does not allow on-premises instance tags that have values only.

    For example:

    aws deploy add-tags-to-on-premises-instances --instance-names AssetTag12010298EX --tags Key=Name,Value=CodeDeployDemo-OnPrem

To tag the on-premises instance (console)

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

   Note

   Sign in with the same user that you set up in Getting started with CodeDeploy.

2. From the CodeDeploy menu, choose On-premises instances.

3. In the list of on-premises instances, choose the arrow next to the on-premises instance you want to tag.

4. In the list of tags, select or enter the desired tag key and tag value. After you enter the tag key and tag value, another row appears. You can repeat this for up to 10 tags. To remove a tag, choose the delete icon ( ).

5. After you have added tags, choose Update Tags.