VCL services
VCL services offer an efficient mechanism to manage and control traffic to your domains, powered by Fastly's variant of the Varnish Configuration Language (VCL). The code you run on VCL services is compiled by Fastly, which means that in addition to uploading VCL code via our API, you can also write it directly into our web interface, or enable high level features that will generate VCL code for you.
This developer guide will help you get started with a VCL service that you wish to manage programmatically. If you prefer to use the web interface, head over to our "start here" guide to quickly get to know Fastly.
Getting started
Create a new Fastly account and invite your collaborators
Fastly services are associated with a customer account, which can have multiple users. To get started, create a free account, and invite your colleagues if you want to provide access to others in your team.
- Create a new account by following the steps in our signup form.
- If you wish, invite additional users to your new account. These users must not already be collaborators on another Fastly account.
Generate an API token
Whether you want to use the API via your own choice of HTTP client (e.g., cURL) or the Fastly CLI, you will need to create an API token for your account. Follow the steps for creating API tokens, make sure it has global
scope, and make a note of the token.
Download and install the Fastly CLI
The Fastly CLI makes it easier to communicate with the Fastly API, by handling authentication, and providing validation and helpful advice in many error situations. However, since VCL services are compiled and executed only on the Fastly platform, you can also use any HTTP client or API client library. If you want to use the Fastly CLI, then it is available for multiple operating systems:
- MacOS: Install from Homebrew:$ brew install fastly/tap/fastly
- Windows: Visit the GitHub repo to download the prebuilt binary for your architecture.
- Linux: Packages are available for many distributions, along with prebuilt binaries. Visit the GitHub repo to download the package for your distro.
Verify everything works by running fastly version. For example:
$ fastly versionFastly CLI version vX.Y.Z (abc0001)Built with go version go1.18 linux/amd64Viceroy version: viceroy X.Y.Z
The CLI will notify you if a new version is available. You can update it using the fastly update command.
Configure the Fastly CLI
Configure the CLI to act on your behalf using the token you previously created. Choose one of the following options to give the CLI access to your API token:
- (Recommended) Run fastly profile create and follow the interactive prompts. This will store your API token credential in a configuration file and remember it for subsequent commands.
- Include the token explicitly on each command you run using the
--token
or-t
flags. - Set a
FASTLY_API_TOKEN
environment variable.
For an overview of all available commands, run fastly with no arguments. Summarized help about any command or subcommand is available via the --help
flag (e.g., fastly service --help). For verbose help, use the help command (e.g., fastly help service).
Create a service
Create a new, empty VCL service.
$ fastly service create --name=my_vcl_serviceSUCCESS: Created service 9yqrXWr5kfqroswtmxgQDz
Add a domain and a backend
VCL services require, as a minimum, a domain and a backend before you can activate them. The domain is the hostname that you want to point to Fastly, and the backend is the location to which Fastly should forward requests. The backend can be an IP address or hostname.
Fastly services are versioned. The first version of your service, created when the service itself is created, is version 1. The --version
flag accepts 'latest', 'active', or the number of a specific version. Use this flag with fastly domain create and fastly backend create to add your domain and backend:
$ fastly domain create --name=example.com --service-id=9yqrXWr5kfqroswtmxgQDz --version=latestSUCCESS: Created domain example.com (service 9yqrXWr5kfqroswtmxgQDz version 1)
$ fastly backend create --name=app_server --address=192.168.123.123 --service-id=9yqrXWr5kfqroswtmxgQDz --version=latestSUCCESS: Created backend app_server (service 9yqrXWr5kfqroswtmxgQDz version 1)
If you add multiple domains, all will be associated with the service and traffic to any of them will be processed in the same way. If you add multiple backends, only the first will be used, unless you configure conditions, load balancing, or failover, or explicitly change the backend by setting the value of req.backend
in VCL. Learn more about using backends with your Fastly service.
Depending on the type of domain you've chosen, you may need to also configure DNS and TLS settings before traffic will be routed correctly to your service. For full details, see Routing traffic to Fastly.
Activate your service
The first version of your service, which you have been editing to add the domain and backend, is created in draft mode. That allows you to make changes to the service configuration individually, and then apply the changed configuration in a way that is guaranteed to be one changeset. It also allows you to roll back to any earlier version of your configuration, should you make a mistake or discover a problem.
You can activate your draft service version by clicking the Activate button in the web interface, or by sending an API request to the activation endpoint, or by using the CLI:
$ fastly service-version activate --service-id=9yqrXWr5kfqroswtmxgQDz --version=latestSUCCESS: Activated service 9yqrXWr5kfqroswtmxgQDz version 1
Test the service
After activation, use your own domain or a fastly test domain you attached to your service to send a request to Fastly:
$ curl -si "https://example-com.global.ssl.fastly.net/"HTTP/1.1 200 OKContent-Type: text/html; charset=utf-8Date: Thu, 28 May 2020 17:48:38 GMTAge: 0X-Served-By: cache-lon4266-LONX-Cache: MISSX-Cache-Hits: 0
...
The X-Served-By
header shows you which Fastly POP handled your request, and the X-Cache
header tells you that it was a cache miss (i.e., the request was forwarded to the backend).
Next steps
Now that you have a working VCL service up and running, check out using VCL to find out how to start writing your own edge processing logic. When you're ready to upload VCL to your service, clone the current service version, then upload new VCL and activate a new version.
You can find hundreds of examples of VCL solutions in our solutions library, from simple ones that add geo data to your request to complex solutions like doing A/B testing at the edge,