If you have not done so already, follow the steps in (Alternate) Use Berkshelf to Get Cookbooks from a Remote Source (p. 82) to ensure that your Berksfile or Policyfile.rb file references the Chef Client cookbook and installs the cookbook.
Step 3: Create Instances by Using an Unattended Association Script
Step 3: Create Instances by Using an Unattended Association Script
1. To create EC2 instances, you can copy the userdata script from the Starter Kit (p. 78) to the userdata section of EC2 instance instructions, Amazon EC2 Auto Scaling group launch configurations, or an AWS CloudFormation template. For more information about adding scripts to user data, see Running Commands on Your Linux Instance at Launch in the Amazon EC2 documentation.
This script runs the opsworks-cm API associate-node command to associate a new node with your Chef server.
By default, the name of the new registered node is the instance ID, but you can change the name by modifying the value of the NODE_NAME variable in the userdata script. Because changing the organization name in the Chef console UI is currently not possible, leave CHEF_ORGANIZATION set to default.
2. Follow the procedure in Launching an Instance in the EC2 documentation, with modifications here.
In the EC2 instance launch wizard, choose an Amazon Linux AMI.
3. On the Configure Instance Details page, select the role you created in Step 1: Create an IAM Role to Use as Your Instance Profile (p. 121), as your IAM role.
4. In the Advanced Details area, upload the userdata.sh script that you created earlier in this procedure.
5. No changes are needed on the Add Storage page. Go on to Add Tags.
6. On the Configure Security Group page, choose Add Rule, and then choose the type HTTP to open port numbers 443 and 80 for the Apache web server in this example.
7. Choose Review and Launch, and then choose Launch. When your new node starts, it applies the configurations specified by the recipes you have specified in the RUN_LIST parameter.
8. Optional: If you have added the nginx cookbook to your run list, when you open the webpage linked to the public DNS of your new node, you should see a website that is hosted by your nginx web server.
Other Methods of Automating Repeated Runs of chef-client
Although more difficult to achieve, and not recommended, you can run the script in this topic solely as part of standalone instance user data, use a AWS CloudFormation template to add it to new instance user data, configure a cron job to run the script regularly, or run chef-client within a service.
However, we recommend the Chef Client Cookbook method because there are some disadvantages with other automation techniques.
For a complete list of parameters you can provide to chef-client, see the Chef documentation.
Related Topics
The following AWS blog posts offer more information about automatically associating nodes with your Chef Automate server, by using Auto Scaling groups, or within multiple accounts.
• Using AWS OpsWorks for Chef Automate to Manage EC2 Instances with Auto Scaling
• OpsWorks for Chef Automate – Automatically Bootstrapping Nodes in Different Accounts
Remove nodes
Disassociate a Node from an AWS OpsWorks for Chef Automate Server
This section describes how to disassociate, or remove, a managed node from management by an AWS OpsWorks for Chef Automate server. This operation is performed on the command line; you cannot disassociate nodes in the AWS OpsWorks for Chef Automate management console. Currently, the AWS OpsWorks for Chef Automate API does not allow for batch removal of multiple nodes. The command in this section disassociates one node at a time.
We recommend that you disassociate nodes from a Chef server before you delete the server, so that the nodes continue to operate without trying to reconnect with the server. To do this, run the disassociate-node AWS CLI command.
To disassociate nodes
1. In the AWS CLI, run the following command to disassociate nodes. Node_name is the name of the node that you want to disassociate; for Amazon EC2 instances, this is the instance ID. Server_name is the name of the Chef server from which you want to disassociate the node.
--engine-attributes specifies your default CHEF_ORGANIZATION name. All three of these parameters are required.
The --region parameter is not required unless you want to disassociate a node from a Chef server that is not in your default region.
aws opsworks-cm --region Region_name disassociate-node --node-name Node_name --server-name Server_--server-name --engine-attributes "Name=CHEF_ORGANIZATION,Value='default'"
The following command is an example.
aws opsworks-cm region us-west-2 disassociate-node node-name i-0010zzz00d66zzz90 --server-name opsworkstest --engine-attributes "Name=CHEF_ORGANIZATION,Value='default'"
2. Wait until a response message indicates that the disassociation is finished.
After you successfully disassociate a node from an AWS OpsWorks for Chef Automate server, it might still be visible in the Chef Automate dashboard. By default, Chef enforces a retention period for node state information, and purges the node automatically after a few days. For more information about data retention management and the Chef Reaper tool, see Data Retention Management in the Chef documentation.
For more information about how to delete an AWS OpsWorks for Chef Automate server, see Delete an AWS OpsWorks for Chef Automate Server (p. 124).
Related Topics
The following AWS blog posts offer more information about automatically associating nodes with your Chef Automate server, by using Auto Scaling groups, or within multiple accounts.
• Using AWS OpsWorks for Chef Automate to Manage EC2 Instances with Auto Scaling
• OpsWorks for Chef Automate – Automatically Bootstrapping Nodes in Different Accounts
Delete a Chef Automate server
Delete an AWS OpsWorks for Chef Automate Server
This section describes how to delete an AWS OpsWorks for Chef Automate server. Deleting a server also deletes its events, logs, and any cookbooks that were stored on the server. Supporting resources (Amazon Elastic Compute Cloud instance, Amazon Elastic Block Store volume, etc.) are deleted also, along with all automated backups.
Although deleting a server does not delete nodes, they are no longer managed by the deleted server, and will continuously attempt to reconnect. For this reason, we recommend disassociating managed nodes before you delete a Chef server. In this release, you can disassociate nodes by running an AWS CLI command.
Step 1: Disassociate Managed Nodes
Disassociate nodes from the Chef server before you delete the server, so that the nodes continue to operate without trying to reconnect with the server. To do this, run the disassociate-node AWS CLI command.
To disassociate nodes
1. In the AWS CLI, run the following command to disassociate nodes. Server_name is the name of the Chef server from which you want to disassociate the node.
aws opsworks-cm --region Region_name disassociate-node --node-name Node_name --server-name Server_--server-name
2. Wait until a response message indicates that the disassociation is finished.
Step 2: Delete the Server
1. On the server’s tile on the dashboard, expand the Actions menu.
2. Choose Delete server.
3. When you are prompted to confirm the deletion, choose Yes.
Reset Chef Automate Dashboard Credentials
Periodically, you might want to change the password with which you sign in to the Chef Automate dashboard. You can also use the Amazon EC2 Systems Manager AWS CLI commands shown in this section to change the Chef Automate dashboard password if you have lost it. The command you use depends on whether your Chef Automate server is running version 1 or version 2 of Chef Automate.
1. To return the instance ID of your Chef server, open the AWS Management Console to the following page.
https://console.aws.amazon.com/ec2/v2/home?
region=region_of_your_server#Instances:search=aws-opsworks-cm-server_name
For example, for a Chef server named MyChefServer in the US West (Oregon) Region, the console URL would be the following.
Using AWS CloudTrail
https://console.aws.amazon.com/ec2/v2/home?region=us-west-2#Instances:search=aws-opsworks-cm-MyChefServer
Make a note of the instance ID that is displayed in the console; you will need it to change your password.
2. To reset the Chef Automate dashboard sign-in password, run one of the following AWS CLI commands, depending on whether your server is running Chef Automate 1 or Chef Automate 2.
Replace enterprise_name with your enterprise or organization name, user_name with the IAM user name of an administrator on the server, new_password with the password you want to use, andregion_name with the region in which your server is located. If you do not specify an enterprise name, the enterprise name will be default. By default, enterprise_name is default (this is the name of the organization that is always provisioned). For user_name, AWS OpsWorks for Chef Automate only creates a user named admin. Make a note of the new password, and store it in a safe but convenient location.
For Chef Automate 1:
aws ssm send-command --document-name "AWS-RunShellScript" --comment "reset admin password" --instance-ids "instance_id"
--parameters commands="sudo delivery-ctl
reset-password enterprise_name user_name new_reset-password" --region region_name --output text
For Chef Automate 2:
aws ssm send-command --document-name "AWS-RunShellScript" --comment "reset admin password" --instance-ids "instance_id"
parameters commands="sudo chef-automate iam admin-access restore new_password" --region --region_name --output text
3. Wait for output text (in this case, the command ID) to show that the password change is finished.
For more information about working with the Chef Automate dashboard, see An Overview of Visibility in Chef Automate.
Logging AWS OpsWorks for Chef Automate API Calls with AWS CloudTrail
AWS OpsWorks for Chef Automate is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in AWS OpsWorks for Chef Automate. CloudTrail captures all API calls for AWS OpsWorks for Chef Automate as events, including calls from the AWS OpsWorks for Chef Automate console and from code calls to the AWS OpsWorks for Chef Automate APIs. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for AWS OpsWorks for Chef Automate. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can determine the request that was made to AWS OpsWorks for Chef Automate, the IP address from which the request was made, who made the request, when it was made, and additional details.
To learn more about CloudTrail, see the AWS CloudTrail User Guide.
AWS OpsWorks for Chef Automate Information in CloudTrail
AWS OpsWorks for Chef Automate Information in CloudTrail
CloudTrail is enabled on your AWS account when you create the account. When activity occurs in AWS OpsWorks for Chef Automate, that activity is recorded in a CloudTrail event along with other AWS service events in Event history. You can view, search, and download recent events in your AWS account. For more information, see Viewing Events with CloudTrail Event History.
For an ongoing record of events in your AWS account, including events for AWS OpsWorks for Chef Automate, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all regions. The trail logs events from all regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify.
Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see:
• Overview for Creating a Trail
• CloudTrail Supported Services and Integrations
• Configuring Amazon SNS Notifications for CloudTrail
• Receiving CloudTrail Log Files from Multiple Regions and Receiving CloudTrail Log Files from Multiple Accounts
All AWS OpsWorks for Chef Automate actions are logged by CloudTrail and are documented in the AWS OpsWorks for Chef Automate API Reference. For example, calls to the CreateServer, CreateBackup, and DescribeServers actions generate entries in the CloudTrail log files.
Every event or log entry contains information about who generated the request. The identity information helps you determine the following:
• Whether the request was made with root or IAM user credentials.
• Whether the request was made with temporary security credentials for a role or federated user.
• Whether the request was made by another AWS service.
For more information, see the CloudTrail userIdentity Element.
Understanding AWS OpsWorks for Chef Automate Log File Entries
A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files are not an ordered stack trace of the public API calls, so they do not appear in any specific order.
The following example shows a CloudTrail log entry for the AWS OpsWorks for Chef Automate CreateServer action.
{"eventVersion":"1.05",
"userIdentity":{
"type":"AssumedRole",
"principalId":"ID number:OpsWorksCMUser",
"arn":"arn:aws:sts::831000000000:assumed-role/Admin/OpsWorksCMUser", "accountId":"831000000000","accessKeyId":"ID number",
"sessionContext":{
"attributes":{
Understanding AWS OpsWorks for
"arn":"arn:aws:iam::831000000000:role/Admin", "accountId":"831000000000",
"endpoint":"OpsChef-test-server-thohsgreckcnwgz3.us-west-2.opsworks-cm.io", "createdAt":"Jan 5, 2017 10:18:22 PM",
"serviceRoleArn":"arn:aws:iam::831000000000:role/service-role/aws-opsworks-cm-service-role",
"preferredBackupWindow":"Wed:08:00", "status":"CREATING",
"subnetIds":["subnet-1e111f11"], "engine":"Chef",
"instanceType":"t2.medium",
"serverName":"OpsChef-test-server",
"serverArn":"arn:aws:opsworks-cm:us-west-2:831000000000:server/OpsChef-test-server/8epp7f6z-e91f-4z10-89z5-8c6219cdb09f",
"engineModel":"Single", "backupRetentionCount":3, "engineAttributes":[
{"name":"CHEF_STARTER_KIT","value":"*** Redacted ***"}, {"name":"CHEF_PIVOTAL_KEY","value":"*** Redacted ***"},
{"name":"CHEF_DELIVERY_ADMIN_PASSWORD","value":"*** Redacted ***"}], "engineVersion":"12.11.1",
"instanceProfileArn":"arn:aws:iam::831000000000:instance-profile/aws-opsworks-cm-ec2-role",
"preferredMaintenanceWindow":"Fri:21:00"
}
Troubleshooting
Troubleshooting AWS OpsWorks for Chef Automate
This topic contains some common AWS OpsWorks for Chef Automate issues, and suggested solutions for those issues.
Topics
• General Troubleshooting Tips (p. 128)
• Troubleshooting Specific Errors (p. 128)
• Additional help and support (p. 131)
General Troubleshooting Tips
If you are unable to create or work with a Chef server, you can view error messages or logs to help you troubleshoot the issue. The following tasks describe general places to start when you are troubleshooting a Chef server issue. For information about specific errors and solutions, see the Troubleshooting Specific Errors (p. 128) section of this topic.
• Use the AWS OpsWorks for Chef Automate console to view error messages if a Chef server fails to start. On the Chef server detail page, error messages related to launching and running the server are shown at the top of the page. Errors can come from AWS OpsWorks for Chef Automate, AWS CloudFormation, or Amazon EC2, services that are used to create a Chef server. On the detail page, you can also view events that occur on a running server, which can contain failure event messages.
• To help resolve EC2 issues, connect to your server's instance by using SSH, and view logs. EC2 instance logs are stored in the /var/log/aws/opsworks-cm directory. These logs capture command outputs while AWS OpsWorks for Chef Automate launches a Chef server.
Troubleshooting Specific Errors
Topics
• Managed node shows up in the Chef Automate dashboard in the Missing column (p. 128)
• Cannot create a Chef vault; knife vault command fails with errors (p. 129)
• Server creation fails with "requested configuration is currently not supported" message (p. 129)
• Chef server doesn't recognize organization names added in the Chef Automate dashboard (p. 130)
• Unable to create the server's Amazon EC2 instance (p. 130)
• Service role error prevents server creation (p. 130)
• Elastic IP address limit exceeded (p. 130)
• Cannot sign into the Chef Automate dashboard (p. 131)
• Unattended node association fails (p. 131)
Managed node shows up in the Chef Automate dashboard in the Missing column
Problem: A managed node is showing up in the Chef Automate dashboard's Missing column.
Cause: When a node doesn't connect to the Chef Automate server for more than 12 hours, and chef-client cannot run on the node, the node changes from the state it was in before the 12-hour period, and moves to the Missing column of the Chef Automate dashboard.
Troubleshooting Specific Errors
Solution: Verify that the node is online. Try running knife node show node_name --run-list to see whether chef-client is able to run on the node, or knife node show -l node_name to display all information about the node. The node might be offline or disconnected from the network.
Cannot create a Chef vault; knife vault command fails with errors
Problem: You are trying to create a vault on your Chef Automate server (such as a vault for storing credentials for domain-joining Windows-based nodes) by running the knife vault command. The command returns an error message similar to the following.
WARN: Auto inflation of JSON data is deprecated. Please pass in the class to inflate or use ├edit_hash (CHEF-1)
at /opt/chefdk/embedded/lib/ruby/2.3.0/forwardable.rb:189:in `edit_data'.Please see https://docs.chef.io/deprecations_json_auto_inflate.html
for further details and information on how to correct this problem.
WARNING: pivotal not found in users, trying clients.
ERROR: ChefVault::Exceptions::AdminNotFound: FATAL: Could not find pivotal in users or clients!
The pivotal user is not returned when you run knife user list remotely, but you can see the pivotal user in results when you run the chef-server-ctl user-show command locally on your Chef Automate server. In other words, your knife vault command cannot find the pivotal user, but you know it exists.
Cause: Though the pivotal user is considered the superuser in Chef, and has full permissions, it is not a member of any organization, including the default organization that is used in AWS OpsWorks for Chef Automate. The command knife user list returns all the users that are in the current organization in your Chef configuration. The chef-server-ctl user-show command returns all users regardless of organization, including the pivotal user.
Solution: To fix the problem, add the pivotal user to the default organization by running knife opc.
First, you'll need to install the knife-opc plugin.
chef gem install knife-opc
After you install the plugin, run the following command to add the pivotal user to the default organization.
knife opc org user add default pivotal
You can verify that the pivotal user is part of the default organization by running knife user list again. pivotal should be listed in the results. Then, try running knife vault again.
Server creation fails with "requested configuration is currently not supported" message
Problem: You are trying to create a Chef Automate server, but server creation fails with an error message that is similar to "The requested configuration is currently not supported. Please check the documentation for supported configurations."
Cause: An unsupported instance type might have been specified for the Chef Automate server. If you choose to create the Chef Automate server in a VPC that has a non-default tenancy, such as one for dedicated instances, all instances inside the specified VPC must also be of dedicated or host tenancy.
Troubleshooting Specific Errors
Because some instance types, such as t2, are available only with default tenancy, the Chef Automate server instance type might not be supportable by the specified VPC, and server creation fails.
Because some instance types, such as t2, are available only with default tenancy, the Chef Automate server instance type might not be supportable by the specified VPC, and server creation fails.