Coreroller

Overview

CoreRoller is a set of tools to control and monitor the rollout of your updates. It's aimed to be an open source alternative to CoreOS CoreUpdate.

Screenshots:

News

May 8, 2017

CoreRoller 1.0 released! The project will use semantic versioning from now on and docker images automatically built will be tagged accordingly as well. If you were already using CoreRoller before this release please check out the release notes below.

Features

Dashboard to control and monitor your applications updates
Ready to serve updates for to CoreOS clusters out of the box
Manage updates for your own applications as well, not just CoreOS
Define your own groups and channels, even for the CoreOS application (pre-installed)
Define roll-out policies per group, controlling how updates should be applied to a set of instances
Pause/resume updates at any time at the group level
Statistics about versions installed in your instances, updates progress status, etc
Activity stream in UI to get notified about important events or errors
Post HipChat notifications about important events
Based on the Omaha protocol developed by Google

Status

CoreRoller is stable. It has been used in production enviroments for over a year without any major issues.

Please report any bug you find as issues on this repository.

Getting started

The best way to give it a try is to launch a Docker container using the public images hosted in Docker Hub:

docker run -d -p 8000:8000 coreroller/demo

Once the container is up, just point your browser to:

http://localhost:8000/

and you should be ready to go. Default username/password is admin/admin.

This demo container runs PostgreSQL (the datastore used by CoreRoller) and the CoreRoller server (aka rollerd).

In addition to this coreroller/demo image, there are some other images available in the docker hub that may be helpful to you as a starting point when preparing your own custom images.

coreroller/rollerd: this image runs the backend server, a dependency free Golang binary that will power the dashboard and serve all Omaha updates and events requests.
coreroller/postgres: this image runs PostgreSQL and creates the database used by CoreRoller. Do not forget to setup properly the volumes in the container to avoid any data loss.

These images are rebuilt and tagged automatically after every commit. Dockerfiles used to build them can be found in the backend/docker directory.

Additionally, in the backend/systemd directory there are some systemd unit files that might be handy in case you want to deploy CoreRoller in your CoreOS cluster using fleet. You can also use the sample kubernetes configuration files in the backend/kubernetes folder to deploy CoreRoller using kubernetes (kubectl create -f backend/kubernetes). These units and config files are just samples, feel free to adjust them to suit your specific needs.

Managing CoreOS updates

Once you have CoreRoller up, it's time to give it some work to do. You may be interested in managing the CoreOS updates in your cluster with it.

The process is slightly different if you want to do it in existing machines or in new ones. In both cases it's very simple as it only requires updating the server url the CoreOS updater uses to pull updates from. By default your CoreOS instances use the public CoreOS servers to get updates, so you'll have to point them to your CoreRoller deployment instead.

New machines

In new machines, you can set up the updates server in the cloud config. Here is a small example of how to do it:

coreos:
	update:
		group: stable
		server: http://your.coreroller.host:port/v1/update/

In addition to the default stable, beta and alpha groups, you can also create and use custom groups for greater control over the updates. In that case, you must use the group id (not the name) you will find next to the group name in the dashboard.

coreos:
	update:
		group: ab51a000-02dc-4fc7-a6b0-c42881c89856
		server: http://your.coreroller.host:port/v1/update/

Note: The sample CoreRoller containers provided use the port 8000 by default (plain HTTP, no SSL). Please adjust the update url setup in your servers to match your CoreRoller deployment.

Existing machines

To update the update server in existing instances please edit /etc/coreos/update.conf and update the SERVER value (and optionally GROUP if needed):

SERVER=https://your.coreroller.host/v1/update/

When using custom groups instead of the official ones (stable, beta, alpha) the group id must be used, not the group name:

GROUP=ab51a000-02dc-4fc7-a6b0-c42881c89856

To apply these changes run:

sudo systemctl restart update-engine

In may take a few minutes to see an update request coming through. If you want to see it sooner, you can force it running this command:

update_engine_client -update

Note: the CoreUpdate docs do a great job explaining in detail how this process works and most of the information it contains applies to CoreRoller as well, so please have a look at them here for more information.

CoreOS packages in CoreRoller

Out of the box CoreRoller polls periodically the public CoreOS update servers to create packages and update channels in your CoreRoller deployment as they become publicly available. So if rollerd has access to the Internet you'll see eventually new packages (pointing to the official image files) added to the CoreOS application in CoreRoller. This functionality can be disabled if needed (i.e. you want to deploy your custom built images, etc) using the rollerd flag -enable-syncer=false.

By default, CoreRoller only stores metadata about the official CoreOS packages available, not the packages payload. This means that the updates CoreRoller serves to your instances contain instructions to download the packages payload from the public CoreOS update servers directly, so your servers need access to the Internet to download them.

In some cases, you may prefer to host the CoreOS packages payload as well in CoreRoller. When CoreRoller is instructed to behave this way, in addition to get the packages metadata, it will also download the package payload itself so that it can serve it to your instances when serving updates.

Enabling CoreOS packages payload hosting requires passing some parameters to rollerd:

rollerd -host-coreos-packages=true -coreos-packages-path=/PATH/TO/STORE/PACKAGES -coreroller-url=http://your.coreroller.host:port

Managing updates for your own applications

In addition to manage updates for CoreOS, you can use CoreRoller for your own applications as well. It's really easy to send updates and events requests to the Omaha server that CoreRoller provides.

In the updaters/lib directory there are some sample helpers that can be useful to create your own updaters that talk to CoreRoller or even embed them into your own applications.

In the updaters/examples you'll find a sample minimal application built using grace that is able to update itself using CoreRoller in a graceful way.

Other features

HipChat notifications

CoreRoller supports posting notifications to HipChat when certain events occur. This way you'll be notified when a channel points to a new package, a rollout starts, fails or succeeds, etc.

Enabling HipChat notifications requires setting a couple of environment variables for rollerd:

CR_HIPCHAT_ROOM=ROOM_ID
CR_HIPCHAT_TOKEN=TOKEN

Contributing

CoreRoller is an Open Source project and we welcome contributions. Before submitting any code for new features or major changes, please open an issue and discuss first.

Below you will find some introductory notes that should point you in the right direction to start playing with the CoreRoller source code.

Backend

The CoreRoller backend (aka rollerd) is a Golang application. Builds and vendored dependencies are managed using gb, so you just need a working Golang environment and gb installed to start working with it (there is no need to do a go get to fetch the dependencies as they are already contained in backend/vendor).

The backend source code is located inside backend/src and is structured as follows:

Package api: pr