DOC-1528 Document Schema Registry and ACLs (#448)

* DOC-1528 Document Schema Registry and ACLs

* Add section on creds

* Add links

* Apply suggestions from code review

Co-authored-by: Michele Cyran <[email protected]>

* Update terraform-provider.adoc

---------

Co-authored-by: Michele Cyran <[email protected]>

Author: JakeSCahill

modules/manage/pages/terraform-provider.adoc

@@ -5,23 +5,27 @@ The https://registry.terraform.io/providers/redpanda-data/redpanda/latest[Redpan
 
 With the Redpanda Terraform provider, you can manage:
 
-* ACLs
-* Clusters
-* Networks
-* Resource groups
-* Topics
-* Users
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/acl[ACLs^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/cluster[Clusters^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/network[Networks^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/resource_group[Resource groups^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/role_assignments[Role assignments^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/schema[Schemas^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/schema_registry_acl[Schema Registry ACLs^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/serverless_cluster[Serverless clusters^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/topic[Topics^]
+* link:https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/user[Users^]
 
 == Why use Terraform with Redpanda?
 
 * **Simplicity**: Manage all your Redpanda Cloud resources in one place.
 * **Automation**: Create and modify resources without manual intervention.
-* **Version Control**: Track and roll back changes using version control systems such as GitHub.
+* **Version Control**: Track and roll back changes using version control systems, such as GitHub.
 * **Scalability**: Scale your infrastructure as your needs grow with minimal effort.
 
 == Understand Terraform configurations
 
-Terraform configurations are written in link:https://developer.hashicorp.com/terraform/language[HCL (HashiCorp Configuration Language)], which is declarative. Here are the main building blocks of a Terraform configuration:
+Terraform configurations are written in link:https://developer.hashicorp.com/terraform/language[HCL (HashiCorp Configuration Language)^], which is declarative. Here are the main building blocks of a Terraform configuration:
 
 === Providers
 
@@ -422,6 +426,181 @@ resource "redpanda_topic" "example" {
 }
 ----
 
+=== Manage Schema Registry and Schema Registry ACLs
+
+You can also use Terraform to manage data plane resources, such as schemas and access controls, through the Redpanda Schema Registry.
+
+The Redpanda Schema Registry provides centralized management of schemas for producers and consumers, ensuring compatibility and consistency of data serialized with formats such as Avro, Protobuf, or JSON Schema. Using the Redpanda Terraform provider, you can create, update, and delete schemas as well as manage fine-grained access control for Schema Registry resources.
+
+You can use the following Terraform resources:
+
+* `redpanda_schema`: Defines and manages schemas in the Schema Registry.
+* `redpanda_schema_registry_acl`: Defines access control policies for Schema Registry subjects or registry-wide operations.
+
+==== Create a schema
+
+The `redpanda_schema` resource registers a schema in the Redpanda Schema Registry. Each schema is associated with a subject, which serves as the logical namespace for schema versioning. When you create or update a schema, Redpanda validates its compatibility level.
+
+[source,hcl]
+----
+data "redpanda_cluster" "byoc" {
+  id = "byoc-cluster-id"
+}
+
+resource "redpanda_user" "schema_user" {
+  name            = "schema-user"
+  password        = var.schema_password
+  mechanism       = "scram-sha-256"
+  cluster_api_url = data.redpanda_cluster.byoc.cluster_api_url
+  allow_deletion  = true
+}
+
+resource "redpanda_schema" "user_events" {
+  cluster_id  = data.redpanda_cluster.byoc.id
+  subject     = "user_events-value"
+  schema_type = "AVRO"
+
+  schema = jsonencode({
+    type = "record"
+    name = "UserEvent"
+    fields = [
+      { name = "user_id", type = "string" },
+      { name = "event_type", type = "string" },
+      { name = "timestamp", type = "long" }
+    ]
+  })
+
+  username = redpanda_user.schema_user.name
+  password = var.schema_password
+}
+----
+
+In this example:
+
+* `cluster_id` identifies the Redpanda cluster where the schema is stored.
+* `subject` defines the logical name under which schema versions are registered.
+* `schema_type` specifies the serialization type (`AVRO`, `JSON`, or `PROTOBUF`).
+* `schema` provides the full schema definition, encoded with `jsonencode()`.
+* `username` and `password` authenticate the user to the Schema Registry.
+
+==== Store credentials securely
+
+Store credentials using environment variables or sensitive Terraform variables.
+
+For short-lived credentials or CI/CD usage, use provider-level environment variables:
+
+[source,bash]
+----
+export REDPANDA_SR_USERNAME=schema-user
+export REDPANDA_SR_PASSWORD="your-secret-password"
+----
+
+Or, declare a sensitive Terraform variable and inject it at runtime:
+
+[source,hcl]
+----
+variable "schema_password" {
+  description = "Password for the Schema Registry user"
+  sensitive   = true
+}
+----
+
+Then, set the value securely using an environment variable before running Terraform:
+
+[source,bash]
+----
+export TF_VAR_schema_password="your-secret-password"
+----
+
+This avoids committing secrets to source control.
+
+==== Manage Schema Registry ACLs
+
+The `redpanda_schema_registry_acl` resource configures fine-grained access control for Schema Registry subjects or registry-wide operations. Each ACL specifies which principal can perform specific operations on a subject or the registry.
+
+[source,hcl]
+----
+resource "redpanda_schema_registry_acl" "allow_user_read" {
+  cluster_id    = data.redpanda_cluster.byoc.id
+  principal     = "User:${redpanda_user.schema_user.name}"
+  resource_type = "SUBJECT"        # SUBJECT or REGISTRY
+  resource_name = "user_events-value"
+  pattern_type  = "LITERAL"        # LITERAL or PREFIXED
+  host          = "*"
+  operation     = "READ"           # READ, WRITE, DELETE, DESCRIBE, etc.
+  permission    = "ALLOW"          # ALLOW or DENY
+  username      = redpanda_user.schema_user.name
+  password      = var.schema_password
+}
+----
+
+In this example:
+
+* `cluster_id` identifies the cluster that hosts the Schema Registry.
+* `principal` specifies the user or service account (for example, `User:alice`).
+* `resource_type` determines whether the ACL applies to a specific `SUBJECT` or the entire `REGISTRY`.
+* `resource_name` defines the subject name (use `*` for wildcard).
+* `pattern_type` controls how the resource name is matched (`LITERAL` or `PREFIXED`).
+* `operation` defines the permitted action (`READ`, `WRITE`, `DELETE`, etc.).
+* `permission` defines whether the operation is allowed or denied.
+* `host` specifies the host filter (typically `"*"` for all hosts).
+* `username` and `password` authenticate the principal to the Schema Registry.
+
+TIP: To manage Schema Registry ACLs, the user must have cluster-level `ALTER` permissions. This is typically granted through a Kafka ACL with `ALTER` on the `CLUSTER` resource.
+
+==== Combine schema and ACLs
+
+You can define both the schema and its ACLs in a single configuration to automate schema registration and access setup.
+
+[source,hcl]
+----
+data "redpanda_cluster" "byoc" {
+  id = "byoc-cluster-id"
+}
+
+resource "redpanda_user" "schema_user" {
+  name            = "schema-user"
+  password        = var.schema_password
+  mechanism       = "scram-sha-256"
+  cluster_api_url = data.redpanda_cluster.byoc.cluster_api_url
+  allow_deletion  = true
+}
+
+resource "redpanda_schema" "user_events" {
+  cluster_id  = data.redpanda_cluster.byoc.id
+  subject     = "user_events-value"
+  schema_type = "AVRO"
+
+  schema = jsonencode({
+    type = "record"
+    name = "UserEvent"
+    fields = [
+      { name = "user_id", type = "string" },
+      { name = "event_type", type = "string" },
+      { name = "timestamp", type = "long" }
+    ]
+  })
+
+  username = redpanda_user.schema_user.name
+  password = var.schema_password
+}
+
+resource "redpanda_schema_registry_acl" "user_events_acl" {
+  cluster_id    = data.redpanda_cluster.byoc.id
+  principal     = "User:${redpanda_user.schema_user.name}"
+  resource_type = "SUBJECT"
+  resource_name = redpanda_schema.user_events.subject
+  pattern_type  = "LITERAL"
+  host          = "*"
+  operation     = "READ"
+  permission    = "ALLOW"
+  username      = redpanda_user.schema_user.name
+  password      = var.schema_password
+}
+----
+
+This configuration registers an Avro schema for the `user_events` subject and grants a service account permission to read it from the Schema Registry.
+
 == Delete resources
 
 Terraform provides a way to clean up your infrastructure when resources are no longer needed. The `terraform destroy` command deletes all the resources defined in your configuration.
@@ -455,4 +634,7 @@ This will delete only the `redpanda_network.example` resource.
 == Suggested reading
 
 * https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs[Redpanda Terraform Provider documentation^]
-* https://github.com/redpanda-data/terraform-provider-redpanda/tree/main/examples[Redpanda Terraform Provider Examples^]
+* https://github.com/redpanda-data/terraform-provider-redpanda/tree/main/examples[Redpanda Terraform Provider examples^]
+* https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/schema[Schema resource documentation^]
+* https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/schema_registry_acl[Schema Registry ACL resource documentation^]
+