This cookbook manages the deployment logic for managing instances used in Chef training during the lifecycle of classes in Chef's training catalog.
In order to use this repo, you must have the following setup:
AmazonEC2FullAccess
(assigned to the portal instance)Details on fulfilling AWS Requirements below
To set up a Chef Training Classroom, do the following:
Create your ~/.aws/config
file if you don't already have one. It should have content similar to the snippet below, except with your own AWS API credentials here:
[default]
aws_access_key_id = AKIAAABBCCDDEEFFGGHH
aws_secret_access_key = "Abc0123dEf4GhIjk5lMn/OpQrSTUvXyz/A678bCD"
Create a new role called class.json
in 'roles' folder
# cat roles/class.json
{
"name" : "class",
"default_attributes" : {
"chef_classroom" : {
"region" : "us-west-2",
"iam_instance_profile" : "arn:aws:iam::643494220119:instance-profile/chef-portal",
"number_of_students" : 1,
"ip_range" : "0.0.0.0/0",
"class_name" : "CLASS_NAME"
}
}
}
Replace the IAM Instance Profile with the ARN name of your choice.
Additional attributes may be set in the class
role, including automatic localization via the chef_classroom['region']
attribute (note: so far only AWS US regions available). Instructors are strongly encouraged to replace the value of chef_classroom['ip_range']
with an appropriate IP address range (e.g. "184.106.28.82/32") for any classroom being managed. The permissions and security settings of these instances are... lax. However, none of these changes are required for basic (demo) use of this repo.
Run berks vendor cookbooks
Run chef-client -z -r 'chef-client -z -r "role[class],recipe[chef_classroom::deploy_portal]'
You should now have a Classroom Portal set up. Visit the portal web UI in a browser by hitting the front-end IP. To find the portal node front-end IP, at this time the best way is to run the command grep public_ipv4 nodes/mytraining-portal.json
. There's a gem conflict preventing knife from working in local-mode that should be resolved the next time ChefDK ships.
Visit the portal node in a web browser. Additional actions should be taken from the portal to run your class. These actions are not yet available. See the Demo workflow below and follow steps 1-3 to get an entire classroom provisioned for training material verification.
Setup steps 1-6 (above) could be handled by shipping a pre-baked Chef Classroom AMI. See the Roadmap section below for intended usage and next steps.
Only Chef Fundamentals 3.x workflow is currently supported.
Additional actions from the web UI are not yet available. So to see the instructor experience, you have to run chef-provisioning recipes via the local shell. The mock buttons in the web UI should eventually do this. But for now, your steps to see the classroom go are:
SSH to the portal instance and cd into the chef_classroom dir (See AWS Setup for details).
ssh root@PORTAL_ADDRESS -i ~/.ssh/CLASSNAME-portal_key
[root@PORTAL_ADDRESS]# cd chef_classroom
Presently, you have to set your classroom attributes once again on the portal instance. Ensure you set the same ARN name as you used to provision the portal instance. Again, set all of your desired classroom settings here.
Every time you make a local modification to the code in the chef_classroom
cookbook dir, you must re-vendor cookbooks. (TODO: fix this duplicate step)
[root@PORTAL_ADDRESS chef_classroom]# vi attributes/default.rb
[root@PORTAL_ADDRESS chef_classroom]# rm -rf cookbooks
[root@PORTAL_ADDRESS chef_classroom]# berks vendor cookbooks
To create the entire classroom in one fell swoop, run the default recipe.
chef-client -z -r 'recipe[chef_classroom]'
Alternately, you may instead manage the classroom in steps that match our proposed instructor workflow.
Create the student remote virtual workstations
chef-client -z -r 'recipe[chef_classroom::deploy_workstations]'
Optional: At some appropriate point, remote virtual workstations are abandoned
chef-client -z -r 'recipe[chef_classroom::destroy_workstations]'
At some appropriate point, students will need a target node (without chef installed) to configure
chef-client -z -r 'recipe[chef_classroom::deploy_first_nodes]'
At some appropriate point, students need a Chef Server
chef-client -z -r 'recipe[chef_classroom::deploy_server]'
At some appropriate point, students will need multiple target nodes (without chef installed) to configure
chef-client -z -r 'recipe[chef_classroom::deploy_multi_nodes]'
When you are finished with the classroom environment, all nodes must be destroyed (including the portal).
Class ends and all workstations, nodes, and the Chef server must be destroyed
chef-client -z -r 'recipe[chef_classroom::destroy_lab]'
Destroy the portal instance from your local workstation
chef-client -z -r 'recipe[chef_classroom::destroy_portal]'
Depending on your workflow, sometimes the portal page may not properly refresh. You can force a refresh of the portal page with chef-client -z -r 'recipe[chef_classroom::_refresh_portal]
On occasion, chef-provisioning-aws may lose track of an object it provisioned and you will get errors similar to
Problem: AWS::EC2::Errors::InvalidInstanceID::NotFound
The instance ID 'i-a1b2c3d4' does not exist
This transient error has been difficult to replicate, but should hopefully be fixed in chef-provisioning-aws v.1.4.0. If this error occurs, run the chef recipe again and it will pick up where you left off. You will have an unmanaged instance occupying your security group when you attempt to destroy the entire classroom. So you will see an error specifying your SG's cannot be removed. You may manually remove the transient instance(s) and try again. Another option may be to set action :purge
on the aws_security_group resources that clean everything up.
AWS API Rate Limits are in place to throttle instance creation requests as a DDOS prevention technique. You may see these errors if creating large batches of machines all at once.
AWS::EC2::Errors::RequestLimitExceeded: Request limit exceeded
These limits may be adjusted for your AWS account by contacting support. If you see errors indicating you've hit these limits, the best thing to do is get them raised. Alternately, you may just run the recipe again and it will pick up where it left off.
Other normal EC2 error conditions apply (e.g. account quotas, IAM permissions, etc)
If you started this environment from a workstation using chef-provisioning, you now have a new ssh key called "#{name}-portal_key", where name
is the name of the classroom you set. If you used defaults, it is located in ~/.ssh/mytraining-portal_key
. To reach your workstation, run the following command from a terminal.
ssh -i ~/.ssh/CLASSNAME-portal_key -l root <ip of your instance>
By default, the chef_portal cookbook sets up password auth on the portal instance. Alternatively, you may SSH in to the portal instance as the portal user using the portal password from that cookbook.
For AMI consistency, this repo uses AWS Marketplace images for Centos6, Windows 2012, and Chef Server. You must accept the licensing terms from your AWS account for each of those AMIs, in each region for which you want to deploy a classroom, before this repo will work. If you have not, chef-provisioning-aws will throw an error letting you know you must go do this.
The Marketplace AMIs used are referenceable at:
Follow these instructions to create API credentials.
Follow these instructions to create IAM roles via the AWS console. When you create this role, select AmazonEC2FullAccess
as the 'policy to attach'. Once you create the role, note the 'Instance Profile ARN(s)'. Use this value as the ARN in your attributes file.
The idea is to solidify this cookbook to manage all the steps required for a Chef classroom workflow. This cookbook should only handle chef-provisioning logic.
There are (currently), two dependent cookbooks that probably should be packaged as AMIs. The chef server is also a time consuming piece to build and may be a candidate to package as well.
At present the Chef Server setup takes ~15 mins and consumes a large majority of the classroom setup time (~30 mins). The initial compile of guacamole on the portal instance is also significant (~10 mins). The goal probably would be to stop building these on the fly and use pre-baked images instead (using the chef recipes demonstrated here) once this passes the MVP phase.
The setup steps above are minimal and we should be able to put some polish around them in order to make them consumable in a more "easy to use" manner.
See issues for other pending items.
Usage note: if you make changes to the chef_classroom
cookbook, you must berks vendor cookbooks
again before running chef-client -z
for those changes to get picked up while testing.
License:: MIT
Copyright (c) 2015 Chef Software, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.