이 페이지는 Cloud Translation API를 통해 번역되었습니다.

23. 코드형 인프라 설정

예상 소요 시간: 60분

작동 가능 구성요소 소유자: IAC

기술 프로필: 배포 엔지니어

에어 갭이 적용된 Google Distributed Cloud (GDC)의 코드형 인프라 (IaC)는 다음 두 시스템으로 구성됩니다.

구성 동기화는 분산 클라우드 코드형 인프라 (IaC)에서 클러스터 수준 리소스와 공유 서비스를 관리하는 데 사용되는 구성요소입니다.
GitLab은 구성 동기화의 정보 소스 (SoT)로 사용되는 Git 저장소를 호스팅합니다. 타겟 클러스터는 저장소의 SoT에서 구성 동기화가 관리하는 클러스터입니다.
- GitLab에는 정책 및 구성 변경사항에 다자간 승인(MPA)을 구현하는 코드 검토 시스템이 포함되어 있습니다.

배포에는 다음 두 가지 영역 유형이 포함됩니다.

앵커 영역: 이미 전역 컨트롤 플레인의 일부인 영역입니다. 첫 번째 영역은 배포의 앵커 영역입니다.
조인 영역: 전역 컨트롤 플레인에 조인하는 영역입니다.

구성 동기화는 root-admin 및 조직 관리자 클러스터에서 Kubernetes 객체를 관리합니다. 기본 root-admin 클러스터의 GitLab에서 제공하는 분산 클라우드 IaC 저장소에서 읽도록 구성되어 있습니다.

Distributed Cloud는 부트스트랩 중에 IaC를 설치합니다. 다음 수동 단계를 실행하여 IaC 설정을 완료합니다.

23.1. 첫 번째 영역 IaC 설정

이 섹션에는 배포의 첫 번째 영역에서 IaC를 설정하는 단계가 포함되어 있습니다.

23.2. 기본 요건

루트 관리자 클러스터를 부트스트랩했습니다.
OC IT의 Active Directory Federation Services (ADFS) 인스턴스에서 SAML 클라이언트를 GitLab의 ID 제휴 클라이언트로 만듭니다.

23.3. GitLab 액세스 0일차

https://iac.GDC_URL에서 GitLab 웹 콘솔을 엽니다. GDC_URL은 CIQ에 지정된 도메인입니다.

# Use the root kubeconfig of the root admin cluster.
export ANCHOR_KUBECONFIG=ANCHOR_ZONE_KUBECONFIG
echo https://$(kubectl --kubeconfig $ANCHOR_KUBECONFIG get dnsregistrations \
     -n gitlab-system iac -o jsonpath='{.status.fqdn}')

0일차 사용자 이름(ioadmin)을 사용합니다.

다음 명령어를 실행하여 비밀번호를 가져옵니다.

export IO_ADMIN_PWD=$(kubectl --kubeconfig $ANCHOR_KUBECONFIG \
  get secret gitlab-basic-users -n gitlab-system  \
  -o jsonpath='{.data.admin}' | base64 -d)

로그인하고 메뉴 > 프로젝트 > 프로젝트 탐색 gdch / iac로 이동하여 iac Git 저장소가 생성되었는지 확인합니다.

23.4. 관리자 사용자 만들기

ADFS에서 전용 관리자 사용자를 만듭니다. 관리 목적이 아닌 용도로 사용해서는 안 되며 '-ga' 확장자가 있어야 합니다. 초기 관리자 사용자는 Active Directory Federation Services (ADFS)에서 사용하는 것과 동일한 email를 사용해야 합니다.

다음 명령어를 실행하여 새 사용자를 만듭니다.

export NEW_USER_NAME=NEW_USER_NAME
export NEW_USER_USERNAME=NEW_USERNAME
export NEW_USER_PWD=NEW_USER_PWD
export NEW_USER_EMAIL=NEW_USER_EMAIL
export GDC_URL=GDC_URL
export TOKEN=$(curl -X POST https://iac.$GDC_URL/oauth/token \
    -d "grant_type=password&username=ioadmin&password=${IO_ADMIN_PWD}" \
    | jq -r '.access_token')
