Cloudflare AI Search Terraform 변경: namespace 수정은 데이터 이동이 아니다

네임스페이스 변경 전에 검색 인덱스와 변경 계획을 확인하는 AI 생성 개념 이미지.

Cloudflare가 November 13, 2026 제품 변경 공지에서 AI Search의 Terraform 네임스페이스 지원을 안내했다. Cloudflare provider v5.29.0부터 default 밖의 인스턴스도 관리할 수 있다. 다만 기존 인스턴스의 namespace 값을 바꾸는 작업은 단순한 폴더 이동이 아니다. 교체 계획과 데이터 보존을 먼저 확인해야 하는 변경이다. 공식 변경 공지

1. 리소스의 기본값과 조회 범위를 구분하기

이번 변경에서 확인할 지점은 세 가지다.

cloudflare_ai_search_instance 리소스의 namespace 기본값은 default다. 기존 설정에 이 인자가 없다고 해서 다른 네임스페이스로 자동 이동하는 것은 아니다.

인스턴스 import 식별자는 이제 <account_id>/<namespace>/<id> 형태다. 기본 네임스페이스도 경로 중간의 default를 생략하지 않는다.

공식 공지는 단일·목록 데이터 소스에 namespace를 지정하도록 요구한다. cloudflare_ai_search_instances의 결과는 지정한 한 네임스페이스 범위이며, 단일 데이터 소스의 기존 filter.namespace는 제거됐다. 업그레이드 확인 항목

여기서 데이터 소스는 Terraform의 조회용 블록을 뜻한다. AI Search가 문서를 수집하는 R2·웹사이트 등의 데이터 소스와 같은 의미가 아니다. 목록을 계정 전체의 인스턴스 목록처럼 사용하던 자동화는 조회 범위를 다시 점검해야 한다.

문서와 스키마의 차이도 있다. 11월 13일 공지는 데이터 소스의 namespace를 필수로 안내하지만, 확인한 v5.29.0 단일 데이터 소스 소스 코드에서는 Optional: true, Computed: true로 선언돼 있다. 따라서 생략하면 반드시 Terraform 구문 검증 단계에서 실패한다고 단정하지 않는다. 운영 설정에는 네임스페이스를 명시하고, 설치된 provider의 검증 결과와 실제 조회 대상을 따로 확인하는 편이 안전하다. v5.29.0 데이터 소스 스키마

2. namespace 수정은 인덱스를 보존하는 이동이 아니다

공식 인스턴스 문서는 namespace 변경이 기존 인스턴스를 삭제하고 새 인스턴스를 만드는 교체라고 명시한다. 교체 시에는 임베딩·청크와 내장 스토리지에 업로드한 파일을 포함한 인덱스 데이터가 영구 삭제된다. 원본이 외부 저장소에 남아 있는 경우와, 내장 업로드 파일이 유일한 사본인 경우의 복구 조건은 다르다. 인스턴스 교체와 데이터 삭제 범위

provider의 리소스 스키마에도 namespace에 RequiresReplaceIfConfigured()가 설정돼 있다. 설정 파일의 문자열만 바꾸면 데이터와 검색 결과가 그대로 따라갈 것이라고 가정해서는 안 된다. v5.29.0 리소스 스키마

실무적으로는 provider 버전 업데이트와 네임스페이스 재배치를 별도 변경으로 나누는 것이 좋다. 먼저 현재 네임스페이스를 유지한 상태로 새 버전의 계획을 검토하고, 재배치가 필요할 때 원본 보관·재수집·검색 검증·호출 대상 전환을 별도 작업으로 설계한다. 이는 공식 삭제 동작을 바탕으로 한 운영 제안이며, 자동 무중단 이전 기능이 있다는 뜻은 아니다.

네임스페이스 이름 변경에도 주의해야 한다. 네임스페이스 리소스의 name이나 account_id 변경은 교체이며, 인스턴스가 남아 있으면 네임스페이스 삭제가 거절된다. 특히 다른 설정 파일이나 런타임에서 만든 인스턴스까지 존재하는지 확인해야 한다. 네임스페이스의 수명주기와 의존성

3. import는 데이터 이전 명령이 아니다

새 import 경로는 이미 존재하는 인스턴스의 위치를 정확히 가리키기 위한 것이다. 예를 들어 계정 아래 support 네임스페이스의 docs 인스턴스라면 식별자는 <account_id>/support/docs다. 이를 사용한다고 기존 default/docs가 support/docs로 복사되지는 않는다. AI Search import 형식

Terraform의 import는 원격 객체를 특정 Terraform 리소스 주소의 state에 연결한다. 같은 원격 객체를 여러 주소로 중복 import하면 원하지 않는 동작이 생길 수 있다. 기존에 관리 중인 객체를 새 경로 형식 때문에 무조건 다시 import하지 말고, 현재 state의 연결과 설치 버전의 전환 동작을 먼저 확인해야 한다. Terraform import의 역할과 주의점

팀의 운영 문서, 신규 환경 편입 스크립트, 복구 절차에 예전 두 구간 경로가 남아 있는지 찾는 것이 우선이다. 원격 데이터의 백업과 Terraform state의 백업 역시 서로 대체할 수 없는 별개의 준비물이다.

4. 적용 전 계획에서 멈춰야 할 신호

승인된 작업 디렉터리에서 provider 버전을 확인하고, 다음 명령으로 변경 계획을 검토할 수 있다.

이 옵션의 종료 코드는 0이면 변경 없음, 1이면 오류, 2이면 변경이 있는 정상 계획이다. CI가 2를 일반 오류로만 처리하지 않도록 구분해야 한다. plan 자체는 제안된 변경을 적용하지 않지만 원격 객체의 현재 상태를 읽는다. -out으로 계획을 저장한다면 민감 값이 평문으로 포함될 수 있으므로 공개 로그나 저장소에 올리지 않는다. Terraform plan 문서

적용 승인 전에는 다음을 확인한다.

예상하지 않은 교체가 없는가: must be replaced가 보이면 어떤 필드가 원인인지 확인한다. 버전 업데이트만 하려던 작업이라면 네임스페이스 재배치를 함께 승인하지 않는다.

검색 원본을 되살릴 수 있는가: 내장 업로드 파일의 별도 사본, 외부 소스 접근 권한, 재수집 조건을 확인한다. state 복원만으로 삭제된 인덱스 데이터가 복구된다고 가정하지 않는다.

앱이 같은 위치를 보는가: Terraform 설정, Worker 바인딩, 조회 자동화의 네임스페이스와 인스턴스 식별자를 대조한다. 새 인스턴스 생성 성공과 실제 검색 성공은 다른 완료 기준이다.

파괴 방지 장치의 한계를 아는가: 중요한 리소스의 lifecycle.prevent_destroy = true는 파괴 계획을 거절하는 보조 장치다. 해당 리소스 설정 자체를 제거하면 보호되지 않으며, 백업이나 이전 절차를 대신하지 않는다. prevent_destroy의 동작과 한계

이 글은 공식 공지·문서와 공개 provider 소스 코드를 대조한 점검 가이드다. 실제 Cloudflare 계정에서 Terraform 명령이나 인덱스 재생성을 실행한 결과는 아니다. 이번 변경의 안전한 출발점은 버전을 올리는 일, state에 연결하는 일, 검색 데이터를 옮기는 일을 분리하는 것이다.