Walkthrough: Register an Instance from Your Workstation - AWS OpsWorks
Step 1: Create a Stack and an InstanceStep 2: Install and Configure the AWS CLIStep 3: Register the Instance with the EC2Register Stack

Walkthrough: Register an Instance from Your Workstation

Important

AWS OpsWorks Stacks is no longer accepting new customers. Existing customers will be able to use the OpsWorks console, API, CLI, and CloudFormation resources as normal until May 26, 2024, at which time they will be discontinued. To prepare for this transition, we recommend you transition your stacks to AWS Systems Manager as soon as possible. For more information, see AWS OpsWorks Stacks End of Life FAQs and Migrating your AWS OpsWorks Stacks applications to AWS Systems Manager Application Manager.

Note

This feature is supported only for Linux stacks.

The registration process supports several scenarios. This section walks you through an end-to-end example of one scenario: how to use your workstation to register an Amazon EC2 instance. Other registration scenarios use a similar procedure. For more information, see Registering Amazon EC2 and On-premises Instances.

Note

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

Registration is performed by using the AWS CLI aws opsworks register command. Before you register your first instance, you must be running version 1.16.180 of the AWS CLI or newer. The installation details depend on your workstation's operating system. For more information about installing the AWS CLI, see Installing the AWS Command Line Interface. To check the version of the AWS CLI that you are running, enter aws --version in a shell session.

Note

To prevent users or roles from registering instances, update the instance profile to deny access to the register command.

We strongly recommend that you do not skip this step, even if you are already running the AWS CLI on your workstation. Using the most current release of the AWS CLI is a security best practice.

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 user with appropriate permissions, installing the user's credentials on the workstation, and then passing those credentials to register.

Warning

IAM users have long-term credentials, which presents a security risk. To help mitigate this risk, we recommend that you provide these users with only the permissions they require to perform the task and that you remove these users when they are no longer needed.

To create the user

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

  2. Add a user named EC2Register.

  3. Choose Next.

  4. On the Set permissions page, choose Attach policies directly.

  5. Enter OpsWorks in the Permissions policy filter box to display the AWS OpsWorks policies, select one of the following policies, and then choose Next: review. The policy grants your user the permissions that are required to run register.

    • Choose AWSOpsWorksRegisterCLI_EC2 to allow the user permissions to register EC2 instances that use instance profiles.

    • Choose AWSOpsWorksRegisterCLI_OnPremises to allow the user permissions to register on-premises instances.

  6. Choose Next.

  7. On the Review page, choose Create user.

  8. Now create access keys for your user. From the navigation pane, choose Users, and then choose the user you want to create access keys for.

  9. Choose the Security credentials tab, then choose Create access key.

  10. Choose the Access key best practices & alternatives that best corresponds to your task.

  11. Choose Next.

  12. (Optionally) enter a tag to identify the access keys.

  13. Choose Next.

  14. Choose Download .csv file, save the credentials file to a convenient location on your system, and choose Done.

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
    Note

    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.

    Important

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