12 AWS opsworks-cm server CLI Examples to Manage Chef or Puppet OpsWorks Server

by Ramesh Natarajan on March 26, 2019

In your AWS environment, for configuration management, you can use AWS OpsWorks which provides managed instances of either Chef or Puppet. You have the following three options when using AWS OpsWorks.

AWS Opsworks for Chef Automate
AWS OpsWorks for Puppet Enterprise
AWS OpsWorks Stacks – This is for application modeling and management. You can model your app as a stack with different layers (e.g: web layer, db layer, etc.). This uses Chef solo in the backend to configure nodes.

This tutorial provides the following examples on how you can manage your AWS OpsWorks servers from CLI using aws opsworks-cm command.

Create OpsWorks Server (Chef or Puppet) using create-server
View OpsWorks Server Details using describe-servers
Delete an OpsWorks Server using delete-server
View Account Attributes and Server Events of a Server
Update Server Maintenance and Backup Window using update-server
Disable or Enable Automated Backups
Specify Backup Retention Count
Reset Chef Server’s Private Key (or) Update Puppet Admin Password
Take a Backup of OpsWorks Server using backup-server
View Available Backups using describe-backups
Delete an OpsWorks Backup using delete-backup
Restore OpsWorks Server from a Backup using restore-server

1. Create OpsWorks Server (Chef or Puppet) using create-server

First, create an instance profile and service role that is required during OpsWorks server creation from CLI.

For this, use this OpsWorks CM Role CFN template to create the required Role and Instance Profile. Once created, use the ARN in the following variable, which we’ll use on aws create-server CLI.

OPS_IP_ARN=arn:aws:iam::111111111111:instance-profile/OpsWorksCMRoles-InstanceProfile
OPS_SR_ARN=arn:aws:iam::111111111111:role/service-role/aws-opsworks-cm-service-role

The following command creates a AWS OpsWorks Server. In this example, we are using “Chef” as the engine.

OPS_NAME=optimusprime

aws opsworks-cm create-server --engine "Chef" \
  --engine-model "Single" --engine-version "12" \
  --server-name $OPS_NAME --instance-profile-arn $OPS_IP_ARN \
  --instance-type "m4.large" --key-pair "my-key-pair" \
  --preferred-maintenance-window "Mon:08:00" \
  --preferred-backup-window "Sun:02:00" \
  --service-role-arn $OPS_SR_ARN \
  --subnet-ids $OPS_SUBNET_ID  > /var/tmp/$OPS_NAME.json

In the above:

aws opsworks-cm create-server – CLI Command to create server
–engine “Chef” – Here we are creating Chef server. You can also specify “Puppet” here.
–engine-model “Single” – For chef it’s Single. For Puppet it’s Monolithic.
–engine-version “12” – This specifies the Chef’s engine version. If you are using Puppet, specify 2017
–server-name $OPS_NAME – Name of the server. In this example, it’s “optimusprime”
–instance-profile-arn $OPS_IP_ARN – Instance profile ARN that was created using the CFN template mentioned above
–instance-type “m4.large” – Specify the instance type for your engine
–key-pair “my-key-pair” – Your EC2 keypair
–service-role-arn $OPS_SR_ARN – ARN of the service role that you created above
-subnet-ids $OPS_SUBNET_ID – The subnet where you like to deploy the OpsWorks server

Partial output of the above command is shown below:

