Spatial IaC Terraform & Pulumi for GIS

GeoServer Deployment Patterns for Spatial Infrastructure as Code

GeoServer remains the default engine for publishing OGC-compliant map services, yet its origins as a stateful, console-administered Java application make it one of the hardest spatial components to deliver through automated pipelines. The operational problem is concrete: a server whose catalog, styles, and datastore connections live in a hand-edited data_dir cannot be rebuilt deterministically, drifts silently between environments, and turns every scaling event into a configuration gamble. Treating GeoServer as a stateless application tier — immutable images, externalized configuration, and persistence pushed entirely to managed backends — resolves this, and it situates the engine cleanly inside the broader Geospatial Resource Provisioning discipline. The patterns below assume the transactional backend defined in PostGIS Cluster Provisioning and the tile and style archive defined in Object Storage for Raster/Vector Workloads already exist as their own version-controlled stacks, so this guide concerns itself only with the publishing tier and how it binds to them.

Environment Parity and Configuration Drift Mitigation

The single largest source of GeoServer incidents is divergence between the running catalog and the catalog described in version control. Because GeoServer historically stores its entire configuration — workspaces, layers, layer groups, styles, datastore parameters, and global settings — as XML inside a writable data_dir, any change made through the web admin console is invisible to the pipeline and lost on the next image roll. Parity therefore begins with declaring the data_dir read-only and reconstructing it from code on every boot.

Three classes of drift have to be locked down explicitly. The first is binary parity: the GeoServer minor version, the bundled GeoTools build, and the set of installed extensions (the wps, csw, vectortiles, mbstyle, or pyramid plugins) must be pinned to exact versions in the image build, not assembled at runtime. A node that boots with a mismatched vectortiles extension will silently serve malformed pbf tiles while passing its health check. The second is JVM and GeoWebCache parity: heap sizing, the -XX garbage-collector flags, and the GeoWebCache blobstore configuration must be identical across stages, because a smaller heap in staging hides the out-of-memory behaviour that production will exhibit under the same tile-seeding load. The third is catalog parity: workspace names, store connection parameters, native and declared SRS, and coverage band ordering must be generated from the same parameterized source so that a layer published in staging resolves to the identical EPSG code and axis order in production.

The promotion cycle is where these guarantees pay off. By baking the engine and its extensions into one immutable image tag and injecting only environment-specific values — database host, bucket name, CORS origins — at deploy time, a release promoted from staging to production swaps a variable file rather than rewriting logic. This mirrors the parameter-group and extension-matrix locking practiced for the database in PostGIS Cluster Provisioning, and the same rule applies: configuration is immutable infrastructure, and the only supported way to change it is a new commit that produces a new artifact.

CI/CD Validation and Operational Guardrails

GeoServer changes must pass through the same gated pull-request workflow as application code, with validation stages tuned to the failure modes spatial publishing actually exhibits. Conventional IaC linting catches malformed HCL or TypeScript; it does not catch a style that references a missing attribute or a datastore that points at a decommissioned read replica. The pipeline needs spatial-aware gates layered on top of the generic ones.

A production-grade pipeline runs, in order: static analysis and policy-as-code evaluation of the infrastructure definitions; an ephemeral preview deployment of the candidate image; a catalog smoke test that issues a GetCapabilities request and asserts that every expected workspace and layer is advertised; a rendering probe that requests a known GetMap tile and compares it against a reference image to catch SLD regressions; and a connection-pool check that confirms the engine can reach the PostGIS Cluster Provisioning backend through the correct private endpoint before any traffic is shifted. Only when all gates pass does an automated promotion shift the load balancer to the new replicas, with a rollback trigger wired to a sustained increase in 5xx responses or readiness-probe failures.

