Acquia Purge Varnish - API V2 (Drupal Module)

Acquia Purge Varnish clears the Varnish cache on Acquia Cloud Platform from a Drupal admin form, Drush, or a post-deployment hook, authenticating against Acquia's Cloud API v2 with an OAuth2 client-credentials grant. It declares core_version_requirement: ^10 || ^11 || ^12, so it already runs on Drupal 12, and it is free on drupal.org.

What it does

Acquia's platform sits Varnish in front of every environment. After a deploy, a config import, or a content push between environments, the cache in front of your site is still serving the old response until something purges it. This module is that purge button — reachable from the admin interface, from Drush for automation, or from an Acquia Cloud Platform hook script that fires on every deploy.

It talks to Acquia's Cloud API v2 through GuzzleHttp\ClientInterface — Drupal core's own HTTP client — so no additional HTTP library is pulled in for the request layer itself.

Requirements

Authentication, and one thing to fix before you install

The module authenticates with the OAuth2 client-credentials grant, using League\OAuth2\Client\Provider\GenericProvider against https://accounts.acquia.com/api/auth/oauth/token. There is no CSRF token exchange in the authentication path — that would be the wrong mechanism for a server-to-server API call — and the module does not use one there. A CSRF token does guard the purge action route itself (/admin/config/acquia-purge/varnish), which is the form submission a signed-in administrator triggers, not the API call the module makes on Acquia's behalf.

The dependency this needs is not declared in composer.json. The module's own requirements check — both at install time and on every subsequent status report — looks for League\OAuth2\Client\Provider\GenericProvider and refuses to let the module stay enabled if the class cannot be autoloaded. But nothing in composer.json pulls league/oauth2-client in for you. If Composer has not already installed it as a dependency of something else on your site, install fails with an error naming the missing library. Run this once, before or right after you require the module:

composer require league/oauth2-client:^2.7

This is a real gap in the module's own dependency declaration, not a hypothetical — treat it as a required manual step rather than an oversight you can ignore.

Installing and configuring

composer require drupal/acquia_purge_varnish
composer require league/oauth2-client:^2.7
drush en acquia_purge_varnish -y

Credentials come from Acquia Cloud → Profile → API Tokens. Create a token, copy the key and secret immediately — the secret is shown once — and confirm the account can clear caches on the target application.

Three ways to supply them:

The settings form

/admin/config/acquia-purge/settings, gated behind the Administer Acquia Purge Varnish permission.

Drush

drush acquia-purge-varnish:config --api-key="KEY" --api-secret="SECRET"

settings.php

The recommended path for production, because it keeps credentials out of the config export entirely:

$settings['acquia_purge_varnish_credentials'] = [
  'api_key' => 'your-acquia-api-key',
  'api_secret' => 'your-acquia-api-secret',
  'application_name' => 'your-app-name', // optional — auto-detects from AH_SITE_GROUP
];

When this override is present, the settings form fields disable themselves and show a notice rather than silently doing nothing.

Drush commands

Choosing what gets purged

The --domain option, or the equivalent config setting, takes three values: current purges only the domain that served the request, all purges every domain in the environment, and custom purges a fixed list you supply with --custom-domains or --domains. A custom list is filtered against the domains that actually exist in the matched environment before the request goes out, so a typo in the list does not silently fail — it falls back to purging the current domain instead.

drush apv-purge --domain=all
drush apv-purge --domain=current
drush apv-domains --format=json

For an automated purge on every deploy, an Acquia Cloud Platform hook script is the standard place:

#!/bin/bash
# hooks/common/post-code-deploy/purge-varnish.sh
site="$1"
target_env="$2"
drush @$site.$target_env apv-purge --domain=all

Common questions

Will this work off Acquia Cloud Platform?

No. Every command checks AH_SITE_ENVIRONMENT and refuses to run when it is not set. The module is built specifically around Acquia's Cloud API and environment variables.

Why did my install fail on a fresh site?

Almost certainly the missing league/oauth2-client dependency described above. Run composer require league/oauth2-client:^2.7 and try again.

Is this affiliated with Acquia?

No. It is an independent open-source project that talks to Acquia's publicly documented Cloud API; it has not been developed or endorsed by Acquia Inc.

Does it work on Drupal 12?

Yes — ^10 || ^11 || ^12 — and its status-report logic was specifically rewritten for Drupal 12's removal of the old requirement constants, so the OAuth-library check keeps working rather than silently passing.

Can I purge more than one application's domains at once?

Not in one command. Each Drush invocation targets one Acquia application, matched by name; run it once per application, or loop it in your own deploy script.

Need Acquia or Varnish work done properly?

Acquia Purge Varnish is free and will stay that way. If you want help wiring cache purging into a real deploy pipeline, sorting out an Acquia Cloud Platform migration, or a Drupal 11 or 12 upgrade that this kind of integration depends on, that is the work I do day to day.

See my Drupal services, read about what a Drupal developer brings to a project, or get in touch to talk about your environment.