AWS OpsWorks
User Guide (API Version 2013-02-18)

Walkthrough: Register an Instance from Your Workstation


This feature is supported only for Linux stacks.

The registration process is designed to support a variety of scenarios. This section gets you started by walking you through an end-to-end example of one of those scenarios, how use your workstation to register an Amazon EC2 instance. The other registration scenarios use a similar procedure. For more information, see Registering Amazon EC2 and On-premises Instances.


You typically want to register an existing Amazon EC2 instance. However, you can just create a new instance and a new stack for the walkthrough and delete them when you are finished.

Step 1: Create a Stack and an Instance

To get started, you need a stack and an Amazon EC2 instance to be registered with that stack.

To create the stack and instance

  1. Use the AWS OpsWorks Stacks console to create a new stack named EC2Register. You can accept default values for the other stack settings.

  2. Launch a new instance from the Amazon EC2 console. Note the following.

    • The instance must in the same region and VPC as the stack.

      If you are using a VPC, pick a public subnet for this walkthrough.

    • If you need to create an SSH key, save the private key file to your workstation and record the name and file location.

      If you use an existing key, record the name and private key file location. You need those values later.

    • The instance must be based on one of the supported Linux operating systems. For example, if your stack is in US West (Oregon), you can use ami-35501205 to launch a Ubuntu 14.04 LTS instance in that region.

    Otherwise, accept the default values.

While the instance is booting, you can proceed to the next section.

Step 2: Install and Configure the AWS CLI

The key part of the registration process is handled by the aws opsworks register AWS CLI command. Before you register your first instance, install a current version of the AWS CLI or update your existing version. The installation details depend on your workstation's operating system. See Installing the AWS Command Line Interface for installation steps.

You must provide register with a set of AWS credentials that have appropriate permissions. The recommended way to do this—so that you avoid installing credentials directly on an instance—is to register instances that are launched with an instance profile, and then add the --use-instance-profile switch to your register command. If you are getting credentials from an instance profile, skip to Step 3: Register the Instance with the EC2Register Stack in this topic. However, if your instance was not launched with an instance profile, you can create an IAM user. The following procedure creates a new IAM user with appropriate permissions, installing the user's credentials on the workstation, and then passing those credentials to register.

To create the IAM User

  1. On the IAM console, choose Users in the navigation pane, and then choose Add user.

  2. Add a user named EC2Register. In the Select AWS access type area, select Programmatic access, and then choose Next: Permissions.

  3. On the Set permissions page, choose Attach existing policies directly.

  4. Enter OpsWorks in the Policy type filter box to display the AWS OpsWorks policies, select AWSOpsWorksRegisterCLI, and then choose Next: review. This policy grants your user the permissions that are required to run register.

                                Adding the AWSOpsWorksRegisterCLI policy
  5. On the Review page, choose Create user.

  6. Choose Download .csv, save the credentials file to a convenient location on your system, and then choose Close.

You need to provide the IAM user's credentials to register. This walkthrough handles the task by installing the EC2Register credentials in your workstation's credentials file. For information about other ways to manage credentials for the AWS CLI, see Configuration and Credential Files.

To install the user's credentials

  1. Create or open your workstation's credentials file. The file is located at ~/.aws/credentials (Linux, Unix, and OS X) or C:\Users\User_Name\.aws\credentials (Windows systems).

  2. Add a profile for the EC2Register user to the credentials file, using the following format.

    [ec2register] aws_access_key_id = access_key_id aws_secret_access_key = secret_access_key

    Replace access_key_id and secret_access_key with the EC2Register keys for that you downloaded earlier.

Step 3: Register the Instance with the EC2Register Stack

You are now ready to register the instance.

To register the instance

  1. In AWS OpsWorks Stacks, return to the EC2Register stack, choose Instances in the navigation pane, and then choose Register an instance.

  2. Select EC2 Instances, choose Next: Select Instances, and select your instance from the list.

  3. Choose Next: Install AWS CLI, and Next: Register Instances. AWS OpsWorks Stacks automatically uses the available information, such as the stack ID and the instance ID to create a register command template, which is displayed on the Register Instances page. For this example, you use register to log in to the instance with an SSH key and explicitly specify the key file, so set I use SSH keys to connect to my instances to Yes. The command template resembles the following.

    aws opsworks register --infrastructure-class ec2 --region region endpoint ID --stack-id 247be7ea-3551-4177-9524-1ff804f453e3 --ssh-username [username] --ssh-private-key [key-file] i-f1245d10


    You must set the region to the AWS OpsWorks Stacks service's endpoint region, not the stack's region, if the stack is within a classic region associated with the us-east-1 regional endpoint. AWS OpsWorks Stacks determines the stack's region from the stack ID.

  4. The command template contains several user-specific argument values, which are indicated by brackets and must be replaced with appropriate values. Copy the command template to a text editor and edit it as follows.


    The IAM user that is created during the registration process is required throughout the life of a registered instance. Deleting the user causes the AWS OpsWorks Stacks agent to be unable to communicate with the service. To help prevent problems managing registered instances in the event that the IAM user is accidentally deleted, add the --use-instance-profile parameter to your register command to use the instance's built-in instance profile instead. Adding the --use-instance-profile parameter also prevents errors from occurring when you rotate AWS account access keys every 90 days (a recommended best practice), because it prevents mismatches between the access keys available to the AWS OpsWorks agent and required IAM user.

    • Replace key file with the fully qualified path of the private key file for the Amazon EC2 key pair that you saved when you created the instance.

      You can use a relative path, if you prefer.

    • Replace username with the instance's user name.

      For this example, the user name is either ubuntu, for an Ubuntu instance, or ec2-user, for a Red Hat Enterprise Linux (RHEL) or Amazon Linux instance.

    • Add --use-instance-profile, which runs register with the instance profile to prevent errors during key rotation or if the principal IAM user is accidentally deleted.

    Your command should resemble the following.

    aws opsworks register --use-instance-profile --infrastructure-class ec2 \ --region us-west-2 --stack-id 247be7ea-3551-4177-9524-1ff804f453e3 --ssh-username ubuntu \ --ssh-private-key "./keys/mykeys.pem" i-f1245d10
  5. Open a terminal window on your workstation, paste the register command from your editor, and run the command.

    Registration typically takes around five minutes. When it is complete, return to the AWS OpsWorks Stacks console and choose Done. Then choose Instances in the navigation pane. Your instance should be listed under Unassigned Instances. You can then assign the instance to a layer or leave it where it is, depending on how you intend to manage the instance.

  6. When you are finished, stop the instance and then delete it by using the AWS OpsWorks Stacks console or commands. This terminates the Amazon EC2 instance, so you don't incur any further charges.