Skip to content

A complete environment that helps you create, manage, and test your Azure Automation runbooks in a standardized and efficient way.

License

Notifications You must be signed in to change notification settings

workoho/AzAuto-Common-Runbook-FW

Repository files navigation

Contributors Forks Stargazers Issues MIT License Workoho


Logo

Azure Automation Common Runbook Framework

A complete environment that helps you create, manage, and test your Azure Automation runbooks in a standardized and efficient way.
Explore the docs »

Open template in GitHub Codespaces     View template online in Visual Studio Code
Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Contributing
  5. License
  6. Maintainers
  7. Projects using this framework

About The Project

Starting a new Azure Automation project can be very time consuming. After you create an Automation account, you have a blank slate to start writing your PowerShell runbooks. You are wondering how to start developing locally and what to consider now to work around the Azure Automation sandbox limitations and avoid running on a virtual machine with a hybrid worker.

Quick Summary

The purpose of the framework: The framework is designed to provide a repeatable way to set up and reconfigure an Azure Automation instance, and to enable modular runbook development with common child runbooks.

The features of the framework: The framework supports best practice standard runbooks, local development, versioning and release management, multi-platform compatibility, and integration with other systems.

The development environment options: The framework allows the use of development containers on GitHub Codespaces, Docker, or any remote server to launch a consistent and reliable PowerShell development environment.

Built With

Azure Automation GitHub Codespaces Visual Studio Code PowerShell

(back to top)


1. Setup with ease

With this framework, you can easily set up and change your Azure Automation instance. For example, activating managed identities, adding permissions for them in the Microsoft Azure Cloud, the Microsoft Entra directory and enterprise applications in your tenant.

2. Best practice standard runbooks

It also provides common child runbooks to start modular runbook development from day one.

You can start these from your own runbooks by using inline execution to do very basic tasks that you usually want to do the same way in many runbooks. For example, connecting to Azure Cloud, Microsoft Graph API, Exchange Online API, etc. In addition, you probably want to know more about the tenant and the environment you are working in so that you can use this information in your script.

Debugging is also an important part of development and daily operations. The common runbooks provided help you to filter out unnecessary information, e.g. when importing modules. They help you to focus on the actual debugging information that you have included in your own code and not on what PowerShell modules have included for debugging themselves. The output and debugging information from child runbooks is always visible, so you can quickly and easily identify the line of code you may need to correct.

Writing secure automations is also very important because we are often dealing with very sensitive parts of the infrastructure, such as identity management issues and the administration of roles and privileges. This requires additional effort and code and is not the first priority for what you actually need to achieve from a functional perspective. Dedicated common runbooks provide a standard approach to critical security issues that can be easily integrated into your own automations so you can focus on what you want to achieve.

3. Runbook development made easy

Developing your runbooks can be annoying because triggering a new job in Azure Automation takes a long time, especially when using the serverless Azure Automation sandbox.

The framework includes common runbooks that make it faster and cheaper to develop locally. They are designed to work with interactive connections to Microsoft services when you are developing locally on your workstation and use managed identities when running as an actual Azure Automation job.

When testing in the Azure Automation Sandbox, a draft version of all your updated runbooks can be easily synchronized with a single command, without interrupting your live runbooks. Of course, you can also set up a 1-to-1 copy of your production Automation Account for testing and development. Since setting up your runtime environment is just some keystrokes away, this might even be your preferred option.

We also support the new Azure Automation Runtime Environments, which offer you even more flexibility during development and production rollout.

4. Versioning and release management

Tracking changes is just as important as communicating those changes to your team to keep your runbooks running. Correct and easy versioning is an essential part of this. It starts with the very first line of code, leads to a testing phase and ends in a production release, so the cycle can start from the beginning. Continuous improvement according to the motto "publish often, publish fast" requires a clear process. This framework is designed to support you on several levels and is fully compatible with Semantic Versioning 2.0.

5. Development environment without barriers

Speaking of setting up your development environment: To get things started as quickly as possible, you can use Development Containers on either GitHub Codespaces, Docker on your workstation, or any remote server to launch a consistent and reliable PowerShell development environment. With GitHub Codespaces, you can even do this in your browser without having to install anything on your local device. Visit Visual Studio Code docs to learn more about developing inside a container.

6. Multi-platform support

All common runbooks are designed to run on multiple platforms, including Windows PowerShell 5.1 on Windows and modern PowerShell Core on Windows, Linux, and macOS. This provides the most flexibility for developing and maintaining your automation projects.

Due to feature limitations of PowerShell 7 runbooks in Azure Automation, all common runbooks are backward compatible and will use Windows PowerShell 5.1 within the Azure Automation sandbox.

7. Integrate with other systems in your organization

The provided template comes with some sample runbooks to demonstrate how you can use the common runbooks and write standardized runbooks that can be easily integrated into your enterprise environment. For example, you can send a job result in JSON format, including important and useful metadata about the job status, to your back-end systems for further processing (e.g., ServiceNow, Tenfold, etc.). The result can either be submitted using a webhook, or by manually polling the PowerShell output stream of the Azure Automation job using a service principal with limited access to your Automation Account.

(back to top)

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

This is an example of how to list things you need to use the software and how to install them.

Installation

  1. Describe Step 1.

  2. Describe Step 2.

(back to top)

Usage

Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.

For more examples, please refer to the Wiki.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Maintainers

Project Link: https://github.com/workoho/AzAuto-Common-Runbook-FW

(back to top)

Projects using this framework

(back to top)