USERID=$(curl -X GET https://iac.$GDC_URL/api/v4/users \
    -d access_token=${TOKEN} -d username=ioadmin |\
    sed -E 's/.*"id":"?([^,"]*)"?.*/\1/')
curl -X POST https://iac.$GDC_URL/api/v4/users \
    -d username=${NEW_USER_USERNAME} -d password=${NEW_USER_PWD} -d name=${NEW_USER_NAME} \
    -d email=${NEW_USER_EMAIL} -d admin=true -d access_token=${TOKEN} 
curl -X POST https://iac.$GDC_URL/oauth/revoke \
    -d client_id=${USERID} -d "token=${TOKEN}"

23.5. GitLab 라이선스 업데이트

GitLab의 많은 기능을 사용하려면 'Ultimate' 라이선스가 필요합니다. 이 단계에서는 GDC와 함께 제공된 임시 라이선스를 사이트의 자체 라이선스로 바꿉니다. 라이선스 파일 또는 키로 GitLab EE 활성화에 자세한 내용이 나와 있습니다.

받은 사이트의 라이선스 키는 .gitlab-license 확장자가 있는 base64 인코딩 ASCII 텍스트 파일입니다. 이 키를 사용하여 GitLab을 활성화합니다.

ioadmin로 GitLab 웹 콘솔에 로그인합니다.
탐색 메뉴에서 메뉴를 선택한 다음 관리자를 선택합니다.
탐색 메뉴에서 설정을 선택한 다음 일반을 선택합니다.
라이선스 추가 영역에서 파일을 업로드하거나 키를 입력하여 라이선스를 추가합니다.
서비스 약관 체크박스를 선택합니다.
라이선스 추가를 선택합니다.

23.6. GitLab 저장소 설정

ConfigSync는 루트 관리자 클러스터와 조직 관리자 클러스터에서 Kubernetes 객체를 관리하며 루트 관리자 클러스터의 GitLab에서 제공하는 Distributed Cloud IaC 저장소에서 읽도록 구성됩니다.

Configsync가 구성을 사용하고 필요한 Kubernetes 클러스터에 적용할 수 있도록 초기 GitLab 폴더를 설정해야 합니다.

infrastructure
│   └── zonal
│     └── zones
│         ├── ${anchor_zone_name}
│           ├── root-admin
│             ├── kustomization.yaml
│   └── global
│     └── orgs
│         ├── root
│           ├── kustomization.yaml

다음 단계에 따라 초기 파일 구조를 만듭니다.

'메뉴 -> 프로젝트 탐색'에서 iac 저장소를 엽니다.
'Web IDE'를 엽니다.
다음 콘텐츠로 /infrastructure/zonal/zones/${anchor_zone_name}/root-admin/kustomization.yaml에 파일을 만듭니다.
```
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
metadata:
  name: root-admin-kustomization
```
'커밋' 버튼을 클릭합니다.
'기본 브랜치에 커밋'을 선택하고 확인합니다.

23.7. 복수 사용자 승인 체계 (MPA) 설정

이 섹션을 사용하여 iac 저장소의 모든 병합 요청에 승인을 요구하고 main 브랜치에 직접 커밋 (병합 요청을 생성하지 않고)하는 것을 방지하여 다자간 승인 (MPA)을 적용하도록 시스템을 구성합니다.

23.7.1. GitLab에서 병합 요청 승인 사용 설정

iac 저장소로 이동합니다.
웹 IDE를 사용하여 루트 폴더에 CODEOWNERS라는 파일을 만들고 첫 번째 단계로 Distributed Cloud 그룹을 저장소 소유자로 추가합니다.
```
[Repository Owners]
* @gdch
```
CODEOWNERS 파일에 추가된 사용자만 iac 저장소에서 병합 요청을 승인할 수 있습니다. 이 일반 파일은 설정 목적으로만 사용됩니다. 세부 승인 권한에 관한 자세한 내용은 IAC-R0007을 참고하세요.
커밋 버튼을 클릭합니다.
main 브랜치에 커밋을 선택하고 확인합니다.
CODEOWNERS 파일에 사용자를 더 추가하려면 CODEOWNERS의 기존 사용자가 승인할 병합 요청을 만드세요.

23.8. Active Directory Federation Services (ADFS)를 GitLab에 연결

