molecule-hetznercloud/README.md

214 lines
6.3 KiB
Markdown
Raw Normal View History

# Molecule Hetzner Cloud Plugin
2020-04-24 11:15:45 +00:00
[![Drone CI-CD](https://drone.autonomic.zone/api/badges/autonomic-cooperative/molecule-hetznercloud/status.svg)](https://drone.autonomic.zone/autonomic-cooperative/molecule-hetznercloud)
[![PyPI Package](https://badge.fury.io/py/molecule-hetznercloud.svg)](https://badge.fury.io/py/molecule-hetznercloud)
[![Repository License](https://img.shields.io/badge/license-LGPL-brightgreen.svg)](LICENSE)
2020-04-25 06:14:56 +00:00
A [Hetzner Cloud](https://www.hetzner.com/cloud) plugin for [Molecule](https://molecule.readthedocs.io/en/latest/).
This plugin allows you to do `molecule init role myrolename -d hetznercloud`
and have Molecule provision on-demand Hetzner Cloud VPSes of your choice for
your integration testing. New VPSes will be automagically created and
provisioned on each `molecule test` run, SSH keys are generated and managed
2020-04-25 06:16:06 +00:00
internally and all resources are cleaned up regardless of whether the role
under test succeeds or fails.
2020-04-25 06:14:56 +00:00
## Support
2020-04-25 06:17:16 +00:00
If you use this plugin in a commercial setting or you find it personally
2020-04-25 06:17:46 +00:00
useful, please support my maintenance work financially through my
[Liberapay](https://liberapay.com/decentral1se/) profile or through my [Github
Sponsor profile](https://github.com/sponsors/decentral1se). I do not receive
any financial support from RedHat or Hetzner Cloud for this work.
2021-01-06 21:22:00 +00:00
## Install
```bash
$ pip install molecule-hetznercloud
```
2021-06-02 11:05:25 +00:00
If you're looking for a container approach, see [ansible-community/toolset](https://github.com/ansible-community/toolset).
2021-01-06 21:22:00 +00:00
## Upgrade
Please see the [CHANGELOG.md](./CHANGELOG.md) for migration guides.
```bash
$ pip install --upgrade molecule-hetznercloud
```
2020-04-24 11:15:45 +00:00
## Usage
2020-04-25 06:14:56 +00:00
You need to expose a `HCLOUD_TOKEN` environment variable in your environment.
2020-04-27 14:27:23 +00:00
2020-04-25 06:18:49 +00:00
Find out more about how to get one of those [over here](https://docs.hetzner.cloud/#overview-authentication).
2020-04-25 06:14:56 +00:00
```bash
$ export HCLOUD_TOKEN=mycoolapitoken
```
2021-01-06 21:22:15 +00:00
Then create a role using the driver plugin.
2020-04-25 06:14:56 +00:00
```bash
$ molecule init role myrolename -d hetznercloud
```
Your `myrolename/molecule/default/molecule.yml` should then look like the following.
```yaml
---
dependency:
name: galaxy
driver:
name: hetznercloud
platforms:
2020-04-27 14:27:23 +00:00
- name: instance
2020-04-25 06:14:56 +00:00
server_type: cx11
image: debian-10
provisioner:
name: ansible
verifier:
name: ansible
```
Please see [docs.hetzner.cloud](https://docs.hetzner.cloud/) for information regarding images and server types.
Then just run the role.
```bash
$ cd myrolename && molecule test
```
2020-04-26 19:07:06 +00:00
To ease initial debugging for getting things started, also expose the following
2020-04-25 06:14:56 +00:00
environment variables.
```bash
$ export MOLECULE_NO_LOG=False # not so verbose, helpful
$ export MOLECULE_DEBUG=True # very verbose, last ditch effort
```
2021-01-06 12:13:51 +00:00
## Volume Handling
2021-01-06 11:17:20 +00:00
2021-06-02 11:06:57 +00:00
> **WARNING**: this feature appears to be broke. See [#24](https://github.com/ansible-community/molecule-hetznercloud/issues/24) for more
2021-06-02 11:04:04 +00:00
2021-06-02 11:06:57 +00:00
It is possible to have the driver manage volumes during the test run. You can
add the following stanza to your Molecule configuration to have Molecule create
this volume for the managed VPS. This volume will be cleaned up after use.
2021-01-06 11:17:20 +00:00
```yaml
2021-05-28 13:30:17 +00:00
platforms:
- name: instance
server_type: cx11
image: debian-10
volumes:
- name: "molecule-hetznercloud-volume-1-${INSTANCE_UUID}"
location: /foo/bar
- name: "molecule-hetznercloud-volume-2-${INSTANCE_UUID}"
size: 20
2021-01-06 11:17:20 +00:00
```
2021-01-06 14:21:42 +00:00
Supported keys are:
- **name** (required): name of volume
- **size** (optional, default: `10GB`): size of volume
- **location** (optional, default: `omitted`): path for volume
2021-05-28 13:30:17 +00:00
## Network Creation
This Driver is able to generate networks and subnetworks during the test run.
This can be useful for cluster tests. You can create networks with the
following snippet:
```yaml
platforms:
- name: instance1
server_type: cx11
image: debian-10
networks:
test-network:
ip_range: 10.10.0.0/16
subnet:
ip: 10.10.10.1/24
type: cloud
network_zone: eu-central
test-network-2:
ip_range: 10.20.0.0/16
subnet:
ip: 10.20.10.1/24
- name: instance2
server_type: cx11
image: debian-10
networks:
test-network:
subnet:
ip: 10.10.10.2/24
```
The networks **ip_range** is only important for creating. If you have multiple
hosts, it is okay to only define **ip_range** once. The supported keys are:
- **networks**
- **ip_range** (required): ip range of network (usually `/16`)
- **subnet**
- **ip** (required): ip that should be assigned to host (also generates subnetwork) - prefix mandatory
- **type** (optional, default: `cloud`): type of subnetwork
- **network_zone** (optional, default: `eu-central`): network zone of subnetwork
2020-04-27 14:27:23 +00:00
## Only use `molecule.yml` for configuration
It is being worked on that it is possible to remove all the files except the
`molecule.yml` scenario file in your scenario directory. This is useful when
you only require this plugin to do the default behaviour each time. It is also
useful to reduce maintenance effort for migration of configurations. This
plugin currently embeds the `create.yml` and `destroy.yml` playbooks. All other
playbooks (e.g. prepare, cleanup) can be created as needed and Molecule will
pick them up and run them. Embedding the `converge.yml` awaits [this feature
request](https://github.com/ansible-community/molecule/issues/2675).
2020-04-24 11:15:45 +00:00
## Mirroring
2020-04-25 06:14:56 +00:00
Issues will be responded to on both issue trackers.
- [git.autonomic.zone](https://git.autonomic.zone/autonomic-cooperative/molecule-hetznercloud) (primary)
- [github.com](https://github.com/ansible-community/molecule-hetznercloud) (mirror)
2020-04-25 06:24:39 +00:00
## Change log
See [CHANGELOG.md](./CHANGELOG.md).
2020-04-24 11:15:45 +00:00
## Molecule Documentation
2020-04-24 11:15:45 +00:00
> https://molecule.readthedocs.io
2020-04-24 11:15:45 +00:00
## Contact
2021-06-02 09:12:56 +00:00
- Ping @decentral1se on the `#ansible-molecule` channel on [Libera](https://libera.chat/).
2020-04-24 11:15:45 +00:00
## License
2020-04-25 06:34:01 +00:00
The [LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.en.html) license.
2020-04-24 12:12:57 +00:00
## Testing
2020-04-25 06:14:56 +00:00
This is all done on our [drone.autonomic.zone](https://drone.autonomic.zone/autonomic-cooperative/molecule-hetznercloud) setup.
2020-04-27 14:27:23 +00:00
### Unit
2020-04-24 12:12:57 +00:00
```bash
$ pip install tox
$ tox -v
```
2020-04-27 14:27:23 +00:00
### Integration
2020-04-24 12:12:57 +00:00
2021-06-02 11:14:05 +00:00
```
git clone https://github.com/ansible-community/molecule-hetznercloud.git
cd molecule-hetznercloud
python3 -m venv .venv && source .venv/bin/activate
2021-06-02 11:21:37 +00:00
pip install -e . "ansible<4" netaddr
2021-06-02 11:14:05 +00:00
export INSTANCE_UUID=$(openssl rand -hex 5)
export HCLOUD_TOKEN=YOURKEY
cd integration && molecule test
2020-04-24 12:12:57 +00:00
```