구성 동기화에 Git 저장소 액세스 권한 부여

이 페이지에서는 구성 동기화를 Git 저장소에 인증하는 방법을 설명합니다. 구성 동기화는 구성을 읽고, 클러스터에 적용하고, 동기화 상태를 유지할 수 있도록 정보 소스에 대한 읽기 전용 액세스 권한이 필요합니다.

인증 방식 선택

사용하는 인증 방법은 소스 유형에 지원되는 방법에 따라 다릅니다.

다음 표에는 구성 동기화와 함께 사용할 수 있는 인증 방법이 요약되어 있습니다.

메서드	지원되는 소스	설명	제한사항
인증 없음	Git, OCI, Helm	추가 설정이 필요하지 않습니다.	정보 소스가 공개 상태인 경우에만 작동합니다.
SSH 키 쌍	Git	대부분의 Git 제공업체에서 지원합니다.	키 관리가 필요합니다. OCI 또는 Helm에서는 지원되지 않습니다.
토큰	Git, Helm	대부분의 Git 제공업체에서 지원합니다. 조직에서 SSH 키 사용을 허용하지 않는 경우 좋은 대안입니다. Helm의 사용자 이름과 비밀번호를 지원합니다.	토큰 관리가 필요합니다. 토큰은 만료될 수 있습니다. OCI에서는 지원되지 않습니다.
Kubernetes 서비스 계정	OCI, Helm	IAM을 사용하여 Kubernetes 서비스 계정에 Artifact Registry 액세스 권한을 직접 부여합니다. 클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있어야 합니다.	Git에서는 지원되지 않습니다.
Google 서비스 계정	Git	Kubernetes 보안 비밀에 사용자 인증 정보를 저장하지 않는 IAM을 사용합니다. Secure Source Manager 및 Cloud Source Repositories에 권장됩니다. 클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있어야 합니다.	클러스터에 구성 동기화를 설치하기 전후에 구성이 필요합니다. Secure Source Manager 또는 Cloud Source Repositories 외부에서 호스팅되는 저장소에는 지원되지 않습니다.
GitHub 앱	Git	GitHub와 직접 통합 세분화된 권한을 허용합니다.	GitHub에 호스팅된 저장소에서만 지원됩니다. 구성 동기화 버전 1.19.1 이상에서만 지원됩니다.

구성 동기화는 다음 인증 방법도 지원하지만, 앞의 표에 나열된 옵션 중 하나를 사용할 수 없는 경우에만 이러한 방법을 사용하는 것이 좋습니다.

• cookiefile:은 일부 Git 제공업체에서 지원되지 않을 수 있습니다. OCI 또는 Helm에서는 지원되지 않습니다.
• Compute Engine 기본 서비스 계정 (gcenode): GKE용 워크로드 아이덴티티 제휴가 사용 중지된 경우에만 작동하므로 권장되지 않습니다. Git, OCI, Helm에서 지원됩니다.
• Helm 및 OCI용 Google 서비스 계정: 지원되지만 Kubernetes 서비스 계정 메서드는 구성이 덜 필요하므로 권장되지 않습니다.

Fleet 패키지를 사용한 인증

플릿 패키지를 사용하는 경우 이 페이지의 안내를 완료하지 않아도 됩니다. Fleet 패키지는 Cloud Build를 사용하여 Git에 인증하므로 프로젝트당 한 번 인증하면 됩니다. 따라서 클러스터에 구성 동기화를 설치할 때마다 액세스 권한을 부여할 필요가 없습니다.

시작하기 전에

구성 동기화에 Git 저장소에 대한 읽기 전용 액세스 권한을 부여하기 전에 다음 작업을 완료하세요.

• 구성 동기화가 동기화할 구성 파일을 저장하는 Git 저장소를 준비하거나 액세스합니다. 자세한 내용은 다음 리소스를 참조하세요.

  • 정보 소스에 구성 추가: 구성에 관한 개념 정보입니다.
  • GitOps 권장사항: 저장소를 정리하고 관리하기 위한 도움말과 일반 권장사항입니다.
  • 구조화되지 않은 저장소 사용: 구조화되지 않은 저장소를 사용하고 정리하기 위한 권장사항입니다.

• GKE 클러스터를 만들거나 이에 대한 액세스 권한을 갖습니다. 클러스터를 만들기 전에 구성 동기화의 클러스터 구성 요구사항 및 권장사항을 검토하세요.

중요: 이 페이지의 단계에 따라 생성된 모든 비밀 또는 민감한 정보를 보호하세요. 예를 들어 파일이 필요하지 않으면 삭제하거나 안전한 방식으로 저장할 수 있습니다.

SSH 키 쌍 사용