Gated CI/CD Validation Pipeline for the GeoServer Publishing Tier The pipeline runs in order: (1) static analysis and policy-as-code asserting no public IP, pinned image digests and secret references; (2) an ephemeral preview deploy of the candidate image on an isolated stack; (3) a GetCapabilities catalog smoke test confirming every workspace and layer is advertised; (4) a GetMap render-diff probe comparing a tile to a reference image to catch SLD regressions; (5) a connection-pool check confirming the engine reaches PostGIS over the private endpoint; and (6) a gated promotion that shifts the load balancer to the new replicas. A 5xx-surge or readiness-probe-failure monitor downstream of promotion fires a rollback that loops back to the render-diff stage. 1 · Static analysis & policy no public IP · pinned digest · secret refs 2 · Ephemeral preview deploy candidate image on isolated stack 3 · GetCapabilities smoke test every workspace & layer advertised 4 · GetMap render-diff probe ref-image diff catches SLD drift 5 · Connection-pool check reach PostGIS via private endpoint 6 · Gated promotion shift load balancer to new replicas 5xx surge · readiness failure rollback

Policy-as-code gates encode the non-negotiables: no datastore may use a public IP, every image tag must be a pinned digest rather than latest, admin credentials must resolve from a secret reference rather than a literal, and any change to a shared workspace requires an explicit reviewer. These gates draw their identity boundaries from the IAM Role Mapping for GIS patterns and their network boundaries from Security Group Hardening, so the publishing tier inherits the same least-privilege posture as every other resource on the platform.

Resource Architecture and Service Integration

GeoServer sits in the middle of the spatial data path, and its deployment shape is dictated by what it binds to on either side. Upstream, it depends on persistent state it must never own; downstream, it fronts a cache and a delivery edge that absorb the bulk of read traffic.

On the persistence side, transactional vector workloads connect directly to a highly available relational backend. Provisioning that connectivity as part of the PostGIS Cluster Provisioning stack — rather than letting GeoServer hold a brittle pool of long-lived connections — isolates spatial indexing, connection pooling, and read-replica routing from the application lifecycle. The publishing tier should consume a connection-pool endpoint (PgBouncer or RDS Proxy) so that a rolling restart of GeoServer replicas does not exhaust the database’s backend connection slots. Raster coverages, vector tile pyramids, and SLD/SLD-SE style documents are externalized to managed object storage; routing those assets through Object Storage for Raster/Vector Workloads lets the GeoWebCache blobstore live on a shared, lifecycle-managed bucket and lets a CDN serve seeded tiles without touching the application tier at all.

On the compute side, the engine is packaged into immutable container images and deployed across an orchestrated fleet, which unlocks horizontal scaling, zero-downtime rolling updates, and fast fault recovery. Where rendering or WPS workloads are bursty, the fleet integrates with the autoscaling behaviour described in Compute Node Orchestration, so heavy GetMap or process-execution spikes scale the publishing tier independently of the database. Network reachability between the load balancer, the replicas, and the database is governed by the routing rules in VPC Routing for Tile Servers, keeping all datastore traffic on private paths. Liveness and readiness probes follow the Kubernetes health check specifications so the load balancer routes only to fully initialized instances, and the readiness probe targets an OWS endpoint rather than the web UI so a node is marked ready only once it can actually answer service requests.

Runnable Configuration

The following Pulumi TypeScript program deploys GeoServer as a stateless tier: a pinned image, a read-only configuration volume sourced from a ConfigMap, secret-injected database credentials, resource bounds tuned for rendering, and probes pointed at the OWS endpoint. Every choice annotated below is geospatial-specific. The decision between expressing this in TypeScript versus HCL is examined in Terraform vs Pulumi for Spatial Infrastructure as Code; the programmatic form is used here because the replica count and resource bounds are commonly computed from per-environment configuration.

import * as k8s from "@pulumi/kubernetes"; // pin: @pulumi/kubernetes ~4.18
import * as pulumi from "@pulumi/pulumi";  // pin: @pulumi/pulumi ~3.130

