이 튜토리얼에서는 Terraform의 오픈 소스 포크인 OpenTofu를 사용해 코드형 인프라(Infrastructure as Code, IaC)로 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 프록시 도메인. 예를 들면 workspaces.example.dev 입니다.
   • GitLab Workspaces 프록시 와일드카드 도메인. 예를 들면 *.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. 토큰과 GitLab Relay(KAS) 주소를 이후 사용을 위해 저장합니다.
8. Continue를 선택합니다.

GitLab OAuth 구성#

다음으로, 워크스페이스에 안전하게 접근할 수 있도록 OAuth 인증을 설정합니다.

GitLab OAuth를 구성하려면 다음 절차를 수행합니다.

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

2. Edit profile을 선택합니다.

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

4. 아래로 스크롤해 OAuth applications로 이동합니다.

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

6. 다음 설정을 입력합니다.

   • Name: GitLab Workspaces Proxy
   • Redirect URI: 예를 들면 https://workspaces.example.dev/auth/callback 입니다. 직접 정한 도메인으로 바꿉니다.
   • Confidential 체크박스를 선택합니다.
   • Scopes: 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 Relay(KAS) 주소. GitLab Self-Managed 인스턴스에서는 필수입니다. 예를 들면 grpcs://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	Ingress 클래스 이름.
   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"  # Replace with your domain
   

   구성 옵션에 대한 자세한 내용은 워크스페이스 설정을 참고합니다.

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

파이프라인 실행#

이제 인프라를 배포할 차례입니다. CI/CD 파이프라인을 실행해 AWS에 필요한 리소스를 모두 생성합니다.

파이프라인을 실행하려면 다음 절차를 수행합니다.

1. GitLab 프로젝트에서 새 파이프라인을 만듭니다.
   1. 왼쪽 사이드바에서 Build > Pipelines를 선택합니다.
   2. New pipeline을 선택한 다음, 확인을 위해 New pipeline을 다시 선택합니다.
2. plan job 이 성공하는지 확인한 다음 apply job을 수동으로 트리거합니다.

OpenTofu 코드가 실행되면 AWS에 다음 리소스가 생성됩니다.

• Virtual Private Cloud(VPC).
• Elastic Kubernetes Service(EKS) 클러스터.
• Kubernetes용 GitLab 에이전트 Helm 릴리스.
• GitLab Workspaces Proxy 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. Web IDE를 열거나 터미널에 접근하거나 프로젝트 파일을 수정해 워크스페이스를 사용해 봅니다.

이로써 AWS에 GitLab 워크스페이스 인프라 구성을 마쳤습니다. 이제 사용자는 각자의 프로젝트에 개발 워크스페이스 환경을 만들 수 있습니다.

문제가 발생하면 로그에서 자세한 내용을 확인하고 워크스페이스 문제 해결을 참고합니다.

관련 주제#

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