Chef

Table Of Contents

knife ec2

Amazon EC2 is a web service that provides resizable compute capacity in the cloud, based on pre-configured operating systems and virtual application software using Amazon Machine Images (AMI). The knife ec2 subcommand is used to manage API-driven cloud servers that are hosted by Amazon EC2.

Note

This plugin requires the knife windows plugin to be present on the same machine.

Note

Review the list of common options available to this (and all) Knife subcommands and plugins.

Install this plugin

To install the knife ec2 plugin using RubyGems, run the following command:

$ /opt/chef/embedded/bin/gem install knife-ec2

where /opt/chef/embedded/bin/ is the path to the location where the chef-client expects Knife plugins to be located. If the chef-client was installed using RubyGems, omit the path in the previous example.

instance data

The instance data argument is used to generate instance metadata used with custom Chef Amazon Machine Images (AMI). This process will read the validation certificate and Chef server URL from the Knife configuration file (~/.chef/knife.rb) and will output the data in JSON format.

Warning

Using this sub-command is an older way of launching Amazon EC2 instances and should be considered deprecated. Using the server create sub-command is preferred (and more flexible). Although this sub-command will remain, the Chef custom Amazon Machine Images (AMI) are out of date.

Syntax

This argument has the following syntax:

$ knife ec2 instance data (options)

Options

This argument has the following options:

-A KEY, --aws-access-key-id KEY
The access key identifier used with Amazon EC2.
-e, --edit
Use to edit instance data using the default text editor.
-K SECRET, --aws-secret-access-key SECRET
The secret access key for the API endpoint used with Amazon EC2.
-r RUN_LIST, --run-list RUN_LIST
A comma-separated list of roles and/or recipes to be applied.
--region REGION
The name of the region from which instances of hosted applications are launched. Each region has a unique endpoint.

server create

The server create argument is used to create a new Amazon EC2 cloud instance. This will provision a new image in Amazon EC2, perform a bootstrap (using the SSH protocol), and then install the chef-client on the target system so that it can be used to configure the node and to communicate with a Chef server.

Syntax

This argument has the following syntax:

$ knife ec2 server create (options)

Options

This argument has the following options:

-A KEY, --aws-access-key-id KEY
The access key identifier used with Amazon EC2.
--bootstrap-protocol PROTOCOL
The protocol used to bootstrap on a machine that is running Windows Server: winrm or ssh.
--bootstrap-version VERSION
The version of the chef-client to install.
-d DISTRO, --distro DISTRO
The template file to be used during a bootstrap operation. The following distributions are supported: chef-full (the default bootstrap), centos5-gems, fedora13-gems, ubuntu10.04-gems, ubuntu10.04-apt, ubuntu12.04-gems, and the name of a custom bootstrap template file. When this option is used, Knife will search for the template file in the following order: the bootstrap/ folder in the current working directory, the bootstrap/ folder in the chef-repo, the bootstrap/ folder in the ~/.chef/ directory, or a default bootstrap file. Do not use the --template-file option when --distro is specified.
--ebs-size SIZE
The size of the Amazon Elastic Block Store volume, in GB. This option is only available for instances that are backed with Amazon Elastic Block Store.
--ebs-no-delete-on-term
Use to prevent the Amazon Elastic Block Store volume from being deleted upon instance termination. This option is only available for instances that are backed with Amazon Elastic Block Store.
--ephemeral DEVICE
A comma-separated list of device locations to be mapped to ephemeral devices.
-f FLAVOR, --flavor FLAVOR
The name of the flavor that identifies the hardware configuration of the server, including disk space, memory capacity, and CPU priority.
--fqdn FQDN
The FQDN of the host. This value should be pre-defined.
-g X,Y,Z, --security-group-ids X,Y,Z
A comma-separated list of security group identifiers. Required when using Amazon Virtual Private Cloud.
-G X,Y,Z, --groups X,Y,Z
A comma-separated list of security groups. Not supported when using Amazon Virtual Private Cloud.
--hint HINT_NAME[=HINT_FILE]
An Ohai hint to be set on the target of the bootstrap. The hint is contained in a file and is formatted as JSON: {"attribute":"value","attribute":"value"...}. HINT_NAME is the name of the hint and HINT_FILE is the name of the hint file located at /etc/chef/ohai/hints/HINT_FILE.json. Use multiple --hint options in the command to specify multiple hints.
-i IDENTITY_FILE, --identity-file IDENTITY_FILE
The SSH identity file used for authentication. Key-based authentication is recommended.
-I IMAGE, --image IMAGE
The name of the image that identifies the operating system (and version) that will be used to create the virtual machine.
-K SECRET, --aws-secret-access-key SECRET
The secret access key for the API endpoint used with Amazon EC2.
-N NAME, --node-name NAME
The name of the node.
--[no-]host-key-verify
Use --no-host-key-verify to disable host key verification. Default setting: --host-key-verify.
-p PORT, --ssh-port PORT
The SSH port.
-P PASSWORD, --ssh-password PASSWORD
The SSH password. This can be used to pass the password directly on the command line. If this option is not specified (and a password is required) Knife will prompt for the password.
--prerelease
Use to install pre-release gems.
-r RUN_LIST, --run-list RUN_LIST
A comma-separated list of roles and/or recipes to be applied.
--region REGION
The name of the region from which instances of hosted applications are launched. Each region has a unique endpoint.
-s SUBNET_ID, --subnet SUBNET_ID
The Amazon Virtual Private Cloud instance in which a node will be created.
-S KEY, --ssh-key KEY
The SSH key for the Amazon EC2 environment.
--server-connect-attribute ATTRIBUTE
The attribute that is used when opening the SSH connection. This should be an Amazon EC2 server attribute. This option is especially useful when creating instances in a VPC. Will allow the bootstrapping ssh client to connect to the VPC after an EIP is attached.
--T Tag=Value[,Tag=Value], --tags Tag=Value[,Tag=Value]
The tags for this server.
--template-file TEMPLATE
The path to a template file that will be used during a bootstrap operation. Do not use the --distro option when --template-file is specified.
-u USER_DATA_FILE, --user-data USER_DATA_FILE
The Amazon EC2 user data file used during instance provisioning.
-w GATEWAY, --ssh-gateway GATEWAY
The SSH tunnel or gateway that is used to run a bootstrap action on a machine that is not accessible from the workstation.
-x USERNAME, --ssh-user USERNAME
The SSH user name.
-Z ZONE", --availability-zone ZONE
The name of the availability zone. Each availability zone is unique within a region. Default: us-east-1b.

