# Molecule Hetzner Cloud Driver
[](https://pypi.org/project/molecule-hetznercloud/)
[](https://app.codecov.io/gh/ansible-community/molecule-hetznercloud/tree/main)
[](LICENSE)
A [Hetzner Cloud](https://www.hetzner.com/cloud) driver for [Molecule](https://ansible.readthedocs.io/projects/molecule/).
This plugin allows you to use on-demand Hetzner Cloud servers for your molecule integration tests.
## Install
```bash
$ pip install molecule-hetznercloud
```
## Upgrade
This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
```bash
$ pip install --upgrade molecule-hetznercloud
```
### Upgrading to v2
- In your `molecule.yml` files, rename the molecule driver name (`driver.name`) to `molecule_hetznercloud`:
```patch
driver:
- name: hetznercloud
+ name: molecule_hetznercloud
```
- In your `molecule.yml` files, the volumes name (`platforms[].volumes[].name`) field is now required. If the field is missing, you MUST add it:
```patch
platforms:
- name: instance-1
image: debian-12
volumes:
- - size: 20
+ - name: volume-1
+ size: 20
```
- Each resource (servers, volumes, networks) name are prefixed with a hash (32 chars) based on the role and scenario path. This means you MAY reuse the same names (e.g. `instance-1`) across your scenarios. Resource names MUST not exceed their max length, for example the server name max length is 63 chars, with the prefix you only have 31 chars left for your name.
- In your `molecule.yml` files, the platforms server type (`platforms[].server_type`) field now defaults to `cx22`. If you already use the default, you MAY remove the field:
```patch
platforms:
- name: instance-1
image: debian-12
- server_type: cx22
```
## Usage
To communicate with the Hetzner Cloud API, you need to expose a `HCLOUD_TOKEN` environment variable. Find out more about how to get a Hetzner Cloud API token in the [authentication documentation](https://docs.hetzner.cloud/#authentication).
```bash
$ export HCLOUD_TOKEN="set_the_hcloud_token_here"
```
Then setup a new molecule scenario using the driver plugin.
```bash
$ molecule init scenario --driver-name molecule_hetznercloud
```
> [!WARNING]
> With molecule 6, the `molecule init scenario` command dropped support for driver provided configuration. If you are using molecule >=6, please copy the example below and paste it in your scenario `molecule.yml` file.
> See [this commit](https://github.com/ansible/molecule/commit/21dcd2bb7e8e9002be8bbc19de3e66ec3ce586f1) for details.
Your `molecule/default/molecule.yml` should then look like the following.
```yaml
---
driver:
name: molecule_hetznercloud
platforms:
- # Name of the Server to create (must be unique per Project and a valid hostname as per RFC 1123).
# required
name: instance-1
# Name of the Image the Server is created from.
# required
image: debian-12
# Name of the Server type this Server should be created with.
# default: cx22
server_type: cx22
# Name of Location to create Server in (must not be used together with datacenter).
# default: omit
location: hel1
# Name of Datacenter to create Server in (must not be used together with location).
# default: omit
datacenter: null
# Cloud-Init user data to use during Server creation. This field is limited to 32KiB.
# default: omit
user_data: null
# List of volumes to attach to the server.
volumes:
- # Name of the volume.
# required
name: volume-1
# Size of the Volume in GB.
# default: 10
size: 10
# Dictionary of private networks the server should be attached to.
networks:
# Name of the network
network-1:
# IP range of the whole network which must span all included subnets. Must be one of the private IPv4 ranges of RFC1918.
# If multiple hosts using the same network, you may only define it once.
# required
ip_range: 10.0.0.0/16
subnet:
# IP to assign to the server.
# required
ip: 10.0.0.1/24
# Type of subnetwork.
# default: cloud
type: cloud
# Name of network zone.
# default: eu-central
network_zone: eu-central
network-2:
ip_range: 10.1.0.0/16
subnet:
ip: 10.1.0.1/24
```
> [!NOTE]
> The `networks.ip_range` is important for creating. If you have multiple
> hosts, you may only define it once.
> [!NOTE]
> You may list the server types and available images using the `hcloud` command line tool:
>
> ```bash
> # List server types
> $ hcloud server-type list --sort name
> # List images for the x86 architecture
> $ hcloud image list --type system --architecture x86 --sort name
> ```
Then test your role.
```bash
$ molecule test
```
To ease initial debugging for getting things started, also expose the following
environment variables.
```bash
$ export MOLECULE_NO_LOG=False # not so verbose, helpful
$ export MOLECULE_DEBUG=True # very verbose, last ditch effort
```
You may also define a custom resource namespace by exposing the following
environment variables, for example in CI workflows:
```bash
$ export RESOURCE_NAMESPACE=e121dc64ff615ccdfac71bb5c00296b9 # Ensure the value length is <= 32
```
## Development
### Testing
Run unit tests:
```bash
make test
```
Run integration tests
```bash
export HCLOUD_TOKEN="set_the_hcloud_token_here"
make integration
```
## History
The project was initially maintained by [@decentral1se](https://github.com/decentral1se). After a long period [looking for new maintainers](https://github.com/ansible-community/molecule-hetznercloud/issues/43), the project was archived in early 2023.
In September 2023, the code has been rewritten by [@jooola](https://github.com/jooola) and the project was reactivated to continue development.
## License
The [LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.en.html) license.
Raw data
{
"_id": null,
"home_page": "https://github.com/hetznercloud/hcloud-python",
"name": "molecule-hetznercloud",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ansible molecule driver hcloud hetzner cloud testing",
"author": "Hetzner Cloud GmbH",
"author_email": "support-cloud@hetzner.com",
"download_url": "https://files.pythonhosted.org/packages/d6/0b/78a908cc0c1bb77b0f9eec8f2e9d079e2bbf86e03c39c9e0634cfa354a13/molecule_hetznercloud-2.3.0.tar.gz",
"platform": null,
"description": "# Molecule Hetzner Cloud Driver\n\n[](https://pypi.org/project/molecule-hetznercloud/)\n[](https://app.codecov.io/gh/ansible-community/molecule-hetznercloud/tree/main)\n[](LICENSE)\n\nA [Hetzner Cloud](https://www.hetzner.com/cloud) driver for [Molecule](https://ansible.readthedocs.io/projects/molecule/).\n\nThis plugin allows you to use on-demand Hetzner Cloud servers for your molecule integration tests.\n\n## Install\n\n```bash\n$ pip install molecule-hetznercloud\n```\n\n## Upgrade\n\nThis project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n```bash\n$ pip install --upgrade molecule-hetznercloud\n```\n\n### Upgrading to v2\n\n- In your `molecule.yml` files, rename the molecule driver name (`driver.name`) to `molecule_hetznercloud`:\n\n```patch\n driver:\n- name: hetznercloud\n+ name: molecule_hetznercloud\n```\n\n- In your `molecule.yml` files, the volumes name (`platforms[].volumes[].name`) field is now required. If the field is missing, you MUST add it:\n\n```patch\n platforms:\n - name: instance-1\n image: debian-12\n volumes:\n- - size: 20\n+ - name: volume-1\n+ size: 20\n```\n\n- Each resource (servers, volumes, networks) name are prefixed with a hash (32 chars) based on the role and scenario path. This means you MAY reuse the same names (e.g. `instance-1`) across your scenarios. Resource names MUST not exceed their max length, for example the server name max length is 63 chars, with the prefix you only have 31 chars left for your name.\n\n- In your `molecule.yml` files, the platforms server type (`platforms[].server_type`) field now defaults to `cx22`. If you already use the default, you MAY remove the field:\n\n```patch\n platforms:\n - name: instance-1\n image: debian-12\n- server_type: cx22\n```\n\n## Usage\n\nTo communicate with the Hetzner Cloud API, you need to expose a `HCLOUD_TOKEN` environment variable. Find out more about how to get a Hetzner Cloud API token in the [authentication documentation](https://docs.hetzner.cloud/#authentication).\n\n```bash\n$ export HCLOUD_TOKEN=\"set_the_hcloud_token_here\"\n```\n\nThen setup a new molecule scenario using the driver plugin.\n\n```bash\n$ molecule init scenario --driver-name molecule_hetznercloud\n```\n\n> [!WARNING]\n> With molecule 6, the `molecule init scenario` command dropped support for driver provided configuration. If you are using molecule >=6, please copy the example below and paste it in your scenario `molecule.yml` file.\n> See [this commit](https://github.com/ansible/molecule/commit/21dcd2bb7e8e9002be8bbc19de3e66ec3ce586f1) for details.\n\nYour `molecule/default/molecule.yml` should then look like the following.\n\n```yaml\n---\ndriver:\n name: molecule_hetznercloud\nplatforms:\n - # Name of the Server to create (must be unique per Project and a valid hostname as per RFC 1123).\n # required\n name: instance-1\n # Name of the Image the Server is created from.\n # required\n image: debian-12\n # Name of the Server type this Server should be created with.\n # default: cx22\n server_type: cx22\n # Name of Location to create Server in (must not be used together with datacenter).\n # default: omit\n location: hel1\n # Name of Datacenter to create Server in (must not be used together with location).\n # default: omit\n datacenter: null\n # Cloud-Init user data to use during Server creation. This field is limited to 32KiB.\n # default: omit\n user_data: null\n\n # List of volumes to attach to the server.\n volumes:\n - # Name of the volume.\n # required\n name: volume-1\n # Size of the Volume in GB.\n # default: 10\n size: 10\n\n # Dictionary of private networks the server should be attached to.\n networks:\n # Name of the network\n network-1:\n # IP range of the whole network which must span all included subnets. Must be one of the private IPv4 ranges of RFC1918.\n # If multiple hosts using the same network, you may only define it once.\n # required\n ip_range: 10.0.0.0/16\n subnet:\n # IP to assign to the server.\n # required\n ip: 10.0.0.1/24\n # Type of subnetwork.\n # default: cloud\n type: cloud\n # Name of network zone.\n # default: eu-central\n network_zone: eu-central\n network-2:\n ip_range: 10.1.0.0/16\n subnet:\n ip: 10.1.0.1/24\n```\n\n> [!NOTE]\n> The `networks.ip_range` is important for creating. If you have multiple\n> hosts, you may only define it once.\n\n> [!NOTE]\n> You may list the server types and available images using the `hcloud` command line tool:\n>\n> ```bash\n> # List server types\n> $ hcloud server-type list --sort name\n> # List images for the x86 architecture\n> $ hcloud image list --type system --architecture x86 --sort name\n> ```\n\nThen test your role.\n\n```bash\n$ molecule test\n```\n\nTo ease initial debugging for getting things started, also expose the following\nenvironment variables.\n\n```bash\n$ export MOLECULE_NO_LOG=False # not so verbose, helpful\n$ export MOLECULE_DEBUG=True # very verbose, last ditch effort\n```\n\nYou may also define a custom resource namespace by exposing the following\nenvironment variables, for example in CI workflows:\n\n```bash\n$ export RESOURCE_NAMESPACE=e121dc64ff615ccdfac71bb5c00296b9 # Ensure the value length is <= 32\n```\n\n## Development\n\n### Testing\n\nRun unit tests:\n\n```bash\nmake test\n```\n\nRun integration tests\n\n```bash\nexport HCLOUD_TOKEN=\"set_the_hcloud_token_here\"\nmake integration\n```\n\n## History\n\nThe project was initially maintained by [@decentral1se](https://github.com/decentral1se). After a long period [looking for new maintainers](https://github.com/ansible-community/molecule-hetznercloud/issues/43), the project was archived in early 2023.\n\nIn September 2023, the code has been rewritten by [@jooola](https://github.com/jooola) and the project was reactivated to continue development.\n\n## License\n\nThe [LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.en.html) license.\n",
"bugtrack_url": null,
"license": "LGPL",
"summary": "Molecule driver for Hetzner Cloud",
"version": "2.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/ansible-community/molecule-hetznercloud/issues",
"Changelog": "https://github.com/ansible-community/molecule-hetznercloud/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/ansible-community/molecule-hetznercloud#readme",
"Homepage": "https://github.com/hetznercloud/hcloud-python",
"Source Code": "https://github.com/ansible-community/molecule-hetznercloud"
},
"split_keywords": [
"ansible",
"molecule",
"driver",
"hcloud",
"hetzner",
"cloud",
"testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a83ef808a6fb13740ab172f56fb3bb438be3b8f7f894b17af35278ee54b2121",
"md5": "be9e9bb0190e146017d07fe1dcbcd6d9",
"sha256": "2c8ff55d5e8cf7d6de664062ea9ed0cf3c7b328127f16acb2386221497163505"
},
"downloads": -1,
"filename": "molecule_hetznercloud-2.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be9e9bb0190e146017d07fe1dcbcd6d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15398,
"upload_time": "2024-08-19T08:21:33",
"upload_time_iso_8601": "2024-08-19T08:21:33.468586Z",
"url": "https://files.pythonhosted.org/packages/7a/83/ef808a6fb13740ab172f56fb3bb438be3b8f7f894b17af35278ee54b2121/molecule_hetznercloud-2.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d60b78a908cc0c1bb77b0f9eec8f2e9d079e2bbf86e03c39c9e0634cfa354a13",
"md5": "44219059e913fc8535e9ae32d46c8b6a",
"sha256": "04aaa885381f4816fb3bc04b7d925e3d0c1afd93f39703fd3f39db31b15726fb"
},
"downloads": -1,
"filename": "molecule_hetznercloud-2.3.0.tar.gz",
"has_sig": false,
"md5_digest": "44219059e913fc8535e9ae32d46c8b6a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 14634,
"upload_time": "2024-08-19T08:21:34",
"upload_time_iso_8601": "2024-08-19T08:21:34.750198Z",
"url": "https://files.pythonhosted.org/packages/d6/0b/78a908cc0c1bb77b0f9eec8f2e9d079e2bbf86e03c39c9e0634cfa354a13/molecule_hetznercloud-2.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-19 08:21:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hetznercloud",
"github_project": "hcloud-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "molecule-hetznercloud"
}
JSON
