diff options
authorLars Wirzenius <>2018-06-30 13:23:29 +0300
committerLars Wirzenius <>2018-06-30 13:23:59 +0300
commit817a03175395405b1f9c5620b1998f71c62d1b88 (patch)
parent5110808439344bd5f66f5b90ecf08835a820acc1 (diff)
Change: README
1 files changed, 98 insertions, 34 deletions
diff --git a/README b/README
index ffb63c9..d48f2bc 100644
--- a/README
+++ b/README
@@ -3,13 +3,31 @@ hetznertool - create VMs in the Hetzner Cloud for QvarnLabs Ab
`hetznertool` is a little utility to make it easier to manage VMs in
the Hetzner Cloud. It's inspired by the OpenStack Heat tooling we've
-used before. The utility can:
+used before at QvarnLabs.
-* list all servers in all hcloud contexts
-* create servers in a context based on a YAML specification file
- * also, update DNS (``)
- * also, write Ansible inventory files
-* delete all servers in a named context
+* The user is expected to create Hetzner Cloud "projects" manually via
+ the web interface: create project, add ssh keys, create an access
+ token.
+* Everything else can be done with hetznertool, which wraps around the
+ Hetzner hcloud tool.
+* User uses hetznertool to create a "context", giving it a name, and
+ the access token from the web UI. hetznertool configures hcloud to
+ use this context.
+* A new project and context is expected for each group of servers,
+ similar to a "stack" in OpenStack. Hetznertool creates all servers
+ in a group in the same context, and deletes all servers in a
+ context.
+* Hetznertool reads server descriptitions from a "foo.hz" file, see
+ below. This is needed for creation also.
+* Hetznertool updates DNS via the QvarnLabs DNS server, or via the
+ service.
+* Hetznertool creates Ansible inventory files ("hosts files").
@@ -18,11 +36,67 @@ Requirements
* Python 3
* `hcloud` from <>
* Download, unpack tarball from above URL.
- * Move `bin/hcloud` into a location on the PATH.
- * Create one or more contexts by going adding projects, ssh keys,
- and access tokens via the Hetzner Cloud console. (See below.)
+ * Move the unpacked `bin/hcloud` into a location on the PATH.
+* `pass` for password storage.
* Get `hetznertool` with git clone from
+ * Maybe copy it somewhere on the PATH.
+Preparation: configure hetznertool
+Create `~/.config/hetznertool/hetznertool.yaml` as a dict, where each
+dict entry is a "profile". You can have one profile for work and
+another for persoanl use. For each profile, define the full set of
+configutation variable.
+ liw:
+ ssh-key: liw-openpgp
+ pass-dir: /home/liw/.password-store
+ pass-subdir: hetzner
+ ns1: ''
+ domain:
+ dnszone-dir: /home/liw/data/
+ dnszone-file:
+ ansible-inventory-dir: /home/liw/code/ick/ick2-ansible
+ style: dns-api
+ ql:
+ ssh-key: liw-openpgp
+ pass-dir: /home/liw/qvarnlabs/code/qvarnlabs-secrets
+ pass-subdir: infra/hetzner
+ ns1:
+ domain:
+ dnszone-dir: /home/liw/qvarnlabs/code/dnszone
+ dnszone-file:
+ ansible-inventory-dir: /home/liw/qvarnlabs/code/qvarn-prov/ansible
+ style: qvarnlabs
+* `ssh-key`: name of ssh key to install for root on servers; this needs
+ to be the name defined in the Hetzner Cloud web UI for the key
+* `pass-dir`: where the `pass` directory is
+* `pass-subdfir`: sub-directory where `pass` stores context tokens
+* `ns1`: ssh target (user@addr) where the primary name server runs,
+ when using a self-hosted name server (e.g., QvarnLabs
+; can be the empty string if `style` is not `qvarnlabs`
+* `style`: which style of DNS updates to do, must be one of `dns-api`
+ or `qvarnlabs`
+* `domain`: domain under which DNS entries are created
+* `dnszone-dir`: directory where DNS zone files are created; it is
+ assumed to be a git checkout
+* `dnszone-file`: file for the DNS zone file
+* `ansible-inventory-dir`: directory where inventory files are to be
+ created
Preparation: Hetzner project creation
@@ -33,11 +107,12 @@ Log into
Create projects as needed, add ssh keys to them, and create access
-tokens for each. Use the access tokens to create "contexts" for
-`hcloud` (run `hcloud context create FOO`, it will ask for the access
+tokens for each. Use the access tokens to create "contexts" by running
+`hetznercloud create-context FOO TOKEN`. Hetznertool puts the token in
+a password store (using `pass`), so it is shared among users of the
+same organisation.
-Use the ssh token at once when creating it: it cannot be recovered
+Use the access token at once when creating it: it cannot be recovered
later (but a new one can be created at will). Not that it's not
necessary to store the access token elsewhere, but do guard the
`.config/hcloud/cli.toml` file, which is where `hcloud` stores the
@@ -50,55 +125,44 @@ This only needs to be done once per project.
-All `hetznertool` invocations should be done in the directory to where
-you cloned it.
+All operations MUST give the `-p profile` option, where the name of
+the profile is defined in the config file (see above).
-Create `~/.config/hetznertool/hetznertool.yaml`:
- ssh-key: liw-openpgp
- ansible-inventory-dir: /home/liw/qvarnlabs/code/qvarn-prov/ansible
-(edit values as suits you).
-List all servers:
+List all servers, with DNS names and IPv4 addresses:
- ./hetznercloud list
+ hetznercloud -p ql list
-Create a server specification file (`qvarn.servers`):
+Create a server specification file (`qvarn.hz`):
type: cx11
image: debian-9
- name: haproxy
- type: cx51
- name: qvarn1
- name: qvarn2
- name: qvarn3
- name: qvarn4
+ - name: qvisvqe
- name: postgres
type: cx51
- - name: qvisvqe
Values from `defaults` are used if a dict in the list in `hosts`
doesn't specify a value.
Create servers (may take a minute per server):
- ./hetznertool create mydev qvarn.server
+ hetznertool -p ql create mydev qvarn.hz
-(where `mydev` is the name of a context). This will write inventory
-files and update DNS, creating names like
+(where `mydev` is the name of an existing context). This will write
+inventory files and update DNS, creating names like
@@ -106,7 +170,7 @@ Delete
Delete sll servers in a context:
- ./hetznertool delete mydev
+ hetznertool -p ql delete mydev
This will also rewrite zone and inventory files to update them to any
remaining servers.