Using Chef With Your API Gateway

SaaS On-premises 2.0

This document refers to the Chef Integration for the downloadable Nginx configuration files. This is currently not supported in the latest version of APIcast.

This tutorial describes how to use the official 3scale Chef Cookbook to automate the deployment of your API gateway.

The 3scale Chef Cookbook allows any Chef user to automate the deployment of the 3scale API gateway. Running the Cookbook on one or multiple target nodes will install OpenResty, plus all the necessary system dependencies required to run it. After the execution completes, the nodes will have an up-and-running gateway listening for incoming API requests.

The Cookbook not only installs the API gateway, but it will also deploy your 3scale NGINX configuration files, specifically tailored for your API configuration, to the exact location they are needed.

Chef is a configuration management tool that automates and simplifies software installation by using reusable configuration scripts called Cookbooks. The 3scale API gateway is one of the integration methods that our customers use to integrate their APIs with the 3scale API Management Platform. It’s based on OpenResty, a bundle that includes NGINX and some very useful third-party modules that complement it with features such as support for Lua scripting.


This tutorial assumes familiarity with how Chef works and a ready-to-use Chef environment. Here are some resources that will help you get to that point:

You’ll also need to have previously configured your API in your 3scale Admin Portal. If you haven’t gone through that step yet, you should do it now. You can follow the instructions here (stop at the part about running your gateway self-managed).

How to use it

1. Add the Cookbook to your run list

The first step is to add the default recipe of the Cookbook to your node or role run list.

2. Configure the required Cookbook attributes

There are four attributes to set to configure the Cookbook. All of them are under the 3scale namespace: 3scale namespace.

  • ['3scale']['config-source'] – Where your NGINX configuration files will be taken from. Two options: "local" or "3scale". Read the "Applying your own 3scale configuration" section of this tutorial before setting this attribute.
  • ['3scale']['provider-key'] – The key that identifies you as a 3scale customer. It can be found in the "Account" menu of your 3scale admin portal.
  • ['3scale']['admin-domain'] – If your 3scale Admin Portal domain is, then the value of this attribute should be "mycompany".
  • ['3scale']['config-version'] – Version ID. If not included, the current configuration from your 3scale account will be used. If included, the value must be a timestamp of one deployment, formatted as: 2015-09-15-041532. See the "Rollback process" section for more information on this.

Here you can see the default value each one of this attributes has. This Cookbook uses and depends on the OpenResty Cookbook, so attributes of that Cookbook are also available to you. You can see a full list here.

Since you’ll be using the NGINX configuration files that 3scale generates for you, you won’t be able to use the attributes of the OpenResty Cookbook related to configuration parameters that go in the nginx.conf file.

Here is an example of a JSON node description that’s ready to be used. In this case, the configuration files will be downloaded from 3scale – as you can see in the config-source attribute


Applying your own 3scale configuration

For the API gateway to be configured for your own API endpoints, you need to deploy it using your own set of NGINX configuration files. There are two ways to apply your own configuration files to the Cookbook:

Option 1: Local configuration files

This is the option you should use if:

  • Your NGINX configuration has any customization on top of the default files generated by 3scale.
  • You have more than one service in 3scale (since you will need to set the domains for each of them in the configuration).

Configure your API in 3scale using the self-managed gateway option. Click on Download the Nginx Config files at the bottom of the screen. Then drop these files on the /files/default/config/ directory of the Cookbook.

To use this option you’ll need to set the ['3scale']['config-source'] attribute to local in your node or role description.

Option 2: Fetch configuration files from your 3scale account

With this option, the Cookbook will automatically fetch the NGINX configuration files from your 3scale account when running the deployment. You’ll need to set the following attributes in your node or role description:

  • ['3scale']['config-source'] = "3scale"
  • ['3scale']['provider-key'] = (see attributes section)
  • ['3scale']['admin-domain'] = (see attributes section)

In both cases, the NGINX configuration files will be copied to a subdirectory in /var/chef/cache and symlinked to the NGINX working directory (/etc/nginx/).

Rolling back to a previous version of the configuration

The 3scale Cookbook allows rolling back to a previously deployed version of the configuration. This can be used in cases where you have a node where the API gateway had already been deployed one or multiple times, and you want to deploy it again but using the configuration files from one of the previous deployments instead of the latest version.

The built-in way to roll back is by using the ['3scale']['config-version'] attribute. Here’s an example of a full node description using the rollback attribute:


If you’re having problems deploying your API gateway when running the Cookbook, the best first step is to look at Chef’s own logs. You can find some useful debugging tips here.

If the deployment completed successfully but the API gateway is not running as expected, the problem is probably in the NGINX configuration files you deployed. The best place to start troubleshooting is the NGINX error log, located at /var/log/nginx/error.log

If there are no errors in the NGINX log, you might want to double-check how you configured your API in 3scale. Check out this debugging guide.