Docs terraform context

[ian-at-airbyte]

What

Expand our Terraform stub article and add new Terraform tutorial. Resolves the docs component of #11525.

How

Expands our stub Terraform topic to be a fully-fledged Terraform tutorial. Includes new discussions and code samples, specifically around the use of JSON strings as alternatives to strongly typed configurations to help deal with Terraform drift.

Not included in this PR are two decisions we need to make about previously created resources:

• The existing Terraform guide in the API docs
• The exceptional YouTube series on this from our DevRel team

Both of these resources are out of date compared to this content, and I expect they will be replaced by it. This is a fuller discussion about current challenges and, unlike those other resources, should be technically correct to the latest version of the Terraform provider.

Review guide

• /docs/terraform-documentation.md.

For the nice version, just open the linked Vercel build as usual and scroll down to Terraform Provider in the menu.

User Impact

• An accurate, up to date Terraform tutorial, as a companion to the autogenerated reference docs.
• A way to help deal with Terraform drift.

Can this PR be safely reverted and rolled back?

• YES 💚
• NO ❌

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
airbyte-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 26, 2025 10:45pm

[Charlesnorris509]

Great job with pull requests your changes make the markdown file much more readable and engaging for new users like me. Now i still have a remark. I would increase the possibility for test driven development in this project and for future contributors. By a bulk test procedure for the most important feature of the project.

[ian-at-airbyte]

Thanks, everyone, for your feedback. I've applied them.

• Everyone including OSS uses a client ID and client secret. This allowed me to remove several tab sets and go from 2 code samples to 1.
• JSON is the default code sample for sources and destinations.
• Removed some unnecessary code blocks around creating .tf files.

@Charlesnorris509 I did not incorporate your request as it was outside the scope of this particular contribution but I've noted it for the future.

[abuchanan-airbyte]

Would it be better to use jsonencode here instead of a heredoc?

[ian-at-airbyte]

Yes. I did originally try that and it was my preferred option too, but something about the way Terraform interacts with the API created encoding problems that caused terraform apply to fail. This seemed to be a problem with BigQuery specifically, not with other destinations, although the exact nature of the issue escapes me now.