Get started with Ansible on Quake AI

This guide walks you through installing Ansible, authenticating to Quake AI, building a minimal inventory file, and running your first playbook against an existing instance. By the end, you will have a working Ansible setup that connects to Quake AI and configures a host over SSH.

For the conceptual overview of where Ansible fits on the platform, read Ansible on Quake AI first.

Prerequisites#

Quickstart completed: account, project, SSH key
A running Quake AI VM you can reach over SSH on its floating IP. If you do not have one, the getting started IaC guide creates one in under 10 minutes.
Application credentials downloaded as clouds.yaml or openrc.sh
Python 3.6 or newer on your workstation

Install Ansible and the OpenStack collection#

The openstack.cloud Ansible collection ships the modules and the dynamic inventory plugin you need to manage Quake AI resources. Install Ansible itself, the OpenStack SDK, and the collection.

bash

brew install ansible
pip3 install --user "openstacksdk>=1.0.0"
ansible-galaxy collection install openstack.cloud

Verify the installation:

bash

ansible --version
ansible-galaxy collection list openstack.cloud

You should see ansible 2.13 or newer and openstack.cloud 2.2.0 or newer.

Configure authentication#

Ansible authenticates to Quake AI the same way OpenTofu and the OpenStack CLI do: through application credentials in a clouds.yaml file or OS_* environment variables. The recommended path is clouds.yaml because the dynamic inventory plugin reads it automatically.

Create or edit ~/.config/openstack/clouds.yaml:

YAML

clouds:
  quakeai:
    auth_type: v3applicationcredential
    auth:
      auth_url: https://keystone.rumble.cloud/v3
      application_credential_id: YOUR_APPLICATION_CREDENTIAL_ID
      application_credential_secret: YOUR_APPLICATION_CREDENTIAL_SECRET
    region_name: us-east-1
    interface: public
    identity_api_version: 3

Test the credentials with the OpenStack CLI before running any playbooks:

bash

openstack --os-cloud quakeai server list

A list of running instances confirms that the credentials work. If you prefer environment variables, source the openrc.sh you downloaded with the application credentials:

bash

source openrc.sh

Build a minimal inventory#

Create a project directory and a static inventory file pointing at one Quake AI VM:

bash

mkdir ansible-quickstart && cd ansible-quickstart

Create inventory.ini:

ini

[web]
my-server ansible_host=203.0.113.42 ansible_user=ubuntu

[web:vars]
ansible_ssh_private_key_file=~/.ssh/id_ed25519
ansible_python_interpreter=/usr/bin/python3

Replace 203.0.113.42 with the floating IP of your VM and ubuntu with the default user for your image (Ubuntu images use ubuntu, Debian images use debian, Rocky and AlmaLinux use rocky or almalinux).

Verify SSH connectivity through Ansible:

bash

ansible -i inventory.ini web -m ansible.builtin.ping

A pong response confirms that Ansible can reach the host over SSH.

Write your first playbook#

Create site.yml:

YAML

---
- name: Configure web host
  hosts: web
  become: true

  tasks:
    - name: Update apt cache
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600

    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present

    - name: Render landing page
      ansible.builtin.copy:
        dest: /var/www/html/index.html
        content: |
          <!doctype html>
          <html><body><h1>Configured by Ansible on Quake AI</h1></body></html>
        owner: www-data
        group: www-data
        mode: "0644"

    - name: Ensure nginx is running
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

This playbook updates the package cache, installs nginx, writes a placeholder landing page, and starts the service. The become: true directive runs tasks with sudo.

Run the playbook#

bash

ansible-playbook -i inventory.ini site.yml

Ansible prints a play recap when it finishes. Look for ok=4 changed=4 (or similar) on the first run; subsequent runs report changed=0 because the tasks are idempotent.

Verify the result by hitting the host's floating IP in a browser or with curl:

bash

curl http://203.0.113.42

You should see the landing page text.

Tear down#

This guide does not create any infrastructure beyond the playbook output, so there is nothing to destroy on the Quake AI side. To revert the host configuration, write a playbook that sets state: absent on the same resources, or rebuild the VM from a clean image.

Next steps#

You now have a working Ansible setup that targets Quake AI over SSH. From here:

Replace the static inventory with the dynamic inventory plugin: see How to use Ansible dynamic inventory on Quake AI.
Combine OpenTofu provisioning with Ansible configuration in a single workflow: see How to use Ansible with OpenTofu on Quake AI.
Provision Quake AI resources directly from Ansible (with trade-offs): see How to provision a Quake AI instance with Ansible.

Get started with Ansible on Quake AI

Get started with Ansible on Quake AI

Prerequisites#

Install Ansible and the OpenStack collection#

Configure authentication#

Build a minimal inventory#

Write your first playbook#

Run the playbook#

Tear down#

Next steps#

See also#

Usage Guidelines

Quick answers

See Also