1. Home
2. Guides
3. Core concepts
4. Edge state and caching

Fastly services execute youredge code, which is compiled into aservice version and is immutable once 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, or user preferences.

Dynamic configuration is data that is available to your application at runtime, and editable without creating a new version of your service. All dynamic configuration options shown here are read-only at the edge, writable via theFastly API, globally consistent, durable, and have low read latency (around 1ms).

The following dynamic configuration features are currently available:

Dictionaries

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 services, dictionaries are exposed asVCL tables and can be accessed using thetable.contains andtable.lookup functions. 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.

Dictionary items areversionless. Changes to them immediately impact all service versions, including the active one.

Limitations

Dictionaries are subject to the following constraints:

• Dictionaries are not writable from edge code.
• Maximum 1000 keys per dictionary. If you need more, contactFastly support 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 othertyped tables but these are not manageable as dictionaries.
• Dictionaries cannot be shared between services.

Private dictionaries

When creating a dictionaryvia the API orfastly dictionary create, thewrite_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 VCLtable declarations that are generated into VCL services. However, the contents of private dictionaries are still stored in plain text and are not recommended for storing secrets, credentials or personal data.

Access control lists

Exclusive toVCL 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 canwrite 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 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:

ACL entries areversionless. Changes to them immediately impact all service versions, including the active one.

Limitations

ACLs are subject to similar constraints to dictionaries:

• ACLs are not writable from edge code.
• Maximum 1000 entries per ACL. If you need more, contactFastly support and we can discuss your use case.
• Entries must be IPv4 or IPv6 addresses or subnets.
• ACLs cannot be shared between services.
• ACLs are not currently available in Compute services.

Access control lists on compute

Access control lists on Compute (ACLs on Compute) are similar toAccess control lists exclusive to VCL. They are durable, globally consistent lists of IP addresses or subnets that can allow or block traffic based on a client's identity. You can use ACLs on Compute to do things like provide privileged access to your organization's IP ranges, conduct A/B testing on groups identified by IP, or block malicious clients.

ACLs on Compute are designed to improve read performance at the edge and, when properly configured, their entries can be proactively pushed to all Fastly POPs to ensure they are readable at the edge with minimal latency. Using theFastly SDKs inCompute, you can check whether a given IP address is a member of the ACL.

Similar toConfig stores, ACLs are read-only at runtime and can be created or updated in a number of ways:

ACLs on Compute are created at the customer level and must be attached to a service using theResources API. 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 compute acl create --name="block list" --version=active --autoclone
$ fastly service-version activate --version=latest

To test whether an IP address is in an ACL using theCompute SDKs:

Limitations

ACLs on Compute are subject to the following constraints:

• ACLs are not writable from edge code.
• Maximum 1000 entries per ACL. If you need more, contactFastly support and we can discuss your use case.
• Entries must be IPv4 or IPv6 subnets (e.g. 192.168.0.0/16, FD00::/7).
• ACLs on Compute are not available in VCL. Refer toAccess control lists for the VCL implementation.

Config stores

Like dictionaries, Config stores are durable, globally consistent key-value stores for string keys and values, which offer extremely fast read performance (microseconds) at the edge, a separate HTTP API for writes and are designed for configuration data such as flags, A/B testing settings, path routing rules, etc. Config stores differ from dictionaries in the following respects:

• Config stores are only available toCompute services, whereas dictionaries are only available inVCL services.
• Config stores are optimized for up to 100,000 entries.
• As aservice-linked resource, config stores can be shared between services.

Config stores can be created using theConfig store API, and must be attached to a service using theResources API.

For example, the following curl commands create a config store and add it to a service:

# Create a config store
$ curl -i -X POST "https://api.fastly.com/resources/stores/config" -H "Fastly-Key: YOUR_FASTLY_TOKEN" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"name":"example-store"}'
# Link the config store to a service
$ curl -i -X POST "https://api.fastly.com/service/YOUR_FASTLY_SERVICE_ID/version/YOUR_FASTLY_SERVICE_VERSION/resource" -H "Fastly-Key: YOUR_FASTLY_TOKEN" -H "Content-Type: application/x-www-form-urlencoded" -H "Accept: application/json" -d "name=example_store_service_a&resource_id=YOUR_CONFIG_STORE_ID"

Config stores are exposed to Compute services via dedicated interfaces in eachSDK:

usefastly::{Error,ConfigStore,Request,Response};
#[fastly::main]
fnmain(_request:Request)->Result<Response,Error>{
// Define a config store instance using the resource link name
let store=ConfigStore::open("example_store_service_a");
// Get the value back from the config store (as a string),
// and return it, with HTTP response code 200
let value= store.try_get("cat")?.unwrap_or_default();
Ok(Response::from_status(200).with_body(value))
}

See theCompute SDKs reference for more information about individual methods in each SDK.

Data in config stores is proactively pushed to all FastlyPOPs, and is reliably readable at the edge with sub-millisecond latency. Changes to config store data immediately impact all service versions, including the active one.

Limitations and constraints

The following limitations apply:

• Store names have a maximum length of 255 characters, must start with a letter, and may contain only letters, numbers, spaces, and underscores
• Config stores are eventually consistent, so the contents of a given key may not be immediately available to read from all edge locations
• Keys have a maximum length of 1024 UTF-8 characters
• Values have a maximum size of 8000 UTF-8 characters

Secret stores

Secret stores provide a state-of-art solution for encryption and securely storing/retrieving the sensitive information you need to properly operate your Fastly services.

Secret stores can be created and managed via multiple methods:

Secret storesmust be attached to a service using theResources API.

For example, the following curl commands create a secret store and add it to a service:

# Create a secret store
$ curl -i -X POST "https://api.fastly.com/resources/stores/secret" -H "Fastly-Key: YOUR_FASTLY_TOKEN" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"name":"example-secrets"}'
# Link the secret store to a service
$ curl -i -X POST "https://api.fastly.com/service/YOUR_FASTLY_SERVICE_ID/version/YOUR_FASTLY_SERVICE_VERSION/resource" -H "Fastly-Key: YOUR_FASTLY_TOKEN" -H "Content-Type: application/x-www-form-urlencoded" -H "Accept: application/json" -d "name=example-secrets-service-a&resource_id=YOUR_SECRET_STORE_ID"

Secret stores are exposed to Compute services via dedicated interfaces in eachSDK, which return secrets as a complex type with a method that provides access to the plaintext value:

usefastly::{Error,SecretStore,Request,Response};
#[fastly::main]
fnmain(mut req:Request)->Result<Response,Error>{
let secrets=SecretStore::open("example-secrets-service-a")?;
let secret= secrets.get("cat-api-key").unwrap();
  req.set_header("cat-api-key", secret.plaintext().to_vec());
let beresp= req.send("example_backend")?;
Ok(beresp)
}

See theCompute SDKs reference for more information about individual methods in each SDK.

Data in secret stores is proactively pushed to all FastlyPOPs, and is reliably readable at the edge with sub-millisecond latency. Changes to secret store data immediately impact all service versions, including the active one.

Limitations and constraints

The following limitations apply:

• Secret stores are eventually consistent, so a store and its the contents may not be immediately available to read from all edge locations
• Store and secret names have a maximum length of 255 characters and may contain letters, numbers, dashes (-), underscores (_), and periods (.)
• Secret values have a maximum size of 64 kilobytes