VCL services

The standard service type on the Fastly platform is a VCL service, 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.

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.

  1. Create a new account by following the steps in our signup form.
  2. 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 client library. If you want to use the Fastly CLI, install it from your system's package registry:

  • MacOS: Install from Homebrew:
    $ brew install fastly/tap/fastly
  • Windows: Install from Scoop:
    $ scoop bucket add fastly-cli https://github.com/fastly/scoop-cli.git
    $ scoop install fastly
  • Linux: Packages are available for Debian/Ubuntu, Fedora, CentOS and SUSE, along with prebuilt binaries. Visit the GitHub repo to download the package for your distro and see installation instructions for your package manager.

Verify everything works by running fastly version. For example:

$ fastly version
Fastly CLI version vX.Y.Z (abc0001)
Built with go version go1.13.1 linux/amd64

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 configure 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. Succinct help about any command or subcommand is available via the --help flag (e.g., fastly service -h). For verbose help, use the help command (e.g., fastly help service).

Create a service

Create a new, empty VCL service. Ensure you specify that you want a vcl service type:

$ fastly service create --name=my_vcl_service --type=vcl
SUCCESS: Created service 9yqrXWr5kfqroswtmxgQDz

Add a domain and a backend

Fastly 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, and the first version of your service, created with the service itself, is version 1. You must cite the version number of the service and the service ID when adding the domain and backend:

$ fastly domain create --name=example.com --version=1 --service-id=9yqrXWr5kfqroswtmxgQDz
SUCCESS: Created domain example.com (service 9yqrXWr5kfqroswtmxgQDz version 1)
$ fastly backend create --name=app_server --address=192.168.123.123 --version=1 --service-id=9yqrXWr5kfqroswtmxgQDz
SUCCESS: Created backend app_server (service 9yqrXWr5kfqroswtmxgQDz version 1)

Check the API reference for the domain and backend endpoint collections to understand the options that are available when adding domains or backends to your service.

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, automatic load balancing, directors, or explicitly change the backend by setting the value of req.backend in VCL.

HINT: If you are not yet ready to configure your DNS settings to point your domain to Fastly, you can use a Fastly domain to get started without configuring DNS and TLS. Add a domain in the form <name>.global.ssl.fastly.net, where <name> is a single hostname token (i.e., it does not contain any . characters):

$ fastly domain create --name=example-com.global.ssl.fastly.net --version=1 --service-id=9yqrXWr5kfqroswtmxgQDz

After activating your service (see next step) this domain will work without any further configuration.

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=1
SUCCESS: Activated service 9yqrXWr5kfqroswtmxgQDz version 1

Test the service

After activation, use your own domain or the 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 OK
Content-Type: text/html; charset=utf-8
Date: Thu, 28 May 2020 17:48:38 GMT
Age: 0
X-Served-By: cache-lon4266-LON
X-Cache: MISS
X-Cache-Hits: 0
...

The X-Served-By header shows you which Fastly data center 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,

User contributed notes

We welcome comments that add use cases, ideas, tips, and caveats. All comments will be moderated before publication. To post support questions, visit our support center and we'll find you the help you need.