TFE FDO ACTIVE ACTIVE GUIDE (폐쇄망)

0. Infra 구성도

[TFE]

Direction	PORT	CIDR	Purpose
Inbound	22	Client	SSH 접속
Inbound	443	NLB 보안그룹	Web 접속
Inbound	443	Github 서버	VCS 연동
Inbound	8201	TFE 서버	Vault 연동
Outbound	443	sts, ec2 등 필요한 엔드포인트 보안그룹	AWS API 송출
Outbound	5432	TFE 서버	PostgreSQL 접근
Outbound	6379	TFE 서버	Elasticache 접근
Outbound	443	S3 앤드포인트 Prefix list	S3 접근
Outbound	443	Github 서버	VCS 연동
Outbound	8201	TFE 서버	Vault 연동

[NLB]

Direction	PORT	CIDR	Purpose
Inbound	443	Client	Web 접속
Inbound	443	Github 서버	VCS 연동
Outbound	443	TFE 서버	Web 접속 / VCS 연동

[RDS]

Direction	PORT	CIDR	Purpose
Inbound	5432	TFE 서버	TFE 연동

[Elasticache]

Direction	PORT	CIDR	Purpose
Inbound	6379	TFE 서버	TFE 연동

[Interface 엔드포인트]

Direction	PORT	CIDR	Purpose
Inbound	443	TFE 보안그룹	AWS API 수신
Outbound	443	0.0.0.0/0	AWS API 송출

1. NLB 설정

1. 체계

   • Private

2. 리스너

   • TLS:443

3. Target Group

   • TLS:443

   ACM을 적용한 TLS NLB라면 TLS 프로토콜로 해야한다. (TCP는 HTTP통신)

2. Route 53 설정

1. Private Hosting zone 생성

2. 레코드 생성

   • TFE
     • TFE Hostname : NLB DNS
     • CNAME
   • Github Enterprise
     • GIthub Hostname : Github 인스턴스 IP
     • A

   

3. 엔드포인트 생성

TFE가 AWS자원을 생성하기 위해 AWS로 신호를 보내기 위한 경로가 필요하다.

NAT가 연결되어 있다면 엔드포인트는 없어도 무관하나, NAT가 없다면 생성할 AWS 자원에 따라 엔드포인트를 각각 연결해주어야 한다.

VPC생성은 EC2 엔드포인트로 연결됨 

4. RDS 설정

1. 생성 시 주의사항
   • Multi AZ를 위해 '다중 AZ DB 인스턴스' 로 배포

2. 생성 후 주요 확인점

5. Elasticache (redis) 설정

1. 생성 후 주요 확인점

6. TFE Bundle 준비

1. go 설치 https://go.dev/dl/

2. terraform bundle 설치

git clone --single-branch --branch=v0.15 --depth=1 https://github.com/hashicorp/terraform.git
cd terraform
go build -o ../terraform-bundle ./tools/terraform-bundle

3. bundle.hcl 작성

terraform {
  # Version of Terraform to include in the bundle. An exact version number is required.
  version = "1.7.1"
}

providers {
  tfe = {
    versions = ["= 0.52.0"]
  }
  github = {
    source = "integrations/github"
    versions = ["= 6.0.1"]
  }
}

• 형식은 위와 같이 작성
• Source나 Version정보는 Terraform Registry를 바탕으로 작성
• Official Provider 가 아니면 Source 명시 필요

4. bundle 파일 생성 및 sha256 값 확인

terraform-bundle package -os=<linux> -arch=<amd64> bundle.hcl

# redhat linux
sha256sum <terraform_bundle.zip>

# mac 
shasum -a 256 <terraform_bundle.zip>

7. Github 설치 및 설정

0. Hardware Requirement

사용자 라이선스	x86-64 vCPUs	메모리	루트 스토리지	연결된(데이터) 스토리지
평가판, 데모 또는 10명의 라이트 사용자	4	32GB	200GB	150GB
10~3,000	8	48GB	200GB	300GB
3,000~5000	12	64GB	200GB	500GB
5,000~8,000	16	96GB	200GB	750GB
8,000~10,000+	20	160GB	200GB	1000GB

• 평가판 : r5.xlarge

