cookbook 'chef-3scale', '= 0.1.1'
The chef-3scale cookbook has been deprecated
Author provided reason for deprecation:
The chef-3scale cookbook has been deprecated and is no longer being maintained by its authors. Use of the chef-3scale cookbook is no longer recommended.
chef-3scale (8) Versions 0.1.1 Follow1
Install and configures the 3scale API gateway
cookbook 'chef-3scale', '= 0.1.1', :supermarket
knife supermarket install chef-3scale
knife supermarket download chef-3scale
3scale API gateway cookbook
This cookbook installs the 3scale API gateway. 3scale is an API management platform that makes it easy to open, distribute, control, and monetize your API. The API gateway is the simplest and most performant way to integrate your API with the 3scale platform.
Running the cookbook will install Openresty, which the 3scale API gateway is based upon, plus all the required system dependencies.
The cookbook not only installs the API gateway but it will also deploy your 3scale Nginx configuration files, specifically tailored for your API configuration. The result of running this cookbook will be an up-and-running API gateway listening for incoming authenticated requests.
Attributes
There are 4 attributes that you will need to set to configure how you use the cookbook. All of them are under the 3scale
namespace:
Attribute | Description | Default |
---|---|---|
['3scale']['config-source'] |
Where your Nginx configuration files will be taken from. Two options: "local" or "3scale". More on this the section “Applying your own 3scale configuration”. | 'local' |
['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. | 'REPLACE_WITH_3SCALE_PROVIDER_KEY' |
['3scale']['admin-domain'] |
If your 3scale admin portal domain is "mycompany-admin.3scale.net", then the value of this attribute should be "mycompany". | 'REPLACE_WITH_3SCALE_ADMIN_URL_PART' |
['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 like in the following example: "2015-09-15-041532". See the "Rollback process" section for more information on this. | nil |
The default value for each of those attributes is defined here.
This cookbook uses and depends on the Openresty cookbook. Therefore attributes of that cookbook are also available to you. You can see a full list here.
Since you will be using the Nginx configuration files that 3scale generates for you, you will not be able to use the attributes of the Openresty cookbook that are related to configuration parameters that go in the nginx.conf file.
Usage
Include chef-3scale
in your node's run_list
:
{ "run_list": [ "recipe[chef-3scale::default]" ] }
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
configure your API in 3scale using the “On-premise Gateway” option
click on “Download the Nginx Config files” at the bottom of the screen
drop those files on the /files/default/config/
directory of the cookbook
To use this option you will 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.
To use this option you will 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 the /var/chef/cache/
and symlinked to the Nginx working directory (/etc/nginx/
).
Rollback process
The chef-3scale cookbook allows rolling back to a previously deployed version of the configuration. This is useful if 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 using the latest version.
The built-in way to roll back is by using the ['3scale']['config-version']
attribute. Here is an example of a full node description using the rollback attribute:
{ "3scale": { "provider-key": "YOURPROVIDERKEY", "admin-domain": "mycompany", "config-version": "2015-09-15-050545" }, "openresty": { "source": { "prefix": "/etc" } }, "run_list": [ "recipe[chef-3scale::default]" ] }
The value of the attribute must be the timestamp generated by the cookbook when running a deployment. This attribute is always logged and printed to the screen while running the cookbook:
3SCALE - deploying gateway with LATEST configuration version: 2015-09-15-050545
When a gateway has been deployed using one of the previous versions of the configuration, the logged message will be slightly different:
3SCALE - rolling back to configuration version: 2015-09-15-050545
The rollback process will symlink the configuration files located at:
/var/chef/cache//*
to the Nginx configuration directory and then reload the gateway.
Troubleshooting
If you are having problems deploying your API gateway when running the cookbook, then the best first step is to look at Chef’s own logs. Here you can find some useful debugging tips: https://docs.chef.io/debug.html
If the deployment completed successfully but the issue is that the API gateway is not running as expected, then the problem most probably is 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 have configured your API in 3scale. There are plenty of resources available on our support portal, such as this debugging guide.
Supported platforms
This cookbook has been tested on the following platforms:
- Ubuntu
- CentOS
License and Authors
Author:: Victor Delgado (victor@3scale.net)
The MIT License (MIT) Copyright (c) 2015 3scale Inc. (https://3scale.net) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Dependent cookbooks
openresty >= 0.0.0 |
Contingent cookbooks
There are no cookbooks that are contingent upon this one.
0.1.0
Initial release of chef-3scale
Foodcritic Metric
0.1.1 passed this metric
0.1.1 passed this metric