Serving a static site from GCS with correct cache headers

A static bundle in Cloud Storage is cheap to run and easy to get wrong: which Cache-Control values to set, how to upload them, and how Cloud CDN behaves.

Published

Updated

Reading time

8 min

A static bundle has two kinds of file that need opposite cache policies, and a bucket gives both of them the same one. index.html should be fetched fresh after every deploy. app.3f9c1b.js should never be fetched twice by the same browser. Leave the headers alone and Cloud Storage treats them identically, which produces the quiet failures: a deploy half your visitors do not see for an hour, a stylesheet re-downloaded on every page view, or a single-page app whose old JavaScript keeps asking for files that no longer exist. This walkthrough sets up a bucket for a front end (a single-page app, a documentation site, a marketing page), uploads it with the right headers in the right order, checks the result, and then adds Cloud CDN without hiding deploys.

What the bucket does when you set nothing#

The object metadata documentation gives the default. An object with no Cache-Control metadata is served with public, max-age=3600 when it is not encrypted with a customer-managed key and not inside a VPC Service Controls perimeter; other cases get stricter defaults such as no-cache, no-store, max-age=0. One hour is wrong for both kinds of file:

  • For index.html it is too long. Browsers and any shared cache may keep serving the old document for up to an hour after a deploy, and the same page notes there is no way to force a cached object to expire globally.
  • For a hashed JavaScript file it is too short. The file will never change, yet every visitor revalidates it hourly.
StrategyEntry pointAssetsResult
Leave defaultsone hourone hourStale entry point after deploys; wasted revalidation on assets
Short TTL on everythinga few minutesa few minutesDeploys visible quickly; every asset re-fetched constantly
No-store on everythingnever cachednever cachedAlways fresh; slow and expensive for repeat visitors
Two policies with hashed filenamesalways revalidatecached for a yearFast repeat visits and visible deploys
CDN force-caching everythingoverridden by CDNoverridden by CDNFast, but each deploy needs an explicit invalidation
Table 1— Cache strategies for a bundle, and what each one costs you

The fourth row is the only one that serves both goals, and it rests on one property of modern build tools: they put a content hash in each asset's filename. A file named app.3f9c1b.js can be cached forever because a changed file gets a different name, and the new name reaches users only through the entry point, the one file you keep fresh.

The values:

  • Hashed assets: Cache-Control: public, max-age=31536000, immutable. A year is the conventional ceiling for "forever", and immutable tells browsers not to revalidate on reload.
  • HTML and other fixed-name files (index.html, 404.html, robots.txt, sitemap.xml): Cache-Control: no-cache, or a short max-age where a few minutes of staleness is acceptable. no-cache does not mean "do not store"; it means a cache must revalidate with the origin before reuse, which is cheap because an unchanged file answers with a small not-modified response. The MDN reference for Cache-Control defines each directive.
One deploy, two cache policies. Only the fixed-name files decide how fast a release becomes visible.

Create the bucket and make it a website#

The commands use gcloud storage, which Google recommends over gsutil. Bucket names and paths are examples.

terminalbash
gcloud storage buckets create gs://example-site-static \
  --location=europe-west1 \
  --uniform-bucket-level-access
 
gcloud storage buckets add-iam-policy-binding gs://example-site-static \
  --member=allUsers \
  --role=roles/storage.objectViewer
 
gcloud storage buckets update gs://example-site-static \
  --web-main-page-suffix=index.html \
  --web-error-page=404.html

The last command comes from the static website hosting guide. Without a main page suffix, a visitor to the top-level site is served an XML listing of the public objects, and a missing or non-public file returns a 403 unless you set an error page, which turns it into a 404. Making the bucket publicly readable publishes everything in it, so check the build output before uploading.

The same guide says Cloud Storage does not support custom domains with HTTPS on its own, so HTTPS on your own domain means an external Application Load Balancer and a certificate in front. Plain HTTP bucket hosting works without one.

Single-page apps need a plan here. Deep links such as /settings/profile do not exist as objects, and the error page is the only fallback the bucket offers, served with a 404 status that some crawlers treat as an error. Either generate a real HTML file per route at build time or put a load balancer rule in front. This is where "no servers" runs out.

Upload the assets first, then the entry points#

gcloud storage cp accepts --cache-control and --content-type on upload (command reference). Two passes, hashed files first:

terminalbash
BUILD_DIR=dist
BUCKET=gs://example-site-static
 
# Pass 1: hashed assets, long-lived and immutable
gcloud storage cp --recursive "$BUILD_DIR/assets" "$BUCKET" \
  --cache-control="public, max-age=31536000, immutable"
 
# Pass 2: fixed-name files, revalidated every time
gcloud storage cp "$BUILD_DIR/index.html" "$BUILD_DIR/404.html" "$BUCKET" \
  --cache-control="no-cache"

The order matters. When the new index.html lands and starts pointing at app.3f9c1b.js, that file must already exist; reverse the order and there is a window where the entry point references files that are not there yet. In the other direction, never delete the previous release's assets immediately: a visitor who loaded the old index.html a minute ago will still request the old hashed files. Keep the last two releases' assets and delete older ones in a scheduled clean-up.