const config = new pulumi.Config("geoserver");
const replicaCount = config.getNumber("replicas") || 3;

const gsDeployment = new k8s.apps.v1.Deployment("geoserver", {
  spec: {
    replicas: replicaCount,
    selector: { matchLabels: { app: "geoserver" } },
    template: {
      metadata: { labels: { app: "geoserver" } },
      spec: {
        containers: [{
          name: "geoserver",
          // Pin to a digest, never :latest — a floating tag breaks binary parity.
          image: "docker.io/geoserver/geoserver:2.27.0",
          env: [
            // data_dir is reconstructed from the ConfigMap, never written to at runtime.
            { name: "GEOSERVER_DATA_DIR", value: "/opt/geoserver/data_dir" },
            // DB host/credentials injected from a secret — never baked into the image.
            { name: "POSTGRES_HOST", valueFrom: { secretKeyRef: { name: "db-creds", key: "host" } } },
            { name: "POSTGRES_PASSWORD", valueFrom: { secretKeyRef: { name: "db-creds", key: "password" } } },
            // Heap is pinned for GeoWebCache seeding parity across environments.
            { name: "JAVA_OPTS", value: "-Xms2g -Xmx3g -XX:+UseG1GC" },
          ],
          volumeMounts: [{
            name: "config-vol",
            mountPath: "/opt/geoserver/data_dir",
            readOnly: true, // immutable catalog: console edits are physically impossible
          }],
          resources: {
            // GEOS/GDAL rendering is CPU- and memory-hungry; size for throughput, not vCPU alone.
            requests: { cpu: "500m", memory: "1Gi" },
            limits: { cpu: "2", memory: "4Gi" },
          },
          // Readiness targets OWS, not /web — a node is "ready" only once it answers service requests.
          livenessProbe: { httpGet: { path: "/geoserver/web/", port: 8080 }, initialDelaySeconds: 45, periodSeconds: 10 },
          readinessProbe: { httpGet: { path: "/geoserver/ows?service=wms&request=GetCapabilities", port: 8080 }, initialDelaySeconds: 20, periodSeconds: 5 },
          lifecycle: {
            // Drain in-flight GetMap requests before the pod is removed from the LB.
            preStop: { exec: { command: ["/bin/sh", "-c", "sleep 30"] } },
          },
        }],
        volumes: [{
          name: "config-vol",
          configMap: { name: "geoserver-workspace-config" },
        }],
        terminationGracePeriodSeconds: 60, // must exceed the preStop drain window
      },
    },
  },
});

The deployment pattern keeps the GeoServer tier stateless, pushing all persistence to decoupled backends so replicas can scale or fail without data loss:

Stateless GeoServer Tier with Externalized Persistence A load balancer distributes requests across two interchangeable GeoServer replicas. Both replicas mount the same read-only ConfigMap as their data_dir, serve tiles and styles from managed object storage backing the GeoWebCache blobstore, and read transactional vector features from PostGIS through a connection pooler. Liveness and readiness probes target each replica's OWS endpoint independently. All durable state lives in the three external backends, so a replica can be replaced, scaled, or lost without data loss. Load balancer routes only to ready nodes GeoServer replica stateless · immutable image GeoServer replica stateless · immutable image Liveness / readiness probes Read-only ConfigMap catalog / data_dir Object storage tiles · styles · GWC blobstore PostGIS via pooler vector features

Guardrails Embedded in Configuration

The guardrails that keep this deployment safe are not bolt-on policies; they are properties of the configuration itself, which is why they survive every redeploy.

State locking. The Pulumi or Terraform state for the publishing tier lives in a remote, encrypted backend with mandatory locking, following the State Backend Selection patterns. Locking is what prevents two concurrent pipeline runs from racing to reconcile the same Deployment and leaving the catalog half-applied; without it, a parallel hotfix and nightly drift-correction job can interleave writes and corrupt the recorded resource graph.

