Dynamic configuration data for Fastly services

Fastly services combine edge code in VCL or Webassembly with resources such as log endpoints, domains and backends, which are compiled together into a service version and deployed to our edge cloud. However, you may have additional data that you want to make available to the service at runtime, but which isn't hard-coded into the application itself - for example, feature flags, IP ranges, secrets, keys, tokens, URL mappings, user preferences etc.

Dynamic configuration features allow data to be made available to your application at runtime in a way that offers almost zero-latency for reads. Dynamic configuration data is read only at the edge, globally consistent, and writable via the Fastly API, without creating a new version of your service.

ProductPlatformsShareableTypical use cases
Edge dictionariesC@E / VCLNoConfiguration
Access control listsVCLNoIP allowlists / blocklists

Edge dictionaries

Edge dictionaries are small, durable, globally consistent key-value stores for string keys and values, which offer extremely fast read performance (microseconds) at the edge and a separate HTTP API for writes. Dictionaries are ideal for storing configuration such as flags, A/B testing settings, path routing rules, and more. Updates to dictionaries made via the Fastly API are available at the edge within around 30 seconds.

Dictionaries can be created and managed via multiple methods:

Dictionaries must be created on a draft version of your service, and once a new dictionary is created, the new version of the service must be activated to make the dictionary available at the edge. The dictionary will then be accessible to your code via the name you assigned it. Using the CLI, you can create a new version of your service and add a dictionary to it in one step:

$ fastly dictionary create --version=active --autoclone --name=ttls
$ fastly service-version activate --version=latest

In VCL servies, dictionaries are exposed as VCL tables and can be accessed using the table.contains and table.lookup functions. In Compute@Edge services, each supported language SDK has a mechanism for opening and querying an edge dictionary.

In the following example, a dictionary maps URL path prefixes (such as /products) to an override TTL (the cache lifetime in seconds). When a request is received for a URL matching one of the paths in the dictionary, the override TTL is applied.

  1. Fastly VCL
  2. Rust
  3. JavaScript

Dictionary items are versionless.

Limitations

Edge dictionaries are subject to the following constraints:

  • Dictionaries are not writable from edge code. If you need to update state from the edge, consider using an object store instead.
  • Maximum 1000 keys per dictionary. If you need more, contact us and we can discuss your use case.
  • Keys may be up to 256 characters long. Values may be up to 8000 characters long.
  • All keys and values are strings. VCL provides other typed tables but these are not manageable as Edge Dictionaries.
  • Dictionaries cannot be shared between services.

Private dictionaries

When creating an edge dictionary, the write_only property may be set to mark the dictionary as private. This will prevent dictionary items being enumerated via the API, and will redact the VCL table declarations that are generated into VCL services. However, the contents of private edge dictionaries are still stored in plain text and are not recommended for storing secrets, credentials or personal data.

Access control lists

Exclusive to VCL services, ACLs store lists of IP addresses or subnets. These are useful for making access or content decisions based on the identity of the client - perhaps to block malicious clients, provide privileged access to your organization's own IP ranges, or to conduct A/B testing on groups identified by IP.

Using the ~ operator in VCL, you can check whether a given IP address is a member of the ACL. While you can write ACL definitions into VCL source code directly, they can also be created and managed separately, and Fastly will generate the ACL definition for you when your VCL is compiled. Updates to ACLs made via the Fastly API are available at the edge within around 30 seconds.

Similarly to edge dictionaries, ACLs are small, durable, globally consistent, and read-only at runtime. A managed ACL can be created and updated in a number of ways:

ACLs must be created on a draft version of your service, and once a new ACL is created, the new version of the service must be activated to make the ACL available at the edge. The ACL will then be accessible to your code via the name you assigned it. Using the CLI, you can create a new version of your service and add an ACl to it in one step:

$ fastly acl create --version=active --autoclone --name=ban_acl
$ fastly service-version activate --version=latest

To test whether an IP address is in an ACL, use the ~ operator:

Limitations

ACLs are subject to similar constraints to edge dictionaries:

  • ACLs are not writable from edge code.
  • Maximum 1000 entries per ACL.
  • Keys may be up to 256 characters long. Values may be up to 8000 characters long.
  • ACLs cannot be shared between services.
  • ACLs are not currently available in Compute@Edge services.