클라우드플레어 API 사용법

요약

Cloudflare API를 사용하면 DNS, 존, Workers, 보안 및 분석을 프로그래밍 방식으로 관리할 수 있습니다. API 토큰(권장) 또는 전역 키로 인증하고, api.cloudflare.com/client/v4를 호출하며, 비율 제한을 적절히 처리해야 합니다. 테스트를 위해 Apidog를 사용하여 DNS 변경 유효성 검사, Worker 배포 테스트 및 여러 환경에 걸친 구성 자동화를 할 수 있습니다.

서론

Cloudflare는 수백만 개의 웹사이트 앞에 위치합니다. DNS, CDN, DDoS 방어, WAF, Workers 서버리스 함수 등을 처리합니다. 대시보드를 통해 이 모든 것을 관리하는 것은 소규모 설정에 적합하지만, 대규모에서는 자동화가 필요합니다.

Cloudflare API는 대시보드에서 할 수 있는 모든 기능을 제공합니다. 존 생성, DNS 레코드 업데이트, 페이지 규칙 구성, Workers 배포, SSL 설정 관리 및 분석 데이터 가져오기 등 모든 것을 프로그래밍 방식으로 처리할 수 있습니다.

개발자들은 Cloudflare API를 다음과 같은 용도로 사용합니다:

코드형 인프라(Terraform, Pulumi)
CI/CD 파이프라인 통합
다중 존 관리
자동화된 DNS 업데이트
Worker 배포

💡

Cloudflare 기반으로 구축하는 경우, Apidog는 API 호출을 테스트하고, 응답의 유효성을 검사하며, 통합을 문서화하는 데 도움이 됩니다. 존 구성을 재사용 가능한 요청으로 저장하고 팀과 공유할 수 있습니다.

버튼

Apidog로 Cloudflare API 테스트 - 무료

이 가이드를 마치면 다음을 할 수 있게 됩니다:

Cloudflare API 토큰으로 인증
존 및 DNS 레코드 관리
Workers 배포 및 관리
보안 설정 구성
분석 및 로그 가져오기

인증

Cloudflare는 두 가지 인증 방법을 제공합니다. 전역 키 대신 API 토큰을 사용하세요.

방법 1: API 토큰 (권장)

API 토큰은 특정 권한으로 범위가 지정됩니다. 토큰이 유출되더라도 피해는 제한적입니다.

토큰 생성:

Cloudflare 대시보드 → 내 프로필 → API 토큰으로 이동
토큰 생성
템플릿(존 DNS 편집, Workers 배포 등) 또는 사용자 지정 선택
특정 존 또는 모든 존 설정
토큰 복사

토큰 사용:

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

방법 2: 전역 API 키 (권장하지 않음)

전역 키는 전체 계정 접근 권한을 가집니다. 사용을 피하세요.

curl -X GET "https://api.cloudflare.com/client/v4/user" \
  -H "X-Auth-Email: your-email@example.com" \
  -H "X-Auth-Key: YOUR_GLOBAL_API_KEY"

응답 형식

모든 Cloudflare API 응답은 다음 구조를 따릅니다:

{
  "result": { ... },
  "success": true,
  "errors": [],
  "messages": []
}

result를 처리하기 전에 항상 success를 확인하세요.

존 관리

존은 Cloudflare에서 도메인을 나타냅니다.

존 목록 조회

curl -X GET "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

응답:

{
  "result": [
    {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com",
      "status": "active",
      "paused": false,
      "type": "full",
      "development_mode": 0,
      "name_servers": [
        "ns1.cloudflare.com",
        "ns2.cloudflare.com"
      ],
      "original_name_servers": [
        "ns1.example.com"
      ],
      "original_registrar": null
    }
  ],
  "success": true
}

존 생성

curl -X POST "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "newdomain.com",
    "account": {
      "id": "ACCOUNT_ID"
    },
    "type": "full"
  }'

존 세부 정보 가져오기

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

DNS 레코드 관리

DNS 레코드는 도메인 이름을 IP 주소 및 서비스에 매핑합니다.

DNS 레코드 목록 조회

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

DNS 레코드 생성

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "192.0.2.1",
    "ttl": 3600,
    "proxied": true
  }'

레코드 유형:

A - IPv4 주소
AAAA - IPv6 주소
CNAME - 다른 도메인의 별칭
MX - 메일 서버
TXT - 텍스트 레코드 (SPF, DKIM, 인증)
NS - 네임 서버

DNS 레코드 업데이트

curl -X PUT "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "192.0.2.2",
    "ttl": 3600,
    "proxied": true
  }'

DNS 레코드 삭제

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Cloudflare Workers

