From 817a03175395405b1f9c5620b1998f71c62d1b88 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 30 Jun 2018 13:23:29 +0300 Subject: Change: README --- README | 132 ++++++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file 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 (`CONTEXT-PROJECT.h.qvarnlabs.eu`) - * 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 + dns-api.com service. + +* Hetznertool creates Ansible inventory files ("hosts files"). Requirements @@ -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 `ssh://git@git.qvarnlabs.net/hetznertool` + * 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: vm.liw.fi + dnszone-dir: /home/liw/data/dns-api.com/zones + dnszone-file: vm.liw.fi + 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: root@ns1.qvarnlabs.net + domain: h.qvarnlabs.eu + dnszone-dir: /home/liw/qvarnlabs/code/dnszone + dnszone-file: db.h.qvarnlabs.eu + ansible-inventory-dir: /home/liw/qvarnlabs/code/qvarn-prov/ansible + style: qvarnlabs + +Variables: + +* `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 + ns1.qvarnlabs.net); 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 https://console.hetzner.cloud/projects 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 -token). +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. Use ============================================================================= -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). -Config ------------------------------------------------------------------------------ - -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 ----------------------------------------------------------------------------- -List all servers: +List all servers, with DNS names and IPv4 addresses: - ./hetznercloud list + hetznercloud -p ql list Create ----------------------------------------------------------------------------- -Create a server specification file (`qvarn.servers`): +Create a server specification file (`qvarn.hz`): defaults: type: cx11 image: debian-9 hosts: - 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 `mydev-haproxy.h.qvarnlabs.eu`. Delete @@ -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. -- cgit v1.2.1