이 튜토리얼은 Infrastructure as Code(IaC)를 통한 Terraform의 오픈 소스 포크인 OpenTofu를 사용하여 AWS에서 GitLab 워크스페이스 인프라를 설정하는 방법을 안내합니다.

시작하기 전에#

이 튜토리얼을 따르려면 다음이 필요합니다:

• Amazon Web Services(AWS) 계정.
• 워크스페이스 환경을 위한 도메인 이름.

GitLab 워크스페이스 인프라를 설정하려면:

1. 리포지터리 포크
2. AWS 자격 증명 설정
3. 도메인 및 인증서 준비
4. 필수 키 생성
5. Kubernetes용 GitLab 에이전트 토큰 생성
6. GitLab OAuth 구성
7. CI/CD 변수 구성
8. Kubernetes용 GitLab 에이전트 구성 업데이트
9. 파이프라인 실행
10. DNS 레코드 구성
11. 에이전트 승인
12. 워크스페이스 생성 및 설정 확인

리포지터리 포크#

먼저, 환경에 맞게 구성할 수 있도록 인프라 설정 리포지터리의 사본을 만들어야 합니다.

리포지터리를 포크하려면:

1. Workspaces Infrastructure Setup AWS 리포지터리로 이동합니다.
2. 리포지터리의 포크를 생성합니다. 자세한 내용은 포크 생성을 참조하세요.

AWS 자격 증명 설정#

다음으로, 인프라가 올바르게 프로비저닝될 수 있도록 AWS에서 필요한 권한을 설정합니다.

AWS 자격 증명을 설정하려면:

1. IAM 사용자 또는 IAM 역할을 생성합니다.

2. 다음 권한을 할당합니다:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "VisualEditor0",
         "Effect": "Allow",
         "Action": [
           "ec2:*",
           "eks:*",
           "elasticloadbalancing:*",
           "autoscaling:*",
           "cloudwatch:*",
           "logs:*",
           "kms:DescribeKey",
           "kms:TagResource",
           "kms:UntagResource",
           "kms:ListResourceTags",
           "kms:CreateKey",
           "kms:CreateAlias",
           "kms:ListAliases",
           "kms:DeleteAlias",
           "iam:AddRoleToInstanceProfile",
           "iam:AttachRolePolicy",
           "iam:CreateInstanceProfile",
           "iam:CreateRole",
           "iam:CreateServiceLinkedRole",
           "iam:GetRole",
           "iam:ListAttachedRolePolicies",
           "iam:ListRolePolicies",
           "iam:ListRoles",
           "iam:PassRole",
           "iam:DetachRolePolicy",
           "iam:ListInstanceProfilesForRole",
           "iam:DeleteRole",
           "iam:CreateOpenIDConnectProvider",
           "iam:CreatePolicy",
           "iam:TagOpenIDConnectProvider",
           "iam:GetPolicy",
           "iam:GetPolicyVersion",
           "iam:GetOpenIDConnectProvider",
           "iam:DeleteOpenIDConnectProvider",
           "iam:ListPolicyVersions",
           "iam:DeletePolicy"
         ],
         "Resource": "*"
       }
     ]
   }
   

3. 사용자 또는 역할에 대한 액세스 키를 생성합니다.

4. 액세스 키 ID와 비밀 액세스 키를 저장합니다. 나중에 CI/CD 변수를 구성할 때 필요합니다.

도메인 및 인증서 준비#

워크스페이스에 액세스하려면 도메인과 연결을 보호하기 위한 TLS 인증서가 필요합니다.

도메인과 인증서를 준비하려면:

1. 워크스페이스 환경을 위한 도메인을 구매하거나 기존 도메인을 사용합니다.
2. 다음을 위한 TLS 인증서를 생성합니다:
   • GitLab 워크스페이스 프록시 도메인. 예: workspaces.example.dev.
   • GitLab 워크스페이스 프록시 와일드카드 도메인. 예: *.workspaces.example.dev.

자세한 내용은 TLS 인증서 생성을 참조하세요.

필수 키 생성#

이제 인증 및 SSH 연결을 위한 보안 키를 생성해야 합니다.

필수 키를 생성하려면:

1. 임의의 문자, 숫자 및 특수 문자로 구성된 서명 키를 생성합니다. 예를 들어 다음을 실행합니다:

   openssl rand -base64 32
   

2. SSH 호스트 키를 생성합니다:

   ssh-keygen -f ssh-host-key -N '' -t rsa
   

Kubernetes용 GitLab 에이전트 토큰 생성#

