Terraform으로 FortiGate 자동화 첫걸음 — REST API 관리자부터 provider까지

• FortiGate REST API 관리자 만드는 법, 인증서 등록 방법, Terraform provider 정의, 모듈 사용 시 흔한 실수
• 적용 환경: FortiGate 7.x / Terraform 1.x
• GitHub 저장소: https://github.com/20eung/terraform-fortios-howto

1. 왜 FortiGate를 코드로 관리해야 할까

수십 대의 FortiGate를 GUI로 일일이 클릭해서 설정한 적 있으신가요. 한 번은 괜찮지만 100대 firewall policy, 50개 SD-WAN 구성을 매번 손으로 한다면 변할 때마다 같은 실수를 반복하게 됩니다. Terraform으로 바꾸면 설정이 Git에서 diff로 보이고, 신규 장비 추가 시 같은 코드로 몇 분 만에 부트스트랩이 끝납니다.

2. 사전 준비: REST API 관리자 만들기

Terraform이 FortiGate와 통신하려면 전용 REST API 관리자가 있어야 합니다. 일반 admin 계정을 그대로 쓰면 실수로 잘못된 변경이 일어날 수 있습니다.

2.1 1단계: Admin Profile 생성

System > Admin Profile > +Create New로 이동합니다.

• Name: api_super_admin
• Access Permissions: 시스템/네트워크/방화벽/VPN 모두 Read/Write

CLI로 만들 때는 다음과 같습니다.

config system accprofile
    edit "api_super_admin"
        set sysgrp read-write
        set netgrp read-write
        set fwgrp read-write
        set vpngrp read-write
    next
end

2.2 2단계: REST API Admin 생성

System > Administrators > +Create New > REST API Admin에서:

• Username: terraform-api
• Administrator Profile: api_super_admin
• Trusted Hosts: Terraform을 실행할 서버 IP만 등록 (보안 필수)

CLI로는 다음과 같이 생성합니다.

config system api-user
    edit "terraform"
        set comments "terraform automation"
        set api-key <발급된 키>
        set accprofile "super_admin"
        set vdom "root"
        config trusthost
            edit 1
                set ipv4-trusthost 1.2.3.4 255.255.255.255
            next
        end
    next
end

3. 사전 준비: CA 인증서 등록

VPN이나 HTTPS GUI 접근에 사용할 인증서를 FortiGate에 등록합니다. 별도 저장소에서 만드는 과정을 정리해 두었습니다.

🔗 CA 인증서 생성 가이드

3.1 인증서 Import 절차

System > Certificates > Import로 이동합니다.

1. Type: Local Certificate 선택

1. CRT, KEY 파일 업로드
2. 인증서 생성 시 사용한 Password 입력

1. OK 클릭 → 등록 완료 화면

CLI로 등록할 때는 다음과 같습니다.

config vpn certificate local
    edit "terraform"
        set password pass-phrase-for-terraform-key-file
        set private-key "[REDACTED PRIVATE KEY]"
        set certificate "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
    next
end

config vpn certificate local
    edit "terraform"
        set range global
    next
end

4. 환경변수 설정

Terraform이 FortiGate에 접속하려면 3개 환경변수가 필요합니다. ~/.bashrc에 추가해 두면 모든 Terraform 실행 시 자동으로 적용됩니다.

export "FORTIOS_ACCESS_HOSTNAME"="10.10.10.10"
export "FORTIOS_ACCESS_TOKEN"="9kNtm6bx0~~~~~"
export "FORTIOS_INSECURE"="true"

5. Terraform provider 정의

5.1 단일 모듈 프로젝트

루트 디렉터리의 provider.tf에 정의합니다.

terraform {
    required_providers {
        fortios = {
            source = "fortinetdev/fortios"
        }
    }
}

provider "fortios" {}

6. 모듈에서 흔히 겪는 함정

6.1 트리 구조

실제 FortiGate를 Terraform으로 운영하는 프로젝트는 보통 다음과 같이 모듈로 분리합니다.

.
├── main.tf
├── modules
│   ├── bgp
│   │   ├── outputs.tf
│   │   ├── route.tf
│   │   ├── sdwan.tf
│   │   ├── system_interface.tf
│   │   ├── variables.tf
│   │   └── vpn.tf
│   └── static
│       ├── route.tf
│       ├── variables.tf
│       └── vpn.tf
├── provider.tf
├── variables.auto.tfvars
└── variables.tf

6.2 흔한 실수: 모듈 안에서 provider 미정의

가장 많이 겪는 함정입니다. 모듈 디렉터리(modules/bgp)에서 .tf 파일이 provider를 참조하면, 별도로 정의하지 않으면 Terraform은 기본적으로 hashicorp/fortios를 찾으려 합니다. 그러면 다음과 같은 에러가 납니다.

Error: Failed to query available provider packages
...
Could not retrieve the list of available versions for provider
"hashicorp/fortios": provider registry.hashicorp.com does not have
a provider named "hashicorp/fortios"

6.3 해결: 모듈에도 provider 블록 추가

modules/bgp/vpn.tf 등 모듈 안의 임의 파일에 동일한 provider 정의를 한 번 더 추가하면 됩니다.

terraform {
    required_providers {
        fortios = {
            source = "fortinetdev/fortios"
        }
    }
}

resource "fortios_vpnipsec_phase1interface" "azure-us-1" {
    # ...
}

이렇게 하면 모듈 단독으로도 terraform init이 정상 동작합니다.

7. 자주 발생하는 오류와 해결법

8. 마치며

FortiGate를 Terraform으로 다루기 위한 가장 기본적인 준비 단계를 정리했습니다.