oceanix

A small program to do nix deployments & provisioning into digitalocean.

This has a small subset of the features in nixops.

Installation

$ nix-env -i -f .

Usage

Environment

• You must set:
  • DIGITALOCEAN_ACCESS_TOKEN to do anything involving digitalocean
  • DIGITALOCEAN_SPACES_ACCESS_KEY and DIGITALOCEAN_SPACES_SECRET_KEY to upload images.
• You can set:
  • DEPLOY_NETWORK, DEPLOY_REGION, DEPLOY_TAG, DEPLOY_SPACES_REGION, DEPLOY_SPACES_BUCKET

    These will stand in for arguments like --network, --tag etc.

Network definition

You need a network file, which should look mostly like what nixops wants.

The network file should have an attribute set in it containing a thing called network, and then other things which are the machines.

{
  network = {
    name = "my network";
    defaults = {
       deployment.sshKey = "ssh-rsa AAA ...";
       deployment.digitalOcean.region = "lon1";
    };
  };

  machine1 = {config, pkgs, ...} : {
    deployment.digitalOcean.size = "c-32";
    ...
    services.nginx.enable = true;
  };

  machine2 = ...;
}

Extra things you can put in machine config or default are:

deployment.digitalOcean.size

a digitalocean size slug

deployment.digitalOcean.region

a digitalocean region slug

deployment.digitalOcean.image

either the numeric ID of an image, or the name of an image. You can make an image using oceanix image or oceanix base-image.

deployment.digitalOcean.tag

This isn’t something you can change, but you can refer to it elsewhere in the config; for example if you have tags live and staging and you want those to go into the hostname you could say

networking.hostName = "my-thing-${deployment.digitalOcean.tag}";
    

Note that you can get hold of a lot of this kind of information dynamically as well using the digitalocean metadata service, but this is a little easier and more nixy.

deployment.sshKey

an ssh public key; this will be enabled for root ssh login on the machine, and also added to digitalocean’s cloud-init setup.

deployment.copies

an integer; if > 1, this machine will be replaced with machine-1 machine-2 … machine-n.

deployment.addHost

true/false, if true this machine’s ip address will be baked into /etc/hosts on all the machines against its name. For copies > 1 the addresses of every copy will be baked in.

deployment.keys

A set of keys, like in nixops; you can write things like

deployment.keys.smtp = {
  keyFile = /path/to/secret.key;
  user = "root"; group = "root"; permissions = "0600";
  transient = false;
};

deployment.keys.fromPass.keyCommand = ["pass" "show" "secret-thing"];
    

If you set transient = true the key is copied into /run/keys and will be lost on reboot. If you set transient = false the key is copied into /var/keys and symlinked into /run/keys. The symlinks are restored on reboot.

A bit like nixops there is a service you can depend on; it is called keys@keyname so you could say after = [ "keys@smtp.service" ]; and wants = [ "keys@smtp.service" ]; to wait for that key.

Creating a base image

oceanix depends on having a nixos image to start from (unlike nixops, which uses a fearsome script to brain-wipe an existing install).

It can create you an image with

$ oceanix base-image -k "SOME SSH PUBLIC KEY" -u base-image --spaces-bucket my-images

This will upload the image to lon1 under the name base-image, by transferring it via an S3 bucket called my-images in ams3.

Alternatively you can create images for a specific deployment with

$ oceanix image -n network.nix -u --spaces-bucket my-images

This will create images for each machine and upload them under the name given in deployment.digitalOcean.image.

Deploying a network

Deployments to go a digitalocean tag; if you run

$ oceanix deploy -n network.nix -t deployment-tag

this will

1. List the machines on digitalocean tagged with deployment-tag
2. List the machines defined in network.nix
3. Create / destroy droplets so that there is exactly one droplet with deployment-tag for each machine in network.nix, whose name will be the name used in network.nix

   This stage is where oceanix provision stops.

4. Build system root for these machines
5. Deploy system root to the machines

Limitations

• If you change a machine’s size or region, this is not aligned later, or reported on.

  Management of regions in general is fairly poor.

• Some default configuration is baked into digitalocean.nix, which you can’t replace right now.
• The nix evaluation is done for every machine in the whole system in one go, which uses up a lot of memory if you have a lot of machines.

  If you have a lot of identical machines you can say deployment.copies = N on them though.

• Host key checking is off, which is clearly not what anyone wants