community.hrobot.storagebox_subaccount module – Create, update, or delete a subaccount for a storage box

Note

This module is part of the community.hrobot collection (version 2.4.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.hrobot.

To use it in a playbook, specify: community.hrobot.storagebox_subaccount.

New in community.hrobot 2.4.0

Synopsis

  • Create, update, or delete a subaccount for a storage box.

Parameters

Parameter

Comments

comment

string

A custom comment for the subaccount.

Is required when using idempotence=comment for updates or deletion of a subaccount.

external_reachability

boolean

Enable or disable external reachability (from outside Hetzner’s networks).

Choices:

  • false

  • true

hetzner_password

string / required

The password for the Robot web-service user.

hetzner_user

string / required

The username for the Robot web-service user.

homedirectory

string

Home directory of the subaccount.

Required only when creating a subaccount (state=present).

idempotence

string

Select which attribute to use to check subaccount existence.

If set to username, then subaccounts are identified by their username. Note that usernames cannot be specified on creation, so you need to use different module arguments for creation and updating.

If set to comment, then subaccounts are identified by their comment. If there already exist more than one subaccount with the given comment, the module will fail.

Choices:

  • "username" ← (default)

  • "comment"

password

string

Password to use or change.

See password_mode for how and when this is used.

Will be ignored if password_mode=set-to-random.

password_mode

string

Controls how password updates are handled.

If update-if-provided, the password always updated if provided (default).

If ignore-if-exists, password is only used during creation.

If set-to-random, password is reset to a randomly generated one.

When a new subaccount is created, the password is set to the specified one if password is provided, and a random password is set if password is not provided.

Choices:

  • "update-if-provided" ← (default)

  • "ignore-if-exists"

  • "set-to-random"

rate_limit_retry_timeout

integer

added in community.hrobot 2.1.0

Timeout (in seconds) for waiting when rate limit exceeded errors are returned.

Set to 0 to not retry.

Set to a negative value like -1 to retry forever.

Default: -1

readonly

boolean

Enable or disable read-only mode.

Choices:

  • false

  • true

samba

boolean

Enable or disable Samba.

Choices:

  • false

  • true

ssh

boolean

Enable or disable SSH access.

Choices:

  • false

  • true

state

string

Desired state of this subaccount.

Choices:

  • "present" ← (default)

  • "absent"

storagebox_id

integer / required

The ID of the storage box to query.

username

string

Username of the subaccount.

Required when using idempotence=username for updates or deletion of a subaccount.

If idempotence=username and this is not specified, a new subaccount will always be created. If idempotence=comment, this option is ignored, as the Hetzner API does not allow to chose or modify the username.

webdav

boolean

Enable or disable WebDAV.

Choices:

  • false

  • true

Attributes

Attribute

Support

Description

action_group

Action group: community.hrobot.robot

Use group/community.hrobot.robot in module_defaults to set defaults for this module.

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

idempotent

Support: partial

The Hetzner API does not allow to create subaccounts with specific usernames. You can instead use comment to identify accounts by setting idempotence=comment, that way creation is idempotent.

The module is never idempotent if password_mode=set-to-random, or if password_mode=update-if-provided and password is specified. Set password_mode=ignore-if-exists if you want to provide password on every invocation and do not want the module to always change it. Due to how Hetzner’s API works, it is not possible to query the current password for a subaccount, or check whether a given password is set.

When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.

This assumes that the system controlled/queried by the module has not changed in a relevant way.

Notes

Note

  • When passwords are autogenerated by the API (by omitting the password field), the resulting password is returned.

Examples

---
- name: Create a new subaccount with random password
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    homedirectory: "/backups/project1"
    samba: true
    ssh: true
    webdav: false
    comment: "Backup for Project 1"

- name: Create a subaccount with custom password
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    username: "backup1"
    password: "s3cretPass123"
    homedirectory: "/data/backup1"
    readonly: false
    samba: true
    ssh: false

- name: Update an existing subaccount
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    state: present
    username: "backup1"
    homedirectory: "/data/backup1-updated"
    readonly: true
    comment: "Updated path and readonly mode"

- name: Delete a subaccount
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    state: absent
    username: "backup1"

- name: Change password for a subaccount
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    state: present
    username: "backup1"
    password: "n3wSecur3Pass"

- name: Create subaccount using comment for idempotence
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    homedirectory: "/projects/backup1"
    samba: true
    ssh: true
    webdav: false
    readonly: false
    comment: "Backup1 - Project Foo"
    idempotence: comment

- name: Update subaccount identified by comment
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    homedirectory: "/projects/backup1-updated"
    readonly: true
    comment: "Backup1 - Project Foo"
    idempotence: comment

- name: Update password for subaccount using comment idempotence
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    password: "Sup3rSecur3!"
    comment: "Backup1 - Project Foo"
    idempotence: comment
    password_mode: update-if-provided

- name: Delete subaccount identified by comment
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    state: absent
    comment: "Backup1 - Project Foo"
    idempotence: comment

- name: Use password only during creation
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    password: "InitPass$42"
    homedirectory: "/mnt/init"
    samba: true
    ssh: false
    comment: "Init Subaccount"
    idempotence: comment
    password_mode: ignore-if-exists

- name: Always reset to a random password
  community.hrobot.storagebox_subaccount:
    storagebox_id: 123456
    comment: "Temp Access - CI/CD"
    idempotence: comment
    password_mode: set-to-random

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

created

boolean

Whether a new subaccount was created.

Returned: success

deleted

boolean

Whether the subaccount was deleted.

Returned: success

password_updated

boolean

Whether the subaccount’s password was updated.

Returned: success

subaccount

dictionary

The subaccount object returned by the API.

Returned: if state=present

updated

boolean

Whether the subaccount’s configuration was updated (excluding password changes).

Returned: success

Authors

  • Victor LEFEBVRE (@vic1707)