GitLab의 Auth 프레임워크를 사용하여 SAML 클라이언트로 ADFS를 GitLab에 연결할 수 있습니다.

ID 공급업체에 비공개 인증 기관을 사용하는 경우 GitLab 인스턴스에 추가해야 합니다. ADFS CA 인증서의 base64 버전을 가져와 보안 비밀에 넣습니다.

cat <<EOF > adfs-ca-cert-secret.yaml
apiVersion: v1
data:
  tls.crt: ADFS_CA_CERTIFICATE_BASE64
kind: Secret
metadata:
  name: adfs-ca-cert-secret
  namespace: gitlab-system
type: Opaque
EOF

kubectl apply -f adfs-ca-cert-secret.yaml

23.8.1. SAML 인증을 위해 ADFS 구성

Helm 구성을 사용하여 GitLab을 ADFS에 연결하기 전에 ADFS에서 SAML 클라이언트를 만들어야 합니다. Windows 인스턴스에서 다음 단계를 따르세요.

관리자 권한으로 AD FS 관리 앱을 실행합니다.
AD FS 디렉터리에서 Relying Party Trust 폴더를 클릭합니다. 작업 패널에서 신뢰 당사자 트러스트 추가를 클릭합니다.
신뢰 당사자 트러스트 추가 마법사가 열립니다. 첫 번째 단계에서 클레임 인식을 선택하고 시작을 클릭합니다.
신뢰 당사자에 대한 수동 데이터 입력을 선택하고 다음을 클릭합니다.
표시 이름 및 메모 필드에 ADFS 인스턴스에 대해 알아볼 수 있는 정보를 입력합니다. 다음을 클릭합니다.
다음을 클릭하여 인증서 구성 단계를 건너뜁니다.
SAML 2.0 WebSSO 프로토콜 지원 사용 체크박스를 클릭합니다. 신뢰 당사자 SAML 2.0 SSO 서비스 URL 필드에 다음을 입력합니다. https://iac.GDC_URL/users/auth/saml/callback

GDC_URL를 GDC의 조직 URL로 바꿉니다.

IaC 이름을 지정하고 다음을 추가합니다.

https://iac.GDC_URL.sesame.street https://iac.GDC_URL.sesame.street/users/auth/saml/callback

식별자 구성, 액세스 제어 정책 선택, 트러스트 추가 준비 단계에서 다음을 클릭하여 마법사를 완료합니다.

참고: Configure Identifiers 페이지에서 단계를 건너뛰려면 다음 신뢰 당사자 식별자를 추가하세요.
```
  # Replace GDC_URL with the cells URL, for example, bert.sesame.street
  https://iac.GDC_URL
  https://iac.GDC_URL/users/auth/saml/callback
```
새로 만든 신뢰 당사자 트러스트로 디스플레이가 업데이트됩니다. 항목을 마우스 오른쪽 버튼으로 클릭하고 클레임 발급 정책 수정을 선택합니다.
규칙 추가 버튼을 클릭하고 규칙 유형 선택 단계에서 LDAP 특성을 클레임으로 보내기의 클레임 규칙 템플릿을 선택합니다. Next(다음)를 클릭합니다.
클레임 규칙 구성 단계에서 다음 매개변수를 완료합니다.
1. 클레임 규칙 이름 필드에 Email를 입력합니다.
2. 속성 저장소 목록에서 Active Directory를 선택합니다.
3. LDAP 속성을 발신 클레임 유형에 매핑 표의 LDAP 속성 열에서 E-Mail-Addresses를 선택하거나 입력합니다.
4. 표의 보내는 클레임 유형 열에서 E-Mail Address를 선택하거나 입력합니다.
5. 마법사를 완료합니다.
규칙 추가 버튼을 클릭합니다.
항목을 마우스 오른쪽 버튼으로 클릭하고 항목에서 Edit Claim Issurance Policy를 다시 클릭합니다.
규칙 유형 선택 단계에서 수신 클레임 변환의 클레임 규칙 템플릿을 선택합니다. 다음을 클릭합니다.
클레임 규칙 구성 단계에서 다음 매개변수를 완료합니다.
1. 클레임 규칙 이름 필드에 Transform email to nameid를 입력합니다.
2. 수신 클레임 유형 필드에서 E-Mail Address을 선택하거나 입력합니다.
3. 보내는 클레임 유형 필드에서 Name ID를 선택하거나 입력합니다.
4. 발신 이름 ID 형식 필드에서 Persistent Identifier를 선택하거나 입력합니다.
5. 모든 클레임 값 통과 옵션을 선택합니다.
6. 마법사를 완료합니다.