SSH 키 쌍은 공개 키 파일과 비공개 키 파일로 구성됩니다. 구성 동기화는 암호 생성을 지원하지 않습니다. 보안 및 규정 준수 요구사항에 따라 모든 클러스터에 단일 키 쌍을 사용하거나 클러스터별로 키 쌍을 사용할 수 있습니다.

SSH 키 쌍을 사용하여 Git 저장소에 대한 읽기 전용 액세스 권한을 구성 동기화에 부여하려면 다음 단계를 완료하세요.

1. SSH 키 쌍을 만들거나 보안 관리자에게 제공해 달라고 요청합니다. SSH 키 쌍을 만들어야 하는 경우 다음 명령어를 실행하여 4096비트 RSA 키를 만듭니다.

   ssh-keygen -t rsa -b 4096 \
     -C "GIT_REPOSITORY_USERNAME" \
     -N '' \
     -f /path/to/KEYPAIR_FILENAME
   

   다음을 바꿉니다.

   • GIT_REPOSITORY_USERNAME: 구성 동기화가 저장소에 인증하기 위해 사용할 사용자 이름입니다. GitHub와 같은 서드 파티 Git 저장소 호스트를 사용하거나 Secure Source Manager에서 서비스 계정을 사용하려는 경우 인증을 위해 별도의 계정을 사용하는 것이 좋습니다.
   • /path/to/KEYPAIR_FILENAME: 키 쌍 파일의 경로입니다.

2. 저장소가 새로 생성된 공개 키를 인식하도록 구성합니다. Git 호스팅 업체의 문서를 참조하세요. 다음 목록에서 일반적인 Git 호스팅 제공업체에 관한 안내를 확인할 수 있습니다.

   • Secure Source Manager
   • Bitbucket
   • GitHub
   • GitLab

3. 비공개 키를 사용하여 git-creds 보안 비밀을 만듭니다.

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
       --namespace=config-management-system \
       --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME
   

   참고: 프록시를 사용해야 하는 경우 --from-literal=https_proxy=HTTPS_PROXY_URL 플래그를 전달하세요.

   /path/to/KEYPAIR_PRIVATE_KEY_FILENAME를 비공개 키 이름으로 바꿉니다.

4. 선택사항이지만 권장사항: SSH 인증을 사용할 때 알려진 호스트 확인을 구성하려면 git_creds 보안 비밀의 data.known_hosts 필드에 알려진 호스트 키를 추가합니다.

   1. 알려진 호스트 키를 추가하려면 다음 명령어를 실행하세요.

      kubectl edit secret git-creds --namespace=config-management-system
      

   2. data 아래에 known_hosts 항목을 추가하려면 다음 명령어를 실행합니다.

        known_hosts: KNOWN_HOSTS_KEY
      

      KNOWN_HOSTS_KEY을 알려진 호스트 키로 바꿉니다.

   known_hosts 확인을 사용 중지하려면 보안 비밀에서 known_hosts 필드를 삭제합니다.

구성 동기화를 설치할 때 SSH 키 쌍 (ssh)을 인증 유형으로 사용합니다.

Git 저장소의 URL을 입력할 때 URL은 SSH 프로토콜 형식을 사용해야 합니다. URL 형식은 Git 제공업체에 따라 다릅니다.

cookiefile 사용

cookiefile을 획득하는 절차는 저장소 구성에 따라 다릅니다. 일반적으로 사용자 인증 정보는 홈 디렉터리의 .gitcookies 파일에 저장되거나 보안 관리자가 제공합니다.

cookiefile를 사용하여 구성 동기화에 Git 저장소에 대한 읽기 전용 액세스 권한을 부여하려면 다음 단계를 완료하세요.

cookiefile을 만들거나 획득한 후에는 클러스터의 새 보안 비밀에 추가합니다. 보안상의 이유로 HTTPS를 사용하는 것이 좋습니다.

kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-file=cookie_file=/path/to/COOKIEFILE

/path/to/COOKIEFILE을 경로와 파일 이름으로 바꿉니다.

참고: 프록시를 사용해야 하는 경우 --from-literal=https_proxy=HTTPS_PROXY_URL 플래그를 전달하세요.

구성 동기화를 설치할 때 cookiefile (cookiefile)을 인증 유형으로 사용합니다.

토큰 사용

조직에서 SSH 키 사용을 허용하지 않으면 토큰을 대신 사용하는 것이 좋습니다.

토큰을 사용하여 Git 저장소에 대한 읽기 전용 액세스 권한을 구성 동기화에 부여하려면 다음 단계를 완료하세요.