Kubernetes용 GitLab 에이전트는 AWS Kubernetes 클러스터를 GitLab에 연결합니다.

에이전트 토큰을 생성하려면:

1. 그룹으로 이동합니다.
2. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
3. 왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
4. Connect a cluster를 선택합니다.
5. 에이전트 이름을 입력하고 나중에 사용하기 위해 저장합니다. 예: gitlab-workspaces-agentk-eks.
6. Create and register를 선택합니다.
7. 토큰과 KAS 주소를 나중에 사용하기 위해 저장합니다.
8. Continue를 선택합니다.

GitLab OAuth 구성#

다음으로, 워크스페이스에 안전하게 액세스하기 위한 OAuth 인증을 설정합니다.

GitLab OAuth를 구성하려면:

1. 오른쪽 상단에서 아바타를 선택합니다.

2. Edit profile을 선택합니다.

3. 왼쪽 사이드바에서 Access > Applications를 선택합니다.

4. OAuth applications로 스크롤합니다.

5. Add new application을 선택합니다.

6. 다음 설정을 업데이트합니다:

   • 이름: GitLab Workspaces Proxy
   • 리디렉션 URI: 예: https://workspaces.example.dev/auth/callback. 사용자 정의 도메인으로 교체합니다.
   • Confidential 체크박스를 선택합니다.
   • 범위: api, read_user, openid, profile.

7. Save application을 선택합니다.

8. CI/CD 변수에 사용하기 위해 Application ID와 Secret을 저장합니다.

9. Continue를 선택합니다.

CI/CD 변수 구성#

이제 인프라 파이프라인이 실행될 수 있도록 CI/CD 구성에 필요한 변수를 추가해야 합니다.

CI/CD 변수를 구성하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. Settings > CI/CD를 선택합니다.

3. Variables를 펼칩니다.

4. Project variables 섹션에서 다음 필수 변수를 추가합니다:

   변수	값
   AWS_ACCESS_KEY_ID	AWS 액세스 키 ID.
   AWS_SECRET_ACCESS_KEY	AWS 비밀 액세스 키.
   TF_VAR_agent_token	Kubernetes용 GitLab 에이전트 토큰.
   TF_VAR_kas_address	GitLab Kubernetes 에이전트 서버 주소. GitLab Self-Managed 인스턴스인 경우 필수입니다. 예: wss://kas.gitlab.com.
   TF_VAR_workspaces_proxy_auth_client_id	OAuth 애플리케이션 클라이언트 ID.
   TF_VAR_workspaces_proxy_auth_client_secret	OAuth 애플리케이션 시크릿.
   TF_VAR_workspaces_proxy_auth_redirect_uri	OAuth 콜백 URL. 예: https://workspaces.example.dev/auth/callback.
   TF_VAR_workspaces_proxy_auth_signing_key	생성한 서명 키.
   TF_VAR_workspaces_proxy_domain	워크스페이스 프록시 도메인.
   TF_VAR_workspaces_proxy_domain_cert	프록시 도메인의 TLS 인증서.
   TF_VAR_workspaces_proxy_domain_key	프록시 도메인의 TLS 키.
   TF_VAR_workspaces_proxy_ssh_host_key	생성한 SSH 호스트 키.
   TF_VAR_workspaces_proxy_wildcard_domain	워크스페이스의 와일드카드 도메인.
   TF_VAR_workspaces_proxy_wildcard_domain_cert	와일드카드 도메인의 TLS 인증서.
   TF_VAR_workspaces_proxy_wildcard_domain_key	와일드카드 도메인의 TLS 키.

5. 선택 사항. 배포를 사용자 지정하려면 다음 변수를 추가합니다:

   변수	값
   TF_VAR_region	AWS 지역.
   TF_VAR_zones	AWS 가용 영역.
   TF_VAR_name	리소스 이름 접두사.
   TF_VAR_cluster_endpoint_public_access	클러스터 엔드포인트에 대한 공개 액세스.
   TF_VAR_cluster_node_instance_type	Kubernetes 노드의 EC2 인스턴스 유형.
   TF_VAR_cluster_node_count_min	최소 워커 노드 수.
   TF_VAR_cluster_node_count_max	최대 워커 노드 수.
   TF_VAR_cluster_node_count	워커 노드 수.
   TF_VAR_cluster_node_labels	클러스터 노드에 적용할 레이블 맵.
   TF_VAR_agent_namespace	에이전트의 Kubernetes 네임스페이스.
   TF_VAR_workspaces_proxy_namespace	워크스페이스 프록시의 Kubernetes 네임스페이스.
   TF_VAR_workspaces_proxy_ingress_class_name	인그레스 클래스 이름.
   TF_VAR_ingress_nginx_namespace	Ingress-NGINX의 Kubernetes 네임스페이스.