Repair headers on objects that are already uploaded#

If you add or change the header after a first upload, existing objects keep the old value until you rewrite their metadata. The direct tool is gcloud storage objects update, which takes --cache-control and wildcards (reference):

terminalbash
gcloud storage objects update "gs://example-site-static/assets/**" \
  --cache-control="public, max-age=31536000, immutable"

For incremental deploys gcloud storage rsync is available, with --dry-run, --cache-control and --delete-unmatched-destination-objects (reference). The last flag deletes destination objects that are not in the source, is off by default, and the page itself warns it can delete data quickly if source and destination are wrong. Preview first:

terminalbash
gcloud storage rsync "$BUILD_DIR/assets" "$BUCKET/assets" \
  --recursive \
  --cache-control="public, max-age=31536000, immutable" \
  --dry-run

rsync is a content sync that compares modification times and hashes to decide what to copy, so use objects update to fix metadata on files that have not changed and let rsync move content.

Check the headers after every deploy#

terminalbash
curl -sI "https://static.example.com/index.html" | grep -i '^cache-control'
curl -sI "https://static.example.com/assets/app.3f9c1b.js" | grep -i '^cache-control'
curl -sI "https://static.example.com/assets/app.3f9c1b.js" | grep -i '^content-type'

Run it in CI after each deploy and fail the pipeline when a value is not what you set. It takes seconds and catches the day someone changes the upload script. Checking one JavaScript and one CSS file's content type matters too: a script served with a generic type may be blocked by the browser.

On compression, cp offers --gzip-local and --gzip-in-flight. The first stores compressed objects and, per the reference, sets their Cache-Control metadata to no-transform, which is one more header to manage deliberately. Uploading plain files and looking at the resulting headers with the curl checks above is the simpler path.

Add Cloud CDN without hiding deploys#

The metadata page points to Cloud CDN for greater control over caching. The caching overview explains how it reads your headers:

  • A response with max-age is cached for that many seconds, and s-maxage takes precedence if both are present.
  • Values above 30 days are treated as 2,592,000 seconds inside the CDN, while clients still see your original value.
  • With no headers from the origin under CACHE_ALL_STATIC, the default TTL applies (one hour out of the box).
  • no-store and private responses are not cached. A response with no-cache is cached but must be revalidated with the origin before it is served.
  • Entries not accessed for 30 days are evicted, and unpopular entries can go sooner, so rarely requested assets will refetch from the bucket.
  • When the origin is unreachable, the CDN can serve stale content for up to 24 hours by default (serve-while-stale), which is worth knowing before you debug a "stale" page.

The cache modes are CACHE_ALL_STATIC (the default), USE_ORIGIN_HEADERS, which requires valid caching headers from the origin, and FORCE_CACHE_ALL, which caches all successful responses and ignores private and no-store. Because the whole design depends on correct origin headers, use them:

terminalbash
gcloud compute backend-buckets update example-site-backend \
  --cache-mode=USE_ORIGIN_HEADERS

With no-cache on the HTML, the CDN holds a copy but revalidates it against the bucket before each use, so a deploy is visible without any invalidation step, while the year-long assets are served from the edge. FORCE_CACHE_ALL is tempting but makes the entry point sticky: it ignores those directives, and every deploy then needs an explicit invalidation to become visible.

The load balancer has its own fixed monthly charge, on top of storage and egress (Cloud Storage pricing, Cloud CDN pricing). A low-traffic personal site may be cheaper on plain bucket hosting or a managed static host, and the decision is whether you need HTTPS on a custom domain at all.

Ways it still goes wrong#

  • A browser can hold an old entry point. no-cache fixes this for revalidating clients, but a copy cached under an earlier, longer policy stays until it expires. Apply the correct header from the first deploy, not after the first incident.
  • immutable is a promise. If a hashed filename is ever overwritten with different bytes, you cannot take it back for a year. Make the upload step fail if the object already exists with a different checksum.
  • Public by design. The bucket has allUsers as a viewer, so source maps, environment files and anything under the build directory are exposed. Exclude them in the build or with rsync --exclude.
  • Routing is not the bucket's job. The 404 page is a fallback of last resort, not a router. If the site needs server-side rendering, personalisation or authentication, a bucket is the wrong host, and an app that already runs on Cloud Run can serve its few static files from the same service instead; see Cloud Run vs GKE vs Cloud Functions. For user uploads the same cache reasoning is applied in serving user images cheaply.
Share
All articles →

A design review of a Google Cloud image pipeline: signed uploads, fixed variants, immutable names and a CDN, with failure and deletion paths worked through.

15 min

A scheduled sync pays to refresh every record, including the ones nobody reads. Refreshing stale data when someone looks makes cost follow attention.

15 min

Start with a budget that emails a monitored channel, then add a Pub/Sub relay, usage alerts and a heartbeat that notices silence when that is worth building.

10 min