☁️ Azure Search Service Terraform Module

Provisions a hardened Azure AI Search service (azurerm_search_service) as a single, self-contained unit, targeting hashicorp/azurerm ~> 4.0. The empty call yields a private, Entra-ID-only service; every relaxation is an explicit caller opt-in.

• 🔎 Creates one Azure AI Search service (azurerm_search_service) — the managed retrieval engine behind keyword, semantic, and vector search.
• 🔐 Ships private and Entra-ID-only by default: public_network_access_enabled = false and local_authentication_enabled = false.
• 🧮 Exposes tier and capacity — sku, replica_count, partition_count, hosting_mode — with validation on the closed value sets.
• 🧠 Supports semantic ranking (semantic_search_sku) for relevance re-ranking on top of full-text search.
• 🪪 Provisions a system-assigned managed identity by default, so the service can reach data sources and Key Vault without embedded secrets.
• 🧱 Offers a public-endpoint IP allow-list (allowed_ips), a trusted-services bypass (network_rule_bypass_option), and customer-managed-key enforcement (customer_managed_key_enforcement_enabled).

💡 Why it matters: Azure AI Search is the retrieval layer for most Retrieval-Augmented Generation (RAG) workloads. Getting its exposure and authentication posture right at provisioning time keeps index data — often derived from sensitive source documents — off the public internet and behind Entra ID role-based access, rather than behind long-lived API keys.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

flowchart LR
  rg["terraform-azurerm-resource-group"]:::sib
  st["terraform-azurerm-storage-account"]:::sib
  cos["terraform-azurerm-cosmosdb-account"]:::sib
  cog["terraform-azurerm-cognitive-account"]:::sib
  ra["terraform-azurerm-role-assignments"]:::sib
  pe["terraform-azurerm-private-endpoint"]:::sib
  app["Application / RAG workload"]:::sib
  mod["terraform-azurerm-search-service"]:::me
  svc["azurerm_search_service"]:::keystone

  rg -->|"resource_group_name + location"| mod
  mod -->|"creates"| svc
  st -->|"indexer data source"| svc
  cos -->|"indexer data source"| svc
  svc -->|"vector search for RAG"| cog
  ra -->|"Search Index Data Reader / Contributor"| svc
  app -->|"query via Entra ID"| svc
  pe -->|"private endpoint access"| svc

  classDef me fill:#0078D4,color:#fff,stroke:#004578,stroke-width:1px;
  classDef keystone fill:#004578,color:#fff,stroke:#002a4a,stroke-width:1px;
  classDef sib fill:#eef3f8,color:#0a2540,stroke:#b9c9da,stroke-width:1px;

This is a standalone primitive. It consumes a resource group (name + location) and, at run time, reaches sibling data stores (Storage, Cosmos DB) as indexer sources. It pairs with terraform-azurerm-cognitive-account to serve vector search for RAG, is granted data-plane access through terraform-azurerm-role-assignments, and is fronted by terraform-azurerm-private-endpoint for private access.

flowchart LR
  in1["name / resource_group_name / location"]:::sib
  in2["sku + replica_count + partition_count"]:::sib
  in3["identity: SystemAssigned"]:::sib
  in4["secure defaults: private + Entra-only"]:::sib
  svc["azurerm_search_service.this"]:::keystone
  o1["id"]:::sib
  o2["name"]:::sib
  o3["endpoint"]:::sib
  o4["identity_principal_id"]:::sib

  in1 -->|"placement"| svc
  in2 -->|"tier and capacity"| svc
  in3 -->|"managed identity"| svc
  in4 -->|"hardened posture"| svc
  svc -->|"resource id"| o1
  svc -->|"service name"| o2
  svc -->|"query endpoint"| o3
  svc -->|"principal id"| o4

  classDef keystone fill:#004578,color:#fff,stroke:#002a4a,stroke-width:1px;
  classDef sib fill:#eef3f8,color:#0a2540,stroke:#b9c9da,stroke-width:1px;

Resource inventory