• 루트볼륨이 아니라 추가 150GB 볼륨이 필요하다.

1. 준비 사항

   • CA Certficiate

   • cert.pem (crt 파일)

   • key.key (key 파일)

   • github enterprise 라이센스

2. github 주소로 접속확인

3. CLI로 접속하여 CA Certificate 설정

scp -P 122 <CA Certificate> admin@<github instance address>

ssh -p 122 admin@<github instance address>

ghe-ssl-ca-certificate-install -c </CA/Certificate/Full/Path>

참고

/usr/local/share/ca-certificates 에 ca 인증서 위치

4. github enterprise admin setting

   4-1. hostname 인증서 확인

​

​ 4-2. cert.pem , key.key 적용 및 Enable Sign-up

참고

1. ghe-ssl-ca-certificate-install -c /home/admin/rootca.crt 명령어 적용 후에도 CA 인증서가 Github Enterprise의 기본 CA가 박혀있는 것으로 보여진다. 의문....
2. Enable Sign-up ( 회원가입 기능 )

​ 4-3. 인증서 적용 확인 : Enterprise Settings - Site admins - Management console

• SSL 인증서 적용 확인

• CA 적용 확인

8. TFE FDO 설치

8-0. 필요 사항

• docker rpm
• crt : cert.pem
• key : key.pem
• CA : rootca.crt
• TFE FDO 도커 이미지
• TFE FDO 라이센스
• active-active .yaml 파일
• custom tfc-agent 이미지

8-1. TFE 서버 설정

​ 1. CA 인증서 OS에 신뢰 등록

# redhat
sudo cp <CA인증서> /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

# ubuntu
sudo cp <CA인증서> /usr/share/ca-certificates
sudo dpkg-reconfigure ca-certificates

​ 2. (redhat 경우) SELinux 해제 설정 및 확인

sudo setenforce 0 

# 확인
sudo getenforce 
Permissive 

​ 3. docker 설치 및 실행

sudo yum install -y <docker rpm> 

sudo systemctl start docker 

• dependency 관련 모든 docker 패키지를 받는 명령어

  yumdownloader --downloadonly --resolve <패키지 명>

• docker sudo 권한 없이 실행 (재로그인 필요)
  v202402-1 이상 버전에서는 권한에 대한 설정시 read-only file system 에러가 발생하므로 권한설정 하지 말것

  chmod 666 /var/run/docker.sock
  sudo groupadd docker

  sudo usermod -aG docker ${USER}

​ 4. docker image load

docker load -i <이미지.tar>

이미지 tar파일로 저장 방법

1. docker image 다운로드

cat <PATH_TO_HASHICORP_LICENSE_FILE> |  docker login --username terraform images.releases.hashicorp.com --password-stdin

docker pull images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>

2. docker 이미지 tar 파일로 저장

docker save -o <이미지명>.tar <이미지명:태그>

# 예시
docker save -o tfe_v1.tar images.releases.hashicorp.com/hashicorp/terraform-enterprise:v202311-1

​ 5. active-active용 .yaml 파일 설정