# cat /var/tmp/optimusprime.json
{
    "Server": {
        "Engine": "Chef",
        "PreferredBackupWindow": "Sun:02:00",
        "Status": "CREATING",
        "Endpoint": "optimusprime-abcdefghijklmn.us-east-1.opsworks-cm.io",
        "SubnetIds": [
            "subnet-12345678"
        ],
        "DisableAutomatedBackup": false,
        "PreferredMaintenanceWindow": "Mon:08:00",
        "ServerName": "optimusprime",
        "BackupRetentionCount": 10,
        "InstanceType": "m4.large",
        ..
        ..

2. View OpsWorks Server Details using describe-servers

Once a server is created, you can use the following describe-server command to view the details.

OPS_NAME=optimusprime

aws opsworks-cm describe-servers --server-name $OPS_NAME

If you like to just view the status and the endpoint of your OpsWork, use jq to filter-out as shown below.

aws opsworks-cm describe-servers --server-name $OPS_NAME > /var/tmp/ops-server.json

OPS_STATUS=`cat /var/tmp/ops-server.json | jq -r .Servers[].Status`

OPS_ENDPOINT=`cat /var/tmp/ops-server.json | jq -r .Servers[].Endpoint`

echo $OPS_STATUS
echo $OPS_ENDPOINT

The following is an example full output of the describe-server command.

# aws opsworks-cm describe-servers --server-name $OPS_NAME
{
    "Servers": [
        {
            "Engine": "Chef",
            "PreferredBackupWindow": "Sun:02:00",
            "Status": "CREATING",
            "CloudFormationStackArn": "arn:aws:cloudformation:us-east-1:111111111111:stack/aws-opsworks-cm-instance-optimusprime/abcde-fgh-ijklmn",
            "SubnetIds": [
                "subnet-123456789"
            ],
            "DisableAutomatedBackup": false,
            "PreferredMaintenanceWindow": "Mon:08:00",
            "ServerArn": "arn:aws:opsworks-cm:us-east-1:111111111111:server/optimusprime/abcdef-ghijk-lmnop",
            "ServerName": "optimusprime",
            "BackupRetentionCount": 10,
            "InstanceType": "m4.large",
            "KeyPair": "my-key-pair",
            "ServiceRoleArn": "arn:aws:iam::111111111111:role/service-role/aws-opsworks-cm-service-role",
            "EngineModel": "Single",
            "Endpoint": "optimusprime-abcdef.us-east-1.opsworks-cm.io",
            "AssociatePublicIpAddress": true,
            "SecurityGroupIds": [
                "sg-12345"
            ],
            "EngineVersion": "12.17.33",
            "InstanceProfileArn": "arn:aws:iam::111111111111:instance-profile/OpsWorksCMRoles-InstanceProfile-ABCDEF",
            "EngineAttributes": [],
            "CreatedAt": 12345.183
        }
    ]
}

3. Delete an OpsWorks Server using delete-server

The following command deletes the OpsWorks server. All you have specify is the server-name as shown below.

OPS_NAME=optimusprime

aws opsworks-cm delete-server --server-name $OPS_NAME

Note: As you can imagine, once you execute the above command, your OpsWorks server will be deleted. So, don’t execute this command on your production server.

While the server is getting deleted, if you try to describe-server, you’ll see the status says “DELETING”

# aws opsworks-cm describe-servers --server-name $OPS_NAME
{
    "Servers": [
        {
            "ServerArn": "arn:aws:opsworks-cm:us-east-1:111111111111:server/optimusprime/12345",
            "EngineAttributes": [],
            "EngineModel": "Single",
            "Engine": "Chef",
            ..
            "StatusReason": "Client.UserInitiated",
            "Status": "DELETING",
            ..

4. View Account Attributes and Server Events of a Server

The following displays only the account attributes of the server. Apart from giving the details on the Maximum value, it will also display how many of that is currently Used. This is helpful when you want to increase the limit.

The following is a sample output that shows the ServerLimit and the ManualBackupLimit.

# aws opsworks-cm describe-account-attributes
{
    "Attributes": [
        {
            "Name": "ServerLimit",
            "Maximum": 5
        },
        {
            "Name": "ManualBackupLimit",
            "Maximum": 10
        }
    ]
}

You can view server events using describe-events. The following command will display all the events related to your OpsWorks Server.

# aws opsworks-cm describe-events --server-name $OPS_NAME
{
    "ServerEvents": [
        {
            "ServerName": "optimusprime",
            "Message": "Successfully launched Server optimusprime",
            "CreatedAt": 1234567890.582
        },
        {
            "ServerName": "optimusprime",
            "Message": "Created DNS optimusprime-abcdef.us-east-1.opsworks-cm.io",
            "CreatedAt": 1234567890.572
        },
        ..
        ..
    ]
}

5. Update Server Maintenance and Backup Window using update-server

Available time format options for the following commands:

DDD:HH:MM (weekly start time) or HH:MM (daily start time).
DDD in the above is for valid day of the week are: Mon , Tue , Wed , Thr , Fri , Sat , or Sun
Time window uses UTC.

As you see from the following output, the current preferred maintenance window is Monday at 8:00 a..m

# aws opsworks-cm describe-servers --server-name $OPS_NAME | jq -r .Servers[].PreferredMaintenanceWindow
Mon:08:00

You can change the maintenance window to Sunday at 11 p.m (23:00) using the following update-server command.

# aws opsworks-cm update-server --server-name $OPS_NAME --preferred-maintenance-window "Sun:23:00"

You can change the backup window to Saturday at 1 p.m (13:00) using the following update-server command.

# aws opsworks-cm update-server --server-name $OPS_NAME --preferred-backup-window "Sat:13:00"
{
    "Server": {
        "Engine": "Chef",
        "PreferredBackupWindow": "Sat:13:00",
        "Status": "HEALTHY",
...

6. Disable or Enable Automated Backups

By default automated backups of your server is enabled.

You can disable automated or scheduled backups by setting DisableAutomatedBackup to true using the update-server command with –disable-automated-backup option as shown below.

# aws opsworks-cm describe-servers --server-name $OPS_NAME | jq -r .Servers[].DisableAutomatedBackup
false

# aws opsworks-cm update-server --server-name $OPS_NAME --disable-automated-backup

By mistake, if you’ve disabled automated backup and like to enable it again, use the –no-disable-automated-backup option as shown below.

aws opsworks-cm update-server --server-name $OPS_NAME --no-disable-automated-backup

7. Specify Backup Retention Count

Sets the number of automated backups that you want to keep.

Using the –backup-retention-count in the update-server you can specify how many automated backups you like to keep. The following sets the value to 5, which will always keep 5 last automated backups for you.

aws opsworks-cm update-server --server-name $OPS_NAME --backup-retention-count 5

8. Reset Chef Server’s Private Key (or) Update Puppet Admin Password

Using update-server-engine-attributes option, you can either reset CHEF_PIVOTAL_KEY or PUPPET_ADMIN_PASSWORD.

The following example shows how to reset chef server’s private key.

The current key can be found from the describe-server output as shown below.

echo -n "Chef Pivotal Key: "

cat /var/tmp/$OPS_NAME.json | jq -r '.Server.EngineAttributes[] | select(.Name == "CHEF_PIVOTAL_KEY") | .Value'

To create a new custom key, use openssl genrsa as shown below.

# umask 077

# openssl genrsa -out "pivotal" 2048
Generating RSA private key, 2048 bit long modulus
....+++
e is 65537 (0x10001)

# openssl rsa -in "pivotal" -pubout
writing RSA key
-----BEGIN PUBLIC KEY-----
ABCDEFline1
ABCDEFline2
ABCDEFline3
ABCDEFline4
ABCDEFline5
ABCDEFline6
ABCDEFline7
-----END PUBLIC KEY-----

Now, use the update-server-engine-attributes option to change the CHEF_PIVOTAL_KEY key as shown below.

aws opsworks-cm update-server-engine-attributes \
--attribute-name CHEF_PIVOTAL_KEY \
--attribute-value "-----BEGIN PUBLIC KEY-----\nABCDEFline1\nABCDEFline2\nABCDEFline3\nABCDEFline4\nABCDEFline5\nABCDEFline6\nABCDEFline7\n-----END PUBLIC KEY-----\n" \
--server-name $OPS_NAME

Note: While giving the multiline key information value for the –atribute-value, make sure to add “\n” after each and every line as shown in the above example. Don’t forget to include the BEGIN and END line also.

9. Take a Backup of OpsWorks Server using backup-server

Creates an application-level backup of a server. While the server is in the BACKING_UP state, the server cannot be changed, and no additional backup can be created.

Backups can be created for servers in RUNNING , HEALTHY , and UNHEALTHY states. By default, you can create a maximum of 50 manual backups.

The following create-backup option takes a backup of your OpsWorks server. By default you can take a maximum of 50 manual backups.

# OPS_NAME=optimusprime

# aws opsworks-cm create-backup --server-name $OPS_NAME --description "Initial Gold Backup after Install"
{
    "Backup": {
        "Engine": "Chef",
        "PreferredBackupWindow": "Sun:02:00",
        "Status": "IN_PROGRESS",
        "ToolsVersion": "5007",
        "Description": "Initial Gold Backup after Install",
        "PreferredMaintenanceWindow": "Mon:08:00",
        "ServerName": "optimusprime",
        "SecurityGroupIds": [
            "sg-12345"
        ],
        "BackupType": "MANUAL",
        "ServiceRoleArn": "arn:aws:iam::111111111111:role/service-role/aws-opsworks-cm-service-role",
        "KeyPair": "my-key-pair",
        "EngineModel": "Single",
        "EngineVersion": "12.17.33",
        "SubnetIds": [
            "subnet-12345"
        ],
        "BackupId": "optimusprime-2019-03-10T16:22:42.981Z",
        "BackupArn": "arn:aws:opsworks-cm:us-east-1:111111111111:backup/optimusprime-2019-03-10T16:22:42.981Z",
        "InstanceProfileArn": "arn:aws:iam::111111111111:instance-profile/OpsWorksCMRoles-InstanceProfile-ABCDEF",
        "InstanceType": "m4.large",
        "CreatedAt": 123456.981,
        "UserArn": "arn:aws:iam::111111111111:user/ramesh"
    }
}

10. View Available Backups using describe-backups

All available OpsWorks backup can be listed using the describe-backups command as shown below.

# aws opsworks-cm describe-backups
{
    "Backups": [
        {
            "Engine": "Chef",
            "PreferredBackupWindow": "Sun:02:00",
            "Status": "OK",
            "ToolsVersion": "5007",
            "Description": "Initial Gold Backup after Install",
            "PreferredMaintenanceWindow": "Mon:08:00",

            "BackupType": "MANUAL",
            "BackupId": "optimusprime-2019-03-10T16:22:42.981Z",
            "BackupArn": "arn:aws:opsworks-cm:us-east-1:111111111111:backup/optimusprime-2019-03-10T16:22:42.981Z",
            ...
            ...

Note: Only partial output shown above.

If you want to view details of a specific backup, you can use the –backup-id as shown below.

aws opsworks-cm describe-backups --backup-id optimusprime-2019-03-10T16:22:42.981Z

11. Delete an OpsWorks Backup using delete-backup

The following delete-backup command deletes a manual or automated backup of a Chef Automate server, identified by the backup ID. This command is useful when you are approaching the maximum number of backups that you can save, or you want to minimize your Amazon S3 storage costs.:

If you have taken many manual backups, you may want to delete some of the oldest backup to keep the S3 storage cost down.

Use the delete-backup option to delete a specific backup using the backup-id as shown below.

aws opsworks-cm delete-backup --backup-id "optimusprime-2019-03-10T16:22:42.981Z"

When a backup is getting deleted, you’ll see the status as DELETING in the describe-backups command output.

# aws opsworks-cm describe-backups

{
    "Backups": [
        {
            "Engine": "Chef",
            "PreferredBackupWindow": "Sun:02:00",
            "Status": "DELETING",
            "BackupId": "optimusprime-2019-03-10T16:22:42.981Z",
            "BackupArn": "arn:aws:opsworks-cm:us-east-1:111111111111:backup/optimusprime-2019-03-10T16:22:42.981Z",
            ...
            ..

If you don’t have any backups, you’ll see the following output.

# aws opsworks-cm describe-backups --region $REGION
{
    "Backups": []
}

12. Restore OpsWorks Server from a Backup using restore-server

You can restore your current running OpsWorks server from a copy of your backup. When you restore, keep in mind that the current EC2 instance is terminated and a new EC2 instance is launched. But, your existing server endpoint will still remain the same. So, your configuration management client doesn’t have to change it’s configuration.

The following command will restore the server from the given backup-id.

aws opsworks-cm restore-server --backup-id optimusprime-2019-03-10T16:22:42.981Z --server-name $OPS_NAME

While the restore is running, you can check the status using describe-server as shown below.

# aws opsworks-cm describe-servers --server-name $OPS_NAME
{
    "Servers": [
        {
            "ServerArn": "arn:aws:opsworks-cm:us-east-1:111111111111:server/optimusprime/abcde-ghij-lkmn",
            "EngineAttributes": [],
            "EngineModel": "Single",
            "Engine": "Chef",
            ...
            "Status": "RESTORING",
            "Endpoint": "optimusprime-abcdefgh.us-east-1.opsworks-cm.io",
..

Add your comment