Schema notes that bite (verified against the live provider schema):

• name, resource_group_name, and location are force-new — changing any of them replaces the service.
• hosting_mode is force-new, and HighDensity is only accepted when sku = "standard3".
• sku changes are partly force-new: tier upgrades within Basic and Standard apply in place, but downgrades, any change to or from free, and any change to or from the storage-optimized tiers replace the service.
• 🔴 replica_count and partition_count CAN be set on the free tier. An earlier revision of this document said they could not. The provider refuses only values greater than 1 there — and its own schema default of 1 is sent on every apply, including on free, so the arguments are never absent. The real per-tier ceilings, none of which were documented and all of which the module now checks at terraform validate: replicas 1 on free, 3 on basic, 12 elsewhere; partitions 1 on free, 3 on basic, 3 on standard3 with HighDensity, 12 elsewhere.
• 🔴 The module's hosting_mode check used to be case-SENSITIVE while the provider's is not. hosting_mode is the only enum on this resource whose provider check ignores case, so "highdensity" was accepted by the provider and refused by this module — and because a failed validation {} blocks terraform destroy as well as apply, anyone who had used that spelling could not manage the service through the module at all. The check now compares case-insensitively, matching the provider.
• ⚠️ **authentication_failure_mode is REFUSED, not ignored, when local_authentication_enabled = false.** The provider's CustomizeDifferrors outright. Since this module defaults that flag tofalse, setting the failure mode alone is the *default* path into that error, not an unusual one — so the module now catches it at terraform validate`.
• ⚠️ The IP firewall is not supported on the free tier at all, so allowed_ips entries there configure nothing.
• allowed_ips are only honored when public_network_access_enabled = true; with public access disabled, only private endpoint connections are accepted.
• authentication_failure_mode is only honored when local_authentication_enabled = true.
• semantic_search_sku cannot be set when sku = "free", and semantic ranking is region-limited.
• primary_key, secondary_key, and query_keys are computed and sensitive — this module deliberately does not emit them.

Least-privilege, at the smallest scope that works:

