Spatial IaC Terraform & Pulumi for GIS

Configuring CORS Headers for Mapbox GL JS via Infrastructure as Code

In spatial platform engineering, cross-origin resource sharing (CORS) misconfigurations remain a primary failure vector for Mapbox GL JS deployments. When tile servers, style endpoints, or vector data APIs reject browser-originated requests, the frontend experiences silent rendering failures, preflight OPTIONS rejections, and cascading state inconsistencies across the delivery pipeline. Managing these headers through Spatial Infrastructure as Code (IaC) requires deterministic provisioning, strict alignment with network boundaries, and automated drift detection. This guide details symptom triage, state reconciliation, and production-grade remediation workflows for Terraform and Pulumi deployments targeting modern GIS architectures.

Symptom Triage and Diagnostic Workflows

The primary indicator of a CORS misconfiguration in Mapbox GL JS is the browser console emitting Access-Control-Allow-Origin or Access-Control-Allow-Methods violations during tile or style JSON fetches. Network traces typically reveal 403 Forbidden or 400 Bad Request responses to preflight OPTIONS calls. Even successful GET requests may fail downstream if the Vary: Origin header is absent, causing aggressive CDN caching of unauthenticated responses that break subsequent cross-origin sessions. In IaC-managed environments, these symptoms frequently correlate with state drift where manual console edits override declarative configurations, or where CDN edge rules desynchronize from origin bucket policies.

Engineers must immediately verify whether the failure originates from the application layer, the network perimeter, or the storage configuration. Cross-referencing these symptoms with your Network Security & Access Control baselines isolates whether the rejection stems from origin whitelisting, method restrictions, or credential exposure requirements. Browser developer tools should be paired with curl -I -X OPTIONS or httpie to validate preflight responses independently of the frontend runtime, ensuring that diagnostic efforts target the correct infrastructure tier.

Architectural Integration and Security Boundaries

CORS headers do not operate in isolation. In a production GIS topology, tile servers and vector endpoints are typically routed through private subnets, requiring precise VPC Routing for Tile Servers alignment to ensure preflight traffic reaches the correct origin without traversing public NAT gateways unnecessarily. When Mapbox GL JS requests authenticated tiles, the CORS policy must explicitly permit Access-Control-Allow-Credentials: true alongside a specific origin, never a wildcard. This constraint directly intersects with IAM Role Mapping for GIS, where temporary credentials issued via STS assume roles that validate against the declared origin headers.

Perimeter defenses must be calibrated through Security Group Hardening to allow inbound OPTIONS and GET traffic on ports 443 and 80 while blocking unauthorized cross-origin probes. Every CORS adjustment should trigger Audit Logging Integration to capture origin mismatches, rejected preflights, and state drift events for compliance and forensic analysis. Aligning header policies with your CORS & CSP Configuration standards ensures that browser security contexts remain synchronized with backend delivery rules.

Production-Grade Terraform Configuration

The following Terraform configuration demonstrates a production-ready S3 bucket and CloudFront distribution setup optimized for Mapbox GL JS tile delivery. It enforces strict origin validation, limits allowed methods, and includes lifecycle rules to prevent manual drift.

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}

variable "allowed_origins" {
  type        = list(string)
  description = "Explicit list of frontend domains permitted to request tiles."
  validation {
    condition     = alltrue([for o in var.allowed_origins : can(regex("^https?://", o))])
    error_message = "Origins must be fully qualified URLs (http/https). Wildcards are prohibited for credential-based requests."
  }
}

resource "aws_s3_bucket" "tile_assets" {
  bucket = "prod-gis-tile-assets-${var.environment}"
  tags   = { ManagedBy = "Terraform", Service = "MapboxGLJS" }
}

resource "aws_s3_bucket_cors_configuration" "tile_cors" {
  bucket = aws_s3_bucket.tile_assets.id

  cors_rule {
    allowed_origins = var.allowed_origins
    allowed_methods = ["GET", "HEAD", "OPTIONS"]
    allowed_headers = ["Authorization", "Content-Type", "Accept"]
    expose_headers  = ["ETag", "Cache-Control"]
    max_age_seconds = 86400
  }

  lifecycle {
    ignore_changes = [cors_rule[0].allowed_origins] # Optional: prevents drift on dynamic staging URLs
  }
}

