How maxbirkner/terraform-provider-awx works
Project Type and Purpose
• This is a Terraform Provider plugin (written in Go) for AWX (Ansible Tower).
• It integrates with Terraform Core to allow users to define AWX resources (organizations, inventories, job templates, etc.) and data-sources in HCL, and reconcile them with an AWX server via its HTTP API.
File Structure Analysis
• Top‐level files & folders:
• main.go, go.mod/go.sum, internal/, tools/, examples/, docs/, develop/, test/, Makefile, README.md
• internal/awx/ – Terraform provider implementation: schema, resources, data-sources
• tools/goawx/ – SDK that wraps AWX’s REST API, used by internal/awx
• examples/ – HCL examples for both data-sources and resources
• docs/ – Generated provider documentation
• develop/ – Local development infra (Docker Compose, Terraform, scripts)
• test/ – Acceptance tests against a live AWX instance
• Patterns & config:
• Terraform plugin architecture (provider.go, resource_*.go, data_source_*.go)
• use of Go modules (go.mod), goreleaser for binary distribution
a. Terraform Core and CLI
• The “terraform” binary and core engine that reads HCL, builds plans, invokes providers.
b. AWX Provider Plugin (Go binary)
• main.go: plugin entrypoint
• internal/awx/provider.go: provider schema (hostname, token, insecure)
• internal/awx/resource_*.go & data_source_*.go: CRUD or Read logic
c. goawx SDK (tools/goawx)
• HTTP client library for AWX API endpoints
• Models, request/response types, helpers for pagination, error handling
d. AWX Server (external service)
• Receives REST calls from the provider plugin
e. Development Infrastructure (develop/)
• Local AWX via Docker Compose, Terraform to provision it, scripts for env setup
f. Examples & Docs
• Usage and generate Terraform Registry docs
g. Tests
• test/terraform_minimal_acc_test.go: acceptance tests that drive Terraform against AWX
Relationships & Data Flow
• User writes HCL → Terraform CLI
• Terraform Core loads Provider plugin via RPC
• Provider plugin initializes (reads hostname/token), then handles resource/data-source lifecycle calls
• Provider calls goawx SDK methods (HTTP requests) → AWX API
• AWX responds with JSON → goawx → provider code → Terraform Core → State updates
• develop/infra and test harness orchestrate a throw-away AWX instance for development and CI
Architectural Patterns & Principles
• Provider Plugin Pattern (RPC‐based plugin interface)
• Separation of Concerns:
• Provider schema & Terraform SDK bits (internal/awx/provider.go)
• Resource/Data-source logic (internal/awx/resource_*.go)
• API client (tools/goawx)
• Reuse: goawx SDK is leveraged rather than hand‐rolling HTTP code
• Infrastructure‐as‐Code (examples/) and Documentation (docs/) aligned with Terraform Registry requirements