Summary

This cookbook should be used as an example of how to automate the process of running multiple instances of Microgateway on a single VM. This doc outlines how to accomplish this with Chef 12.0, Node.js and Nginx.

edgemicro Cookbook

This cookbook starts Apigee Edgemicro 2.1.1 via npm and it will install the following components:

• Nginx
• Node LTS
• Edgemicro

If you enable Nginx from the attributes/default.rb file then it will

• install Nginx which will listen on port 80
• install and enable firewalld and only open ports 22, 80

Requirements

This cookbook was tested on CentOS 7.

You must have an Apigee Edge public account.

You must create an edgemicro aware proxy. Please see the following link which describes how to create the proxy in Edge.

• http://docs.apigee.com/microgateway/latest/edge-microgateway-tutorial

You should also have a target service to which the Apigee edgemicro proxy will send requests.

Platforms

• CentOS 7

Chef

• Chef 12.0 or later

Microgateway

Microgateway is installed via the Node.js package manager, NPM, which is the preferred way to install the Microgateway.

i.e.

npm install -g edgemicro@latest

or

npm install -g edgemicro@2.1.1

Cookbooks

Depends on the following cookbooks when you enable nginx:

• firewalld to enable specific ports
• nginx to proxy requests to Edgemicro

Depends on the following cookbooks whether you enable or disable nginx:

• yum - to update all the yum repositories
• tar - to untar installation files
• zipfile - to unzip the microgateway zip file

Attributes

• node['edgemicro']['user'] = 'vagrant'
• node['edgemicro']['initscript'] = 'init.sh'
• node['edgemicro']['initscript_mode'] = '0777'
• node['edgemicro']['version'] = '2.1.1'
• node['edgemicro']['folder_prefix'] = 'apigee-edge-micro-'
• node['edgemicro']['port'] = 8000
• node['edgemicro']['nginx_upstream_port'] = 8000
• node['edgemicro']['cluster_enabled'] = false
• node['edgemicro']['cluster_processes'] = 2
• node['edgemicro']['processes'] = 2
• node['edgemicro']['node_version'] = 'v4.4.7'
• node['edgemicro']['node_os_version'] = 'linux-x64'
• node['edgemicro']['node_tarball_mode'] = '0777'
• node['edgemicro']['nginx_enabled'] = true
• node['edgemicro']['nginx_conf'] = 'nginx.conf'
• node['edgemicro']['nginx_conf_mode'] = '0777'

Please update the following attributes

• node['edge']['org'] = 'apigee_edge_orgname'
• node['edge']['env'] = 'apigee_edge_environment'
• node['edge']['org_admin'] = 'apigee_edge_org_admin'
• node['edge']['org_admin_password'] = 'apigee_edge_org_admin_password'

Key	Type	Description	Default
['edgemicro']['user']	String	edgemicro user	edgemicro
['edgemicro']['init']	String	inital run script; currently this file is blank.	init.sh
['edgemicro']['initscript_mode']	String	This is sets the mode for the init script when it is copied to the VM.	0777
['edgemicro']['version']	String	This should be the latest version.	2.1.1
['edgemicro']['folder_prefix']	String	The version above is appended to the folder prefix and this is the folder name that is extracted from the zip file downloaded from Apigee.	apigee-edge-micro-
['edgemicro']['port']	Number	Default starting port for Edgemicro. Do not change this port value.	8000
['edgemicro']['nginx_upstream_port']	Number	This is a bit of a hack. For some reason the port attribute above was not being set correctly when the Chef script executed for nginx. So I had to define another starting port for Nginx. This should always be the same as t he port attribute above.	8000
['edgemicro']['cluster_enabled']	Boolean	Microgateway has the ability to run in cluster mode with multiple child processes. This enables cluster mode.	false
['edgemicro']['cluster_processes']	Number	If you enable cluster mode, then this controls how many child processes will be started.	2
['edgemicro']['processes']	Number	You have the ability to run multiple Edgemicro parent processes on the same VM. This attribute controls how many processes will be started. In order to run multiple parent processes on the same VM, then each process must listen on a different port. The starting port is 8000 and it increments that number by 1 for each additional parent process.	2
['edgemicro']['node_version']	String	This is the version of Node that Chef will install. The recommended version for Edgemicro is Node LTS.	v4.4.7
['edgemicro']['node_os_version']	String	OS version on which Node will be installed.	linux-x64
['edgemicro']['node_tarball_mode']	String	This is the mode of the node tar.gz that is downloaded from nodejs.org.	0777
['edgemicro']['nginx_enabled']	Boolean	Enables nginx and firewalld. Only port 80 and 22 will be opened on firewall port. Nginx will listen on port 80 and forward requests to localhost:edgemicro_port.	true
['edgemicro']['nginx_conf']	String	This override the default nginx.conf with our settings.	nginx.conf
['edgemicro']['nginx_conf_mode']	String	This sets the mode of nginx.conf file when it is copied to the VM.	0777
['edgemicro']['org']	String	Apigee Edge organization name.
['edgemicro']['env']	String	Apigee Edge environment name.
['edgemicro']['org_admin']	String	Apigee Edge org admin email address.
['edgemicro']['org_admin_password']	String	Apigee Edge org admin password.

Usage

Make sure to update the following attributes in the attributes/default.rb file.

• node['edge']['org'] = 'apigee_edge_orgname'
• node['edge']['env'] = 'apigee_edge_environment'
• node['edge']['org_admin'] = 'apigee_edge_org_admin'
• node['edge']['org_admin_password'] = 'apigee_edge_org_admin_password'