resource "aws_cloudfront_distribution" "tile_cdn" {
  enabled             = true
  is_ipv6_enabled     = true
  default_root_object = "index.html"

  origin {
    domain_name = aws_s3_bucket.tile_assets.bucket_regional_domain_name
    origin_id   = "s3-tile-origin"
    s3_origin_config { origin_access_identity = aws_cloudfront_origin_access_identity.tile_oai.cloudfront_access_identity_path }
  }

  default_cache_behavior {
    allowed_methods  = ["GET", "HEAD", "OPTIONS"]
    cached_methods   = ["GET", "HEAD"]
    target_origin_id = "s3-tile-origin"
    compress         = true

    forwarded_values {
      query_string = true
      headers      = ["Origin", "Access-Control-Request-Method", "Access-Control-Request-Headers"]
      cookies      { forward = "none" }
    }

    viewer_protocol_policy = "redirect-to-https"
    min_ttl                = 0
    default_ttl            = 3600
    max_ttl                = 86400
  }

  restrictions { geo_restriction { restriction_type = "none" } }
  viewer_certificate { cloudfront_default_certificate = true }
}

State Implications: Terraform tracks CORS rules as part of the S3 bucket resource state. Manual modifications via the AWS Console will be overwritten on the next terraform apply. To safely introduce dynamic origins, utilize the lifecycle.ignore_changes block or pass origins via a CI/CD pipeline variable that updates the state deterministically.

Pulumi Implementation and Type Safety

Pulumi provides native type safety and stack-aware configuration management, reducing the risk of malformed CORS arrays during deployment. The following TypeScript program mirrors the Terraform architecture while leveraging Pulumi’s stack references for multi-environment origin management.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const config = new pulumi.Config();
const allowedOrigins = config.requireObject<string[]>("allowedOrigins");
const env = config.require("environment");

const tileBucket = new aws.s3.Bucket(`tile-assets-${env}`, {
  bucket: `prod-gis-tile-assets-${env}`,
  tags: { ManagedBy: "Pulumi", Service: "MapboxGLJS" },
});

const corsRule = new aws.s3.BucketCorsConfigurationV2(`tile-cors-${env}`, {
  bucket: tileBucket.id,
  corsRules: [{
    allowedOrigins,
    allowedMethods: ["GET", "HEAD", "OPTIONS"],
    allowedHeaders: ["Authorization", "Content-Type", "Accept"],
    exposeHeaders: ["ETag", "Cache-Control"],
    maxAgeSeconds: 86400,
  }],
});

export const bucketName = tileBucket.bucket;
export const corsApplied = corsRule.id;

Operational Guardrails: Pulumi’s requireObject enforces schema validation at deployment time. If an invalid origin format is injected via pulumi config set, the stack will fail before reaching the cloud provider API, preventing partial CORS states that could break tile rendering.

State Reconciliation and Drift Mitigation

When Terraform or Pulumi state diverges from the live CORS configuration, the remediation workflow begins with state reconciliation. Execute terraform plan -refresh-only or pulumi refresh to sync the local state file with the actual cloud resource. If manual overrides are detected, evaluate whether the change was intentional (e.g., emergency hotfix) or accidental. Intentional changes must be codified back into the IaC repository before the next scheduled deployment.

Automated drift detection should be integrated into CI/CD pipelines using scheduled plan jobs that run against production state. Any deviation triggers a Slack/PagerDuty alert and blocks subsequent deployments until the state is reconciled. For high-availability GIS platforms, implement a read-only audit role that periodically queries the live CORS configuration via AWS CLI or Pulumi automation API, logging discrepancies to a centralized SIEM.

Security Guardrails and Compliance Validation

CORS policies must be treated as security controls, not convenience toggles. Wildcard origins (*) should never be deployed alongside Access-Control-Allow-Credentials: true, as this combination is explicitly rejected by modern browsers and violates Cross-Origin Resource Sharing (CORS) - MDN Web Docs specifications. When serving authenticated vector tiles, validate that the origin list matches your DNS registrar and CDN allowlists exactly.

Implement automated compliance checks using tools like checkov or tfsec to scan IaC templates before merge. Rules should enforce:

  • Maximum max_age_seconds ≤ 86400 to prevent stale preflight caching
  • Explicit allowed_headers lists (no *)
  • Origin validation against RFC 3986 URI schemes
  • Mandatory Vary: Origin propagation at the CDN layer

For comprehensive guidance on aligning browser security headers with spatial data delivery, consult the CORS & CSP Configuration reference architecture. When integrating with AWS storage services, ensure your bucket policies align with the official Configuring Cross-Origin Resource Sharing (CORS) - AWS Documentation to prevent implicit permission denials.

By treating CORS as a first-class IaC resource, spatial platform teams eliminate silent rendering failures, enforce strict origin boundaries, and maintain deterministic state across multi-region GIS deployments.