Examples

Launch an instance which has a single Chef role

To launch a new Amazon EC2 instance with the webserver role, enter:

$ knife ec2 server create -r "role[webserver]" -I ami-2d4aa444 --flavor m1.small -G www,default -x ubuntu -N server01

Launch an instance which has many Chef roles

To launch a new Amazon EC2 instance with multiple roles, enter:

$ knife ec2 server create -r "role[base],role[webserver]" -I ami-2d4aa444 -G www,default -x ubuntu --node-name server01

server delete

The server delete argument is used to delete one or more nodes that are running in the Amazon EC2 cloud. To find a specific cloud instance, use the knife ec2 server list argument. Use the --purge option to delete all associated node and client objects from the Chef server or use the knife node delete and knife client delete sub-commands to delete specific node and client objects.

Syntax

This argument has the following syntax:

$ knife ec2 server delete SERVER [NODE_NAME...] (options)

Options

This argument has the following options:

-A KEY, --aws-access-key-id KEY
The access key identifier used with Amazon EC2.
-K SECRET, --aws-secret-access-key SECRET
The secret access key for the API endpoint used with Amazon EC2.
-N NODE_NAME, --node-name NODE_NAME
The name of the node to be deleted, if different from the server name. This must be used with the --purge option.
-p, --purge
Use to destroy all corresponding nodes and clients on the Chef server, in addition to the Amazon EC2 node itself. This action (by itself) assumes that the node and client have the same name as the server; if they do not have the same names, then the --node-name option must be used to specify the name of the node.
--region REGION
The name of the region from which instances of hosted applications are launched. Each region has a unique endpoint.

Examples

Delete an instance

To delete a node called preprod in an instance named operations, enter:

$ knife ec2 server delete operations preprod

server list

The server list argument is used to find instances that are associated with a Amazon EC2 account. The results may show instances that are not currently managed by the Chef server.

Syntax

This argument has the following syntax:

$ knife ec2 server list

Options

This argument has the following options:

-A KEY, --aws-access-key-id KEY
The access key identifier used with Amazon EC2.
-n, --no-name
Use to prevent tag names from being displayed in the output.
--region REGION
The name of the region from which instances of hosted applications are launched. Each region has a unique endpoint.
-t TAG1, TAG2, --tags TAG1, TAG2
A list of tags that will be displayed in the output.