1. Git 제공업체에서 토큰을 생성합니다. 안내는 Git 호스팅 업체의 문서를 참고하세요. 다음 목록에서 일반적인 Git 호스팅 제공업체에 관한 안내를 확인할 수 있습니다.

   • GitHub: PAT를 만듭니다. 비공개 저장소에서 읽을 수 있도록 토큰에 repo 범위를 부여합니다. PAT를 GitHub 계정에 결합하므로 머신 사용자를 만들고 PAT를 머신 사용자에게 결합하는 것도 좋습니다.
   • GitLab: PAT를 만듭니다 또는 배포 토큰을 만듭니다.
   • Bitbucket: 앱 비밀번호를 만듭니다.

2. 토큰을 만들거나 획득한 후에는 클러스터의 새 보안 비밀에 추가합니다. 보안상의 이유로 HTTPS를 사용하는 것이 좋습니다.

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-literal=username=USERNAME \
     --from-literal=token=TOKEN
   

   참고: 프록시를 사용해야 하는 경우 --from-literal=https_proxy=HTTPS_PROXY_URL 플래그를 전달하세요.

   다음을 바꿉니다.

   • USERNAME: 사용할 사용자 이름입니다.
   • TOKEN: 이전 단계에서 만든 토큰입니다.

구성 동기화를 설치할 때 토큰 (token)을 인증 유형으로 사용합니다.

Google 서비스 계정 사용

Google 서비스 계정을 사용하여 구성 동기화에 관리형 클러스터와 동일한 프로젝트의 저장소에 대한 액세스 권한을 부여할 수 있습니다. 다음 요구사항을 충족해야 합니다.

• 저장소가 Secure Source Manager 또는 Cloud Source Repositories에 있습니다.
• 클러스터에 GKE용 워크로드 아이덴티티 제휴 또는 GKE용 Fleet 워크로드 아이덴티티 제휴가 사용 설정되어 있습니다.

Google 서비스 계정을 사용하여 Git 저장소에 대한 읽기 전용 액세스 권한을 구성 동기화에 부여하려면 다음 단계를 완료하세요.

