How ciscodevnet/terraform-provider-catalystcenter works
Project type and purpose
• This is a Terraform Provider plugin for Cisco Catalyst Center, written in Go.
• It consists of a build‐time code‐generation pipeline, the provider runtime (plugin binary), documentation generation, example configurations, tests, and CI/CD workflows.
• At runtime, Terraform Core loads the provider plugin, which translates Terraform resource/data-source blocks into REST calls to the Catalyst Center API.
File structure
• Top level
– gen/definitions/*.yaml: canonical resource & data-source definitions
– gen/generator.go + gen/templates/: code-gen engine and Go/TF template files
– internal/provider/: generated & handwritten Go code implementing the Terraform Plugin SDK interfaces (resources, data-sources, models)
– main.go: plugin entrypoint (registers provider with Terraform SDK)
– docs/ + templates/guides: Markdown docs sources for Terraform Registry
– examples/: sample Terraform configurations (basic, data-sources, resources)
– .github/, GNUmakefile, .goreleaser.yml: CI/CD definitions (GitHub Actions, Make targets, GoReleaser)
• Architectural patterns
– Build-time code generation (DRY definitions → Go code + docs)
– Plugin pattern (Terraform SDK)
– Clear separation: generator, provider runtime, docs, examples, CI
README for insights
• Describes the provider purpose (REST API integration)
• Lists build/release/test commands (go install, go generate, make testacc, GitHub Actions)
• Points at Terraform Registry for generated docs
a. Components
1. Definitions (gen/definitions/*.yaml)
2. Generator Tool (gen/generator.go + templates)
3. Generated Code (models, schema, provider stubs in internal/provider)
4. Provider Entrypoint (main.go) → Compiled binary (Terraform plugin)
5. Terraform Core (CLI & SDK)
6. Cisco Catalyst Center REST API (external)
7. Documentation Generator (same gen pipeline → docs/)
8. Examples & Tests (examples/, internal/provider/*_test.go)
9. CI/CD Pipeline (GitHub Actions, Make, GoReleaser)
b. Relationships & data flow
• Definitions + Templates → Generator → Generated Code
• Generated Code + Entrypoint → Build → Provider Binary
• Terraform CLI ↔ Provider Binary (RPC via Terraform SDK)
• Provider Binary → REST calls → Catalyst Center API
• Definitions + Templates → Doc Generator → Markdown docs → Terraform Registry
• Examples feed Terraform CLI & acceptance tests
• CI/CD orchestrates Generation → Build → Test → Release → Docs publication
c. Architectural patterns & principles
• Build‐time code generation ensures consistency across code and docs
• Plugin interface for extensibility via Terraform SDK
• Single source of truth: YAML definitions drive both code and documentation
• Modular directories separating concerns (gen, internal, docs, examples, CI)
d. Key technologies
• Go (modules), Terraform Plugin SDK
• YAML & Go templates
• GitHub Actions, Make, GoReleaser
• REST API for Catalyst Center
Detail checklist
• Clearly name each component (e.g., “gen/generator.go”, “internal/provider/resource_xyz.go”, “main.go”)
• Output artifacts (e.g., provider binary, Markdown docs)
• Flow from definitions to generated code to runtime behavior
• External dependency (Cisco Catalyst Center REST API)
• CI/CD steps: test (unit + acc), release (GoReleaser), docs publish
• Where examples and tests plug in for validation