Connections

Register an AWX or Ansible Tower server — OAuth2 tokens, basic auth, SSL verification, credential-prefix filtering, and how Fabrik talks to AWX without ever handling device secrets.

An AWX Connection is Fabrik's handle on an AWX or Ansible Tower server. Every automation template, request, and execution is anchored to one. Until at least one connection exists and tests green, none of the rest of the section does anything.

What Fabrik stores — and what it doesn't

Fabrik stores just enough to talk to AWX on your behalf:

The AWX base URL (https://awx.example.com).
Either an OAuth2 token or a username + password (Fernet-encrypted at rest, same mechanism as APIC passwords).
SSL verification preference and a connection timeout.
An optional credential_prefix used to filter which AWX credentials show up in the request wizard.

What Fabrik does not store:

Device credentials (SSH keys, SNMP strings, APIC passwords used by playbooks). Those live in AWX's own credential vault — Fabrik references them by ID when launching a job, never reads their secret fields.
Playbook source. Fabrik never clones a repo or reads Ansible code. It only launches templates that already exist in AWX.

Rotating FERNET_KEY invalidates every stored token and password across APIC, AWX, and anywhere else Fabrik encrypts credentials. Plan rotations carefully; the fix is always "re-enter the credentials," there's no re-encryption command.

Creating a connection

Open AWX → Connections in the main nav and click Add Connection.

Basics

Field	Notes
Name	Displayed throughout the UI. Pick something site-specific (`AWX-DC-EAST`, `Tower-Prod`) if you have multiple.
Description	Free-form. What this AWX is for.
URL	Full base URL with scheme — `https://awx.example.com`. No trailing `/api/v2/`, Fabrik appends that itself.
Verify SSL	On by default. Turn off only for lab AWX servers with self-signed certs — and then only knowingly.
Timeout	Seconds. Default 30. Raise for slow AWX instances; lower for tight health checks.

Authentication

Two options:

OAuth2 Token (recommended) — generate a personal access token in AWX (Users → Your User → Tokens → Add). Scope it appropriately; read/write if Fabrik will launch jobs, read-only if you only want to browse templates.
Username + Password — the AWX user's own credentials. Simpler to set up, weaker as a security posture. Supported for environments that haven't set up OAuth2 yet.

Fabrik stores whichever you provide, encrypts it, and never returns the secret after save. Editing a connection shows a Change token / password toggle — leaving it off keeps the existing stored credential untouched.

Credential prefix (optional)

AWX deployments often have dozens or hundreds of credentials across unrelated projects. The Credential prefix field filters which AWX credentials appear in the request wizard's credential picker to those whose names start with the given string (case-sensitive).

For example, a prefix of CISCO_ACI_ restricts the picker to CISCO_ACI_PROD, CISCO_ACI_LAB, etc. — hiding the irrelevant AWX credentials that belong to unrelated teams.

Leave blank to show all credentials.

Public — all Fabrik users can see and use this connection.
Private — only you can see it. You can also share to specific users via the connection detail view.

Private-by-default matches the AWX side: most tokens are tied to a specific AWX user and shouldn't be shared casually.

Save and test

Click Save. Then click Test on the new row. Fabrik:

Hits AWX's /api/v2/ping/ endpoint.
Verifies the token / password authenticates.
Reads the returned AWX version and stores it on the connection.
Stamps last_tested_at and last_test_status.

If the test fails, the error message usually points at the cause — 401 means bad credentials, 404 means wrong URL (check the trailing path), SSL error means the cert isn't trusted and Verify SSL is on.

Editing a connection

The Edit action opens the same dialog. A few specifics:

Leaving the token / password field blank keeps the existing stored credential — you don't need to re-enter it every edit.
Changing the URL is allowed but re-test afterwards; the stored AWX version won't auto-update.
Changing the credential_prefix takes effect the next time a user opens the request wizard.

Deleting a connection

Connections are protected against deletion while automation templates point at them (on_delete=PROTECT). To remove a connection, either delete the templates first or reassign them to a different connection.

This protection is intentional — a stale template pointing at a deleted connection would be unusable but not obviously broken from the template list.

How the AWX client actually works

The backend's AWXClient service is a thin wrapper around AWX's REST API:

Session reuse. One requests.Session per connection per Celery worker, keeping TLS handshakes cheap.
Retry on transient errors. 500 / 502 / 503 / 504 are retried with exponential backoff; 4xx errors fail immediately.
Job launch. POST to /api/v2/job_templates/{id}/launch/ with extra_vars and a credential override.
Workflow launch. POST to /api/v2/workflow_job_templates/{source_id}/copy/ to create an ephemeral clone, attach the user's credential to the clone's job-template nodes, then POST to /api/v2/workflow_job_templates/{clone_id}/launch/. The clone is deleted once the workflow_job reaches terminal status. See Templates → Workflow clones for why.
Event polling. The job_events_poller service walks /api/v2/jobs/{id}/job_events/?page=N and writes each event to a JobOutputChunk row.

You don't need to interact with any of this directly, but knowing it exists helps when a job "just hangs" — the first question is whether the poller is running (see Executions).

Required AWX permissions

The token / user Fabrik authenticates with needs:

Action	Minimum AWX role
List / read job and workflow templates	Read on the org or specific templates
Launch job templates	Execute on the job template
Launch workflow templates	Execute on the workflow template and Workflow Admin on the org (Fabrik clones the workflow template per launch — clone create + delete is required)
Read credentials for the picker	Read on the credentials

If your AWX role profile is execute-only, workflow launches will fail at the clone step with HTTP 403. Either elevate the role to Workflow Admin or restrict Fabrik usage to job templates.

Multiple AWX servers

You can register as many AWX connections as you like. Each template is bound to exactly one — when AWX-DC-EAST is down, a template targeting AWX-DC-WEST keeps working.

Patterns that come up:

Prod + Lab. One connection per environment; templates duplicated or scoped per environment.
Regional. One AWX per region; per-region templates launched from the same Fabrik instance.
HA. Not currently supported at the connection level — Fabrik doesn't fail over between AWX servers within a single template. If you need that, a reverse proxy or AWX's own HA setup is the right layer.

Troubleshooting

Connection issues that come up often:

"Test says 401." The token is wrong, expired, or was revoked in AWX. Regenerate on AWX side and Change token in the edit dialog.
"Test says 404." The URL is wrong — check you included the scheme (https://) and did not include /api/v2/ at the end.
"SSL: CERTIFICATE_VERIFY_FAILED." AWX's cert isn't trusted by the Fabrik container. Either install the CA chain into the container, use a trusted cert on AWX, or disable Verify SSL if this is a lab.
"Credential picker is empty." Either AWX genuinely has no credentials the token can see, or your credential_prefix filters them all out. Clear the prefix and retest.
"Connection tests green but jobs fail to launch." The token may be read-only. Launching jobs needs write scope on the relevant job template's organization.
"Workflow launch fails with HTTP 403 on /copy/." The token can launch but lacks Workflow Admin on the org — required so Fabrik can create the per-launch clone (see Required AWX permissions).
"AWX template list is filling up with __fabrik__* entries." Those are ephemeral workflow clones that should normally disappear within a minute of the workflow finishing. If they pile up, the awx.cleanup_orphaned_workflow_clones Celery beat task isn't running — check Celery beat / worker health and inspect the task's logs.
"Can't delete a connection." Templates still reference it. Delete or reassign the templates first.

With a connection in place, the next step is bringing the AWX templates you want to expose into Fabrik. That's the next page — Templates.

On this page