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:

  1. attribution of the package (e.g., name, author)
  2. information required by the fastly CLI to compile and upload it to a compatible Fastly service
  3. configuration of local server environments

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.

Example

The following is an example of a fastly.toml file for a project built using our Rust SDK:

fastly.toml
TOML
1manifest_version = 1
2name = "my-compute-project"
3description = "A wonderful Compute@Edge project that adds edge computing goodness to my application architecture."
4authors = ["me@example.com"]
5language = "rust"
6service_id = "SU1Z0isxPaozGVKXdv0eY"

Reference

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:

Property nameTypeDescription
manifest_versionNumberPackage manifest schema version number. Currently there is and has been only one manifest version. This property should always be set to 1. In the future, any breaking changes to the manifest format will be accompanied by a change to the manifest version and the format changes will be documented here.
nameStringName of the package. If there is no service_id specified in the same manifest, a new service will be created and this will become the name of the service as well as the name of the uploaded package. If the project is deployed to an existing service, any change to the name will update the name of the compute package, but will not change the name of the service.
authorsArray: stringAn 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.
descriptionStringBrief description of the project, for audit purposes. Displayed in the web interface and reported back via the API.
languageStringLanguage used for the project. Either "rust", "assemblyscript", or another language SDK supported by Compute@Edge. This determines how the fastly CLI will compile your project to Webassembly before it is uploaded to the Fastly edge cloud.
service_idStringThe Fastly service ID of the service to which the fastly CLI should deploy the package. If not specified, a new service will be created when the project is deployed.
local_serverSectionDescribes the configuration for the local server built into the Fastly CLI, which can be invoked with fastly compute serve.
└─ backendsSectionA list of backends that should be provided by the local server.
   └─ {name}SectionEach backend is a section whose name is the string used as the backend ID in the package code.
      └─ urlStringThe 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.

Local server

IMPORTANT: Local server support is currently being introduced and is not yet supported by the latest public version of the Fastly CLI.

The [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.

Backends

Test backends are local or remote servers to which we should route traffic coming from your package. Each backend is a section and contains a single url key:

fastly.toml
TOML
[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/"

If the 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 https://example.org/path/prefix/foo.

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.

Environments

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.{ENV-NAME}.toml (e.g., fastly.staging.toml), alongside the fastly.toml file. Environment-specific files define an alternative configuration for [local_testing].

For example, the following configuration matches the one above, except that it defines a different URL for backend_b:

fastly.staging.toml
TOML
[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/"```