Terraform Provider Development: English for Infrastructure Tool Engineering Discussions

Building a Terraform provider is a specialised skill, and so is discussing provider development in English with your team. Whether you are contributing to an open-source provider, building an internal one for your platform team, or reviewing a colleague’s provider code, this vocabulary will help you communicate with precision.

Core Vocabulary

Provider schema The structured definition of what configuration options the provider itself accepts — such as credentials, region, or base URL. The schema defines the shape and validation rules for the provider block in HCL.

“The provider schema accepts three attributes: api_key, region, and endpoint. We marked api_key as sensitive so it doesn’t appear in plan output.”

Resource A manageable infrastructure object that Terraform can create, read, update, and delete. In provider development, implementing a resource means writing the four CRUD handler functions and defining its schema.

“We implemented the database_cluster resource this sprint — the tricky part was handling the update logic because the API doesn’t support in-place changes to the cluster tier.”

Data source A read-only Terraform construct that retrieves information about existing infrastructure without managing its lifecycle. Data sources are defined separately from resources in a provider.

“We added a data source for the organisation’s IP allowlist so that other Terraform modules can reference it without creating or owning it.”

CRUD in Terraform context The four operations a resource must implement: Create (terraform apply on a new resource), Read (terraform refresh or drift detection), Update (terraform apply on a changed resource), and Delete (terraform destroy). Each maps to a specific provider SDK function.

“The Delete function is straightforward for this resource, but the Read function is complex — the API returns a 404 for soft-deleted items, and we need to handle that gracefully as a removed-from-state case.”

Plugin framework The modern Go SDK for building Terraform providers, known as terraform-plugin-framework. It replaces the older SDKv2 and provides a more type-safe, structured way to define schemas and implement CRUD handlers.

“We’re starting the new provider on the plugin framework rather than SDKv2 — it’s more verbose to start but the type safety catches schema mistakes at compile time.”

Acceptance tests End-to-end tests for a Terraform provider that actually provision real infrastructure against a live API, verify its state, and clean up afterward. Acceptance tests are the standard way to validate provider behaviour.

“Acceptance tests are slow because they hit the real API, but they’re the only way to catch the subtle differences between what the provider expects and what the API actually returns.”

terraform-plugin-go A low-level Go library that implements the Terraform Plugin Protocol directly. Most providers use a higher-level SDK like the plugin framework, but terraform-plugin-go gives maximum control for advanced use cases.

“We dropped down to terraform-plugin-go for the custom protocol buffers support — the plugin framework didn’t expose the hooks we needed.”

Registry publishing The process of releasing a Terraform provider to the public Terraform Registry at registry.terraform.io, making it installable by any Terraform user via the required_providers block.

“After we pass the final acceptance tests, the release pipeline will tag the version and trigger registry publishing automatically.”

Key Collocations

• implement a resource — “This issue covers implementing the firewall_rule resource — schema, CRUD handlers, and at least one acceptance test.”
• define the schema — “Before writing any CRUD logic, define the schema completely — changing schema attribute types later is a breaking change for users.”
• run acceptance tests — “To run acceptance tests, you need a real API key in the environment — they take about 8 minutes and will create and delete real resources.”
• publish to the registry — “Once the maintainer merges the release PR, the GitHub Action will publish to the registry within about ten minutes.”
• handle drift — “The Read function needs to handle drift correctly — if a resource was deleted outside of Terraform, it should remove it from state rather than error.”
• import existing resources — “We added ImportState support so users can import existing resources into Terraform state without recreating them.”

Using This Vocabulary in Code Reviews

Provider code reviews have a specific vocabulary pattern. Reviewers often ask: “Does the Read function handle the case where the resource has been deleted out-of-band?” The phrase “out-of-band” means a change that happened outside of Terraform — through the UI or a direct API call. Knowing this phrase helps you both give and receive code review comments more precisely.

Another common review comment is about “plan-time validation” versus “apply-time validation.” Plan-time validation happens during terraform plan and catches errors before any infrastructure changes are made. Apply-time validation happens when the provider makes the actual API call. In code reviews, the question is often: “Can we catch this error at plan time instead of apply time?”

When discussing breaking changes to a published provider, the phrase is “a breaking change for users” — not “a bug” or “a problem.” Breaking changes require a major version bump and careful communication in the changelog.

Practice Tip

Find an open-source Terraform provider on GitHub that has recent pull requests. Read the PR descriptions and review comments, and identify instances of the vocabulary from this article. Then write a short comment — as if you were a reviewer — on one of the PR’s changes, using at least three terms from this guide. Writing code review comments is one of the most realistic ways to practise technical English in context.

Navigating Disagreement with Grace – and Precise Language

“Undefined” – it’s a term that can feel surprisingly loaded in professional settings. While technically referring to a missing value in programming, the word “undefined” often crops up when discussing issues within code reviews, project communication, or even just clarifying expectations with colleagues. The key isn’t simply identifying an issue; it’s articulating why it’s problematic and proposing a solution with precision – something that can be particularly challenging for non-native English speakers navigating the nuances of technical jargon and professional discourse. Let’s look at some common scenarios and how to approach them effectively, focusing on clear and impactful phrasing.

One frequent situation is receiving a code review comment like: “This function is undefined.” Immediately, it feels vague. A native speaker might interpret this as a general critique, but the lack of context leaves the developer unsure of what’s expected. Instead of reacting defensively, a more constructive approach would be to respond with something like, “Thank you for pointing this out. Could you clarify which specific parameter is causing the issue? Specifically, I need to understand if the expected type or value isn’t being passed correctly.” Notice how that reframes the conversation – it shifts from a vague criticism to a request for actionable information. Using phrases like “expected type” and “passing correctly” adds crucial technical detail.

Another common situation arises in Slack conversations. Imagine receiving a message: “This needs fixing.” Again, incredibly broad! A better response would be, “Could you elaborate on the issue? Is it related to data validation, error handling, or something else? Providing more details will help me understand the scope of the changes required.” Using phrases like “data validation” and “error handling” demonstrates a level of technical understanding and directs the conversation towards specific areas for resolution. Framing your questions as requests for clarification – “Could you elaborate?” – is almost always preferable to demanding immediate answers.

Finally, when writing PR descriptions, it’s vital to be explicit. Instead of simply stating “Fixed undefined variable,” try something like: “Resolved an issue where the user_id parameter was not being properly validated before being used within the database query. This prevented a potential SQL injection vulnerability and ensured data integrity.” The detail here – specifying the vulnerable parameter, the problem it caused, and the solution implemented – demonstrates thoroughness and professionalism. Employing phrases like “prevented a potential…vulnerability” highlights the impact of the fix. Focusing on what was done and why is paramount to conveying your work effectively.