Secret management. Database credentials, the GeoServer admin password, and any cloud provider tokens resolve from a dedicated secret manager (AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault) through secretKeyRef references, never as literals in the manifest or values committed to the repository. Rotating a credential becomes a secret-store operation followed by a rolling restart, with no image rebuild.

Network isolation. Replicas run in private subnets and reach the database and object store over private endpoints with IAM-scoped identities rather than static keys. Egress is restricted to the approved OGC endpoints and internal service mesh, drawing its rules from Security Group Hardening so the publishing tier cannot exfiltrate to arbitrary hosts even if an extension is compromised.

Heap and resource sizing. Heap (-Xmx) and container memory limits are sized together so the JVM heap plus off-heap GeoWebCache buffers stay below the pod’s memory limit; if -Xmx approaches the container limit the kernel OOM-killer terminates the node mid-render. The CPU limit is set for sustained rendering throughput because GEOS and GDAL operations are compute-bound, and starving them quietly doubles tile-seeding wall-clock time.

GeoWebCache blobstore note: when the tile cache is backed by object storage, size the disk-based metastore and in-memory cache by tile count and average tile bytes, not by a percentage of node memory. A z0–z14 web-mercator pyramid over a national extent is hundreds of millions of tiles; left unbounded, the metastore index alone will exhaust local volume. Cap the blobstore and let the Object Storage for Raster/Vector Workloads lifecycle rules age out cold zoom bands.

For teams expressing the GeoServer catalog itself as type-safe code — workspaces, datastore connections, and layer publishing rules driven through the REST API rather than a mounted data_dir — the resource-mapping approach is detailed in Pulumi Programmatic Resource Mapping for GeoServer, which also covers the drift-detection job that reconciles the live catalog against the desired state on a schedule.

Troubleshooting and Failure Modes

Catalog reset on pod restart. Symptom: workspaces and layers vanish after a rolling update, and GetCapabilities returns an empty list. Cause: the data_dir is writable and was being edited through the admin console, so the changes lived only on the terminated pod’s ephemeral volume. Fix: mount the data_dir read-only from the ConfigMap (as above) and reconstruct all catalog state from code; treat the admin console as read-only in every environment.

Extension version skew. Symptom: vector-tile layers return HTTP 200 but the pbf payload is empty or unparseable, or a WPS process throws ClassNotFoundException. Cause: the running image bundles a vectortiles or wps extension built against a different GeoTools version than the core war. Fix: pin the core version and every extension to the same release in the image build and assert the set with a startup check; never download plugins at runtime.

Connection-pool exhaustion during rollout. Symptom: new replicas fail readiness with FATAL: remaining connection slots are reserved, while old replicas still serve traffic. Cause: each GeoServer replica opened its own direct pool, and a rolling update briefly doubles the replica count, overrunning the database’s max_connections. Fix: front the database with a connection pooler (PgBouncer or RDS Proxy) from the PostGIS Cluster Provisioning stack and size GeoServer’s per-store pool against the pooler’s transaction limit, not the database’s raw slot count.

SRS axis-order mismatch between environments. Symptom: a layer renders correctly in staging but appears flipped or offset in production for the same EPSG:4326 request. Cause: the GEOSERVER_CSV/axis-order JVM flags or the declared-versus-native SRS differ between images, so latitude/longitude ordering diverges. Fix: pin the axis-order handling flags in JAVA_OPTS as part of binary parity and generate native and declared SRS from the same catalog source for every stage.

OOM-kill under tile-seed load. Symptom: replicas restart with exit code 137 during a GeoWebCache seed job, never under normal browsing. Cause: -Xmx plus off-heap cache buffers exceed the container memory limit only at peak seeding concurrency, which staging never reproduced because its heap was smaller. Fix: enforce heap-and-limit parity across stages and cap GeoWebCache in-memory and metastore sizes so seeding cannot grow unbounded.