Workers는 사용자와 가까운 엣지에서 JavaScript를 실행합니다.

Workers 목록 조회

curl -X GET "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/workers/scripts" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Worker 업로드

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/workers/scripts/my-worker" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/javascript" \
  --data-binary @worker.js

Worker 예시:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    
    if (url.pathname === '/api/hello') {
      return new Response(JSON.stringify({ message: 'Hello from the edge!' }), {
        headers: { 'Content-Type': 'application/json' }
      })
    }
    
    return fetch(request)
  }
}

라우트 바인딩

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/workers/routes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "example.com/api/*",
    "script": "my-worker"
  }'

Worker KV 네임스페이스

Workers에서 접근 가능한 데이터 저장:

curl -X POST "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/storage/kv/namespaces" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "my-kv-namespace"
  }'

보안 및 WAF

페이지 규칙

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/pagerules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {
        "target": "url",
        "constraint": {
          "operator": "matches",
          "value": "example.com/*"
        }
      }
    ],
    "actions": [
      {
        "id": "ssl",
        "value": "flexible"
      },
      {
        "id": "cache_level",
        "value": "aggressive"
      }
    ]
  }'

방화벽 규칙

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/firewall/rules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "expression": "ip.geoip.country eq \"CN\"",
      "paused": false
    },
    "action": "block",
    "description": "Block traffic from China"
  }'

비율 제한

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/rate_limits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "disabled": false,
    "description": "Rate limit API endpoints",
    "match": {
      "request": {
        "methods": ["POST"],
        "url_pattern": "*/api/*"
      }
    },
    "threshold": 100,
    "period": 60,
    "action": {
      "mode": "ban",
      "timeout": 600
    }
  }'

분석 및 로그

존 분석

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/analytics/dashboard?since=-1440&continuous=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

응답:

{
  "result": {
    "totals": {
      "requests": {
        "all": 1000000,
        "cached": 800000,
        "uncached": 200000
      },
      "bandwidth": {
        "all": 50000000000,
        "cached": 40000000000
      },
      "threats": {
        "all": 5000
      },
      "pageviews": {
        "all": 250000
      }
    }
  }
}

존 로그 (Logpush)

Logpush를 활성화하여 로그를 저장소로 보낼 수 있습니다:

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/logpush/jobs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Logpush Job",
    "destination_conf": "s3://my-bucket/logs?region=us-east-1",
    "dataset": "http_requests",
    "logpull_options": "fields=ClientIP,ClientRequestPath,EdgeResponseStatus&timestamps=rfc3339"
  }'

Apidog로 테스트하기

Cloudflare 변경 사항은 운영 트래픽에 영향을 미칩니다. 철저히 테스트하세요.

Apidog가 다양한 Cloudflare 서비스와 함께 테스트 프로세스를 보여주는 다이어그램.

1. 환경 설정

CLOUDFLARE_API_TOKEN: your_token
CLOUDFLARE_ACCOUNT_ID: abc123
ZONE_ID: xyz789
BASE_URL: https://api.cloudflare.com/client/v4

2. 응답 유효성 검사

pm.test('Request was successful', () => {
  const response = pm.response.json()
  pm.expect(response.success).to.be.true
  pm.expect(response.errors).to.be.empty
})

pm.test('DNS record created correctly', () => {
  const response = pm.response.json()
  pm.expect(response.result.type).to.eql('A')
  pm.expect(response.result.name).to.eql('www')
  pm.expect(response.result.proxied).to.be.true
})

3. Worker 배포 테스트

Worker 스크립트를 Apidog에 파일로 저장하고 업로드를 테스트합니다:

pm.test('Worker uploaded', () => {
  const response = pm.response.json()
  pm.expect(response.result.id).to.eql('my-worker')
})

Apidog로 Cloudflare API 테스트 - 무료

일반적인 오류 및 해결 방법

403 Forbidden (접근 금지)

원인: 토큰에 필요한 권한이 없습니다.

해결책: Cloudflare 대시보드에서 토큰 권한을 확인하세요. DNS 편집에는 Zone:DNS:Edit 권한이 필요하고, Workers에는 Account:Workers:Edit 권한이 필요합니다.

1003: 잘못되었거나 누락된 존

원인: 존 ID가 존재하지 않거나 토큰이 접근할 수 없습니다.

해결책: URL에서 존 ID를 확인하고 토큰 범위에 해당 존이 포함되어 있는지 확인하세요.

81057: 레코드가 이미 존재함

원인: 동일한 이름과 유형의 DNS 레코드가 이미 존재합니다.

