The easiest and most powerful way to integrate your API with 3scale is using our NGINX-based API gateway. To make it even easier, we provide the gateway available as an AMI in the AWS Marketplace.
The AMI contains:
- A pre-installed OpenResty bundle, including NGINX and complementary modules such as the Lua scripting support.
- A helper command line tool to get the NGINX configuration generated by 3scale for your API.
- Note that the AMI is using APIcast 1.0 (3scale NGINX based API gateway), which is not the latest version.
- You will need an AWS account.
- You should have configured your API details in 3scale beforehand to be able to automatically generate your NGINX configuration. In case you’re not sure how to do this, read this tutorial.
Step 1: Launch your own gateway instance using the AMI
- Go to the 3scale AMI page in the AWS Marketplace
- You have two options to launch the AMI: 1-click launch or manual launch through the EC2 console. Pick the 1-click launch since it’s the simplest way.
- Using the 1-click launch option, these are the settings where you will need to make a choice (go with the defaults for all the others unless you have good reasons to change them):
- AWS region
- EC2 instance type
- Key pair (very important – pick a key pair for which you have the corresponding private key available on your computer, otherwise you won't be able to access the instance)
- Click the Launch with 1-Click button.
- Your instance of the AMI is now being started. It will be ready in about 2 minutes.
- Head over to your AWS Management Console and go into the Running Instances list on the EC2 section.
- Check that your instance is ready to be accessed. This is indicated by a green check mark icon in the column named Status Checks.
- Click on the instance row. Find its public DNS in the lower part of the screen and copy it.
- Log in through SSH using the ubuntu user and the private key you chose before. The command will look more or less like:
ssh -i privateKey.pem email@example.com
- Once you log in, read the instructions that will be printed to the screen: all the necessary commands to manage your gateway are described there. In case you want to read them later, these instructions are located in a file named 3SCALE_README in the home directory.
Step 2: Download your configuration from 3scale
The fastest way to get your NGINX configuration files from 3scale is by using the command line tool included in the AMI. Just run the following command:
You will be prompted to enter the following parameters:
- Your 3scale admin domain (for example mycompany-admin.3scale.net)
- Your provider API key, which can be found in the Account section of your Admin Portal.
- The directory where you want the files to be downloaded – if you simply click Enter they will be downloaded to /home/ubuntu/3scale-nginx-conf
The tool will save your credentials locally so that if you make changes to your configuration (for example when you add a new endpoint mapping), you can just run the command without entering them again.
In case you need or want to be prompted for your credentials again, you can run the command with the reset option:
Once you have downloaded the files, there are a couple of changes that you must do to the file that has the .conf extension before you're ready to start NGINX. You can find detailed information on the required changes in the APIcast self-managed tutorial.
Step 3: Start NGINX
You can now start running the API gateway with your own configuration! Assuming you downloaded it to the default location, the files will now be in the directory
/home/ubuntu/3scale-nginx-conf/. You should move or copy them to the NGINX configuration directory, which in this case is
Then you will need to run the following command to start NGINX:
sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf
You will find other useful commands to operate NGINX in the 3SCALE_README document.
To stop the NGINX:
sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf -s stop
To reload it (useful after you have made changes to the configuration):
sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf -s reload
In case you experience any issues, please let us know at firstname.lastname@example.org.
Step 4: Optimizing the workflow
Creating and testing new versions of your NGINX configuration in a remote server can be quite cumbersome. In the APIcast self-managed tutorial you'll find tips to make the process easier, including how to add NGINX as a system service and some advice on managing multiple versions of your configuration files.
Most errors in the gateway configuration can be detected and solved by looking at the NGINX logs:
- Access log:
- Error log: