asteris-llc / Converge

This project is no longer actively maintained.

Converge is a configuration management tool that makes it easy to manage servers, laptops and other devices.

Key features:

• Easy to install and run. A single binary and configuration file is all you need.
• Resources to make changes on your system: docker images and containers, users and groups, systemd, and more. The Resource Reference at converge.aster.is has a complete list of resources and their configuration settings.
• A powerful graph engine that automatically generates dependencies and runs tasks in parallel.
• API-first communication using grpc.
• Module verification: only run trusted modules.

Table of Contents

• Converge
  • Installation
  • Documentation
  • Usage
  • Development
    • Tools
    • RPC
    • Continuous Integration and Testing
  • License

Installation

The install-converge.sh script will download and install the converge binary to your /usr/local/bin/ directory:

sudo ./install-converge.sh -v 0.4.0

The same installation script is available at get.converge.sh:

curl get.converge.sh | sudo bash -

You can also use go get:

go get github.com/asteris-llc/converge

or download a release for your platform from the releases page on Github.

Documentation

Comprehensive documentation can be found at converge.aster.is.

You can learn more about Converge from the following blog posts and presentations:

• Introducing Converge
• Conditionals In Converge
• Converge Presentation to STL DevOps

Usage

Converge uses HCL for syntax. HCL is a superset of JSON that looks (and acts) quite a bit nicer.

The basic unit of composition in converge is the module. Modules have parameters and contain resources. Creating a module looks something like this:

# write "hello world" to disk
param "message" {
  default = "Hello, World in {{param `filename`}}"
}

param "filename" {
  default = "test.txt"
}

file.content "render" {
  destination = "{{param `filename`}}"
  content     = "{{param `message`}}"
}

Invoke this with converge apply --local samples/fileContent.hcl to place a test file on your system. You can also converge plan --local samples/fileContent.hcl to see what changes will be made before you apply them.

Development

Tools

For linting, you'll need:

RPC

You'll need:

• Google's protobuf compiler, 3.0 or above.
• The go protoc plugin: go get -a github.com/golang/protobuf/protoc-gen-go
• The grpc gateway plugin(s): go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger

Continuous Integration and Testing

We use Wercker for CI with a custom base image. The Dockerfile for that image can be found at /ci/Dockerfile in the root of the project, and is pushed as asteris/converge-ci. You can test Converge in the container with the following invocation:

docker run -i \
           -t \
           --rm \
           --volume $(pwd):/go/src/github.com/asteris-llc/converge \
           asteris/converge-ci \
           /bin/bash -c 'cd /go/src/github.com/asteris-llc/converge; make test'

Benchmarks are run with make bench, and fuzzing is run with make fuzzing/{target}.

License

Converge is licensed under the Apache 2.0 license. See LICENSE for full details.