AWS 인프라 사용자 지정
n8n v2.47요약
terraform-aws-n8n 모듈은 배포의 모든 계층을 프로비저닝하거나, 이미 운영 중인 인프라를 가리키도록 구성할 수 있습니다. 모듈이 프로비저닝할 수 있는 모든 계층은 이미 운영 중인 인프라를 가리키도록 대체할 수 있습니다.
terraform-aws-n8n 모듈은 배포의 모든 계층을 프로비저닝하거나, 이미 운영 중인 인프라를 가리키도록 구성할 수 있습니다. 이 페이지에서는 기존 인프라를 가리키도록 모듈을 구성하는 방법, 인그레스 트래픽을 분리하는 방법, 커스텀 n8n 이미지를 사용하는 방법을 다룹니다.
고객 관리형 인프라#
모듈이 프로비저닝할 수 있는 모든 계층은 이미 운영 중인 인프라를 가리키도록 대체할 수 있습니다. 각 계층은 같은 패턴을 따릅니다. 모듈이 해당 계층을 프로비저닝하지 않도록 하는 create_<x> 부울 값(기본값 true)과, 이 값이 false일 때만 필요한 하나 이상의 참조 입력입니다.
| 계층 | 토글 | 참조 입력 |
|---|---|---|
| RDS PostgreSQL | create_database |
db_host, db_password(또는 db_password_secret_ref) |
| EKS 클러스터 및 노드 그룹 | create_eks |
existing_eks_cluster_name, existing_eks_cluster_prerequisites_confirmed |
| ElastiCache Redis | create_elasticache |
redis_host, redis_port, redis_auth_token(또는 redis_auth_token_secret_ref), redis_transit_encryption_enabled |
| S3 버킷 | create_s3_bucket |
existing_s3_bucket_name |
| RDS KMS 키 | create_db_kms_key |
db_kms_key_arn |
| S3 KMS 키 | create_s3_kms_key |
s3_kms_key_arn |
| 클러스터 컨트롤러(로드 밸런서 컨트롤러, Cluster Autoscaler, metrics-server, KEDA) | install_lbc / install_cluster_autoscaler / install_metrics_server / install_keda |
없음. 기존 클러스터에서 동등한 구성 요소가 이미 실행 중이라고 가정합니다 |
예를 들어 이미 관리하고 있는 Redis 인스턴스를 가리키도록 모듈을 구성하려면 다음과 같이 합니다.
module "n8n" {
# ...
create_elasticache = false
redis_host = aws_elasticache_replication_group.shared.primary_endpoint_address
redis_port = 6379
redis_auth_token = var.shared_redis_auth_token
}
토글과 참조 입력을 함께 맞춰 설정합니다
redis_host 같은 참조 입력만 설정하고 해당 create_<x> 부울 값을 false로 설정하지 않아도 오류가 발생하지 않습니다. 모듈은 자체 관리형 리소스를 그대로 프로비저닝하고 n8n이 그 리소스를 가리키도록 하며, 직접 지정한 인프라는 사용되지 않은 채 남습니다. 항상 두 값을 함께 설정합니다.
두 n8n 배포가 같은 Redis 호스트를 가리키는 경우, 각 배포에 고유한 redis_key_prefix를 설정합니다. 설정하지 않으면 두 배포가 같은 큐와 리더 선출 채널을 공유하게 되어, 한 인스턴스에서 워크플로를 활성화하면 다른 인스턴스에서 webhook not registered 오류가 발생할 수 있습니다.
고객 관리형 계층별로 실행 가능한 참조 구성은 모듈의 examples 폴더(customer-managed-redis, customer-managed-s3, customer-managed-cluster, customer-managed-everything)에 있습니다.
VPC 생성은 항상 범위 밖입니다
모듈은 항상 기존 VPC(vpc_id, private_subnets, public_subnets)를 필요로 합니다. VPC를 직접 생성하지 않습니다.
고객 관리형 인그레스#
기본적으로 모듈은 /webhook을 웹훅 프로세서로, /를 메인 Pod로 라우팅하는 인터넷 연결 Application Load Balancer 하나를 생성합니다. 직접 인그레스를 관리하려면 create_ingress = false로 설정합니다. 예를 들어 공개 웹훅 트래픽을 내부 전용 에디터 및 API와 분리할 때 사용합니다.
모듈이 출력으로 노출하는 Service로 트래픽을 라우팅합니다.
| 출력 | 대상 |
|---|---|
n8n_service_name |
에디터 UI, REST API |
n8n_webhook_service_name |
웹훅, 폼, 대기 재개, MCP |
n8n_webhook_path_prefixes |
웹훅 프로세서에 도달해야 하는 경로 접두사 |
n8n_service_port |
둘 다(5678) |
/webhook뿐 아니라 n8n_webhook_path_prefixes의 모든 접두사를 웹훅 프로세서로 라우팅합니다. 모듈은 메인 Pod에서 프로덕션 웹훅 처리를 비활성화하므로, /webhook-waiting(Wait 노드 재개), /form 및 /form-waiting(Form Trigger 노드), /mcp(MCP 서버 트리거)가 메인 Pod에 도달하면 모두 404를 반환합니다. 이 접두사는 모든 요청을 받는 / 규칙보다 먼저 선언합니다.
호출자가 관리하는 인그레스는 다음도 수행해야 합니다.
n8n_service_name에 세션 스티키니스 활성화: 각 브라우저가 하나의 메인 Pod에 머물도록 합니다. 활성화하지 않으면 한 브라우저의 에디터 요청과 WebSocket 연결이 여러 메인 Pod로 분산되어 에디터가 연결을 잃습니다.n8n_proxy_hops설정: 클라이언트와 n8n 사이에서X-Forwarded-For헤더를 추가하는 프록시의 수로 설정합니다. 모듈은 기본값을1로 설정하며, 모듈 또는 직접 운영하는 로드 밸런서가 유일한 프록시라면 올바른 값입니다. CloudFront처럼 경로에 HTTP 프록시가 추가될 때마다 1씩 더합니다.
인증서와 두 DNS 레코드를 포함한 분리형 인그레스의 실행 가능한 전체 예시는 examples/split-ingress에 있습니다.
커스텀 n8n 이미지#
Helm 릴리즈가 기본 n8n 이미지 대신 직접 빌드한 이미지를 가리키도록 n8n_image_repository를 설정합니다. 내부 베이스 이미지를 사용하거나 커뮤니티 노드를 이미지에 포함하는 경우가 일반적입니다.
module "n8n" {
# ...other inputs...
n8n_image_repository = "123456789012.dkr.ecr.eu-west-1.amazonaws.com/n8n"
n8n_image_tag = "2.27.4-mypackages"
# Pin to the n8n version the custom image is built from.
n8n_task_runner_image_tag = "2.27.4"
# Not needed when packages are already in the image.
n8n_reinstall_missing_packages = false
}
UI를 통해 설치한 커뮤니티 패키지는 커스텀 이미지에서 로드되지 않습니다
n8n은 이미지의 node_modules에 단순히 npm install한 패키지가 아니라, N8N_CUSTOM_EXTENSIONS로 지정한 디렉터리의 커뮤니티 노드만 로드합니다. 이미지가 패키지로 채우는 디렉터리를 n8n_custom_extensions_path로 설정하고, Dockerfile에서 해당 위치에 패키지를 설치합니다. 이 방식으로 로드된 노드는 CUSTOM.* 유형으로 이름이 바뀌므로, 같은 패키지를 UI로 설치해 만든 기존 워크플로는 노드 유형을 업데이트하지 않으면 확인되지 않습니다.
패키지가 바뀔 때마다 이미지를 다시 빌드하기 어렵다면, 이미지에 포함하는 대신 n8n_extra_volumes와 n8n_extra_volume_mounts로 같은 디렉터리를 ConfigMap, Secret 또는 PersistentVolumeClaim에서 마운트할 수 있습니다.
대규모 환경의 Pod DNS#
n8n_dns_config는 n8n Pod의 DNS 옵션을 설정합니다. Pod 수가 많으면 Kubernetes의 기본 DNS 검색 경로 동작(ndots:5)이 S3나 ElastiCache 같은 클러스터 내부 또는 AWS 서비스 호스트 이름을 조회할 때마다, 이름을 그대로 시도하기 전에 불필요한 검색 도메인 쿼리를 최대 네 번 거치게 합니다. 배포가 모든 의존성을 정규화된 도메인 이름(FQDN)으로 지정한다면 n8n_dns_config를 ndots:1로 설정합니다. 이 모듈은 기본적으로 FQDN을 사용합니다.
n8n_dns_config = {
options = [{ name = "ndots", value = "1" }]
}
이 설정은 대규모 환경에서 DNS 쿼리량을 크게 줄이고 CoreDNS 포화로 인한 요청 실패를 없애지만, 개별 요청 자체가 빨라지지는 않습니다.