1. Home
  2. Learn to build on the Fastly platform

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.

  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 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 version
Fastly CLI version vX.Y.Z (abc0001)
Built with go version go1.18 linux/amd64
Viceroy 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_service
SUCCESS: 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=latest
SUCCESS: Created domain example.com (service 9yqrXWr5kfqroswtmxgQDz version 1)


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

HINT: The API reference for the domain and backend endpoints provides the full list of options available to set on a domain or backend if you are creating them via the API.

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=latest
SUCCESS: 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 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 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,

On this page: