AWS OpsWorks
User Guide (API Version 2013-02-18)

Running a Recipe on a Windows Instance

This topic is basically an abbreviated version of Running a Recipe on a Linux Instance, which shows you how to run a recipe on a Windows stack. We recommend that you go through Running a Recipe on a Linux Instance first, because it provides a more detailed discussion, most of which is relevant to either type of operating system.

For a description of how to run recipes on AWS OpsWorks Stacks Linux instances, see Running a Recipe on a Linux Instance.

Enabling RDP Access

Before you start, if you have not done so already, you must set up a security group with an inbound rule that allows RDP access for your instances . You will need that group when you create the stack.

When you create the first stack in a region, AWS OpsWorks Stacks creates a set of security groups. They include one named something like AWS-OpsWorks-RDP-Server, which AWS OpsWorks Stacks attaches to all Windows instances to allow RDP access. However, by default, this security group does not have any rules, so you must add an inbound rule to allow RDP access to your instances.

To allow RDP access

  1. Open the Amazon EC2 console, set it to the stack's region, and choose Security Groups from the navigation pane.

  2. Choose AWS-OpsWorks-RDP-Server, choose the Inbound tab, and choose Edit.

  3. Add a rule with the following settings:

    • TypeRDP

    • Source – The permissible source IP addresses.

      You typically allow inbound RDP requests from your IP address or a specified IP address range (typically your corporate IP address range).


As described later, you also must edit user permissions to authorize RDP access for regular users.

For more information, see Logging In with RDP.

Creating and Running the Recipe

The following briefly summarizes how to create a stack for this example. For more information, see Create a New Stack.

Create a stack

  1. Open the AWS OpsWorks Stacks console and choose Add Stack. Specify the following settings, accept the defaults for the other settings, and choose Add Stack.

    • Name – WindowsRecipeTest

    • Region – US West (Oregon)

      This example will work in any region, but we recommend using US West (Oregon) for tutorials.

    • Default operating system – Microsoft Windows Server 2012 R2

  2. Choose Add a layer and add a custom layer to the stack with the following settings.

    • Name – RecipeTest

    • Short name – recipetest

  3. Add a 24/7 instance with default settings to the RecipeTest layer and start it.

    AWS OpsWorks Stacks automatically assigns AWS-OpsWorks-RDP-Server to this instance, which allows authorized users to log in to the instance.

  4. Choose Permissions and then Edit, and choose SSH/RDP and sudo/admin. Regular users need this authorization in addition to the AWS-OpsWorks-RDP-Server security group to log in to the instance.


    You can also log in as Administrator, but it requires a different procedure. For more information, see Logging In with RDP.

While the instance is starting up—it usually takes several minutes—you can create the cookbook. The recipe for this example creates a data directory, and is basically the recipe from Example 3: Creating Directories, modified for Windows.


When implementing cookbooks for AWS OpsWorks Stacks Windows instances, you use a somewhat different directory structure than you do when implementing cookbooks for AWS OpsWorks Stacks Linux instances. For more information, see Cookbook Repositories.

To set up the cookbook

  1. Create a directory named windowstest and navigate to it.

  2. Create a metadata.rb file with the following content and save it to windowstest.

    name "windowstest" version "0.1.0"
  3. Create a recipes directory within windowstest.

  4. Create a default.rb file with the following recipe and save it to the recipes directory."******Creating a data directory.******") directory 'C:\data' do rights :full_control, 'instance_name\username' inherits false action :create end

    Replace username with your user name.

  5. Put the cookbook in a repository.

    To install your cookbook on an AWS OpsWorks Stacks instance, you must store it in a repository and provide AWS OpsWorks Stacks with the information required to download the cookbook to the instance. You can store Windows cookbooks as an archive file in an S3 bucket or in a Git repository. This example uses an S3 bucket, so you must create a .zip archive of the windowstest directory. For more information on cookbook repositories, see Cookbook Repositories.

  6. Upload the archive to an S3 bucket, make the archive public, and record the archive's URL. It should look something like You can also use a private archive, but a public archive is sufficient for this example and somewhat easier to work with.

    Content delivered to Amazon S3 buckets might contain customer content. For more information about removing sensitive data, see How Do I Empty an S3 Bucket? or How Do I Delete an S3 Bucket?.

