fastly.toml package manifest format
Fastly services provide execution environments for your custom edge code. In the case of VCL services, you can upload VCL source code, which is compiled on the Fastly platform. However, Compute@Edge services are compiled in your own environment using the Fastly CLI, and the resulting binary is uploaded to the Fastly platform.
Compute@Edge packages are configured using a
fastly.toml file in the root of the package directory tree. This file specifies configuration metadata related to a variety of tasks:
- attribution of the package (e.g., name, author)
- information required by the
fastlyCLI to compile and upload it to a compatible Fastly service
- configuration of local server environments
- bootstrapping of service configuration
In general, you should not write a
fastly.toml file yourself. Instead, create a new Compute@Edge project using the fastly CLI by executing:
$ fastly compute init
This will walk you through the creation of the project and will write the
fastly.toml file for you.
The following is an example of a
fastly.toml file for a project built using our Rust SDK:
1manifest_version = 12name = "my-compute-project"3description = "A wonderful Compute@Edge project that adds edge computing goodness to my application architecture."4authors = ["firstname.lastname@example.org"]5language = "rust"6service_id = "SU1Z0isxPaozGVKXdv0eY"
The syntax of fastly.toml is the TOML format.
The TOML format supports comments. A line that begins with a
# character is ignored:
# This is a comment.
Property names and values are separated by
=. The following properties are defined for
fastly.toml files (refer to the TOML specification to understand the 'Types' mentioned below):
|Number||Package manifest schema version number. Currently there is and has been only one manifest version. This property should always be set to |
|String||Name of the package. If there is no |
|Array: string||An array of strings, listing email addresses of the authors of the project, for audit purposes. Displayed in the web interface and reported back via the API.|
|String||Brief description of the project, for audit purposes. Displayed in the web interface and reported back via the API.|
|String||Language used for the project. Either |
|String||The Fastly service ID of the service to which the |
|Table||Describes the configuration for the local server built into the Fastly CLI, which can be invoked with fastly compute serve.|
|Table||A list of backends that should be provided by the local server.|
|Table||Each backend is a section whose name is the string used as the backend ID in the package code.|
|String||The URL of the server to which to route requests made by the package to this backend. Must contain a scheme and host. May contain a port or path prefix. See below for examples.|
|Table||Describes a set of service configuration that works with the code in the package. See setup information below. Ignored if |
|Array: Table||A list of backends that are required to be created on a first run of |
|String||The name of the backend used to connect to it from inside the package code, e.g. "api". Required.|
|String||Label to use to prompt for the backend information, e.g. "API origin server" (defaults to the same as |
|String||Hostname or IP address of the backend.|
|Number||Port number of the backend.|
|Array: Table||A list of Edge dictionaries that are required to be created on a first run of |
|String||The name of the dictionary used to reference it from inside the package code, e.g. "config". Required.|
|String||Label to use to prompt for the dictionary information, e.g. "Configuration settings" (defaults to the same as |
|Array: Table||List of predefined dictionary items for dictionaries requiring a fixed set of entries.|
|String||The key for the dictionary item. Required.|
|String||Suggested value for the dictionary item.|
|String||Label to use to prompt for the value (defaults to the same as |
|String||Input type hint, allowing for validation and improved input form usability. One of |
|Array: Table||A list of Access Control Lists that are required to be created on a first run of |
|String||The name of the ACL used to reference it from inside the package code, e.g. "banned_ips". Required.|
|String||Label to use to prompt for the ACL information, e.g. "Banned IP list" (defaults to the same as |
|Array: string||An array of strings, listing predefined ACL entries.|
|Array: Table||A list of log endpoints that are required to be created on a first run of |
|String||The name of the log endpoint used to reference it from inside the package code, e.g. "bigquery_requests". Required.|
|String||Label to use to prompt for the ACL information, e.g. "BigQuery request log" (defaults to the same as |
[local_server] section of the
fastly.toml file specifies how fastly compute serve should simulate the Fastly platform to enable you to test a package on your local machine. Currently this configuration section supports defining backends.
To see how this configuration is used, read more about testing and debugging Compute@Edge.
Test backends are local or remote servers to which we should route traffic coming from your package. Each backend is a table and contains a single
[local_server][local_server.backends][local_server.backends.backend_a]url = "http://127.0.0.1/"[local_server.backends.backend_b]url = "https://example.org/"[local_server.backends.backend_c]url = "https://example.org/path/prefix"[local_server.backends.backend_d]url = "http://127.0.0.1:8080/"
url field contains a path component, then any request to that backend will be prefixed with that path. For the example shown above, a request to
GET /foo issued by your package to the
backend_c backend will result in a request being made to
HINT: Using a path prefix is useful if your service has multiple backends and, in your test environment, you have a single server that is standing in for all of the backends. The one backend-mocking server can use the path prefix to determine which backend is being targeted by the fetch.
The local server may be invoked with an
--env argument that specifies the name of an environment. Environments are defined by creating files of the form
fastly.staging.toml), alongside the
fastly.toml file. Environment-specific files define an alternative configuration for
For example, the following configuration matches the one above, except that it defines a different URL for
[local_server][local_server.backends][local_server.backends.backend_a]url = "http://127.0.0.1/"[local_server.backends.backend_b]url = "http://localhost:1234/"[local_server.backends.backend_c]url = "https://example.org/path/prefix"[local_server.backends.backend_d]url = "http://127.0.0.1:8080/"
WARNING: Support for setup data is rolling out and may not yet be available in release versions of the Fastly CLI.
[setup] section of the fastly.toml file allows the Fastly CLI and web interface to provide a smarter experience when a deployment of a package requires a Fastly service to be created, normally when you run fastly compute deploy for the first time.
Compute@Edge programs are able to use features of Fastly services configured outside the program by referring to the feature - such as a backend or dictionary - by name. It's therefore important that when deploying a C@E program, the service it is deployed to has a set of configured features matching the expectations of the package code. For example, if the program reads values from a dictionary called "config", then there must be a "config" dictionary in the same service.
Starter kits may include
[setup] in their fastly.toml file so that the Fastly CLI has all the information needed to create a service in which that starter kit can be deployed.
Once a Compute@Edge project is associated with a Fastly service, the
[setup] data is no longer used, and the service configuration can be managed normally via the web interface, the API, using CLI commands, or third party orchestration tooling.