---
name: terraform-enterprise
services:
  tfe:
    image: images.releases.hashicorp.com/hashicorp/terraform-enterprise:<v######-#>
    environment:
      TFE_LICENSE_PATH: "/etc/ssl/private/terraform-enterprise/FDO_231205.hclic"
      TFE_HOSTNAME: "<NLB Address>"
      TFE_ENCRYPTION_PASSWORD: "hashicorp"
      TFE_OPERATIONAL_MODE: "active-active"
      TFE_DISK_CACHE_VOLUME_NAME: "${COMPOSE_PROJECT_NAME}_terraform-enterprise-cache"
      TFE_TLS_CERT_FILE: "/etc/ssl/private/terraform-enterprise/cert.pem" # volumes - bind 참조 
      TFE_TLS_KEY_FILE: "/etc/ssl/private/terraform-enterprise/key.pem"  # volumes - bind 참조
      TFE_TLS_CA_BUNDLE_FILE: "/etc/ssl/private/terraform-enterprise/rootca.crt" # volumes - bind 참조
      TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS: "<TFE LB Address>:<TFE 1 ip>,<TFE LB Address>:<TFE 2 ip>,<Github Address>:<Github IP>"
      TFE_RUN_PIPELINE_IMAGE: <Custom TFC-Agent Image:tag>
      # TFE_IACT_SUBNETS: "<IACT subnet, eg. 10.0.0.0/8,192.168.0.0/24>"


      # Database settings. See the configuration reference for more settings.
      TFE_DATABASE_USER: "<RDS USERNAME>"
      TFE_DATABASE_PASSWORD: "<RDS PASSWORD>"
      TFE_DATABASE_HOST: "<RDS Postgresql ENDPOINT>:5432"
      TFE_DATABASE_NAME: "<RDS DATABASE NAME>"
      TFE_DATABASE_PARAMETERS: "sslmode=require"

      # Object storage settings. See the configuration reference for more settings.
      TFE_OBJECT_STORAGE_TYPE: "s3"
      TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID: "<AWS ACCESS key>"
      TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY: "<AWS SECRET ACCESS KEY>"
      TFE_OBJECT_STORAGE_S3_REGION: "<S3 Region>"
      TFE_OBJECT_STORAGE_S3_BUCKET: "<BUCKET NAME>"

      # Redis settings. See the configuration reference for more settings.
      TFE_REDIS_HOST: "<Elasticache REDIS ENDPOINT>:6379"
      #TFE_REDIS_USER: "<Redis username>"
      #TFE_REDIS_PASSWORD: ""
      #TFE_REDIS_USE_TLS: "false"
      #TFE_REDIS_USE_AUTH: "false"

      # Vault cluster settings.
      # If you are using the default internal vault, this should be the private routable IP address of the node itself.
      TFE_VAULT_CLUSTER_ADDRESS: "http://<자신의 Private IP>:8201" 
    cap_add:
      - IPC_LOCK
    read_only: true
    tmpfs:
      - /tmp:mode=01777
      - /run
      - /var/log/terraform-enterprise
    ports:
      - "80:80"
      - "443:443"
      - "8201:8201"
    user: root 
    volumes:
      - type: bind
        source: /var/run/docker.sock
        target: /run/docker.sock
      - type: bind
        source: <CA, Crt, Key, FDO 라이센스 파일이 모두 있는 디렉토리> 
        target: /etc/ssl/private/terraform-enterprise
      - type: volume
        source: terraform-enterprise-cache
        target: /var/cache/tfe-task-worker/terraform
    extra_hosts:
      - "<GIT ADDRESS>:<GIT IP>"
volumes:
  terraform-enterprise-cache:

• tfe

  • image : 위에서 tar로 말았던 이미지

  • environment : 하위 volumes의 내용과 연결되어 설정됨

    • TFE_LICENSE_PATH : 컨테이너 내 TFE FDO 라이센스 경로

    • TFE_HOSTNAME : TFE NLB 주소

    • TFE_OPERATIONAL_MODE : active-active

    • TFE_TLS_CERT_FILE : 컨테이너 내 crt 파일 경로

    • TFE_TLS_KEY_FILE : 컨테이너 내 key 파일 경로

    • TFE_TLS_CA_BUNDLE_FILE : 컨테이너 내 CA 인증서 경로

    • TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS

      ​ tfc-agent 컨테이너의 /etc/hosts 에 추가되는 내용.

      ​ TFE 서버 (NLB 서버 X), Github 주소를 제대로 바라볼 수 있도록 설정 필요

    • TFE_DATABASE_USER : DB 유저명

    • TFE_DATABASE_PASSWORD : DB 패스워드

    • TFE_DATABASE_HOST : RDS 엔드포인트 주소

    • TFE_DATABASE_NAME : RDS DB 이름

    • TFE_DATABASE_PARAMETERS : active-active시 sslmode=require

    • TFE_OBJECT_STORAGE_TYPE : s3 (minio 가능)

    • TFE_OBJECT_STORAGE_S3_ACCESS_KEY_ID

    • TFE_OBJECT_STORAGE_S3_SECRET_ACCESS_KEY

    • TFE_OBJECT_STORAGE_S3_REGION

    • TFE_OBJECT_STORAGE_S3_BUCKET : bucket 이름

    • TFE_REDIS_HOST : Elasticache Redis 기본 엔드포인트

    • TFE_REDIS_USER : 필요시에만 설정

    • TFE_REDIS_PASSWORD : TFE_REDIS_USE_AUTH가 true일 때 패스워드

    • TFE_REDIS_USE_TLS : 인증서 적용된 Redis 사용시 true ( default : false )

    • TFE_REDIS_USE_AUTH : Elasticache에 암호화 설정시 true ( default : false )

    • TFE_VAULT_CLUSTER_ADDRESS : Vault 주소. External Vault 사용 시 명시 필요.