You can now install the cookbook and run the recipe.

To run the recipe

  1. Edit the stack to enable custom cookbooks and specify the following settings.

    • Repository typeS3 Archive

    • Repository URL – The cookbook archive URL that you recorded earlier

    Accept the default values for the other settings and choose Save to update the stack configuration.

  2. Run the Update Custom Cookbooks stack command, which installs the current version of your custom cookbooks on the stack's instances, including online instances. If an earlier version of your cookbooks is present, this command overwrites it.

  3. After Update Custom Cookbooks is finished, execute the recipe by running the Execute Recipes stack command with Recipes to execute set to windowstest::default. This command initiates a Chef run, with a run list that consists of your recipe.

After the recipe runs successfully, you can verify it.

To verify windowstest

  1. Examine the Chef log. Choose show in the opstest1 instance's Log column to display the log. Scroll down and you will see your log message near the bottom.

    ... [2014-07-31T17:01:45+00:00] INFO: Storing updated cookbooks/opsworks_cleanup/attributes/customize.rb in the cache. [2014-07-31T17:01:45+00:00] INFO: Storing updated cookbooks/opsworks_cleanup/metadata.rb in the cache. [2014-07-31T17:01:46+00:00] INFO: ******Creating a data directory.****** [2014-07-31T17:01:46+00:00] INFO: Processing template[/etc/hosts] action create (opsworks_stack_state_sync::hosts line 3) ...
  2. Choose Instances, choose rdp in the instance's Actions column, and request an RDP password with a suitable expiration time. Copy the DNS name, user name, and password. You can then can use that information with an RDP client, such as the Windows Remote Desktop Connection client, to log in to the instance and verify that c:\data exists. For more information, see Logging In with RDP.


If your recipe isn't working properly, see Troubleshooting and Fixing Recipes for troubleshooting tips; most of them also apply to Windows instances. If you want to test your fix by editing the recipe on the instance, look for your cookbook in the C:\chef\cookbooks directory, where AWS OpsWorks Stacks installs custom cookbooks.

Executing the Recipe Automatically

The Execute Recipes command is a convenient way to test custom recipes, which is why it is used in most of these examples. However, in practice you typically run recipes at standard points in an instance's lifecycle, such as after the instance finishes booting or when you deploy an app. AWS OpsWorks Stacks simplifies running recipes on your instance by supporting a set of lifecycle events for each layer: Setup, Configure, Deploy, Undeploy, and Shutdown. You can have AWS OpsWorks Stacks run a recipe automatically on a layer's instances by assigning the recipe to the appropriate lifecycle event.

You would typically create directories as soon as an instance finishes booting, which corresponds to the Setup event. The following shows how to run the example recipe at setup, using the same stack that you created earlier in the example. You can use the same procedure for the other events.

To automatically run a recipe at setup

  1. Choose Layers in the navigation pane and then choose the pencil icon next to the RecipeTest layer's Recipes link.

  2. Add windowstest::default to the layer's Setup recipes, choose + to add it to the layer, and choose Save to save the configuration.

  3. Choose Instances, add another instance to the layer, and start it.

    The instance should be named recipetest2. After it finishes booting, AWS OpsWorks Stacks will run windowstest::default.

  4. After the recipetest2 instance is online, verify that c:\data is present.


If you have assigned recipes to the Setup, Configure, or Deploy events, you can also run them manually by using a stack command (Setup and Configure) or a deploy command (Deploy) to trigger the event. Note that if you have multiple recipes assigned to an event, these commands run all of them.