Writing Plugin YAML

This page covers the Rogue Arena-specific patterns for writing plugin YAML. It assumes you already know Ansible basics.

Body Only — No Play Headers

You write only the task list. No --- document markers, no hosts:, no tasks: key, no become:. Just start with your first task:

- name: Install DNS Server feature
  ansible.windows.win_feature:
    name: DNS
    include_management_tools: yes
    state: present

- name: Install Active Directory Domain Services
  ansible.windows.win_feature:
    name: AD-Domain-Services
    include_management_tools: yes
    state: present

At build time, the system wraps your code with the full Ansible play header automatically:

---
- name: Deploy
  hosts: all
  become: true
  gather_facts: no
  vars:
    YourParam1: "value1"
    YourParam2: "value2"
  tasks:
    # ... your tasks are indented here

If you accidentally include hosts: or tasks: in your YAML, the build output will be malformed. The editor will warn you: “Ansible YAML should be a list of tasks. Did you forget the leading dash (-)?”

Referencing Parameters

Parameters you define in the Parameters tab are available as Ansible variables. Reference them with double curly braces:

- name: Rename computer
  ansible.windows.win_hostname:
    name: "{{ Hostname }}"

- name: Create new AD forest domain
  ansible.windows.win_domain:
    dns_domain_name: "{{ DomainNameFQDN }}"
    safe_mode_password: "Password1!"

Parameters work anywhere in your YAML — task arguments, PowerShell script blocks, conditionals, when clauses.

Using set_fact for Derived Variables

Use ansible.builtin.set_fact at the top of your YAML to compute values from parameters. This is a common pattern when you need to derive defaults or chain values:

- name: Normalize StaticIP (whitespace-safe)
  ansible.builtin.set_fact:
    _static_ip_clean: "{{ StaticIP | default('') | trim }}"

- name: Derive default gateway from StaticIP (x.y.z.1)
  ansible.builtin.set_fact:
    default_gateway: "{{ (_static_ip_clean.split('.')[0:3] + ['1']) | join('.') if _static_ip_clean != '' else '' }}"

- name: Apply gateway override
  ansible.builtin.set_fact:
    effective_gateway: "{{ (IPGateway | default(default_gateway, true)) | trim }}"

- name: Derive upstream DNS (prefer IPDNS; fallback to effective gateway)
  ansible.builtin.set_fact:
    upstream_DNS: "{{ (IPDNS | default(effective_gateway, true)) | trim }}"

This lets the scenario architect provide just a StaticIP parameter and have the gateway and DNS derived automatically — while still allowing explicit overrides via optional IPGateway and IPDNS parameters.

Mixing Parameters into PowerShell

When embedding PowerShell scripts, reference parameters directly inside the script block. Ansible injects the values before execution:

- name: Set DNS forwarder to gateway
  ansible.windows.win_powershell:
    script: |
      $gw = '{{ upstream_DNS }}'
      Set-DnsServerForwarder -IPAddress $gw -PassThru

This works because the {{ }} values are resolved by Ansible before the script reaches the VM.

Linux Packages — Just apt-get install

All Linux VMs have a local APT mirror configured automatically. You don’t need to add repos, import keys, or configure sources:

- name: Install required packages
  ansible.builtin.apt:
    name:
      - docker-ce
      - docker-ce-cli
      - containerd.io
    state: present
    update_cache: yes

The mirror includes base distro packages plus Docker, VS Code, Chrome, Node.js, Elastic, PostgreSQL, and many more. If you need a package from a repo that isn’t mirrored, store the .deb in your File Vault and install manually.

YAML Validation

The Monaco editor provides real-time validation:

• Syntax errors — highlighted inline as you type
• Parameter reference warnings — if {{ UndefinedParam }} doesn’t match a defined parameter, you’ll see a warning
• Missing vault files — file paths referenced in your YAML that don’t exist in your vault are underlined in red with hover tooltips

Using Oracle AI

The Oracle AI button in the plugin editor toolbar opens an AI assistant that can help generate and refine your Ansible code. It has context about your current YAML, parameters, and vault files.

See YAML Examples for real code snippets from the Root DC plugin.