• volumes

  • type : bind
  • source: 이곳에 설정되는 호스트 서버의 경로 폴더가 컨테이너의 target 경로로 이동된다
  • target: /etc/ssl/private/terraform-enterprise

  즉 source에 설정되는 디렉토리에 CA, crt, key, fdo 라이센스가 모두 들어있어야 함.

6. TFC-Custom Image 준비

• 같은 디렉토리에 CA 인증서, Dockerfile 준비

# Dockerfile

FROM hashicorp/tfc-agent:latest

# Switch the to root user in order to perform privileged actions such as
# installing software.
USER root

# Install sudo. The container runs as a non-root user, but people may rely on
RUN apt-get -y install sudo
# Permit tfc-agent to use sudo apt-get commands.
RUN echo 'tfc-agent ALL=NOPASSWD: /usr/bin/apt-get , /usr/bin/apt' >> /etc/sudoers.d/50-tfc-agent

# the ability to apt-get install things.
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends unzip curl ca-certificates ansible jq python3-pip && wget -qO awscliv2.zip https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip && unzip awscliv2.zip && ./aws/install && rm -rf ./aws && rm -rf /var/lib/apt/lists/*

# Add CA certificates and ca-trust.
ADD <CA 인증서> /usr/local/share/ca-certificates
RUN update-ca-certificates

# Switch back to the tfc-agent user as needed by Terraform agents.
USER tfc-agent

​ 6-1. 이미지 빌드

docker build --no-cache -t custom/tfc-agent:v1 .

​ 6-2. tar로 save

docker save -o custom-tfc.tar custom/tfc-agent:v1

​ 6-3. [TFE 서버] 이미지 로드

docker load -i custom-tfc.tar 

​ 7. [TFE-1] docker compose up

docker compose -f <yaml file> up

​ 8. health check 확인

docker exec <tfe container> tfe-health-check-status

​ 9. [TFE-2] 노드에 1-6, 1-7 반복

​ 10. Admin Token (IACT TOKEN) 조회

docker exec <tfe container> tfectl admin token

​ 11. admin 계정 생성 페이지 접속

https://${TFE_HOSTNAME}/admin/account/new?token=${IACT_TOKEN}

주의!!

TFE 서버의 보안그룹 Inbound가 NLB의 보안그룹으로 오픈되어 있어야 웹에서 접속할 수 있다.

​

8-2. VCS 연동

---

1) VCS 연동 - Github Enterprise

• HTTPS URL :https://< github enterprise url >
• API URL : https://< github enterprise url >/api/v3

2) Github - User Settings - Developer Settings - OAuth apps

3) 연동 완료

8-3. Bundle 사용 설정

1) Github Release 에 Bundle Upload

2) TFE - Admin - Terraform Versions 설정

3) Workspace - Settings

9. TFE-Github Enterprise 연동 테스트

10. Troubleshooting

10-1. TFE 설치 및 설정

1. TFE 컨테이너 로그

   tls: internel handshake error

• NLB의 타겟그룹이 TLS 프로토콜이어야 함 (TCP X)

• 인증서 확인

2. Plan Fetching , Plan Queue 에서 무한 로딩

• .yaml 에서 아래 항목 제대로 설정되어 있는지 확인

  • TFE_RUN_PIPELINE_DOCKER_EXTRA_HOSTS
  • TFE_RUN_PIPELINE_IMAGE

• 필요한 custom tfc-agent 가 안뜨고 있을 확률이 높다. .yaml 파일 및 custom tfc-agent 이미지 확인 필요

10-2. TFE - AWS Network

1. Endpoint가 있음에도 불구하고 Terraform plan 에서 계속 Retry 인 경우
   • Interface Endpoint의 Private DNS 이름 활성화 필요