이 문서에서는 Google Cloud용 Terraform을 사용할 때 고려해야 할 버전 제어 권장사항을 제공합니다.
다른 코드 형식에서와 같이 이전 항목을 보존하고 쉽게 롤백할 수 있도록 버전 제어에 인프라 코드를 저장합니다.
이 가이드는 Terraform 소개 내용이 아닙니다. Google Cloud에서 Terraform 사용에 대한 소개 정보는 Terraform 시작하기를 참조하세요.
기본 브랜치 전략 사용
Terraform 코드가 포함된 모든 저장소의 경우 기본적으로 다음 전략을 사용합니다.
main 브랜치는 기본 개발 브랜치이고 최신 승인 코드를 제공합니다. main 브랜치는 보호됩니다.
개발은 main 브랜치 외부의 기능 및 버그 수정 브랜치에서 수행됩니다.
특성 브랜치 이름을 feature/$feature_name으로 지정합니다.
버그 수정 브랜치 이름을 fix/$bugfix_name으로 지정합니다.
특성 또는 버그 수정이 완료되면 pull 요청을 사용해서 이를 다시 main 브랜치로 병합합니다.
병합 충돌을 방지하기 위해 병합 전 브랜치 기준을 다시 설정합니다.
루트 구성에 환경 브랜치 사용
Google Cloud에 직접 배포되는 루트 구성이 포함된 저장소의 경우 안전한 출시 전략이 필요합니다. 각 환경에 대해 개별 브랜치를 사용하는 것이 좋습니다. 따라서 여러 브랜치 간 변경사항을 병합하여 Terraform 구성에 대한 변경사항을 승격할 수 있습니다.
포괄적인 가시성 허용
Terraform 소스 코드 및 저장소가 엔지니어링 조직 간에, 인프라 소유자(예: SRE)에 대해, 인프라 이해관계자(예: 개발자)에 대해 포괄적으로 표시되고 액세스될 수 있게 합니다. 그러면 인프라 이해관계자가 사용되는 인프라를 더 잘 이해할 수 있습니다.
인프라 이해관계자가 변경 요청 프로세스 중 병합 요청을 제출할 수 있도록 권장합니다.
보안 비밀 커밋 안 함
Terraform 구성을 포함하여 소스 제어에 보안 비밀을 커밋하지 않습니다.
대신 Secret Manager와 같은 시스템에 업로드하고 데이터 소스를 사용해서 참조합니다.
이러한 민감한 값은 결국 상태 파일에 포함될 수 있고 출력으로 노출될 수도 있다는 사실에 주의하세요.
팀 경계를 기반으로 저장소 구성
개별 디렉터리를 사용해서 리소스 간 논리적 경계를 관리할 수 있지만 조직 경계 및 물류에 따라 저장소 구조가 결정됩니다. 일반적으로 승인 및 관리 요구사항이 서로 다른 구성을 서로 다른 소스 제어 저장소로 분리한다는 설계 원칙을 따르세요. 이 원칙을 설명하기 위해 사용 가능한 일부 저장소 구성은 다음과 같습니다.
하나의 중앙 저장소: 이 모델에서는 모든 Terraform 코드가 단일 플랫폼팀에 의해 중앙에서 관리됩니다. 이 모델은 모든 클라우드 관리를 책임지고 다른 팀에서 요청된 변경사항을 승인하는 전용 인프라팀이 있는 경우에 가장 적합합니다.
팀 저장소: 이 모듈에서는 각 팀이 자신의 Terraform 저장소를 책임지고 자신이 소유한 인프라와 관련된 모든 것을 관리합니다. 예를 들어 보안팀은 모든 보안 제어가 관리되는 저장소를 갖고 있고 애플리케이션팀은 애플리케이션 배포 및 관리를 위해 자체 Terraform 저장소를 갖고 있습니다.
팀 경계에 따라 저장소를 관리하는 것이 대부분의 엔터프라이즈 시나리오에서 가장 적합한 구조입니다.
분리된 저장소: 이 모델에서는 각 논리적 Terraform 구성요소가 자체 저장소로 분할됩니다. 예를 들어 네트워킹에 전용 저장소가 있고 프로젝트 만들기 및 관리를 위해 별도의 프로젝트 팩토리 저장소가 있을 수 있습니다. 이 방식은 업무 책임이 다른 팀으로 전환되는 경우가 많은 높은 분산 환경에서 가장 적합합니다.
샘플 저장소 구조
이러한 원칙을 조합해서 Terraform 구성을 서로 다른 저장소 유형으로 분할할 수 있습니다.
기본
애플리케이션 및 팀별
기본 저장소
폴더 또는 조직 IAM과 같은 중요한 중앙 구성요소가 포함된 기본 저장소입니다. 이 저장소는 중앙 클라우드팀에서 관리될 수 있습니다.
이 저장소에서는 각 주요 구성요소(예: 폴더, 네트워크 등)에 대한 디렉터리를 포함합니다.
구성요소 디렉터리에서는 앞에서 설명한 디렉터리 구조 가이드에 따라 각 환경에 대해 개별 폴더를 포함합니다.
애플리케이션 및 팀별 저장소
각 팀이 고유한 애플리케이션별 Terraform 구성을 관리할 수 있도록 애플리케이션 및 팀별 저장소를 개별적으로 배포합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eStore all Terraform infrastructure code in version control to maintain a history of changes and enable easy rollbacks.\u003c/p\u003e\n"],["\u003cp\u003eUtilize a default branching strategy with a protected \u003ccode\u003emain\u003c/code\u003e branch for approved code and feature/bug-fix branches for development, merging changes back into \u003ccode\u003emain\u003c/code\u003e via pull requests.\u003c/p\u003e\n"],["\u003cp\u003eEmploy separate environment branches for root configurations to ensure a safe rollout strategy by merging changes between these branches.\u003c/p\u003e\n"],["\u003cp\u003eOrganize Terraform repositories based on team boundaries, with the option of central, team-specific, or decoupled repositories depending on the organization's structure and management requirements.\u003c/p\u003e\n"],["\u003cp\u003eNever commit secrets directly to source control; instead, use a system like Secret Manager and reference them through data sources, keeping in mind that the values can still end up in the state file.\u003c/p\u003e\n"]]],[],null,["# Best practices for version control\n\nThis document provides version control best practices to consider when using\nTerraform for Google Cloud.\n\nAs with other forms of code, store infrastructure code in version control to\npreserve history and allow easy rollbacks.\n\nThis guide is not an introduction to Terraform. For an introduction to using\nTerraform with Google Cloud, see\n[Get started with Terraform](/docs/terraform/get-started-with-terraform).\n\nUse a default branching strategy\n--------------------------------\n\nFor all repositories that contain Terraform code, use the following strategy by\ndefault:\n\n- The `main` branch is the primary development branch and represents the latest approved code. The `main` branch is [protected](https://docs.gitlab.com/ee/user/project/protected_branches.html).\n- Development happens on feature and bug-fix branches that branch off of the `main` branch.\n - Name feature branches `feature/$feature_name`.\n - Name bug-fix branches `fix/$bugfix_name`.\n- When a feature or bug fix is complete, merge it back into the `main` branch with a pull request.\n- To prevent merge conflicts, rebase branches before merging them.\n\nUse environment branches for root configurations\n------------------------------------------------\n\nFor repositories that include root configurations that are directly deployed to\nGoogle Cloud, a safe rollout strategy is required. We recommend\nhaving a separate *branch* for each environment. Thus, changes to the Terraform\nconfiguration can be promoted by\n[merging changes between the different branches](/docs/terraform/resource-management/managing-infrastructure-as-code).\n\nAllow broad visibility\n----------------------\n\nMake Terraform source code and repositories broadly visible and accessible\nacross engineering organizations, to infrastructure owners (for example, SREs)\nand infrastructure stakeholders (for example, developers). This ensures that\ninfrastructure stakeholders can have a better understanding of the\ninfrastructure that they depend on.\n\nEncourage infrastructure stakeholders to submit merge requests as part of the\nchange request process.\n\nNever commit secrets\n--------------------\n\nNever commit secrets to source control, including in Terraform configuration.\nInstead, upload them to a system like\n[Secret Manager](/secret-manager/docs) and reference them by using data\nsources.\n\nKeep in mind that such sensitive values might still end up in the state file\nand might also be exposed as outputs.\n\nOrganize repositories based on team boundaries\n----------------------------------------------\n\nAlthough you can use separate directories to manage logical boundaries between\nresources, organizational boundaries and logistics determine *repository*\nstructure. In general, use the design principle that configurations with\ndifferent approval and management requirements are separated into different\nsource control repositories. To illustrate this principle, these are some\npossible repository configurations:\n\n- **One central repository**: In this model, all Terraform code is\n centrally managed by a single platform team. This model works best when\n there is a dedicated infrastructure team responsible for all cloud\n management and approves any changes requested by other teams.\n\n- **Team repositories:** In this model, each team is responsible for their\n own Terraform repository where they manage everything related to the\n infrastructure they own. For example, the security team might have a\n repository where all security controls are managed, and application teams\n each have their own Terraform repository to deploy and manage their\n application.\n\n Organizing repositories along team boundaries is the best structure for most\n enterprise scenarios.\n- **Decoupled repositories** : In this model, each *logical* Terraform\n component is split into its own repository. For example, networking might\n have a dedicated repository, and there might be a separate project factory\n repository for project creation and management. This works best in highly\n decentralized environments where responsibilities frequently shift between\n teams.\n\n### Sample repository structure\n\nYou can combine these principles to split Terraform configuration across\ndifferent repository types:\n\n- Foundational\n- Application and team-specific\n\n#### Foundational repository\n\nA *foundational* repository that contains major central\ncomponents, such as folders or org IAM. This repository\ncan be managed by the central cloud team.\n\n- In this repository, include a directory for each major component (for example, folders, networks, and so on).\n- In the component directories, include a separate folder for each environment (reflecting the directory structure guidance mentioned earlier).\n\n#### Application and team-specific repositories\n\nDeploy *application and team-specific* repositories separately for each\nteam to manage their unique application-specific Terraform configuration.\n\nWhat's next\n-----------\n\n- Learn about [best practices for Terraform operations](/docs/terraform/best-practices/operations).\n- Learn about [best practices for using Terraform securely](/docs/terraform/best-practices/security)."]]
