[edit on GitHub]

Use the machine_image resource to define a machine image. This image may then be used by the machine resource when building machines.


This functionality was available with Chef Provisioning and was packaged in the ChefDK.

Chef Provisioning was officially end-of-life on August 31, 2019 and is no longer included with ChefDK. The Chef Provisioning source code and drivers have been moved into the chef-boneyard organization. If you are a current user of Chef Provisioning, please contact your Chef Customer Success Manager or Account Representative to review your options.


The syntax for using the machine_image resource in a recipe is as follows:

machine_image 'name' do
  attribute 'value' # see properties section below
  action :action # see actions section below


  • machine_image tells Chef Infra Client to use the Chef::Provider::MachineImage provider during a Chef Infra Client run
  • name is the name of the resource block and also the name of the machine image
  • attribute is zero (or more) of the properties that are available for this resource
  • action identifies which steps Chef Infra Client will take to bring the node into the desired state


This resource has the following actions:

Use to archive a machine image.
Default. Use to create a machine image.
Use to destroy a machine image.
This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.


This resource has the following properties:

Use to specify a hash of attributes to be applied to the machine image.
The name of the environment.
Use to specify if all of the attributes specified in attributes represent a complete specification for the machine image. When true, any attributes not specified in attributes will be reset to their default values.

Ruby Type: Hash

Use to specify options that are used with this machine image.

The name of the machine image.

The machine image as JSON data. For example:


Use to add a recipe to the run-list for the machine image. Each recipe adds a single recipe to the run-list. The order in which recipe defines the run-list is the order in which Chef will execute the run-list on the machine image.
Use to remove a recipe from the run-list for the machine image.
Use to remove a role from the run-list for the machine image.
Use to add a role to the run-list for the machine image.
Use to specify the run-list to be applied to the machine image. See About Run Lists for more information.
Use to specify the list of tags to be applied to the machine image. Any tag not specified in this list will be removed.


The following examples demonstrate various approaches for using resources in recipes:

Build a machine from a machine image

machine_image 'web_image' do
  recipe 'apache2'

machine 'web_machine' do
 from_image 'web_image'