본문 바로가기

직접 만든 소프트웨어, 두 가지 개발 기록

구현 구조와 적용 범위, 확인한 기능과 남은 한계를 함께 기록합니다.

소프트웨어개발

AI Search를 Terraform으로 관리할 때: namespace 변경과 가져오기는 달라요

by 아빠띠띠뽀 2026. 11. 15.

AI Search의 namespace 값을 바꾸기 전에 기존 인스턴스를 교체하는 변경인지 확인하세요. 이미 있는 대상을 Terraform 관리로 가져오는 일과 새 검색 인스턴스를 만드는 일도 구분해야 합니다. Cloudflare는 2026년 11월 13일 Terraform provider 5.29.0부터 default 외의 네임스페이스에서도 인스턴스를 관리할 수 있다고 발표했습니다.

이번 안내는 검색 서비스를 여러 팀·제품 영역으로 나누거나 기존 구성을 코드로 관리하려는 담당자를 위한 글입니다. 11월 14일 공식 공지와 현재 Terraform·네임스페이스 문서를 읽었어요. 실제 계정에 가져오기나 변경 적용을 실행하지 않았으며, 아래 docs·support 이름은 설명을 위한 가상 구성입니다.

네임스페이스는 검색 인스턴스의 소속을 나눕니다

현재 AI Search 문서에서 네임스페이스는 같은 계정 안의 인스턴스를 논리적으로 묶는 단위입니다. 제품 영역이나 고객, 에이전트별 문맥을 나누는 용도로 설명돼 있어요. 모든 인스턴스는 하나의 네임스페이스에 속하며 계정에는 default 네임스페이스가 자동으로 만들어집니다.

인스턴스 이름은 그 네임스페이스 안에서 고유해야 합니다. 따라서 blog와 support에 각각 docs라는 이름을 둘 수 있어요. 이때 이름 docs만 적으면 어느 검색을 가리키는지 충분하지 않을 수 있습니다. 계정, 네임스페이스, 인스턴스를 함께 식별하는 메모가 필요한 이유입니다.

구분용 이름을 만들었다는 사실과 접근 권한을 알맞게 제한했다는 결과는 다른 문제입니다. 문서는 네임스페이스 바인딩이 그 안의 모든 인스턴스에 접근하고 런타임 생성·삭제 등의 작업을 할 수 있다고 설명해요. 이름을 나눴다는 이유만으로 앱의 권한 설계까지 검증됐다고 생각하지 않는 편이 좋겠습니다.

가상의 고객 지원 검색과 공개 제품 문서 검색을 분리한다면, 먼저 어떤 데이터와 앱이 어느 인스턴스를 쓰는지 적어 보세요. 이번 글은 고객 데이터의 안전성을 시험한 결과가 아닙니다. 관리 단위와 실제 사용 경로를 함께 확인하자는 운영 기록의 예시예요.

새 버전의 기본값과 명시해야 할 값을 나눠요

11월 13일 공지에서 인스턴스 리소스의 namespace 인자는 기본값이 default입니다. 기존 설정에서 이 값을 생략한 경우 같은 기본 네임스페이스를 계속 관리하는 방향으로 설명합니다. 새 기능을 쓰기 위해 기존 모든 인스턴스의 소속을 바꿀 필요가 있다고 읽지는 마세요.

반면 데이터 소스에는 namespace를 명시해야 합니다. Terraform에서 데이터 소스는 기존 정보를 조회할 때 쓰는 구분으로 이해하면 편해요. 기본 네임스페이스를 조회하는 경우에도 default를 넣어야 한다고 공지는 안내합니다. 리소스 생성의 기본값과 조회의 필수값은 같은 조건이 아닙니다.

단일 인스턴스 조회와 목록 조회도 범위를 읽어야 합니다. 현재 공지는 cloudflare_ai_search_instances가 지정한 네임스페이스 하나의 목록을 반환하며, 단일 조회의 이전 filter.namespace 인자는 제거된다고 설명해요. 같은 이름의 결과가 보인다고 예전과 똑같은 계정 전체 목록을 읽었다고 판단하면 확인 범위가 어긋날 수 있습니다.

업그레이드 메모에는 실제 provider 버전과 현재 조회 대상, 기존 필터를 같이 적어 보세요. 이 글의 기준은 5.29.0에서 발표된 변경과 11월 14일 확인한 문서입니다. 실제 프로젝트의 잠금 파일이나 실행 환경을 읽은 것이 아니므로 독자의 설치 버전이 이미 바뀌었다고 확정하지 않습니다.