23.8.2. GitLab에 SAML 구성 추가

이 섹션에서는 Gitlab에 SAML 구성을 추가하는 단계를 설명합니다.

23.8.2.1. ID 공급업체에 GitLab 등록

ADFS에서 SAML 클라이언트 구성을 엽니다. GitLab에서 IdP와 통합하려면 다음 값이 필요합니다.

assertion_customer_service_url - IdP는 사용자를 인증한 후 이 URL로 리디렉션합니다. https://iac.GDC_URL/users/auth/saml/callback으로 설정합니다.

GDC_URL를 GDC의 조직 URL로 바꿉니다.
idp_cert_fingerprint - GitLab은 이 지문을 사용하여 수신되는 SAML 메시지의 인증서를 확인합니다. ADFS에서 idp_cert_fingerprint를 찾으려면 다음 단계를 따르세요.
1. 관리자 권한으로 앱 AD FS Management를 실행합니다.
2. 디렉터리 트리 AD FS > 서비스 > 인증서에서 인증서 폴더를 클릭합니다. 토큰 서명 섹션에 인증서가 표시됩니다. 해당 인증서를 마우스 오른쪽 버튼으로 클릭하고 인증서 보기를 선택합니다.
3. 인증서 창에서 Details 탭으로 이동합니다. Thumbprint이라는 항목이 표시될 때까지 목록을 스크롤합니다. 항목을 클릭하고 콘솔에 표시된 콘텐츠를 복사합니다.
idp_sso_target_url - GitLab에서 SAML로 인증할 때 이 엔드포인트를 타겟팅합니다. ADFS에서 idp_sso_target_url을 찾으려면 다음 단계를 따르세요.
1. 관리자 권한으로 AD FS 관리 앱을 실행합니다.
2. 디렉터리 트리 AD FS > 서비스에서 엔드포인트 폴더를 클릭합니다.
  
  엔드포인트.
3. 중앙 화면에서 SAML 2.0/WS-Federation 유형이 있는 행을 찾습니다. 타겟 엔드포인트는 ADFS URL 및 타겟 엔드포인트입니다. 예를 들어 인스턴스의 도메인 이름이 https://ocit.gdch.test/이고 타겟 엔드포인트가 /adfs/ls이면 idp_sso_target_url은 https://ocit.gdch.test/adfs/ls입니다.

issuer - GitLab에서 자체를 식별하는 데 사용하는 URL입니다. https://iac.GDC_URL를 사용하세요.

위의 IdP 값을 준비하고 custom_saml.yaml이라는 맞춤 구성에 작성합니다. 이 YAML 파일을 수정하여 SAML 클라이언트에 필요한 구성을 가져옵니다.

cat <<EOF > custom_saml.yaml
name: saml
label: "ADFS SAML" # This is the label the login button will use.
args:
  assertion_consumer_service_url: "https://iac.GDC_URL/users/auth/saml/callback"
  idp_cert_fingerprint: "ADFS_IDP_CERT_FINGERPRINT"
  idp_sso_target_url: "ADFS_IDP_SSO_TARGET_URL"
  issuer: "https://iac.GDC_URL"

  # These parameters are necessary for ADFS to connect to GitLab. Do not change unless you are sure of what you're doing.
  name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
  attribute_statements: { email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }
EOF

준비가 되면 custom-gitlab-saml-provider라는 보안 비밀로 구성을 적용합니다.

cat <<EOF > custom-gitlab-saml-provider.yaml
apiVersion: v1
data:
  provider: |
  $(cat custom_saml.yaml | base64 -w 0)
kind: Secret
metadata:
  name: custom-gitlab-saml-provider
  namespace: gitlab-system
  annotations:
    "helm.sh/hook": post-install,post-upgrade
    "helm.sh/hook-weight": "-5"
EOF
kubectl apply -f custom-gitlab-saml-provider.yaml

