kevinheader / atlas

Automating the deployment, configuration, and maintenance of DevOps engineering systems

Atlas

---

Atlas is a tool for automating the deployment, configuration, and maintenance of DevOps engineering systems. It can be run interactively from the command line, or can be run entirely unattended as part of an Azure DevOps (formerly known as VSTS) build or release definition. An Atlas workflow revolves around making the appropriate REST API calls to Azure DevOps, Active Directory, and Azure Resource Manager.

There is a REST API for everything. With Atlas you can make the configuration of everything from CI/CD to production servers consistent, reproducible, and reviewable by capturing them as source controlled templates.

---

Install

Atlas is currently under active development.

Daily builds of the Atlas CLI are available as self-contained downloads:

Platform	Master Branch (0.1)	Latest Build
Windows x64	Download latest zip
Linux x64	Download latest tar.gz

If you want to use a package manager:

Install global tool (Windows or Linux)

1. If dotnet --version isn't >= 2.1.300 then install or upgrade .NET Core
2. dotnet tool install -g atlas-cli --add-source https://aka.ms/atlas-ci/index.json

Getting Started

An existing workflow can be executed directly from a public web server. You can run any of the examples in this repository with the atlas deploy command:

atlas deploy https://github.com/Microsoft/Atlas/tree/master/examples/101-messages

Creating a new workflow

To create a new workflow, from a console window execute mkdir demo to create a new subfolder.

Add a demo/workflow.yaml file to declare operations:

operations:
- message: Running my workflow...
- message: {{ info.greeting }}, {{ info.name }}!
- message: "All values: {{ json . }}"

Add a demo/values.yaml file to declare defaults:

info:
  greeting: Hello
  name: World

Run it!

> atlas deploy demo --set info.name=Atlas

Atlas

  - Running my workflow...

  - Hello, Atlas!

  - All values: {"info": {"greeting": "Hello", "name": "Atlas"}}

Exploring the examples

You can also clone the Atlas GitHub repo to explore the examples and see kinds of operations Atlas can perform.

git clone https://github.com/Microsoft/Atlas.git
cd Atlas/examples
atlas deploy 101-messages

Features

• YAML or JSON syntax to define workflows and input parameters

• Handlebars template engine enables workflows to be highly flexible

• JMESPath provides query language for inputs, outputs, and data transformations

• Works cross-platform as a .NET Core executable

• Invokes any Azure RM, Azure AD, or Azure DevOps REST API

• From the command line, REST API calls are secured via interactive Active Directory login, similar to az login

• From an Azure DevOps build or release definition, REST API calls are secured via Azure DevOps service connection to Azure

• Renders output values and additional templated files to a target folder

• Operations support conditional executions, retries and looping, and can throwing detailed exceptions

• Extensively detailed log output and safe --dry-run support simplify troubleshooting

• Values which are declared secret are redacted (replaced with xxxx) when written to console output and log files

Limitations

• Does not allow arbitrary code or command-line execution in order to limit what can be done to the machine executing a workflow

• Currently designed for Active Directory authentication for Azure and Azure DevOps resources

• Not yet available as a class library package

Goals

• Packing workflows into zip or tarball archive files, publishing and executing workflows from feed locations

• Establishing a repository for collaboration on common in-progress and stable workflows, and default location for common workflows

• Shared workflows for larger scenarios, e.g. ASP.NET Core services on Kubernetes with Azure DevOps CI/CD, Azure VM clusters, Azure DNS, ATM, and ALB for geo-redundant load balancing and service routing

---

System Requirements

Running Atlas

Atlas runs on Windows and Linux. Windows 10 and Ubuntu 16.04 are the tested environments.

Building Atlas from source

Prerequisites:

• Required: Download and install the .NET Core SDK
• Optional: Install or update Visual Studio 2017
• Optional: Download and install Visual Studio Code

To clone and build from source, run the following commands from a console window:

git clone https://github.com/Microsoft/Atlas.git
cd Atlas
build.cmd *or* ./build.sh

Running Atlas from source

To run locally from source, run the following commands:

dotnet restore
./atlas.sh

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.