생성·가져오기·조회는 서로 다른 질문이에요

새 인스턴스를 만드는 설정이라면 어느 네임스페이스에 어떤 이름으로 생성할지 먼저 정합니다. 현재 인스턴스 Terraform 문서에서 id 인자는 인스턴스 이름입니다. namespace를 생략하면 default에 생성되고, 별도 네임스페이스를 쓸 때는 그 이름을 지정해요. 이름만 보고 데이터가 이동한다고 이해하면 안 됩니다.

이미 운영 중인 대상을 관리에 연결하려는 경우에는 가져오기 식별자를 확인해야 합니다. 새 형식은 계정 ID, 네임스페이스, 인스턴스 ID의 세 부분입니다. default에 있는 인스턴스도 가운데 부분을 생략하지 않는다고 공지는 설명해요. 단순히 예전 가져오기 문자열을 그대로 재사용하지 말고 현재 대상을 대조하세요.

가져올 대상과 코드가 가리키는 대상이 같은지도 확인할 항목입니다. support의 docs를 관리하려는데 default의 docs를 메모해 뒀다면, 이름이 같아도 서로 다른 소속이겠죠. 이는 실제 오작동을 재현한 사례가 아니라 식별자를 세 부분으로 남기는 이유를 보여 주는 가상 상황입니다.

네임스페이스 자체를 가져올 때의 식별자는 계정 ID와 네임스페이스 이름 두 부분으로 안내됩니다. 인스턴스와 네임스페이스의 식별자 형식을 하나로 통일해 생각하지 마세요. 글에서는 실제 계정 ID나 실행 명령을 제공하지 않으니, 담당자가 공식 가져오기 안내와 상태 관리 절차를 읽고 적용 범위를 정해 주세요.

조회용 데이터 소스를 추가했다고 기존 대상을 원하는 방식으로 관리하게 됐다는 뜻도 아닙니다. 어떤 블록이 정보를 읽고 어떤 블록이 리소스 생명주기를 관리하는지 구분해 검토하세요. “구성이 보인다”는 확인과 “변경 계획이 의도대로다”라는 확인을 같은 단계로 합치지 않는 편이 좋습니다.

namespace 변경은 단순한 폴더 이동이 아닙니다

인스턴스 문서는 namespace를 바꾸면 기존 인스턴스를 파괴하고 새 인스턴스를 만드는 교체가 일어난다고 명시합니다. id, account_id, type의 변경도 교체 항목으로 안내돼 있어요. 이름을 고치거나 관리 위치를 정리하려는 의도가 실제 인스턴스 교체로 이어질 수 있다는 뜻입니다.

특히 인스턴스 교체는 색인된 데이터와 임베딩·청크, 기본 제공 저장소에 올린 파일을 영구 제거한다고 문서는 경고합니다. 원본 데이터가 다른 곳에 있다는 사실만으로 현재 검색의 상태가 그대로 유지된다고 판단하면 안 됩니다. 어떤 데이터가 보존되고 무엇을 다시 준비해야 하는지 변경 계획과 함께 확인해야 해요.

공식 문서는 변경을 적용하기 전에 Terraform 계획에서 must be replaced 표시를 읽도록 안내합니다. 이 글은 실제 plan을 실행하거나 결과를 관찰하지 않았어요. 담당자가 승인된 환경에서 계획을 읽을 때 어느 리소스의 어떤 변경이 삭제·생성을 포함하는지 구체적으로 기록할 수 있습니다.

가상의 support 검색을 다른 네임스페이스로 정리하려는 상황이라면, 앱의 참조와 검색 데이터, 인스턴스 이름만 적지 말고 교체 여부를 별도 칸으로 두세요. 구성값 한 줄의 수정량과 서비스 영향의 크기가 항상 같지는 않습니다. 자동으로 안전하게 이동된다는 표현은 실제 계획·복구 검증 없이 쓰지 않는 것이 좋겠습니다.

네임스페이스 자체의 교체와 참조 관계도 봐요

네임스페이스 리소스에서는 name이나 account_id 변경이 교체 대상이고, description이나 public_endpoint_params 변경은 같은 대상을 갱신하는 항목으로 설명됩니다. 인스턴스의 namespace 인자 변경과 네임스페이스 리소스의 이름 변경을 같은 목록으로 외우지 말고, 어느 리소스의 속성을 바꾸는지 먼저 표시해 보세요.

