This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
make build— build the provider binary;make install—go installintoGOBINfor~/.terraformrcdev_overrides.make test— unit tests with the race detector. Single test:go test -race -run '^TestName$' ./internal/provider/.make testacc— acceptance tests; they create and destroy real objects and need a live Cozystack cluster viaKUBECONFIG/KUBE_CTX(gated byTF_ACC=1, pointsTF_ACC_TERRAFORM_PATHattofu/terraformautomatically). Single acceptance test:KUBECONFIG=... KUBE_CTX=... TF_ACC=1 go test -run '^TestAccName$' ./internal/provider/.make lint(golangci-lint) andmake fmtmust be clean before committing. CI runs a possibly strictergolangci-lint—goconstfires at 2+ occurrences there even when local says clean.make docs— regeneratedocs/from the schema +examples/viatfplugindocs. It builds the provider and exports the schema through atofudev-override (scripts/gen-docs.sh); a PR must not leavemake docsproducing a diff. Never hand-editdocs/.
The provider talks to the Cozystack aggregated Kubernetes API (apps.cozystack.io/v1alpha1 and sibling groups) with client-go's dynamic client — there is no typed clientset. "Typing" lives at the Terraform layer: typed schema attributes ↔ map[string]any spec ↔ unstructured over the wire. Most Kinds are an Application whose spec is an opaque JSON blob the server turns into a FluxCD HelmRelease.
internal/client/— the wire layer.application.goholds the generalizedclient.Resource{Resource,Kind,Group,Version,ClusterScoped,NoSpec}(defaults toapps.cozystack.io/v1alpha1/namespaced) and CRUD over the dynamic client.config.gobuilds therest.Config(kubeconfig/context/host+token/mTLS/in_cluster/execcredential plugin).outputs.goreads server-generated child Secrets/Services for connection details.platform.go/groups.godeclare thecozystack.io,backups.cozystack.io, andcore.cozystack.ioResources.internal/provider/— the Terraform layer.provider.goregisters every resource/data source/ephemeral.generic_resource.go+crud.goare the engine:newAppResource/newAppDataSource(namespaced) andnewClusterResource(cluster-scoped, imports by name) wire any Kind that supplies anexpand/flattenmodel. Each Kind contributes a*_model.go(pureexpand/flatten, no k8s) and*_schema.go.- Three model styles: typed (
tenant,postgresql,backups_typed, …) for specs worth modelling; rawspec (rawspec_model.go) forspec = jsonencode(...)passthrough usingjsontypes.Normalized; marker (marker_model.go) for spec-less Kinds (NoSpec).tenant_secret.gois bespoke (data/stringData, not.spec) with a write-onlydata_woattribute;ephemeral.goexposes kubeconfig/tenant-secret as ephemeral resources to keep secrets out of state.outputsReader(crud.go) surfaceskubeconfig/endpoints/credentials/ip_address;uidis exposed on every Kind.
- The provider version tracks the Cozystack API version it builds against; the
github.com/cozystack/cozystack/api/apps/v1alpha1module is pinned to a released tag. The one exception is temporary: it is currently pinned to the pseudo-version of cozystack main commit11499c30e, the first one carrying the TenanttracingCentralfield, because no API tag contains it yet. Go orders that pseudo-version belowv1.6.3, so moving to any v1.6.x tag would silently drop the field. Replace the pin by hand with the firstapi/apps/v1alpha1v1.7 tag, and in the same change restore the Renovate rule for this module inrenovate.jsonto disablingdigestupdates only. - Typed models are guarded against upstream spec drift by
assertSpecCoverage(t, emitted, ConfigSpec{}, omit...), which reflects emitted spec keys against the api-module'sConfigSpecjson tags. For Kinds whose Go types live in the heavy root cozystack module, a small vendored guard struct stands in. - Adding a Kind: add the
client.Resourceconstructor, register it inprovider.go, choose typed vs rawspec vs marker, add a unit test (with the spec-coverage guard for typed models), addexamples/resources/+examples/data-sources/entries, then runmake docs. A model with server-generated outputs implementsoutputsReader(readOutputs+outputsPending), which is whatwait_for_readypolls on.
Releases are cut manually and locally with GoReleaser (goreleaser release --clean) and signed with the maintainer GPG key (9C173EB1B531AA1F, forced via the trailing ! in .goreleaser.yaml). There is intentionally no release CI workflow; only ci.yaml (test/lint/markdown/CodeQL) runs in GitHub Actions.