Neuwerk

Terraform Provider

Reference for the Terraform provider, including supported resources and transport behavior.

Neuwerk includes a Terraform provider under:

  • terraform-provider-neuwerk/

Use the provider source:

terraform {
  required_providers {
    neuwerk = {
      source = "moolen/neuwerk"
    }
  }
}

Use it when you want to manage Neuwerk configuration through infrastructure-as-code instead of calling the HTTP API directly.

The current supported distribution path is signed GitHub Releases plus a Terraform filesystem mirror. The intended provider source address is already moolen/neuwerk, so consumer configuration does not need to change when public Terraform Registry publication is added later.

Current Scope

The provider is intentionally small and currently exposes:

  • provider configuration for HTTPS API access
  • eight managed resources
  • no data sources

Implemented resources today are:

  • neuwerk_policy
  • neuwerk_kubernetes_integration
  • neuwerk_tls_intercept_ca
  • neuwerk_service_account
  • neuwerk_service_account_token
  • neuwerk_sso_provider_google
  • neuwerk_sso_provider_github
  • neuwerk_sso_provider_generic_oidc

Provider Configuration

The current provider schema supports these fields:

  • endpoints Required list of HTTPS base URLs; endpoints are tried in order
  • token Required bearer token for API authentication
  • ca_cert_pem Optional PEM-encoded CA certificate
  • ca_cert_file Optional path to a PEM-encoded CA certificate
  • request_timeout Optional per-request timeout in Go duration syntax
  • retry_timeout Optional total retry budget for transient transport failures
  • headers Optional extra headers attached to every request

The intended machine-auth path is an admin-capable service-account token issued by the Neuwerk itself.

Transport Model

The provider uses a hand-written API client rather than generated code.

Current transport behavior includes:

  • HTTPS endpoint normalization
  • bearer-token authentication
  • optional custom CA trust
  • endpoint failover by trying configured endpoints in order
  • retry loops for transient transport failures up to retry_timeout

This makes the provider suitable for talking to a cluster where any one endpoint may be unavailable or may proxy to the current leader.

Resource Coverage

neuwerk_policy

This resource manages an aggregate policy document through the by-name policy API.

Current API mapping:

  • GET /api/v1/policies/by-name/{name}
  • PUT /api/v1/policies/by-name/{name}
  • DELETE /api/v1/policies/{id}

The resource supports two authoring styles:

  • document_json A low-level JSON escape hatch
  • nested HCL fields under source_group A higher-level authoring surface that the provider compiles into the canonical policy JSON

Important current attributes include:

  • name
  • mode
  • default_action
  • document_json
  • source_group
  • computed compiled_json

The provider imports this resource by policy name.

neuwerk_kubernetes_integration

This resource manages Kubernetes integration records through the integrations API.

Current API mapping:

  • GET /api/v1/integrations/{name}
  • POST /api/v1/integrations
  • PUT /api/v1/integrations/{name}
  • DELETE /api/v1/integrations/{name}

Current resource fields are:

  • name
  • api_server_url
  • ca_cert_pem
  • service_account_token
  • computed kind
  • computed auth_type
  • computed token_configured

The provider imports this resource by integration name.

At the moment, this is specifically a Kubernetes integration resource. It is not a generic integration resource that covers every possible future integration kind.

neuwerk_tls_intercept_ca

This resource manages the singleton TLS intercept CA setting.

Current API mapping:

  • GET /api/v1/settings/tls-intercept-ca
  • PUT /api/v1/settings/tls-intercept-ca
  • POST /api/v1/settings/tls-intercept-ca/generate
  • DELETE /api/v1/settings/tls-intercept-ca

Current resource fields are:

  • generate
  • ca_cert_pem
  • ca_key_pem
  • ca_key_der_b64
  • computed configured
  • computed source
  • computed fingerprint_sha256

The provider imports this resource as a singleton binding rather than by a user-chosen name.

neuwerk_service_account

This resource manages service-account identities for Terraform and other automation.

Current resource fields are:

  • name
  • description
  • role
  • computed id
  • computed created_at
  • computed updated_at

The provider imports this resource by UUID.

neuwerk_service_account_token

This resource mints service-account bearer tokens.

Current resource fields are:

  • service_account_id
  • name
  • ttl
  • role
  • eternal
  • computed id
  • computed token
  • computed created_at
  • computed updated_at

The provider imports this resource by <service_account_id>/<token_id>. The resource is immutable after creation; changing its inputs replaces it and mints a new token.

SSO Provider Resources

The provider exposes three first-class SSO resources rather than one generic catch-all:

  • neuwerk_sso_provider_google
  • neuwerk_sso_provider_github
  • neuwerk_sso_provider_generic_oidc

All three share the same core identity and claim-mapping fields. The generic OIDC resource also requires explicit authorization_url, token_url, and userinfo_url values.

The provider imports all SSO resources by provider UUID.

What Is Not Implemented Yet

A few limitations are explicit in the current provider code:

  • no Terraform data sources
  • no resources for performance mode, audit, or DNS cache
  • no provider code generation from OpenAPI
  • no generic “all settings” resource
  • no partial policy-subobject resources; policy is managed as one aggregate document

The provider therefore covers a useful automation subset, not the full HTTP API.

State And Secret Handling

Two state-model details are important when using the provider.

Policy Is Aggregate State

neuwerk_policy manages one named aggregate policy document. Terraform is not updating one rule at a time on the server. Every apply sends the compiled full document for that named policy.

That is the correct mental model for drift and change review.

Integration Tokens Are Effectively Write-Only

The integrations API returns token_configured rather than the original service-account token.

Because of that:

  • imported integration resources do not recover the original token value from the server
  • the Terraform configuration must continue to supply service_account_token
  • state continuity depends on Terraform state and input variables, not on round-tripping the secret from the API

Service Account Tokens And SSO Secrets Are Mint-Once Or Write-Only

Two other resources follow the same broad pattern:

  • neuwerk_service_account_token returns raw token material only at create time
  • SSO resources require client_secret on create, store it as a sensitive Terraform value, and cannot recover it from the API during import

Import Behavior

Current import identifiers are:

  • neuwerk_policy import by policy name
  • neuwerk_kubernetes_integration import by integration name
  • neuwerk_tls_intercept_ca import with any placeholder ID; the resource binds to the singleton setting
  • neuwerk_service_account import by UUID
  • neuwerk_service_account_token import by <service_account_id>/<token_id>
  • neuwerk_sso_provider_google import by provider UUID
  • neuwerk_sso_provider_github import by provider UUID
  • neuwerk_sso_provider_generic_oidc import by provider UUID

For the integration resource, import is best paired with configuration that re-supplies the service account token, because the API does not return it.

Example

The repository includes a concrete example under:

  • terraform-provider-neuwerk/examples/basic/main.tf
  • terraform-provider-neuwerk/examples/service-accounts/main.tf
  • terraform-provider-neuwerk/examples/sso/main.tf

These examples show the provider wired to:

  • one service account
  • one service-account token
  • one Kubernetes integration
  • one generated TLS intercept CA resource
  • one named policy resource

Relationship To The HTTP API Docs

The provider is currently a manually maintained interface layer on top of the HTTP API.

That means:

  • HTTP API changes must be reflected in provider client and resource code
  • provider coverage may lag behind newly added API endpoints
  • OpenAPI is useful as the contract reference, but the provider is not generated from it today

For now, the provider should be treated as a curated automation surface for the implemented API subset above.

Release artifacts are currently distributed through signed GitHub Releases. Manual installs are expected to verify both the checksum file and its detached signature before placing the provider in a Terraform filesystem mirror.