• Search Service Contributor on the target resource group (or a custom role granting Microsoft.Search/searchServices/*) to create and manage the service.
• Granting data-plane access to callers (index read/write) is a separate concern — assign Search Index Data Reader or Search Index Data Contributor to consuming identities via terraform-azurerm-role-assignments, scoped to this service's id.

• An existing resource group in a supported US Azure region (this module does not create it).
• The Microsoft.Search resource provider registered on the target subscription.
• A submitted quota-increase request for the standard2, standard3, storage_optimized_l1, and storage_optimized_l2 tiers.
• The caller configures the provider "azurerm" { features {} } block, authentication, and subscription; the module declares none of these.

terraform-azurerm-search-service/
├── providers.tf     # required_version + azurerm ~> 4.0; no provider block
├── variables.tf     # deeply-typed object() schemas + tags/timeouts tail
├── main.tf          # keystone azurerm_search_service.this; dynamic identity + timeouts, try()
├── outputs.tf       # id first, then name, endpoint, identity principal/tenant, CMK status
├── README.md        # this document
├── SCOPE.md         # the cross-module contract
├── LICENSE          # MIT
└── .gitignore       # canonical library ignore set

The smallest real call — a private, Entra-ID-only Standard service:

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-platform-eastus"
  resource_group_name = "rg-platform-eastus"
  location            = "eastus"
  sku                 = "standard"

  tags = {
    environment = "production"
    workload    = "search"
  }
}

ℹ️ The caller configures the provider, authentication, and the mandatory features {} block:

provider "azurerm" {
  features {}
}

Always pin the module with ?ref=v1.0.0; never track a branch.

Consumes

Emits

The examples below reference existing resources by ID or name rather than creating them; this module owns only its own resource. Those references are declared inputs:

variable "search_identity_id" {
  description = "id of an existing search identity that these examples reference but do not create."
  type        = string
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-min-eastus"
  resource_group_name = "rg-platform-eastus"
  location            = "eastus"
  sku                 = "standard"
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-basic-eastus"
  resource_group_name = "rg-team-eastus"
  location            = "eastus"
  sku                 = "basic"
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-scale-eastus2"
  resource_group_name = "rg-platform-eastus2"
  location            = "eastus2"
  sku                 = "standard"

  replica_count   = 3
  partition_count = 3
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-multitenant-eastus2"
  resource_group_name = "rg-saas-eastus2"
  location            = "eastus2"
  sku                 = "standard3"

  hosting_mode    = "HighDensity"
  partition_count = 3
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-semantic-eastus"
  resource_group_name = "rg-ai-eastus"
  location            = "eastus"
  sku                 = "standard"

  semantic_search_sku = "standard"
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-mixedauth-eastus"
  resource_group_name = "rg-legacy-eastus"
  location            = "eastus"
  sku                 = "standard"

  local_authentication_enabled = true
  authentication_failure_mode  = "http401WithBearerChallenge"
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-uami-eastus"
  resource_group_name = "rg-platform-eastus"
  location            = "eastus"
  sku                 = "standard"

  identity = {
    type         = "UserAssigned"
    identity_ids = [var.search_identity_id]
  }
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-dualid-eastus"
  resource_group_name = "rg-platform-eastus"
  location            = "eastus"
  sku                 = "standard"

  identity = {
    type         = "SystemAssigned, UserAssigned"
    identity_ids = [var.search_identity_id]
  }
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-public-eastus"
  resource_group_name = "rg-edge-eastus"
  location            = "eastus"
  sku                 = "standard"

  public_network_access_enabled = true
  allowed_ips                   = ["203.0.113.10", "198.51.100.0/24"]
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-bypass-eastus"
  resource_group_name = "rg-ai-eastus"
  location            = "eastus"
  sku                 = "standard"

  public_network_access_enabled = true
  network_rule_bypass_option    = "AzureServices"
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-cmk-eastus"
  resource_group_name = "rg-regulated-eastus"
  location            = "eastus"
  sku                 = "standard"

  identity = {
    type = "SystemAssigned"
  }

  customer_managed_key_enforcement_enabled = true
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-private-eastus"
  resource_group_name = "rg-platform-eastus"
  location            = "eastus"
  sku                 = "standard"

  public_network_access_enabled = false
}

locals {
  search_services = {
    eastus  = { location = "eastus", sku = "standard" }
    westus2 = { location = "westus2", sku = "standard" }
  }
}

module "search" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"
  for_each = local.search_services

  name                = "srch-platform-${each.key}"
  resource_group_name = "rg-platform-${each.key}"
  location            = each.value.location
  sku                 = each.value.sku
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-tagged-eastus"
  resource_group_name = "rg-platform-eastus"
  location            = "eastus"
  sku                 = "standard"

  tags = {
    environment = "production"
    cost_center = "1234"
    owner       = "data-platform"
  }

  timeouts = {
    create = "30m"
    delete = "30m"
  }
}

provider "azurerm" {
  features {}
}

module "rg" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-group.git?ref=v1.0.0"

  name     = "rg-rag-eastus"
  location = "eastus"
}

module "search" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-search-service.git?ref=v1.0.0"

  name                = "srch-rag-eastus"
  resource_group_name = module.rg.name
  location            = module.rg.location
  sku                 = "standard"

  semantic_search_sku = "standard"

  identity = {
    type = "SystemAssigned"
  }
}

# Grant the application identity data-plane access to the search indexes,
# and let a platform team manage the service itself.
module "search_access" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"

  scope = module.search.id

  role_assignments = {
    app_reader = {
      role_definition_name = "Search Index Data Reader"
      principal_id         = var.application_principal_id
    }
    platform_admin = {
      role_definition_name = "Search Service Contributor"
      principal_id         = var.platform_group_object_id
    }
  }
}

Required: name, resource_group_name, location, sku.

Capacity: replica_count, partition_count, hosting_mode, semantic_search_sku.

Authentication: local_authentication_enabled, authentication_failure_mode.

Network: public_network_access_enabled, allowed_ips, network_rule_bypass_option.

Encryption & identity: customer_managed_key_enforcement_enabled, identity.

Universal tail: tags, timeouts.

variable "identity" {
  type = object({
    type         = string                 # "SystemAssigned" | "UserAssigned" | "SystemAssigned, UserAssigned"
    identity_ids = optional(list(string)) # required when type includes "UserAssigned"
  })
  default = { type = "SystemAssigned" }
}

variable "timeouts" {
  type = object({
    create = optional(string)
    read   = optional(string)
    update = optional(string)
    delete = optional(string)
  })
  default = null
}

variable "tags" {
  type    = map(string)
  default = {}
}

🔒 The admin keys (primary_key, secondary_key) and query_keys are computed and sensitive; this module deliberately does not emit them. Prefer Entra ID role-based data-plane access.

• Force-new fields. name, resource_group_name, location, and hosting_mode all force replacement. sku is partly force-new: upgrades within Basic/Standard apply in place, while downgrades and any move to or from the free or storage-optimized tiers replace the service. Treat a tier change as a potentially destructive operation and review the plan.
• Free-tier constraints. The free tier rejects replica_count, partition_count, and semantic_search_sku. The module defaults replica_count and partition_count to null so the empty call works on any tier.
• Interdependent fields, and the two behave differently. allowed_ips have no effect while public_network_access_enabled = false — with public access off, private endpoints are the exclusive path and no IP rule changes that. authentication_failure_mode, by contrast, is refused outright when local_authentication_enabled = false: the provider's CustomizeDiff returns an error, so the plan fails rather than the setting being dropped. The module now catches both at terraform validate, along with the per-tier capacity ceilings and the free-tier firewall restriction, so none of them waits for an apply.
• Secret handling. API keys are never accepted as input and never emitted as output. Data-plane access is expected to run through Entra ID role assignments against the service id.
• Identity lifecycle. The default system-assigned identity is created with the service and destroyed with it; a user-assigned identity outlives the service and is the better choice when data-source RBAC must be prepared in advance.
• features {} dependence. The provider will not initialize without a caller-side provider "azurerm" { features {} } block. That is expected — library modules never carry one.

The empty call produces the hardened service; each relaxation is a value the caller must type:

terraform init -backend=false
terraform validate
terraform fmt -check

• Pin the module with ?ref=v1.0.0 — never a branch.
• This library is plan-only during authoring; a human runs terraform plan and terraform apply from CI against real credentials.

The offline proof gate is what this module is validated against:

• terraform init -backend=false — resolves the pinned provider without a backend.
• terraform validate — proves the configuration is internally consistent and type-correct against the pinned provider schema. This catches every typing mistake the object() schemas and validation {} blocks are designed to surface (a bad sku, an out-of-range hosting_mode, a malformed identity).
• terraform fmt -check — enforces canonical formatting.

Neither validate nor fmt calls Azure. Only terraform plan (run by a human, against real credentials) exercises the ARM API and confirms tier availability, quota, and region support.

$ terraform output
id                    = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-rag-eastus/providers/Microsoft.Search/searchServices/srch-rag-eastus"
name                  = "srch-rag-eastus"
endpoint              = "https://srch-rag-eastus.search.windows.net"
identity_principal_id = "11111111-2222-3333-4444-555555555555"
identity_tenant_id    = "66666666-7777-8888-9999-aaaaaaaaaaaa"
customer_managed_key_encryption_compliance_status = "Compliant"

• Provider resource: azurerm_search_service
• Azure AI Search documentation
• Azure AI Search security and Entra ID role-based access
• Sibling modules: terraform-azurerm-resource-group, terraform-azurerm-role-assignments, terraform-azurerm-private-endpoint, terraform-azurerm-cognitive-account, terraform-azurerm-storage-account, terraform-azurerm-cosmosdb-account, terraform-azurerm-user-assigned-identity.
• This module's SCOPE.md.

💙 "Infrastructure as Code should be standardized, consistent, and secure."