Skip to content

GCP Setup

Jump to bottom
Griffen Fargo edited this page Aug 24, 2026 · 1 revision

GCP Setup

Complete guide for setting up Doorman with Google Cloud Armor.

Status: GCP Cloud Armor support is in beta — verified end-to-end against a real GCP project, but not yet as battle-tested as the stable Vercel Firewall support. Review changes carefully before applying to production.

Scope: Doorman manages Cloud Armor's securityPolicies custom rules — the CEL-based rules API. Doorman does not create the security policy resource itself; it manages rules within an existing one.

Prerequisites

  • A GCP project with billing enabled
  • The gcloud CLI installed
  • An existing Cloud Armor security policy (see Create the Security Policy below if you don't have one)
  • Node.js 18+ installed
  • Doorman installed (npm install -g @gfargo/doorman)

Get Your Credentials

Enable the Compute Engine API

Cloud Armor security policies live under the Compute Engine API — enable it once per project:

gcloud services enable compute.googleapis.com --project=YOUR_PROJECT

Authenticate

Two options:

  • Application Default Credentials (recommended for local/dev use):

    gcloud auth application-default login

    Uses your own Google account — no key file to create, store, or later revoke.

  • Service account key (for CI/production): create a service account with the roles/compute.securityAdmin role (the narrowest predefined role covering securityPolicies.get/insert/patch/addRule/patchRule/removeRule/list), then generate a JSON key:

    gcloud iam service-accounts create doorman-ci --display-name="Doorman CI"
gcloud projects add-iam-policy-binding YOUR_PROJECT \
  --member="serviceAccount:doorman-ci@YOUR_PROJECT.iam.gserviceaccount.com" \
  --role="roles/compute.securityAdmin"
gcloud iam service-accounts keys create doorman-key.json \
  --iam-account="doorman-ci@YOUR_PROJECT.iam.gserviceaccount.com"

Create the Security Policy

If you don't already have one, create a Cloud Armor security policy for Doorman to manage:

gcloud compute security-policies create YOUR_POLICY_NAME --description="managed by doorman"

Configure Environment Variables

Unlike Vercel/Cloudflare/Fastly, GCP intentionally reuses GCP's own ecosystem-standard variable names — if you already have gcloud/other GCP tooling configured, you likely have these set already:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/doorman-key.json"  # Optional — omit to use Application Default Credentials
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GCP_POLICY_NAME="your-policy-name"

Or create a .env file in your project root:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/doorman-key.json
GOOGLE_CLOUD_PROJECT=your-project-id
GCP_POLICY_NAME=your-policy-name

Important: Add .env and any service-account key file to .gitignore to avoid committing secrets.

Initialize Your Project

doorman init only supports Vercel today — it has no --provider flag and doesn't prompt for GCP credentials. For GCP, create .doorman.json manually:

{
  "$schema": "https://doorman.griffen.codes/schema.json",
  "provider": "gcp",
  "providers": {
    "gcp": {
      "projectId": "your-project-id",
      "policyName": "your-policy-name"
    }
  },
  "rules": [],
  "ips": []
}

Add Your First Rules

Write rules by hand in your GCP-provider config (see Configuration for the rule format). doorman template doesn't take a --provider flag — doorman template <name> only generates Vercel-format rules today, so it isn't a fit for a GCP config yet.

Deploy

# Preview what will change
doorman diff --provider gcp

# Deploy rules
doorman sync --provider gcp

# Verify deployment
doorman status --provider gcp

Day-to-Day Commands

doorman status --provider gcp    # Check sync status and health
doorman diff --provider gcp      # Preview pending changes
doorman sync --provider gcp      # Deploy changes
doorman download --provider gcp  # Pull the live policy back into your local config
doorman validate                 # Validate config syntax
doorman backup                   # Create a backup

How Doorman Models GCP Cloud Armor

A few things behave differently on GCP than on Vercel/Cloudflare/Fastly — worth knowing before you write rules:

  • A rule's priority is its id. Unlike every other provider, Cloud Armor has no separate server-assigned rule id — a rule's priority (a required integer) is simultaneously its doorman id, its evaluation order, and its addressing key. A new rule with no priority set gets one assigned automatically during sync. Editing a rule's priority relocates it (Cloud Armor has no in-place "change priority" operation — Doorman does a remove-then-add under the new priority instead).
  • No dedicated IP-blocking resource. An ips[] entry is just an ordinary rule under the hood, matched on a single ip condition — Doorman classifies a fetched rule as an IP entry only when it has exactly that shape.
  • Every policy has a rule Doorman doesn't manage. Every real Cloud Armor policy carries a mandatory, server-injected default rule at the maximum priority — Doorman skips it entirely; it never appears in your local config.
  • Rules match on CEL, a flat expression-string language — geo-targeting is country-level only (no city/region/continent), and there's no per-request port or scheme condition.
  • Rate-limit rules require rateLimitOptions — a rate_limit action with no rate-limit block configured will likely be rejected by the API.
  • Mutations are asynchronous under the hood. Every rule add/update/delete returns a long-running GCP Operation that Doorman polls internally — you don't need to do anything differently, but a sync can take a few seconds longer than an equivalent Cloudflare/Fastly one.

Troubleshooting

Authentication Errors

  • Confirm gcloud auth application-default login has been run (or GOOGLE_APPLICATION_CREDENTIALS points at a valid service-account key)
  • Confirm the Compute Engine API is enabled on the target project: gcloud services enable compute.googleapis.com --project=YOUR_PROJECT
  • Confirm your account/service account has roles/compute.securityAdmin (or broader, like Owner/Editor) on the project

"Policy not found"

  • Confirm GCP_POLICY_NAME matches an existing security policy: gcloud compute security-policies describe YOUR_POLICY_NAME --project=YOUR_PROJECT
  • Doorman does not create the policy resource itself — see Create the Security Policy above

Priority Collision Errors

  • Cloud Armor rejects a priority that collides with an existing rule outright — run doorman status --provider gcp to see what's currently occupied before hand-setting a priority

Rules Not Appearing

  • Check the policy's rules in the Cloud Armor console or via gcloud compute security-policies describe YOUR_POLICY_NAME
  • Run doorman sync --provider gcp --debug for detailed output
  • Look for translation warnings — a condition field with no CEL equivalent (region, city, port, scheme) fails loudly rather than syncing a lossy version of the rule

Security Best Practices

  1. Never commit service-account key files — use gcloud auth application-default login locally, or a secrets manager in CI
  2. Use roles/compute.securityAdmin, not Owner/Editor, for any service account Doorman uses
  3. Test in staging first — create rules disabled, enable after testing
  4. Create backups before major changes (doorman backup)
  5. Monitor Cloud Armor's request/policy logs for rule effectiveness

Related Pages

Getting Started

Configuration

Commands

Guides

Clone this wiki locally