[DPE-9764] Add Terraform guide by izmalk · Pull Request #488 · canonical/kafka-operator

izmalk · 2026-04-20T23:02:27Z

Description

Added a Terraform deployment guide.
Updated Juju CLI deployment guide to be a nested page isntead of higher level Landing page.
Updated references.

Checklist

I have added or updated any relevant documentation.
I have cleaned any remaining cloud resources from my accounts.

imanenami

The tutorial looks good to me.

But one general suggestion: I think it would be neater and easier to follow if we put all the contents of TF files in the tutorial into sub-folders in terraform/examples and point the reader to these files. Also makes future updates easier.

We can also add a section for advanced TF deployments and instruct users on how to edit these examples for more complex deployments.

Co-authored-by: Iman Enami <44609233+imanenami@users.noreply.github.com> Signed-off-by: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com>

Combine main.tf code blocks to be standalone when possible. Hide big code blocks in expandable sections. Put the reference section into a dedicated page.

izmalk · 2026-04-23T10:57:04Z

Addressed the comments and refactored the guide.
Now it's more streamlined to be a better guide, rather than everything at once.
Switched to the "one-shot" approach for main.tf files for deployments. Smaller number of steps and less explanation (which we don't want in a how-to guide). I didn't create separate files now, because you can copy the files from the code blocks with a single click and that is simpler and better than blindly downloading a file and running it without looking. Having to copy-paste a config is a common pattern in our docs that we try to use over downloading a file when we can. Unless the file is huge.

I also made the main.tf code blocks hidden by default in expandable blocks. That way, both prod and test deployment sections can fit on a single screen, providing clearer selection at a glance.

The admin user section is still an addendum, which seems like the most intuitive approach here.

I also moved the reference from the how-to guide into a dedicated page in the reference section.

marcoppenheimer · 2026-04-23T16:37:29Z

+
+## Prerequisites
+
+* A Juju controller bootstrapped on a **non-Kubernetes** cloud (see [Juju CLI deployment guide](how-to-deploy-anywhere) for setup instructions)


todo: Mark that the non-Kubernetes part is only for this repo. Link to the equivalent on kafka-k8s-operator

As discussed on a call - we'll add the link later, when we add K8s version of this doc.

marcoppenheimer · 2026-04-23T16:39:07Z

+
+<summary>Terraform configuration for production</summary>
+
+Save the following as `main.tf` in a new working directory. The module is sourced directly from the [`terraform/` directory](https://github.com/canonical/kafka-operator/tree/main/terraform) in the Charmed Apache Kafka GitHub repository.


todo: I don't think we should encourage this. We have a terraform module available at git::https://github.com/canonical/kafka-bundle//terraform, and they should be encouraged to use that.

As such, the contents here should be how they configure their .tfvars file with the various deployment configurations - split, colocated etc

So the contents of the main.tf file they need would just be:

terraform { required_providers { juju = { source = "juju/juju" version = ">= 1.0.0" } } } provider "juju" {} module "kafka" { source = "git::https://github.com/canonical/kafka-bundle//terraform?ref=main" broker = var.broker connect = var.connect ... }

And then we'd share also a kafka.tfvars file:

broker = { app_name = "kafka" channel = "4/stable" units = 3 ... } connect = { app_name = "connect" # if they want it omitted units = 0 ... }

Refactored into having one main.tf and two tfvars files, as we discussed. 263412d

marcoppenheimer · 2026-04-23T16:40:33Z

+
+```shell
+terraform init
+terraform plan -var "model_name=<model-name>"


todo: Similarly, I believe this -var ... can be part of the .tfvars file

Fixed in 263412d

marcoppenheimer · 2026-04-23T16:46:27Z

+(reference-terraform)=
+# Terraform module reference
+
+Reference for the [Charmed Apache Kafka Terraform module](https://github.com/canonical/kafka-operator/tree/main/terraform), used with the [Juju Terraform provider](https://registry.terraform.io/providers/juju/juju/latest/docs).


todo: Here should be the bundle link, not just the Kafka app.

Updated the whole reference according to kafka-bundle, rather than kafka-operator in b891e27

zmraul

LGTM, thanks!

zmraul · 2026-04-24T08:56:24Z

+```{warning}
+This is not recommended for production deployments. Apache Kafka brokers rely on the KRaft controllers to coordinate. If both services go down at the same time, the risk of cluster instability increases.
+```


I think this is redundant, we already specify that this is a non-production setup in the first sentence.

Good idea. Now that we have specific tfvars and have to explicitly select one of them, it kind of makes sense to drop unnecessary warning. Fixed in 0a1548d

zmraul · 2026-04-24T09:02:10Z

+terraform apply -var-file="<profile>.tfvars"
+```
+
+Replace `<profile>` with either `production` or `testing`, depending on the desired deployment.


Maybe a link to configurations#profile could be useful, since we mention it several times. I also noticed we don't have a clear place where we define what profiles do exactly. A good TODO for a future reference doc.

Yes, the existing profile documentation is not very comprehensive. We have planned working on expanding refernces and explanations next cycle. For now, I've added the link to the configurations#profile on charmhub.io here in 0a1548d

Add Terraform guide

17bc3e9

izmalk self-assigned this Apr 20, 2026

izmalk added documentation Improvements or additions to documentation not bug or enhancement PR is not 'bug' or 'enhancement'. For release notes labels Apr 20, 2026

izmalk requested review from imanenami, marcoppenheimer and zmraul April 21, 2026 13:30

imanenami reviewed Apr 23, 2026

View reviewed changes

Comment thread docs/how-to/deploy/deploy-terraform.md Outdated

izmalk and others added 3 commits April 23, 2026 09:20

Apply suggestion

c0af989

Co-authored-by: Iman Enami <44609233+imanenami@users.noreply.github.com> Signed-off-by: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com>

Refactor the guide

a253bb7

Combine main.tf code blocks to be standalone when possible. Hide big code blocks in expandable sections. Put the reference section into a dedicated page.

Fix a broken link

a2dff70

izmalk requested a review from imanenami April 23, 2026 10:57

marcoppenheimer requested changes Apr 23, 2026

View reviewed changes

Update after review

263412d

zmraul previously approved these changes Apr 24, 2026

View reviewed changes

Update terraform reference

b891e27

izmalk dismissed zmraul’s stale review via b891e27 April 24, 2026 21:15

Update terraform guide after review

0a1548d

izmalk requested review from marcoppenheimer and zmraul April 24, 2026 21:26

izmalk added 2 commits April 26, 2026 22:04

Add optional COS and TLS

ee75a41

Fix spellcheck and linkcheck

f5082ac


		## Prerequisites

		* A Juju controller bootstrapped on a non-Kubernetes cloud (see [Juju CLI deployment guide](how-to-deploy-anywhere) for setup instructions)


		<summary>Terraform configuration for production</summary>

		Save the following as `main.tf` in a new working directory. The module is sourced directly from the [`terraform/` directory](https://github.com/canonical/kafka-operator/tree/main/terraform) in the Charmed Apache Kafka GitHub repository.

Conversation

izmalk commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

imanenami left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

izmalk commented Apr 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zmraul left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

izmalk commented Apr 20, 2026 •

edited

Loading