잘 하셨습니다! 인프라 배포에 필요한 모든 변수를 구성했습니다.

Kubernetes용 GitLab 에이전트 구성 업데이트#

이제 워크스페이스를 지원하도록 Kubernetes용 GitLab 에이전트를 구성해야 합니다.

에이전트 구성을 업데이트하려면:

1. 포크된 리포지터리에서 .gitlab/agents/gitlab-workspaces-agentk-eks/config.yaml 파일을 엽니다.

   [!note] config.yaml 파일이 포함된 디렉터리는 Kubernetes용 GitLab 에이전트 토큰 생성 단계에서 생성한 에이전트 이름과 일치해야 합니다.

2. 다음 필수 필드로 파일을 업데이트합니다:

   remote_development:
     enabled: true
     dns_zone: "workspaces.example.dev"  # 도메인으로 교체
   

   추가 구성 옵션은 워크스페이스 설정을 참조하세요.

3. 이 변경 사항을 리포지터리에 커밋하고 푸시합니다.

파이프라인 실행#

이제 인프라를 배포할 시간입니다. CI/CD 파이프라인을 실행하여 AWS에서 필요한 모든 리소스를 생성합니다.

파이프라인을 실행하려면:

1. GitLab 프로젝트에서 새 파이프라인을 생성합니다:
   1. 왼쪽 사이드바에서 Build > Pipelines를 선택합니다.
   2. New pipeline을 선택하고 New pipeline을 다시 선택하여 확인합니다.
2. plan 잡이 성공하면 수동으로 apply 잡을 트리거합니다.

OpenTofu 코드가 실행되면 AWS에 다음 리소스를 생성합니다:

• Virtual Private Cloud(VPC).
• Elastic Kubernetes Service(EKS) 클러스터.
• Kubernetes용 GitLab 에이전트 Helm 릴리스.
• GitLab 워크스페이스 프록시 Helm 릴리스.
• Ingress NGINX Helm 릴리스.

훌륭합니다! 인프라가 이제 배포 중입니다. 완료하는 데 시간이 걸릴 수 있습니다.

DNS 레코드 구성#

인프라가 배포되었으므로 이제 새 환경을 가리키는 DNS 레코드를 구성해야 합니다.

DNS 레코드를 구성하려면:

1. 파이프라인 출력에서 Ingress-NGINX 로드 밸런서 주소를 가져옵니다:

   kubectl get services -n ingress-nginx ingress-nginx-controller
   

2. 도메인이 이 주소를 가리키는 DNS 레코드를 생성합니다. 예:

   • workspaces.example.dev → 로드 밸런서 IP 주소
   • *.workspaces.example.dev → 로드 밸런서 IP 주소

에이전트 승인#

다음으로, Kubernetes용 GitLab 에이전트가 GitLab 인스턴스에 연결할 수 있도록 승인합니다.

에이전트를 승인하려면:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. Settings > Workspaces를 선택합니다.
3. Group agents 섹션에서 All agents 탭을 선택합니다.
4. 사용 가능한 에이전트 목록에서 상태가 Blocked인 에이전트를 찾아 Allow를 선택합니다.
5. 확인 대화 상자에서 Allow agent를 선택합니다.

워크스페이스 생성 및 설정 확인#

마지막으로, 테스트 워크스페이스를 생성하여 모든 것이 올바르게 작동하는지 확인합니다.

워크스페이스 설정을 확인하려면:

1. 워크스페이스 생성의 단계에 따라 새 워크스페이스를 생성합니다.
2. 프로젝트에서 Code를 선택합니다.
3. 워크스페이스 이름을 선택합니다.
4. 웹 IDE를 열거나, 터미널에 액세스하거나, 프로젝트 파일을 변경하여 워크스페이스와 상호 작용합니다.

축하합니다! AWS에서 GitLab 워크스페이스 인프라를 성공적으로 설정했습니다. 이제 사용자가 프로젝트를 위한 개발 워크스페이스 환경을 만들 수 있습니다.

문제가 발생하면 로그에서 추가 세부 정보를 확인하고 지침에 대해 워크스페이스 문제 해결을 참조하세요.

관련 항목#

• 워크스페이스
• 워크스페이스 구성
• 워크스페이스 설정
• 튜토리얼: 임의의 사용자 ID를 지원하는 사용자 지정 워크스페이스 이미지 생성