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.
--aws-credential-file FILE
The credential file that is used by Amazon Web Services command-line tools.
--iam-profile NAME
The name of the Identity and Access Management (IAM) to apply to this instance.
-K SECRET, --aws-secret-access-key SECRET
The secret access key for the API endpoint used with Amazon EC2.
--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 ATTRIBUTE, --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 and will allow the bootstrapping ssh client to connect to the VPC after an EIP is attached.
-A KEY, --aws-access-key-id KEY
The access key identifier used with Amazon EC2.
--associate-eip IP_ADDRESS
Use to associate an elastic IP address with this instance.
--associate-public-ip
Use to associate a public IP address to an Amazon Virtual Private Cloud instance.
--aws-credential-file FILE
The credential file that is used by Amazon Web Services command-line tools.
--bootstrap-protocol PROTOCOL
The protocol used to bootstrap on a machine that is running Windows Server: winrm or ssh. Possible values: ssh and winrm.
--bootstrap-proxy PROXY_URL
The proxy server for the node that is the target of a bootstrap operation.
--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.
--dedicated_instance
Use to launch this instance as an Amazon EC2 Dedicated Instance.
--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.
--ebs-optimized
Use to enable optimized I/O for Amazon Elastic Block Store.
--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-volume-type TYPE
The type of Amazon Elastic Block Store volume. Possible values: standard or io1.
--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]

Use to specify an Ohai hint to be set on the target node.

Ohai hints are used to tell Ohai something about the system that it is running on that it would not be able to discover itself. An Ohai hint exists if a JSON file exists in the hint directory with the same name as the hint. For example, calling hint?('antartica') in an Ohai plugin would return an empty hash if the file antartica.json existed in the hints directory, and return nil if the file does not exist.

If the hint file contains JSON content, it will be returned as a hash from the call to hint?.

{
  "snow": true,
  "penguins": "many"
}
arctic_hint = hint?('antartica')
if arctic_hint['snow']
  "There are #{arctic_hint['penguins']} penguins here."
else
  "There is no snow here, and penguins like snow."
end

The default directory in which hint files are located is /etc/chef/ohai/hints/. Use the Ohai::Config[:hints_path] setting in the client.rb file to customize this location.

HINT_FILE is the name of the JSON file. HINT_NAME is the name of a hint in a JSON file. Use multiple --hint options to specify multiple hints.

-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.
--iam-profile NAME
The name of the Identity and Access Management (IAM) to apply to this instance.
-j JSON_ATTRIBS, --json-attributes JSON_ATTRIBS
A JSON string that is added to the first run of a chef-client.
-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.
--placement-group PLACEMENT_GROUP
The name of the placement group.
--prerelease
Use to install pre-release gems.
--private-ip-address IP-ADDRESS
Use to specify the private IP address of the instance Amazon Virtual Private Cloud mode.
--provisioned-iops IOPS
The IOPS rate used for a EBS Provisioned IOPS volume.
-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 SECRET, --secret SECRET
The encryption key that is used for values contained within a data bag item.
-S KEY, --ssh-key KEY
The SSH key for the Amazon EC2 environment.
--secret-file FILE
The path to the file that contains the encryption key.
--ssh-gateway-identity IDENTITY_FILE
The private key for the SSH gateway.
--subnet SUBNET_ID
The Amazon Virtual Private Cloud instance in which a node will be created.
--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.
--use-iam-profile
Use the Identity and Access Management (IAM) that is assigned to the current machine. Default value: false.
-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.
--windows-auth-timeout MINUTES
The amount of time (in minutes) to wait for authentication to succeed. Default: 25.
-Z ZONE, --availability-zone ZONE
The name of the availability zone. Each availability zone is unique within a region. Default: us-east-1b.

The following settings may be used when --bootstrap-protocol is set to ssh:

--[no-]host-key-verify
Use --no-host-key-verify to disable host key verification. Default setting: --host-key-verify.
-i IDENTITY_FILE, --identity-file IDENTITY_FILE
The SSH identity file used for authentication. Key-based authentication is recommended.
-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.
-x USERNAME, --ssh-user USERNAME
The SSH user name.

The following settings may be used when --bootstrap-protocol is set to winrm:

-i KEYTAB_FILE, --keytab-file KEYTAB_FILE
The keytab file that contains the encryption key required by Kerberos-based authentication.
-p PORT, --winrm-port PORT
The WinRM port. Default: 5985.
-P PASSWORD, --winrm-password PASSWORD
The WinRM password.
-R KERBEROS_REALM, --kerberos-realm KERBEROS_REALM
The administrative domain to which a user belongs.
-S KERBEROS_SERVICE, --kerberos-service KERBEROS_SERVICE
The service principal used during Kerberos-based authentication.
-t TRANSPORT, --winrm-transport TRANSPORT
The WinRM transport type: ssl or plaintext.
-x USERNAME, --winrm-user USERNAME
The WinRM user name.

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.
--aws-credential-file FILE
The credential file that is used by Amazon Web Services command-line tools.
--iam-profile NAME
The name of the Identity and Access Management (IAM) to apply to this instance.
-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.
--aws-credential-file FILE
The credential file that is used by Amazon Web Services command-line tools.
--iam-profile NAME
The name of the Identity and Access Management (IAM) to apply to this instance.
-K SECRET, --aws-secret-access-key SECRET
The secret access key for the API endpoint 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.
-z, --availability-zone
Use to show a list of availability zones.