Starting with Terraform provider version 5.29.0, the cloudflare_ai_search_instance resource now accepts a namespace argument, breaking the previous assumption that all instances live in the default namespace. The argument defaults to default, so unchanged configurations continue to work, but you can now target any custom namespace you have created.
New namespace argument in AI Search resources
Define a namespace resource first, then reference it when creating an AI Search instance. The provider will place the instance under the specified namespace instead of the implicit default.
resource "cloudflare_ai_search_namespace" "support" {
account_id = var.account_id
name = "support"
}
resource "cloudflare_ai_search_instance" "docs" {
account_id = var.account_id
id = "docs"
namespace = cloudflare_ai_search_namespace.support.name
}
Because the argument defaults to default, existing Terraform code that omits namespace does not need immediate changes.
Import and data source adjustments
Importing an existing instance now requires the full path <account_id>/<namespace>/<id>. For resources still in the default namespace, include default explicitly.
terraform import cloudflare_ai_search_instance.docs 12345/support/docs
terraform import cloudflare_ai_search_namespace.support 12345/support
Both the single‑instance and the collection data sources now mandate a namespace argument. Set it to "default" if you are querying the original namespace.
data "cloudflare_ai_search_instance" "docs" {
account_id = var.account_id
namespace = "support"
id = "docs"
}
data "cloudflare_ai_search_instances" "support" {
account_id = var.account_id
namespace = "support"
}
Operational considerations
- State migration: When you add a custom namespace to an existing resource, Terraform will treat the change as a move. Plan carefully to avoid unintended recreation.
- CI/CD pipelines: Pipelines that lock down the provider version should be updated to at least v5.29.0 to avoid import‑ID mismatches.
- Namespace hygiene: Explicitly naming namespaces encourages logical separation of environments (dev, staging, prod) or functional domains (support, marketing). This can simplify audit trails and reduce accidental cross‑namespace modifications.
- Documentation drift: Because the default behavior remains unchanged, teams may overlook the new argument. Conduct a configuration audit to confirm that any intended namespace segregation is reflected in code.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Review all cloudflare_ai_search_instance definitions and decide whether they belong in default or a custom namespace. If you need isolation, add a cloudflare_ai_search_namespace resource and reference its name. Update any import commands to include the namespace segment, and adjust data source blocks accordingly. Finally, bump the provider version in your lock file to v5.29.0 or newer to ensure compatibility across your environments.
