Skip to content

Your first playbook

Goal: prove the whole chain - collection, SDK, credentials, API - with a read-only playbook, and know what success and the common failures look like. Nothing here writes anything.

Prerequisites: installed, and NETORCA_API_URL / NETORCA_API_KEY exported.

The playbook

# first_playbook.yml
- name: Hello NetOrca
  hosts: localhost
  gather_facts: false
  tasks:
    - name: My service items
      netautomate.netorca.netorca_service_item_info:
        runtime_state: [IN_SERVICE]
      register: items

    - name: Anything waiting for my team?
      netautomate.netorca.netorca_change_instance_info:
        state: [PENDING, APPROVED]
      register: open_changes

    - name: What we can see
      ansible.builtin.debug:
        msg:
          - "in service: {{ items.count }} item(s) across
             {{ items.service_items | map(attribute='service.name') | unique | list | length }} service(s)"
          - "open changes: {{ open_changes.count }}"
          - "first item: {{ (items.service_items | first).name | default('(none yet)') }}"

hosts: localhost and gather_facts: false because the modules call the NetOrca API from the controller - there are no managed nodes in this play.

Run it - and what success looks like

$ ansible-playbook first_playbook.yml

PLAY [Hello NetOrca] ***********************************************************

TASK [My service items] ********************************************************
ok: [localhost]

TASK [Anything waiting for my team?] *******************************************
ok: [localhost]

TASK [What we can see] *********************************************************
ok: [localhost] => {
    "msg": [
        "in service: 28 item(s) across 3 service(s)",
        "open changes: 0",
        "first item: pattern1_item_0001"
    ]
}

PLAY RECAP *********************************************************************
localhost                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Both info tasks report ok, never changed - reads are reads. Zero results is still success: a fresh team simply sees in service: 0 (info modules return empty lists, not errors).

The first failures, decoded

Every module failure carries a human msg plus a machine-readable error_type - the full taxonomy is in Error handling. The three you might meet in the first five minutes:

Wrong or expired API key (error_type: auth):

fatal: [localhost]: FAILED! => {"error_type": "auth", "msg": "NetOrca authentication
failed (HTTP 401). Check api_key / NETORCA_API_KEY."}

Fix: re-export NETORCA_API_KEY; check for a trailing newline or a truncated paste.

SDK not installed where Ansible runs :

fatal: [localhost]: FAILED! => {"msg": "Failed to import the required Python library
(netorca-sdk) on ...'s Python ..."}

Fix: pip install "netorca-sdk>=1.0.9,<2.0.0" into the interpreter Ansible uses on the controller. In a venv, either activate it or pin ansible_python_interpreter: "{{ ansible_playbook_python }}" in the play's vars.

Wrong URL / instance unreachable (error_type: transient):

fatal: [localhost]: FAILED! => {"error_type": "transient", "msg": "NetOrca API is
unavailable (...). This is usually transient - retry later."}

Fix: check NETORCA_API_URL (typo? VPN? proxy?). With-or-without /v1 both work; the host must be right.

Next