1. 정책 바인딩을 만드는 데 필요한 권한을 얻으려면 관리자에게 서비스 계정에 대한 서비스 계정 관리자 (roles/iam.serviceAccountAdmin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

   커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

2. 아직 서비스 계정이 없으면 서비스 계정을 만듭니다.

3. 사용 중인 저장소 유형에 따라 Google 서비스 계정에 IAM 역할을 부여합니다.

   Secure Source Manager

   Google 서비스 계정에 Secure Source Manager 인스턴스 접근자 (roles/securesourcemanager.instanceAccessor) 및 Secure Source Manager 저장소 리더 (roles/securesourcemanager.repoReader) IAM 역할을 부여합니다.

   • 프로젝트의 모든 저장소에 동일한 권한이 적용되는 경우 프로젝트 전체 권한을 부여합니다.

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/securesourcemanager.instanceAccessor \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/securesourcemanager.repoReader \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

     다음을 바꿉니다.

     • PROJECT_ID: 프로젝트 ID입니다.
     • GSA_NAME: Secure Source Manager에 연결하려는 Google 서비스 계정의 이름입니다.

   • 저장소별 권한을 부여하려면 Secure Source Manager 문서의 사용자에게 저장소 수준 역할 부여를 참고하세요.

   구성 동기화를 설치할 때 워크로드 아이덴티티(gcpserviceaccount)를 인증 유형으로 사용합니다. 서비스 계정 이메일도 추가해야 합니다.

   Secure Source Manager에는 저장소 URL이 https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git 형식이어야 합니다.

   Cloud Source Repositories

   Cloud Source Repositories 리더 (roles/source.reader) IAM 역할을 Google 서비스 계정에 부여합니다.

   • 프로젝트의 모든 저장소에 동일한 권한이 적용되는 경우 프로젝트 전체 권한을 부여합니다.

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/source.reader \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"
     

     다음을 바꿉니다.

     • PROJECT_ID: 프로젝트 ID입니다.
     • GSA_NAME: Cloud Source Repositories에 연결하려는 Google 서비스 계정의 이름입니다.

   • 서비스 계정이 프로젝트의 저장소마다 다른 수준의 액세스 권한을 갖도록 하려면 저장소별 권한을 부여합니다.

     gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID
     

     다음을 바꿉니다.

     • PROJECT_ID: 프로젝트 ID입니다.
     • REPOSITORY: 저장소의 이름입니다.
     • POLICY_FILE: Identity and Access Management 정책이 포함된 JSON 또는 YAML 파일

   구성 동기화를 설치할 때 워크로드 아이덴티티 (gcpserviceaccount)를 인증 유형으로 사용합니다. 서비스 계정 이메일도 추가해야 합니다.

Kubernetes 서비스 계정은 구성 동기화를 처음 구성할 때까지 생성되지 않으므로 다음 단계는 구성 동기화를 구성한 후에 완료해야 합니다. 이 작업은 차량당 한 번만 수행하면 됩니다. Kubernetes 서비스 계정이 Google 서비스 계정 역할을 하도록 허용하는 바인딩을 만들려면 다음 명령어를 실행합니다.

gcloud iam service-accounts add-iam-policy-binding \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

다음을 바꿉니다.

• FLEET_HOST_PROJECT_ID: GKE용 워크로드 아이덴티티 제휴를 사용하는 경우 값은 PROJECT_ID와 동일합니다. GKE용 Fleet 워크로드 아이덴티티 제휴를 사용하는 경우 클러스터가 등록된 Fleet의 프로젝트 ID를 값으로 사용합니다.
• GSA_NAME: Secure Source Manager 또는 Cloud Source Repositories에 연결하는 데 사용하려는 커스텀 Google 서비스 계정입니다.
• KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다. 대부분의 경우 값은 root-sync입니다. 구성 동기화는 Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 설치할 때 root-sync라는 RootSync 객체를 자동으로 만들기 때문입니다. 그렇지 않으면 root-reconciler-ROOT_SYNC_NAME을 값으로 사용합니다.

Google 서비스 계정으로 구성 동기화에 연결하는 데 문제가 있는 경우 Google 서비스 계정의 권한 문제 해결을 참고하세요.

Compute Engine 기본 서비스 계정 사용

Google 서비스 계정 대신 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있지 않은 경우 Compute Engine 서비스 계정을 사용하여 인증할 수 있습니다. 이 메서드는 Secure Source Manager 및 Cloud Source Repositories의 저장소에만 지원됩니다.

Compute Engine 기본 서비스 계정을 사용하여 구성 동기화에 저장소에 대한 읽기 전용 액세스 권한을 부여하려면 기본 서비스 계정에 roles/source.reader 역할을 부여하세요.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:[e-mail]"

다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID입니다.
• PROJECT_NUMBER: 프로젝트 번호

구성 동기화를 설치할 때 Google Cloud Repository (gcenode)를 인증 유형으로 사용합니다.

GitHub 앱 사용

저장소가 GitHub에 있는 경우 GitHub 앱을 사용하여 저장소를 구성 동기화에 연결할 수 있습니다.

1. GitHub의 안내에 따라 GitHub 앱을 프로비저닝하고 저장소에서 읽을 수 있는 권한을 부여합니다.

2. 클라이언트 또는 애플리케이션 ID를 사용하여 클러스터의 새 보안 비밀에 GitHub 앱 구성을 추가합니다.

   클라이언트 ID

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-literal=github-app-client-id=CLIENT_ID \
     --from-literal=github-app-installation-id=INSTALLATION_ID \
     --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
     --from-literal=github-app-base-url=BASE_URL
   

   • CLIENT_ID를 GitHub 앱의 클라이언트 ID로 바꿉니다.
   • INSTALLATION_ID를 GitHub 앱의 설치 ID로 바꿉니다.
   • /path/to/GITHUB_PRIVATE_KEY를 비공개 키가 포함된 파일의 이름으로 바꿉니다.
   • BASE_URL을 GitHub API 엔드포인트의 기본 URL로 바꿉니다. 이 값은 저장소가 www.github.com에 호스팅되지 않은 경우에만 필요합니다. 그렇지 않으면 인수를 생략할 수 있으며 기본값은 https://api.github.com/입니다.

   애플리케이션 ID

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
       --namespace=config-management-system \
       --from-literal=github-app-application-id=APPLICATION_ID \
       --from-literal=github-app-installation-id=INSTALLATION_ID \
       --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
       --from-literal=github-app-base-url=BASE_URL
   

   • APPLICATION_ID를 GitHub 앱의 애플리케이션 ID로 바꿉니다.
   • INSTALLATION_ID를 GitHub 앱의 설치 ID로 바꿉니다.
   • /path/to/GITHUB_PRIVATE_KEY를 비공개 키가 포함된 파일의 이름으로 바꿉니다.
   • BASE_URL을 GitHub API 엔드포인트의 기본 URL로 바꿉니다. 이 값은 저장소가 www.github.com에 호스팅되지 않은 경우에만 필요합니다. 그렇지 않으면 인수를 생략할 수 있으며 기본값은 https://api.github.com/입니다.

구성 동기화를 설치할 때 GitHub 앱 (githubapp)을 인증 유형으로 사용합니다.

문제 해결

Config Sync를 정보 소스에 연결하는 것과 관련된 문제를 해결하려면 다음 문제 해결 주제를 검토하세요.

• 정보 소스에 연결
• Google 서비스 계정의 권한 문제

다음 단계

• 기본 설정으로 구성 동기화 설치
• 구성 동기화 설치 맞춤설정