azureautomation / automation-packs

Collections of Automation resources that can include runbooks, configurations, modules, credentials, schedules, variables, connections, certificates, jobs, compilation jobs, and nodes.
MIT License
75 stars 42 forks source link

# Automation Packs Automation Packs include an Azure Resource Manager template that deploys Automation resources to Azure. The template can include any Automation resource needed for an Automation solution. Automation resources include:

Rules for contributing to the Automation repository

  1. Each Automation pack is contained in its own folder.

  2. The parent deployment template must be named azuredeploy.json. You can also have child templates which do not need to follow a naming convention.

  3. Include a Readme.md file that explains:

    1. How the template works and what the Automation pack automates
    2. What resources are deployed
    3. Includes the "Deploy to Azure" link
    4. Any known limitations
  4. Any Automation assets used in your runbooks or DSC configurations should be included in the deployment template.

  5. Any runbooks, modules, or DSC Configurations in your ARM template should use the following conventions:

  6. 1. A **variable** containing the **URL** for the resource content
    2. A **variable** containing the **Name** of the resource
  7. Any Automation assets in your template should follow the the following conventions:

  8. 1. **Parameter(s)** for the asset value(s) are in the deployment template to allow end users input their own values
    2.  A **variable** for each asset name  
  9. Template parameters should:

    1. Follow camelCasing
    2. Contain allowedValues wherever it makes sense
    3. Have the description specified using the metadata property. An example is included below:
    "automationAccountName": {
        "type": "string",
        "metadata": {
            "description": "The name of the Automation Account"
        }
    }

Recommendations for writing your Automation Pack

Runbooks in Automation Packs

You can store runbooks referenced in Automation Packs in two different ways:

  1. In an external location of your choice. Preferred locations are the PowerShell Gallery or Script Center
  2. In a Runbook subfolder within the Automation Pack.

Best practices for runbooks:

  1. Follow practices outlined here.
  2. Always include a header with the following when publishing to PowerShell Gallery:
    <#PSScriptInfo

        .Version 1.0
        .Author elcooper
        .CompanyName Microsoft Corporation
        .Copyright (c) 2015 Microsoft Corporation. All rights reserved.
        .Tags Tag1 Tag2
        .LicenseUri https://contoso.com/License
        .ProjectUri https://contoso.com/
        .IconUri https://contoso.com/MyScriptIcon
        .ExternalModuleDependencies bar
        .RequiredScripts foo 

        .ReleaseNotes 
             contoso script now supports following features
             Feature 1
             Feature 2
             Feature 3

    #>

PowerShell Modules in Automation Packs

You can store modules used in your runbook in two different ways:

  1. Create a Module subfolder and place all your modules in the folder.
  2. Place your modules on the PowerShell GitHub repository and publish your module to PowerShell Gallery.

To deploy a module, you must also have a zipped module folder formatted for Azure Automation. This is used in the Azure Resource Manager deployment template. For more on creating modules for Azure Automation see Authoring Integration Modules.

Follow the PowerShell best practices for publishing a module to the PowerShell gallery outlined in this blog.

Other notes on authoring Automation Packs

If you have a pack that contains many Automation resources, you can write one parent template that refers to the base templates: 000-base-templates. This allows you to reuse the core Automation resource templates without having to write your own.