TL;DR

  • Firezone Terraform Provider를 사용하면 Resource, Group, User, Policy 등 접근 설정을 Terraform 코드로 관리하고, 변경 계획 검토와 환경 간 동일한 구성 적용이 가능함.
  • 데모는 Docker 네트워크 2개, 비공개 NGINX 워크로드, Gateway 컨테이너 4개와 이에 대응하는 Firezone 리소스를 구성함.
  • Terraform에서 Sites, Resources, Policies, Gateways를 관리하고, CIDR·IP·DNS 리소스 및 다양한 조건 기반 정책을 선언할 수 있음.
  • Gateway 토큰은 민감한 상태 값으로 저장되며, 토큰 로테이션과 배포 대상 갱신을 코드로 연계할 수 있음.
  • 인증 공급자 설정, 기기 등록 및 실행 중인 Gateway 점검 등 일부 작업은 계속 Portal에서 수행함.

Terraform Provider 소개

  • Firezone은 홈랩부터 대규모 팀까지 유용하게 사용할 수 있는 제품을 지향함.
  • 홈랩이나 소규모 팀은 Firezone Portal에서 간단히 접근을 구성할 수 있지만, Resources, Groups, Users, Policies가 늘면 Portal UI에서 작업하는 데 시간이 들기 시작함.
  • Firezone 계정을 여러 관리자가 함께 운영하면 Resource 추가, Group 삭제, Policy 변경의 이유를 파악하기 어려워짐.
  • 공식 Firezone Terraform Provider를 통해 Firezone에 변경 사항을 적용하기 전에 계획을 확인하고, 풀 리퀘스트에서 변경 사항을 논의하며, 여러 환경에 동일한 구성을 적용할 수 있음.

구성 적용 데모

  • 데모는 두 사이트로 구성된 실험 환경을 생성하며, Docker 네트워크 2개, 비공개 NGINX 워크로드, Gateway 컨테이너 4개를 포함함.
  • 이에 대응하는 Firezone Sites, Resources, Groups, Actors, 멤버십, Policies도 함께 생성함.
  • 각 firezone_gateway가 발급하는 등록 토큰을 Docker 설정에서 해당 Gateway 컨테이너로 전달하며, 컨테이너는 자동으로 실행됨.
  • 코드에서 Gateway를 추가하거나 토큰을 교체하면 Terraform이 대응하는 컨테이너도 갱신함. Portal을 통해 비밀 값을 복사하거나 수동으로 배포를 조율할 필요가 없음.
  • 데모를 로컬에서 쉽게 실행할 수 있도록 Docker Provider를 사용함. 같은 패턴은 AWS, Azure, Google Cloud 또는 Terraform으로 관리하는 다른 인프라 플랫폼에서도 적용 가능함.

시작하기

  • Firezone Portal의 Settings에서 API 클라이언트 토큰을 생성하고, 이를 FIREZONE_TOKEN 환경 변수로 설정한 뒤 Terraform 구성에 Provider를 추가함.
  • Provider의 엔드포인트는 https://rest-api.firezone.dev이며, Terraform은 토큰을 환경 변수에서 읽음.
  • 전체 구성 방법은 Provider 참조 문서에서 확인 가능함.

관리 가능한 항목

Sites, Resources, Policies

  • Firezone의 핵심 접근 모델은 Terraform 리소스에 직접 대응함.
  • 예시 구성은 운영 데이터베이스의 Postgres 포트에 접근할 수 있도록 설정함. 대상은 기업용 Okta로 로그인하고, 업무 시간 중이며, 유효한 X.509 인증서가 있는 기기를 사용하는 Engineering 구성원임.
  • firezone_resource는 CIDR, IP, DNS 리소스를 지원함. 프로토콜과 포트 필터를 추가할 수 있으며, DNS 리소스에는 IP 계열(ip_stack)을 지정할 수 있음.
  • Policy 조건은 다음 항목과 일치시킬 수 있음.
  • 원격 IP를 기준으로 한 기기의 지역
  • CIDR 범위에 따른 기기의 원격 IP
  • 사용자가 로그인할 때 사용한 인증 공급자
  • IANA 시간대의 요일별 시간 범위
  • 관리자가 기기를 검증했는지 여부
  • 계정의 신뢰 앵커 중 하나가 발급한 유효한 X.509 인증서를 기기가 제시했는지 여부(device_attested)

Gateway와 토큰 로테이션

  • firezone_gateway는 Gateway를 생성하고 토큰을 민감한 속성으로 반환함.
  • 반환된 토큰은 Gateway 호스트를 배포하는 구성에 직접 전달할 수 있으며, 예를 들어 AWS, Azure, Google Cloud Gateway 모듈에 전달 가능함.
  • token_rotation_trigger 값이 바뀌면 토큰이 교체됨. 토큰을 로테이션할 때는 Gateway의 rotated 값을 갱신하면 되며, 값은 임의로 지정할 수 있지만 날짜를 쓰면 로테이션 이력을 읽기 쉬움.
  • 기존 토큰은 Gateway가 새 토큰으로 연결하거나 유예 기간이 끝날 때까지 계속 작동함. 따라서 해당 기간 안에 Gateway 호스트가 새 토큰을 사용하도록 갱신해야 함.
  • Terraform은 Gateway 생성 또는 토큰 로테이션 시 토큰을 상태 파일에 저장하므로 원격 상태 백엔드를 보호해야 함.
  • 일반 속성 참조로 민감한 토큰을 AWS Secrets Manager 등 비밀 저장소에 전달할 수 있음. Terraform 1.11 이상에서는 secret_string_wo 같은 쓰기 전용 인수를 사용해 비밀 저장소에 저장한 값이 상태 파일에 추가로 기록되지 않도록 할 수 있음.

Portal에 남는 항목

  • 인증 공급자와 디렉터리는 설정 과정에서 관리자가 대화형 OAuth 인증 흐름을 완료해야 할 수 있으므로 Portal에서 설정함. 설정이 끝난 뒤에는 Terraform에서 해당 통합을 데이터 소스로 참조해 Policy에 사용할 수 있음.
  • Devices는 Terraform에서 읽기 전용임. Device를 참조하고 가져온 정적 Device 풀의 구성원을 관리할 수 있지만, Device 등록은 자체적으로 이루어지며 관리는 Portal에서 수행함.
  • 서비스 계정은 별도의 자격 증명 단계를 거침. 관리자가 Terraform으로 서비스 계정을 생성한 뒤, Portal에서 헤드리스 Device가 로그인할 수 있도록 Device 토큰을 생성함.
  • 실행 중인 Gateway를 점검하는 곳도 Portal임. Portal에서 Gateway의 온라인 여부, IP 주소, 실행 버전을 확인할 수 있음.
  • 계정 설정, 로그, 외부 ID, X.509 인증 공급자, 기기 상태 통합은 Provider 범위 밖에 남음.
  • 전체 리소스 및 데이터 소스 목록은 Provider 참조 문서에서 확인 가능함.

사용해 보기

  • Provider를 현재 Terraform Registry에서 사용할 수 있음. 모든 리소스와 데이터 소스의 전체 참조 및 예시는 문서에 있으며, 소스 코드는 GitHub에서 확인 가능함.
  • 자동화하려는 작업이 지원 범위의 공백에 막히는 경우 이슈를 열어 필요한 작업을 설명할 수 있으며, 해당 피드백은 이후 개발 방향에 반영됨.