Enable Nginx and Firewalld

This will enable Nginx and enable Firewalld on the CentOS machine. node['edgemicro']['nginx_enabled'] = true

Change how many parent processes to start

The following attribute will determine how many parent Edgemicro processes to start.

e.g. The processes attribute is set to 2. Therefore, Chef will start 2 Edgemicro processes the first one listening on port 8000 and the second one on listening on port 8001.

• node['edgemicro']['port'] = 8000
• node['edgemicro']['processes'] = 2

If you change the node['edgemicro']['processes'] to 4, then it will start 4 parent processes starting at port 8000 and ending on port 8003. These ports must be available on the VM.

Enable Edgemicro cluster mode

By default Edgemicro cluster is disabled.

• node['edgemicro']['cluster_enabled'] = false

To enable Microgateway cluster mode then change the values as shown below.

• node['edgemicro']['cluster_enabled'] = true
• node['edgemicro']['cluster_processes'] = 2

With the setting above, cluster mode is enabled. The cluster_proceses attribute determines how many child processes each Edgemicro gateway parent process will create.

e.g. If cluster mode is enabled and the cluster_processes attribute is set to 2, then one Edgemicro process will start 2 child processes. Therefore, there will be 3 processes all together (1 parent and 2 children).

Kitchen

cd into the edgemicro directory:

• kitchen list to list all the kitchen recipes.
• kitchen converge default-centos-7 to start edgemicro running in an virtual box machine.
• kitchen destroy to destroy the edgemicro virtual box VM.
• kitchen login to login to the VM.

Make sure you change the IP address

The Kitchen configuration uses Vagrant as the driver and Vagrant only allows bridged networking. Therefore, you must change the IP address to a unique IP in the same network range as the hosts interface IP.

suites:
  - name: default
    driver:
      vm_hostname: edgemicro.com
      network:
      - ["public_network", {ip: "192.168.103.110", bridge: "en0: Wi-Fi (AirPort)"}]
    run_list:
      - recipe[edgemicro]
    attributes:

For example, if you run ifconfig in your terminal on a Mac or ipconfig on Windows, then you should see your IP address.

en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
  ...
  inet 192.168.111.101 netmask ... broadcast 192.168.111.255
	...
	status: active

Copy your IP address and change the last octet to a different value - 192.168.111.102. Paste it into the edgemicro/.kitchen.yaml file.

execute kitchen destroy

then kitchen converge

Error received during start up

If you receive an error similar to the one below. Then it means that Vagrant could not determine which network interface to use to assign your machine a public IP.

==> default: Available bridged network interfaces:
1) en0: Wi-Fi (AirPort)
2) en1: Thunderbolt 1
3) en2: Thunderbolt 2
4) p2p0
5) awdl0
6) bridge0

In this case you need to copy the first item below and paste it in the edgemicro/.kitchen.yaml file. Replace the value next to bridge with the first item from the list displayed on your machine.

suites:
  - name: default
    driver:
      vm_hostname: edgemicro.com
      network:
      - ["public_network", {ip: "192.168.103.110", bridge: "en0: Wi-Fi (AirPort)"}]
    run_list:
      - recipe[edgemicro]
    attributes:

After kitchen up finishes execution

Once Kitchen finished executing you should see a message similar to the one below.

-----> Kitchen is finished. (3m5.22s)

Now you can run the following command to login to the VM and see nginx and edgemicro running.

kitchen login

Grep for edgemicro. You can see the edgemicro instances running on their respective ports.

# ps -ef | grep edgemicro

root     12303     1  1 19:09 ?        00:00:00 node /usr/local/bin/edgemicro start -o org -e env -k key -s secret --port 8000
root     12318     1  1 19:09 ?        00:00:00 node /usr/local/bin/edgemicro start -o org -e env -k key -s secret --port 8001
root     12380 12366  0 19:10 pts/0    00:00:00 grep --color=auto edgemicro

Grep for nginx. You can see Nginx is running.

#ps -ef | grep nginx

root     12232     1  0 19:08 ?        00:00:00 nginx: master process nginx -c /home/vagrant/nginx/nginx.conf
nginx    12233 12232  0 19:08 ?        00:00:00 nginx: worker process
root     12386 12366  0 19:11 pts/0    00:00:00 grep --color=auto nginx

Send request to nginx

Now you can send requests to the nginx server, which will route requests to the edgemicro. We start Nginx listening on port 80 by default.

Get an access token.

curl -i -X POST --user client_id:secret "http://<org>-<env>.apigee.net/edgemicro-auth/token" -d '{"grant_type": "client_credentials"}' -H "Content-Type: application/json"

curl -i -H "Authorization: Bearer bearer_token" http://{ip_of_vm}:80/base_path/pathsuffix

Berksfile

cd into the edgemicro directory.

• berks install to install the dependent cookbooks to your local machine (~/.berkshelf).

edgemicro::default

Just include edgemicro in your node's run_list:

{
  "name":"my_node",
  "run_list": [
    "recipe[edgemicro]"
  ]
}

Contributing

1. Fork the repository on Github
2. Create a named feature branch (like add_component_x)
3. Write your change
4. Write tests for your change (if applicable)
5. Run the tests, ensuring they all pass
6. Submit a Pull Request using Github

License and Authors

Authors: Sean Williams

Apache 2.0