subcomponentoverride.yaml를 만들 때 보안 비밀을 사용할 수 있습니다. 변수에 대한 자세한 내용은 GitLab 문서를 참고하세요.

cat <<EOF > subcomponentoverride.yaml
apiVersion: lcm.private.gdc.goog/v1
kind: SubcomponentOverride
metadata:
  name: iac-gitlab
  namespace: root
spec:
  subComponentRef: "iac-gitlab"
  backend:
    operableParameters:
      omniauth:
        enabled: true
        providers:
        - secret: custom-gitlab-saml-provider
      certificates:
        customCAs:
        - secret: adfs-ca-cert-secret
        - configMap: trust-store-root-ext
EOF
kubectl apply -f subcomponentoverride.yaml

이렇게 하면 하위 구성요소 재정의가 생성됩니다. 구성이 생성되었는지 확인하려면 다음을 실행합니다. sh kubectl get subcomponentoverride -n root

출력은 다음과 비슷합니다.

NAME            AGE
iac-gitlab   1s

23.8.2.2. 처음 로그인한 SAML 사용자 초기화

SAML을 사용 설정하면 로컬 로그인이 삭제됩니다. 사용자는 비상 액세스 절차를 거쳐 로컬 로그인을 다시 사용 설정하고 ioadmin에 다시 액세스해야 합니다.

관리자 사용자 만들기에서 만든 첫 번째 초기화된 관리자는 추가 수정 없이 관리자로 작동합니다. 프로젝트에 액세스할 수 없어야 합니다. Distributed Cloud 프로젝트에 사용자를 추가하려면 ADFS에서 새 사용자 온보딩을 따르세요.

23.8.3. ADFS 연결 확인

GitLab webservice 포드의 상태를 확인합니다.

kubectl --kubeconfig $KUBECONFIG get pod -l app=webservice,release=gitlab -n gitlab-system

이름	READY	상태	연령
gitlab-webservice-default-5d99b4d7c7-9fmln	2/2	실행 중	4분 6초
gitlab-webservice-default-5d99b4d7c7-w99p4	2/2	실행 중	96초
gitlab-webservice-default-7884d4c8b9-qjhtv	2/2	종료 중	18시간

https://iac.GDC_URL로 이동하여 SSO 로그인에 사용할 ADFS SAML 버튼이 표시되고 직접 로그인 사용자 및 비밀번호 필드가 표시되지 않는 화면이 표시되는지 확인합니다.
ADFS SAML을 클릭합니다. ADFS에 로그인하라는 메시지가 표시되는지 확인합니다.
ADFS에 로그인한 후 GitLab에 로그인되어 있으며 이제 애플리케이션과 상호작용할 수 있는지 확인합니다.

23.9. Day 0 관리자 계정 잠금

SAML을 사용 설정한 후 웹 인터페이스의 비밀번호 인증을 사용 중지하고 API 액세스가 유지되므로 ioadmin의 비밀번호를 재설정합니다.

다음 스크립트를 실행합니다.

  export KUBECONFIG=/root/release/root-admin/root-admin-kubeconfig
  export PWD=$(kubectl get secret gitlab-basic-users -n gitlab-system -o yaml \
      | grep admin | head -n1 | awk '{print $2}' | xargs echo | base64 -d)
  export TOKEN=$(curl -X POST https://iac.GDC_URL/oauth/token \
      -d "grant_type=password&username=ioadmin&password=${PWD}" \
      | jq -r '.access_token')
  curl -X PUT  https://iac.GDC_URL/api/v4/application/settings \
      -d access_token=${TOKEN} \
      -d password_authentication_enabled_for_web=false
  NEWPASS=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)
  USERID=$(curl -X GET https://iac.GDC_URL/api/v4/users \
      -d access_token=${TOKEN} -d username=ioadmin |\
      jq -r '.[] | .id')
  curl -X PUT  https://iac.GDC_URL/api/v4/users/${USERID} \
      -d access_token=${TOKEN} -d username=ioadmin \
      -d "password=${NEWPASS}" \
      -d user_id=${USERID}
  curl -X POST https://iac.GDC_URL/oauth/revoke \
      -d client_id=${USERID} -d "token=${TOKEN}"

