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

Extending AWS OpsWorks Configuration Files Using Custom Templates


Because AWS OpsWorks handles Chef runs differently for Windows stacks than for Linux stacks, you cannot use the techniques discussed in this section for Windows stacks.

AWS OpsWorks uses templates to create files such as configuration files, which typically depend on attributes for many of the settings. If you use custom JSON or custom cookbook attributes to override the AWS OpsWorks definitions, your preferred settings are incorporated into the configuration files in place of the AWS OpsWorks settings. However, AWS OpsWorks does not necessarily specify an attribute for every possible configuration setting; it accepts the defaults for some settings and hardcodes others directly in the template. You can't use custom JSON or custom cookbook attributes to specify preferred settings if there is no corresponding AWS OpsWorks attribute.

You can extend the configuration file to include additional configuration settings by creating a custom template. You can then add whatever configuration settings or other content you need to the file, and override any hardcoded settings. For more information on templates, see Templates.


You can override any built-in template except opsworks-agent.monitrc.erb.

To create a custom template

  1. Create a cookbook with the same structure and directory names as the built-in cookbook. Then, create a template file in the appropriate directory with the same name as the built-in template that you want to customize. For example, to use a custom template to extend the Apache httpd.conf configuration file, you must implement an apache2 cookbook in your repository and your template file must be apache2/templates/default/apache.conf.erb. Using exactly the same names allows AWS OpsWorks to recognize the custom template and use it instead of the built-in template.

    The simplest approach is to just copy the built-in template file from the built-in cookbook's GitHub repository to your cookbook and modify it as needed.


    Do not copy any files from the built-in cookbook except for the template files that you want to customize. Copies of other types of cookbook file, such as recipes, create duplicate Chef resources and can cause errors.

    The cookbook can also include custom attributes, recipes, and related files, but their file names should not duplicate built-in file names.

  2. Customize the template file to produce a configuration file that meets your requirements. You can add more settings, delete existing settings, replace hardcoded attributes, and so on.

  3. If you haven't done so already, edit the stack settings to enable custom cookbooks and specify your cookbook repository. For more information, see Installing Custom Cookbooks.


For a complete walkthrough of this procedure, see Overriding Built-In Templates.

You don't have to implement any recipes or add recipes to the layer configuration to override a template. AWS OpsWorks always runs the built-in recipes. When it runs the recipe that creates the configuration file, it will automatically use your custom template instead of the built-in template.


If AWS OpsWorks makes any changes to the built-in template, your custom template might become out of sync and no longer work correctly. For example, suppose your template refers to a dependent file, and the file name changes. AWS OpsWorks doesn't make such changes often, and when a template does change, it lists the changes and gives you the option of upgrading to a new version. You should monitor the AWS OpsWorks repository for changes, and manually update your template as needed.