인스턴스가 남아 있는 네임스페이스는 삭제할 수 없습니다. 문서는 인스턴스가 네임스페이스 리소스의 이름을 참조하게 하면 생성은 네임스페이스가 먼저, 삭제는 인스턴스가 먼저 진행되는 관계가 만들어진다고 설명해요. 코드에 같은 문자열이 적혀 있다는 것과 리소스 참조가 연결됐다는 것을 나눠 읽을 필요가 있습니다.

같은 구성에서 관리하지 않는 인스턴스나 참조 관계가 없는 인스턴스가 안에 남아 있다면 삭제가 실패할 수 있다고 문서는 안내합니다. 코드 파일에 보이는 대상만으로 현재 네임스페이스 전체를 설명할 수 있는지 확인해 보세요. 실제 계정의 인스턴스 목록과 담당 주체를 함께 읽어야 하는 부분입니다.

이 글은 삭제를 통과시키려고 남은 인스턴스를 지우라는 실행 절차를 제시하지 않습니다. 소유자와 실제 사용 경로, 데이터 보존·복구 요구를 먼저 확인하자는 안내예요. 확인되지 않은 대상을 없애거나 state 기록만 임의로 바꿔 계획을 조용하게 만드는 방식은 검토를 대신하지 못합니다.

변경 전후에 남길 기록을 작게 정해 보세요

먼저 현재 계정·네임스페이스·인스턴스와 provider 버전을 적고, 새로 생성할 대상인지 이미 있는 대상을 가져올 것인지 구분해 보세요. 다음에는 앱이 어느 검색을 참조하는지와 데이터 준비 상태, 현재 구성 밖에서 관리하는 대상이 있는지를 확인할 질문으로 남길 수 있습니다.

그다음 변경 계획을 실제로 읽은 범위와 남은 검증을 나눕니다. 단순 갱신인지 교체인지, 삭제 순서의 참조가 있는지, 교체 뒤 필요한 색인과 파일을 어떻게 준비할지 기록하세요. 문서만 검토했다면 실제 생성이나 검색 결과를 확인한 것처럼 완료 표시를 하지 않는 편이 좋겠습니다.

계획 파일이나 상태에는 민감한 정보가 들어갈 수 있으므로 실제 내용 전체를 공개 질문에 붙일 필요는 없습니다. 팀의 저장·공유 절차에 맞춰 필요한 식별 정보와 변경 의도를 남겨 주세요. 기존 설정과 상태의 보존 방법, 문제가 생겼을 때 담당자가 따라갈 복구 절차도 적용 전에 합의할 항목입니다.

자주 묻는 질문도 정리해 볼게요. 기존 default 설정은 모두 바꿔야 하나요? 생성 기본값과 조회 필수값을 나눠 확인하세요. namespace를 바꾸면 기존 데이터가 그대로 옮겨지나요? 현재 문서는 인스턴스 교체와 색인 데이터 제거를 설명합니다. 가져오기만 끝나면 운영 준비도 끝났나요? 실제 계획, 앱 연결과 검색 결과는 확인한 단계별로 남겨야 합니다.

이번 기능을 활용하는 기준은 네임스페이스 수를 늘리는 데만 있지 않습니다. 어떤 검색을 어느 코드가 관리하는지 식별하고, 갱신과 교체를 적용 전에 알아보는 데 있어요. 그 구분이 정리되면 기존 검색을 보존할지 새 구성을 준비할지 담당자가 근거를 갖고 결정하기 쉬워집니다.

자료 확인일은 2026년 11월 14일입니다. 아래 공식 안내를 기준으로 정리했으며 실제 계정 설정 변경·명령 실행·성능 시험은 하지 않았어요. 적용 시점의 계정·버전·환경 조건은 담당자가 다시 확인해 주세요.

함께 읽어 볼 글: OpenSearch와 Elastic Cloud Hosted의 검색 운영·비용 선택 기준. 배경과 다른 선택 조건을 비교할 때 참고해 보세요.

서로 분리된 검색 문서 상자와 설정 장부를 함께 살펴보는 인프라 관리 개념 그림
검색 인스턴스의 소속과 관리 기록을 구분하는 개념 이미지입니다. 실제 Terraform 실행이나 안전한 이전 완료 결과를 나타내지 않습니다.