Cloud Documentation

Setting Up Ansible

Install Ansible and the CloudStack collection, connect them to your Lightspeed Cloud account, and run a first playbook.

Introduction

Ansible manages Lightspeed Cloud resources through the ngine_io.cloudstack collection, which provides a module for each type of resource - networks, VPCs, instances, volumes, firewall rules and more. Playbooks describe the resources you want, and Ansible creates or changes only what differs, so the same playbook can be run repeatedly. The Ansible sections of the reference architectures assume the setup described on this page.

A working setup has three parts, all installed on the machine that runs your playbooks (the control node):

Ansible itself.
The ngine_io.cloudstack collection, version 3.x.
The cs and sshpubkeys Python libraries, which the collection uses to call the CloudStack API. These must be installed into the same Python environment that Ansible runs in.

Before you start

You need an API key and secret key for your Lightspeed Cloud account. These are generated from your account settings in the portal - see API access.

The control node must be Linux, macOS or another Unix-like system with Python 3. Windows is supported through Windows Subsystem for Linux (WSL): install a Linux distribution under WSL and follow the Linux instructions inside it.

Current releases of Ansible require a recent Python version on the control node; the ansible-core support matrix lists the versions each release supports. The default python3 on AlmaLinux, Rocky Linux and RHEL 9 is older than current releases accept, so on those systems install a newer interpreter first (for example sudo dnf install python3.12) and use it in place of python3 in the commands below.

Installing Ansible

The official Ansible installation guide covers every supported platform and method. For Lightspeed Cloud we recommend installing into a Python virtual environment, because it keeps Ansible and the cs library together in one place, where the collection can always find it.

Recommended: a virtual environment#

python3 -m venv ~/venvs/cloudstack
source ~/venvs/cloudstack/bin/activate
pip install --upgrade pip
pip install ansible-core 'cs>=3.4.0' sshpubkeys

Activate the environment with the source command in each new terminal session before running Ansible. Run deactivate to leave it.

Alternative: pipx#

If you prefer pipx, which places Ansible on your PATH without a manual activation step, inject the Python libraries into the same environment as Ansible:

pipx install ansible-core
pipx inject ansible-core 'cs>=3.4.0' sshpubkeys

Avoid installing the libraries separately. Running pip install cs into the system Python while Ansible runs from pipx, a virtual environment or an operating system package leaves the library where Ansible cannot see it, and every task fails with Failed to import the required Python library (cs). The Python environment Ansible uses is shown on the python version line of ansible --version.

ansible-core or ansible?#

The commands above install ansible-core, which contains the Ansible engine and its built-in modules. The larger ansible package adds a bundle of community collections. The copy of that bundle shipped by several Linux distributions includes ngine_io.cloudstack 2.5.0, which predates the module names used throughout this documentation. Starting from ansible-core and installing the collection yourself, as shown in the next section, ensures you have the current version.

Confirm the installation#

ansible --version
python -c 'import cs, sshpubkeys; print("ok")'

Run the second command with the same environment active. It prints ok when both libraries are present.

Installing the CloudStack collection

ansible-galaxy collection install ngine_io.cloudstack --upgrade

The --upgrade flag matters when an older copy is already present: without it, ansible-galaxy finds the existing version, reports Nothing to do, and leaves it in place.

This documentation targets ngine_io.cloudstack 3.x. Version 3.0.0 dropped the cs_ prefix from every module, so cs_instance became instance and cs_sshkeypair became ssh_key, and raised the minimum cs library version to 3.4.0. Playbooks written for 2.x continue to run through compatibility redirects, but they emit deprecation warnings.

Pinning the version for a project#

For a project that other people or a CI pipeline will run, record the collection version in a requirements.yml file alongside your playbooks:

# requirements.yml
collections:
  - name: ngine_io.cloudstack
    version: ">=3.0.0,<4.0.0"

ansible-galaxy collection install -r requirements.yml --upgrade

Confirm which version Ansible will use#

ansible-galaxy collection list ngine_io.cloudstack

If more than one copy is installed, each is listed under its own path. Ansible uses the copy from the first path listed, which by default is the one in your home directory (~/.ansible/collections). Confirm that copy is 3.x.

Providing credentials

Environment variables#

The simplest method, and the one the reference architectures use. Every module in the collection reads these variables, so no connection arguments are needed on individual tasks:

export CLOUDSTACK_ENDPOINT=https://cloud.lightspeedhosting.com.au/client/api
export CLOUDSTACK_KEY=<api key>
export CLOUDSTACK_SECRET=<secret key>

Two further variables are useful for long-running operations: CLOUDSTACK_TIMEOUT sets the HTTP timeout in seconds (default 10), and CLOUDSTACK_METHOD=post sends requests as HTTP POST, which avoids URL length limits on calls that carry large parameters such as user data.

Ansible Vault#

For playbooks kept in version control, store the keys encrypted with Ansible Vault and apply them to every CloudStack module at once with module_defaults:

ansible-vault create group_vars/all/vault.yml

# group_vars/all/vault.yml (encrypted)
vault_cloudstack_key: <api key>
vault_cloudstack_secret: <secret key>

- name: Manage Lightspeed Cloud resources
  hosts: localhost
  connection: local
  gather_facts: false
  module_defaults:
    group/ngine_io.cloudstack.cloudstack:
      api_url: https://cloud.lightspeedhosting.com.au/client/api
      api_key: "{{ vault_cloudstack_key }}"
      api_secret: "{{ vault_cloudstack_secret }}"
  tasks:
    # ...

Run the playbook with --ask-vault-pass, or with --vault-password-file in automated pipelines.

Running a first playbook

This read-only playbook lists the zones available to your account. It changes nothing, so it is a safe test of the full chain: Ansible, the collection, the Python libraries and your credentials.

# check-connection.yml
- name: Check the Lightspeed Cloud connection
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: List zones
      ngine_io.cloudstack.zone_info:
      register: result

    - name: Show zone names
      ansible.builtin.debug:
        msg: "{{ result.zones | map(attribute='name') | list }}"

ansible-playbook check-connection.yml

A working setup prints a list containing au-mel01. CloudStack modules call the API from the control node, which is why the play targets localhost with a local connection: no inventory or SSH access is involved.

A warning that no inventory was parsed and only localhost is available is expected for a playbook of this kind, and can be ignored.

Troubleshooting

Failed to import the required Python library (cs) - the cs library is installed in a different Python environment from Ansible. Install it into the environment shown by ansible --version, as described in Installing Ansible.
couldn't resolve module/action 'ngine_io.cloudstack.zone_info' - the collection is not installed for the user running the playbook. Run the install command from Installing the CloudStack collection as that user.
Deprecation warnings naming cs_ modules - either the playbook uses 2.x module names, or Ansible is loading an older copy of the collection. Check the second case with ansible-galaxy collection list ngine_io.cloudstack.
unable to verify user credentials and/or request signature - the API key or secret key is incorrect, or the two keys belong to different pairs. Check the values in your environment variables or vault file.
Timeouts on large operations - raise CLOUDSTACK_TIMEOUT, or set api_timeout in module_defaults.

Next steps

Each reference architecture includes a complete Ansible playbook, starting with RA-01. The collection documentation lists every module and its parameters.

For quick queries and one-off changes from the command line, see Setting Up CloudMonkey.