해결책: 생성을 위해 POST 대신 PUT을 사용하여 업데이트하거나, 먼저 삭제하세요.

비율 제한 초과

원인: 너무 많은 요청 (기본값 5분당 1200개).

해결책: 백오프 및 배치 작업을 구현하세요.

async function updateRecords(records) {
  for (const record of records) {
    try {
      await updateRecord(record)
      await sleep(100) // 비율 제한 버퍼
    } catch (error) {
      if (error.status === 429) {
        await sleep(60000) // 1분 대기
        await updateRecord(record) // 재시도
      }
    }
  }
}

대안 및 비교

기능	Cloudflare	AWS Route 53	Fastly
DNS API	✓	✓	✓
CDN API	✓	CloudFront API	✓
엣지 함수	Workers	Lambda@Edge	Compute@Edge
WAF API	✓	AWS WAF	✓
무료 계층	관대한	사용량 기반 요금	제한적
응답 형식	JSON	XML/JSON	JSON

Cloudflare API는 AWS의 분산된 서비스보다 더 통합적입니다. Workers는 Lambda@Edge보다 더 많은 유연성을 제공합니다.

실제 사용 사례

다중 테넌트 SaaS. 고객이 사용자 지정 도메인을 추가할 때 플랫폼이 Cloudflare 존을 자동으로 생성합니다. Workers가 라우팅을 처리하고, API를 통해 DNS 레코드가 생성되며, SSL 인증서가 자동으로 프로비저닝됩니다.

블루/그린 배포. 엔지니어링 팀은 DNS 레코드 업데이트를 사용하여 환경 간에 트래픽을 전환합니다. API는 배포 중 A 레코드를 업데이트하며, Cloudflare 네트워크를 통해 즉시 전파됩니다.

DDoS 방어 자동화. 보안 팀은 분석 API를 통해 트래픽을 모니터링합니다. 공격 패턴이 나타나면 API를 통해 방화벽 규칙이 추가되어 악성 IP를 차단하고, 응답 시간을 몇 시간에서 몇 초로 단축합니다.

마무리

다음은 여러분이 배운 내용입니다:

범위가 지정된 접근을 위한 API 토큰으로 인증
존 및 DNS 레코드를 프로그래밍 방식으로 관리
엣지 컴퓨팅을 위한 Workers 배포
방화벽 규칙 및 비율 제한으로 보안 구성
분석 데이터를 가져오고 로그 전송 구성
운영 환경에 적용하기 전에 Apidog로 테스트

버튼

자주 묻는 질문 (FAQ)

존과 도메인의 차이점은 무엇인가요?존은 Cloudflare에서 도메인을 나타내는 방식입니다. Cloudflare에 도메인을 추가할 때 존을 생성합니다. 해당 도메인에 대한 API 호출에는 존 ID가 사용됩니다.

존 ID는 어떻게 찾나요?Cloudflare 대시보드 → 도메인 선택 → 개요 → API 섹션으로 스크롤합니다. 존 ID가 표시됩니다.

유료 플랜 없이 Cloudflare API를 사용할 수 있나요?네. 대부분의 API 기능은 무료 플랜에서 작동합니다. Workers는 관대한 무료 계층을 가지고 있습니다. 일부 고급 기능(고급 WAF 규칙, Logpush)은 유료 플랜이 필요합니다.

DNS 변경은 얼마나 걸리나요?API를 통한 변경은 Cloudflare 시스템에서 즉시 적용됩니다. Cloudflare 네임서버로의 전파는 몇 초가 걸립니다. 전역 전파는 TTL과 재귀 리졸버에 따라 다르며, 일반적으로 몇 분이 걸립니다.

비율 제한은 어떻게 되나요?기본값: 토큰당 5분 동안 1200개의 요청. X-RateLimit-Remaining 헤더를 확인하세요. 엔터프라이즈 플랜은 더 높은 제한을 가집니다.

하나의 토큰으로 여러 계정을 관리할 수 있나요?아니요. 토큰은 하나의 계정으로 범위가 지정됩니다. 여러 계정을 관리하려면 별도의 토큰을 생성하거나 여러 계정에 접근할 수 있는 사용자 수준 토큰을 사용하세요.

Workers는 Lambda와 어떻게 다른가요?Workers는 특정 리전이 아닌 Cloudflare의 엣지 위치(300개 이상의 도시)에서 실행됩니다. 콜드 스타트(Cold start)가 최소화됩니다. 이는 요청/응답 조작에 이상적이며, 장기 실행 프로세스에는 적합하지 않습니다.

API를 사용하여 캐시를 제거할 수 있나요?네:

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["https://example.com/style.css"]
  }'