새 비밀번호를 보안 비밀 gitlab-basic-users에 저장합니다.

  kubectl patch secret gitlab-basic-users -n gitlab-system --type=json -p'[{"op": "replace", "path": "/data/admin", "value": '"$(echo $NEWPASS | base64 -w0)"'}]'

OI ADFS의 계정을 사용하여 로그인합니다.

23.10. 조인 영역 IaC 설정

이 섹션에서는 배포의 조인 영역에서 IaC를 설정하는 단계를 설명합니다.

23.11. 기본 요건

조인 영역을 설정하기 전에 루트 관리자 클러스터를 부트스트랩해야 합니다.

23.12. configsync 사용자 인증 정보 구성

구성 동기화 사용자 인증 정보를 구성하려면 다음 단계를 따르세요.

앵커 영역의 루트 관리자 클러스터에 연결합니다.

구성 동기화 사용자 인증 정보를 가져옵니다.

kubectl --kubeconfig $ANCHOR_KUBECONFIG get secret -n config-management-system iac-creds-replica -o json |\
    jq 'del(.metadata.creationTimestamp, .metadata.resourceVersion, .metadata.uid)' > iac-creds-replica.json

iac-creds-replica.json 파일을 복사합니다.
조인 영역의 루트 관리자 클러스터에 연결합니다.
iac-creds-replica.json 파일을 붙여넣습니다.

구성 동기화 사용자 인증 정보를 루트 관리자 클러스터에 적용합니다.

# Use the root kubeconfig of the root admin cluster.
export JOINING_KUBECONFIG=JOINING_ZONE_KUBECONFIG
kubectl --kubeconfig $JOINING_KUBECONFIG apply -f iac-creds-replica.json

구성 동기화 사용자 인증 정보가 구성되어 있는지 확인합니다.

kubectl --kubeconfig $JOINING_KUBECONFIG get secret -n config-management-system \
    iac-creds-replica -o yaml

23.13. 구성 동기화 정보 소스 구성

다음 단계에 따라 구성 동기화 정보 소스를 구성하세요.

앵커 영역의 루트 관리자 클러스터에 연결합니다.

GitLab의 FQDN을 가져옵니다.

export primaryDnsFQDN=$(kubectl --kubeconfig $ANCHOR_KUBECONFIG get DNSRegistration \
    -n gitlab-system iac -o jsonpath='{.status.fqdn}')

조인 영역의 루트 관리자 클러스터에 연결합니다.

IaC SubcomponentOverride 파일을 만듭니다.

echo "apiVersion: lcm.private.gdc.goog/v1
kind: SubcomponentOverride
metadata:
    name: iac
    namespace: root
spec:
    subComponentRef: "iac-configsync"
    backend:
        operableParameters:
            primaryDnsFQDN: ${primaryDnsFQDN}" > iac-subcomponentoverride.yaml

구성 동기화 타겟을 구성합니다.

kubectl --kubeconfig $JOINING_KUBECONFIG apply -f iac-subcomponentoverride.yaml

구성 동기화 Git 저장소가 구성되어 있는지 확인합니다.

kubectl --kubeconfig $JOINING_KUBECONFIG get RootSync -n config-management-system \
    root-sync -o jsonpath='{.spec.git.repo}'

구성 동기화에 앵커 및 조인 영역 모두에 오류가 없는지 확인합니다.
```
kubectl --kubeconfig $JOINING_KUBECONFIG get RootSync \
    -n config-management-system root-sync \
    -o jsonpath='{.status.source.errors[0].errorMessage}'
```
1. root-sync에 오류 KNV2004가 포함된 경우 앵커 또는 결합 영역에서 사용되는 디렉터리 경로가 iac 저장소에 없습니다. 다음을 실행하여 필요한 디렉터리를 찾습니다.
```
kubectl --kubeconfig $JOINING_KUBECONFIG get RootSync \
    -n config-management-system root-sync
    -o jsonpath='{.spec.git.dir}'
```
2. iac 저장소에서 이전 명령어로 출력된 경로를 만들고 일반 kustomization.yaml 파일을 추가합니다. 그런 다음 main 브랜치로 병합합니다.
3. 구성 동기화에 오류가 없는지 확인하려면 원래 get RootSync 명령어를 다시 실행합니다.