Updating Guardian from v0.1.0 to v0.2.0

We are in the process of defining a stable API for Guardian. During this transition process, we have modified how both guardian and guardian-cli interact with Redis.

Guardian originally used a combination of command-line and file-based configuration. Guardian configurations are now completely file-based, and if you are upgrading from a previous version of Guardian, you will need to reconfigure Guardian before deployment for each kind of resource.

Create configuration files from existing configuration

First, fetch each resource and create configuration files to match:

GlobalRateLimit

First, get-limit:

$ guardian-cli --redis-address=<address> get-limit
Limit(<count> per <duration>, enabled: <enabled>)

Then, create globalratelimit.yml:

version: "v0"
kind: GlobalRateLimit
name: GlobalRateLimit
description: GlobalRateLimit
globalRateLimitSpec:
  limit:
    count: <count>
    duration: <duration>
    enabled: <enabled>

GlobalSettings

First, get-report-only:

$ guardian-cli --redis-address=<address> get-report-only
<reportOnly>

Then, create globalsettings.yml:

version: "v0"
kind: GlobalSettings
name: GlobalSettings
description: GlobalSettings
globalSettingsSpec:
  reportOnly: <reportOnly>

RateLimit

First, get-route-rate-limits:

$ guardian-cli --redis-address=<address> get-route-rate-limits
route_rate_limits:
- route: <route1>
  limit:
    count: <count1>
    duration: <duration1>
    enabled: <enabled1>
- route: <route2>
  limit:
    count: <count2>
    duration: <duration2>
    enabled: <enabled2>
…
- route: <routeN>
  limit:
    count: <countN>
    duration: <durationN>
    enabled: <enabledN>

Then, create ratelimit.yml:

version: "v0"
kind: RateLimit
name: <route1>
description: <route1>
rateLimitSpec:
  limit:
    count: <count1>
    duration: <duration1>
    enabled: <enabled1>
  conditions:
    path: <route1>
---
version: "v0"
kind: RateLimit
name: <route2>
description: <route2>
rateLimitSpec:
  limit:
    count: <count2>
    duration: <duration2>
    enabled: <enabled2>
  conditions:
    path: <route2>
---
…
---
version: "v0"
kind: RateLimit
name: <routeN>
description: <routeN>
rateLimitSpec:
  limit:
    count: <countN>
    duration: <durationN>
    enabled: <enabledN>
  conditions:
    path: <routeN>

Jail

First, get-jails:

$ guardian-cli --redis-address=<address> get-jails
jails:
- route: <route1>
  jail:
    limit:
      count: <count1>
      duration: <duration1>
      enabled: <enabled1>
    ban_duration: <ban_duration1>
- route: <route2>
  jail:
    limit:
      count: <count2>
      duration: <duration2>
      enabled: <enabled2>
    ban_duration: <ban_duration2>
…
- route: <routeN>
  jail:
    limit:
      count: <countN>
      duration: <durationN>
      enabled: <enabledN>
    ban_duration: <ban_durationN>

Then, create jail.yml:

version: "v0"
kind: Jail
name: <route1>
description: <route1>
jailSpec:
  limit:
    count: <count1>
    duration: <duration1>
    enabled: <enabled1>
  conditions:
    path: <route1>
  banDuration: <ban_duration1>
---
version: "v0"
kind: Jail
name: <route2>
description: <route2>
jailSpec:
  limit:
    count: <count2>
    duration: <duration2>
    enabled: <enabled2>
  conditions:
    path: <route2>
  banDuration: <ban_duration2>
---
…
---
version: "v0"
kind: Jail
name: <routeN>
description: <routeN>
jailSpec:
  limit:
    count: <countN>
    duration: <durationN>
    enabled: <enabledN>
  conditions:
    path: <routeN>
  banDuration: <ban_durationN>

Update Guardian

After the configuration files are created, the Guardian instance can be updated to the version using the new configuration format. If multiple instances are present, e.g. in a blue-green deployment, the remaining guardian-cli commands should be applied to the updated Guardian instance.

Apply configuration files

guardian-cli --redis-address=<address> apply globalratelimit.yml
guardian-cli --redis-address=<address> apply globalsettings.yml
guardian-cli --redis-address=<address> apply ratelimit.yml
guardian-cli --redis-address=<address> apply jail.yml

Once the new configuration files are applied, test that the instance is performing as expected before scaling up.

(Optional) Remove deprecated keys from Redis

Guardian will ignore these keys if they are not removed.

redis-cli -h <hostname> -p <port>
> DEL guardian_conf:limit_count
> DEL guardian_conf:limit_duration
> DEL guardian_conf:limit_enabled
> DEL guardian_conf:reportOnly
> DEL guardian_conf:route_limits:enabled
> DEL guardian_conf:route_limits:duration
> DEL guardian_conf:route_limits:count
> DEL "guardian_conf:jail:limits:enabled
> DEL guardian_conf:jail:limits:duration
> DEL guardian_conf:jail:limits:count
> DEL guardian_conf:jail:ban:duration