ansible-crucible v0.4.0

Crucible for Ansible

Crucible is a tool for writing Ansible Playbooks as Javascript or Typescript Code. Ansible as Code, as it were.

Features Overview:

• Run Ansible Tasks and Plays with Javascript/Typescript
• Simple, in-line secret editing
• Include complex logic in your Plays

Background

I'm a software engineer. I write code. I've been using Ansible for a while now to manage my home lab and make life easier when I have to rebuild servers or VMs. I recently extended from just using Ansible to using Pulumi as well for handling VM creation and management. Pulumi is similar to Terraform, but instead of a custom configuration language (HCL in the case of Terraform), Pulumi lets you define your Infrastructure using an actual programming language. This provides me with immense flexibility and I can use all the power of a programming language (for loops, if/else logic, etc.) to define my infrastructure. It's awesome.

Well, I wanted to be able to apply the same power and flexibility to my Ansible setup. I've run into many cases in Ansible where it would be so nice to just use an if or for statement without trying to figure out the logic and limitations of Ansible's when:, with_items:, etc.

So, I decided to see what I could make, and Crucible was born.

Installation

> yarn install ansible-crucible

Usage

Creating a new Crucible project

> crucible init <project name>

This will create a new crucible project in the current directory, with a sample program, the necessary config files, and an appropriate .gitignore.

Managing Secrets

> crucible vault create <vault name> # Start a wizard to define a new vault

Once a vault is defined, you can include secrets in your code files like so:

import { secret } from 'ansible-crucible';
const some_secret = secret('vault_name', { foo: 'bar' }) // The secret value may be any JSON-serializable value

You can also encrypt parts of non-code files like so:

some:
  value:
    - CRUCIBLE_SECRET(vault_name, secret)

Or encrypt the whole file by adding a first line (any comment format will work - Crucible just looks for the presence of CRUCIBLE_ENCRYPT_FILE on the first line of the file):

# CRUCIBLE_ENCRYPT_FILE(vault_name)

After adding some secrets, encrypt them all in-place:

> crucible vault encrypt [file] # Encrypt all of the secrets in the project or in a given file

To decrypt, you can:

> crucible vault decrypt [file] # Decrypt all of the secrets in the project or in a given file

Or:

> crucible vault edit <file> # Decrypt, open, and re-encrypt the given file

If you're using Git, Crucible will configure a pre-commit hook that will attempt to catch non-encrypted secrets.

NB: By default, the all-file versions of the vault commands will only include files of types .js, .ts, .json, .yml, .yaml, .conf, .cnf, .cf, .ini. This can be changed via the secrets.file_types config parameter. The Git pre-commit hook will check all staged files - not just those of these types.

Licensing

This project is still in it's infancy and I'm unsure of where it will go for me - whether it will continue to just be a side/fun project, or if it has the ability to pay for some of the time that I've spent on it. I'm a lover of Open Source and feel that it can have great use amongst nerds and homelabbers like me, so I wanted to share it as soon as I could. However, for now, I'm reserving my rights when it comes to commercial use, and have defined the below guidelines (which may admittedly change in either direction, so fair warning there). If you're interested in using this tool commercially, I'd love to hear about your use case and am willing negotiate licensing.

• Personal Use is fully permitted
• Commercial Use:
  • May be used by companies of fewer than 3 developers/engineers in the following cases:
    • May be used for internal projects
    • May be used to deploy a customer facing product
  • May not be used with customers (eg where a company manages automation/deployment/systems for another company)
  • May not be used in any production systems or workflows by companies with greater than 3 developers/engineers
  • Forks are permitted, but copy-left is required
  • Contact author to negotiate otherwise