Terraform Provider Pangolin

A Terraform provider for managing Pangolin resources.

Architecture Decisions

1. Framework Selection

This provider is built using the Terraform Plugin Framework (instead of the older SDKv2).

• Why: It provides better type safety, improved validation capabilities, and is the current standard recommended by HashiCorp for new providers.

2. Internal Client Decoupling

The API logic is isolated in internal/client/.

• Why: This separates the HTTP/JSON concerns from the Terraform state management. It makes the code more maintainable and allows for easier unit testing of the API client independent of the Terraform lifecycle.

3. Resource Mapping

• Flat vs. Nested: Resources like pangolin_site_resource include ID lists for roles and users to match the API's expectation of many-to-many relationships via array properties.
• Sub-resources: pangolin_target is treated as a separate resource rather than a block within site_resource because targets have their own lifecycle and IDs in the Pangolin API.

4. Authentication

The provider uses Bearer Token authentication as required by the Pangolin Integration API. The token is marked as sensitive in the schema to ensure it doesn't leak into logs.

Requirements

• Go >= 1.24
• Terraform >= 1.0

Compatibility

Pangolin Version	Provider Version
>= v1.15.2	>= 0.1.0

Building The Provider

To compile the provider locally, run:

go build -o terraform-provider-pangolin

Using the Provider Locally

To test the provider without publishing it, you can use Terraform's dev_overrides feature. Create or edit your ~/.terraformrc file:

provider_installation {
  dev_overrides {
    "registry.terraform.io/groteck/pangolin" = "/path/to/your/project/pangolin-tf"
  }
  direct {}
}

Configuration

This provider communicates with the Pangolin Integration API.

Enabling Integration API in Pangolin

You must enable the Integration API in your Pangolin server configuration (config.yml).

flags:
  enable_integration_api: true

server:
  integration_port: 3003 # Optional, defaults to 3003

Ensure the port 3003 (or your configured port) is exposed and accessible to the machine running Terraform.

provider "pangolin" {
  token    = "your-api-token"
  base_url = "https://your-pangolin-instance.com:3003/v1" # Point to the Integration API
}

Provider Configuration

provider "pangolin" {
  token    = "your-api-token"
  base_url = "https://api.pangolin.net/v1" # Optional
}

Supported Resources

pangolin_site_resource

Manages an application or service exposed through Pangolin (Host or CIDR mode).

• Attributes: name, mode (host/cidr), site_id, destination, alias, user_ids, role_ids.

pangolin_resource

Manages an App-style resource (HTTP/TCP/UDP).

• Attributes: name, protocol, http, subdomain, domain_id.

pangolin_target

Manages a backend target for a pangolin_resource.

• Attributes: resource_id, ip, port, enabled.

pangolin_role

Manages organization-level roles.

• Attributes: name, description, org_id.

Examples

See the examples/ directory for a full configuration.

Contributing

Commit Messages

This project enforces Conventional Commits. All commit messages must follow this specification (e.g., feat: add new resource, fix: resolve crash).

This format is used to automate the semantic versioning and changelog generation via the Release Please workflow.

Release Process

Releases are automated using Release Please.

1. Commit: Push changes using Conventional Commits.
2. Automated PR: The Release Please bot analyzes new commits and automatically creates a "Release PR" with the updated CHANGELOG.md and calculated version bump (e.g., chore(main): release v0.2.0).
3. Merge: When the Release PR is merged, the bot:
   • Creates a GitHub Release.
   • Creates a Git Tag.
4. Artifacts: The creation of the tag triggers GoReleaser to build and upload the provider binaries to the release.

License

This project is licensed under the MIT License - see the LICENSE file for details.