Setting Up Microgateway and a Cloud Foundry App in Separate Containers ("microgateway" plan)

Using code in this directory, you can install an Apigee service broker that manages connections between your Cloud Foundry app and Apigee Microgateway running in a separate Cloud Foundry container.

This section describes how to set up Apigee Edge Microgateway and your Cloud Foundry app in separate containers. To set them up in a single container, be sure to see Setting Up Microgateway and a Cloud Foundry App in a Single Container.

Use the following sections to install the Apigee service broker on Cloud Foundry, then set up a binding between a Cloud Foundry app and the Apigee service.

Ensure you have the prerequisites.
Install the service broker to make it available in the marketplace (CF administrator/operator).
Create an instance of the service broker for your Cloud Foundry org/space (CF user).
Bind or unbind a route service to an app route as needed (CF user).

Step 1: Install the Apigee service broker from source

If you're a Cloud Foundry administrator, you can install a service broker as an application (in other words, a broker app). This is particularly useful when running a Cloud Foundry development environment.

For Pivotal Cloud Foundry users, this broker is also packaged as a tile for easy installation by an Operator. See the Apigee docs for more on installing and configuring the tile.

These instructions assume a local PCF Dev environment, at the domain local.pcfdev.io. If you're using another kind of Cloud Foundry host, be sure to adjust URLs accordingly.

From a command prompt, log in to the Cloud Foundry instance where you'll be installing the Apigee service broker.
```
$ cf login -a <your.endpoint> -u <username> -o <organization> -s <space>
```

Clone this github project to get the service broker source you'll need.

$ cd <your working directory>
$ git clone https://github.com/apigee/cloud-foundry-apigee.git
$ cd cloud-foundry-apigee/apigee-cf-service-broker

Load dependencies and test (requires that Node.js is installed).
```
$ npm install
$ npm test
```

In the apigee-cf-service-broker directory, edit the manifest.yml file to set required variables (org and env) and override defaults as appropriate for your environment and Apigee Edge account.

Item	Purpose	Default (for SaaS Edge)
APIGEE_DASHBOARD_URL	URL for Apigee Edge management UI	`https://enterprise.apigee.com/platform/#/`
APIGEE_MGMT_API_URL	Apigee Edge Management API endpoint	`https://api.enterprise.apigee.com/v1`
APIGEE_PROXY_DOMAIN	Domain for proxy host template	`apigee.net`
APIGEE_PROXY_HOST_TEMPLATE	ES6 template literal for generated proxy host. The template that describes how the Apigee Edge host name should be generated. This represents the hostname that clients use to make calls to your APIs. Change this value if your hostname is not created in the default way -- from your Apigee org an environment names. For example, if your APIs use a custom virtual host, you might have just a domain name: `${domain}` Pivotal Cloud Foundry apps use this host when making calls to your API proxy. The template generates the host name from values specified when binding the PCF app to the service(Note that without any placeholders, will be used as-is.)	`${org}-${env}.${domain}`
APIGEE_PROXY_NAME_TEMPLATE	ES6 template literal for generated proxy	`cf-${route}`
ORG	The Apigee Edge organization with proxies that will handle calls to your app.
ENV	The Apigee Edge environment that with proxies that will handle calls to your app.

If you've got an HTTP(S) proxy server, you can also specify the server's URL, as shown in the example here.

Note: Cloud Foundry does not allow ${...} syntax to be present in the environment variable section. So when changing APIGEE_PROXY_HOST_TEMPLATE or APIGEE_PROXY_NAME_TEMPLATE, be sure to not use ${...} in your changes.

  env:
    APIGEE_CONFIGURATIONS: |
                        [{“org”:”your-apigee-org1”,
                        “env”:”your-apigee-env1”,
                        “apigee_proxy_domain”:”apigee.net”,...},
                        <repeat the preceding for multiple orgs and envs>]
    HTTP_PROXY:”your HTTP proxy server URL”
    HTTPS_PROXY:”your HTTPS proxy server URL”

Deploy the Apigee service broker from the source in this repository.
```
$ cf push
```
Make a note of the broker app's URL, which you'll use to create the service broker later. Here's an example:
```
urls: apigee-cf-service-broker.local.pcfdev.io
```
Choose a user name and password and store them as environment variables for the broker app. Then restage the broker app to load those variables.

Communication with the broker is protected with a user name and password (to prevent unauthorized access to the broker app from other sources). These credentials are specified when the broker is created, and then used for each call. However, validating those credentials is the responsibility of the broker app, which does not have those credentials provided by the runtime.
```
$ cf set-env apigee-cf-service-broker SECURITY_USER_NAME <pick a username>
$ cf set-env apigee-cf-service-broker SECURITY_USER_PASSWORD <pick a password>
$ cf restage apigee-cf-service-broker
```

Use the credentials you just established, along with the URL for the broker app, to create the service broker in Cloud Foundry.

$ cf create-service-broker apigee-edge <security-user-name> <security-user-password> https://apigee-cf-service-broker.local.pcfdev.io

Publish the service broker in your Cloud Foundry marketplace.

$ cf enable-service-access apigee-edge
$ cf marketplace
$ cf marketplace -s apigee-edge

Create an instance of the “microgateway” service:

$ cf create-service apigee-edge microgateway <service-name> -c \
    '{"org":<org from service-broker configuration>, "env":<env from service-broker configuration>}'

Note: Once you have the service broker installed, you might be interested in using the sample app included in this repository to try it out. To do this, you'd replace the following steps with those in this tutorial.

Step 2: Install Apigee Edge Microgateway and Cloud Foundry app

Here, you install Apigee Edge Microgateway and your Cloud Foundry app to the same Cloud Foundry container.

Install and configure Apigee Edge Microgateway.

Clone the Apigee Microgateway Repo:

$ git clone https://github.com/apigee-internal/microgateway.git
$ cd microgateway
$ git checkout tags/v.2.5.4

Copy the configuration file to the following directory in your Cloud Foundry app: <microgateway-repo-directory>/<config-directory>.

Edit the configuration file (e.g {org}-{env}-config.yaml) to have the cloud-foundry-route-service plugin. For instance:

edgemicro:
    port: 8000
    max_connections: 1000
    ...
    plugins:
        sequence:
        - oauth
        - cloud-foundry-route-service

Edit the microgateway manifest.yml as follows:

Edit the following env values so that they correspond to your Apigee Edge Microgateway configuration:

env:
  EDGEMICRO_KEY: 'microgateway-key'
  EDGEMICRO_SECRET: 'microgateway-secret'
  EDGEMICRO_CONFIG_DIR: '/app/<config-directory>'
  EDGEMICRO_ENV: 'your-microgateway-env-name'
  EDGEMICRO_ORG: 'your-microgateway-org-name'

Push Apigee Microgateway as its own app:
```
$ cf push
```
Change to your application's directory and push your app:
```
$ cd <app-directory>
$ cf push
```

Step 3: Bind the Cloud Foundry app's route to the Apigee service

In this step, you bind a Cloud Foundry app's route (its address in Cloud Foundry) to the Apigee service instance you created. That way, requests to the app will be forwarded first to an Apigee Edge Microgateway proxy. The bind-route-service command creates the proxy for you and binds the route to it.

Each bind attempt requires authorization with Apigee Edge, with credentials passed as additional parameters to the cf bind command.

First, get the URL of the app/route to bind. cf routes lists the host and domain separately; cf apps combines them into a FQDN, listed under "urls". For example, if the app's hostname is test-app, then the resulting FQDN is test-app.local.pcfdev.io.
```
$ cf routes
```
Get or update the authorization token using the Apigee SSO CLI script.
```
$ get_token
```
You may be prompted for your Apigee Edge username and password, and an MFA token. This updates the token in the ~/.sso-cli/valid_token.dat file (if that subdirectory exists -- otherwise the file is placed in the current working directory). The next step uses this token.
Bind the app's route to the Apigee service instance with the domain and hostname.

The proxy must be created as a separate step, and then loaded by Microgateway instances before binding. You can create the proxy manually, but to have the broker do it, specify "action":"proxy". Also specify the Microgateway's FQDN as micro.

In this example, Apigee Edge Microgateway is also installed as an app with the hostname edgemicro-app:

Use the bind-route-service command. The following example creates an API proxy on the myorg org and test environment. The protocol parameter specifies the protocol through which the proxy will be called. To do its works, this command authenticates with Apigee Edge using the token in the specified .dat file:
```
$ cf bind-route-service local.pcfdev.io myapigee --hostname test-app \
-c '{"org":"myorg","env":"test",
   "bearer":"'$(cat ~/.sso-cli/valid_token.dat)'",
   "micro":"edgemicro-app.local.pcfdev.io",
   "action":"proxy",
   "protocol":"http"}'
```
Cloud Foundry will report an error during the binding, since the bind was not attempted. But the message returned should indicate that the proxy was created, which you can check with the Edge management UI or API. The proxies created by the bind for Microgateway have an additional edgemicro_ at the beginning of their name, a general requirement unrelated to Cloud Foundry and service brokers.

Wait for the configuration to reload on the Edge Microgateway instance(s) before binding. You might have to wait 5 to 10 minutes. When it has reloaded, the console will list the proxy you just created.

To bind, make the same call with "action":"bind"
```
$ cf bind-route-service local.pcfdev.io myapigee --hostname test-app \
-c '{"org":"<your edge org>","env":"<your edge env>",
   "bearer":"'$(cat ~/.sso-cli/valid_token.dat)'",
   "micro":"edgemicro-app.local.pcfdev.io",
   "action":"bind"}'
```
The proxies created by the bind for Microgateway have an additional edgemicro_ at the beginning of their name, a general requirement unrelated to Cloud Foundry and service brokers. Another general requirement is that the proxy is part of a published API Product; a change you must make manually by following the instructions here to create a product with your newly created proxy.

bind-route-service reference

Use the bind-route-service command to generate an API proxy on Apigee Edge and to bind the Apigee Cloud Foundry service to the proxy. The command this form (be sure to use quotes and command expansion, as shown here):

$ cf bind-route-service <your-app-domain> <service-instance> [--hostname <hostname>] \
-c '{"org":"<your edge org>","env":"<your edge env>",
  "bearer":"<authentication-token-file>" | "basic":"<encoded-username-password>" | "<username>:<password>",
  "micro":"<application-route>"
  "action":"proxy"|"bind"|"proxy bind",
  ["protocol":"http"|"https"]}'

Parameters for the -c argument specify connection details:

Parameter	Purpose	Allowed Values
`org`	Apigee Edge organization hosting the API proxy to be called	Your organization (must be reachable via the authentication token specified in the `bearer` parameter)
`env`	Apigee Edge environment to which the API proxy is (or will be) deployed	Your environment.
`bearer`	Path to a file containing an authentication token valid for your organization	An authentication token, such as one generated with Apigee's get_token command. The broker does not store any data; it requires credentials and other parameters for each individual `cf` command. Instead of a `bearer` token, credentials can also be expressed as: `basic`: standard HTTP Base-64 encoded username and password for `Authorization: Basic`. Note that this is not encrypted and easily converted to clear text. But a jumble of digits and letters may provide some protection in case of momentary exposure (but no better than if the password is already a jumble of digits, letters, and symbols) username and password in clear text
`micro`	Required. Route of the application acting as Edge Microgateway.	Application route.
`action`	A value specifying whether to create or bind an API proxy	`proxy` to generate an API proxy; `bind` to bind the service with the proxy; `proxy bind` to generate the proxy and bind with a single command.
`protocol`	The protocol through which the proxy should be accessed by Cloud Foundry	`http` or `https`; default is `https`.

Unbinding the route service

The unbind command does not accept any parameters

$ cf unbind-route-service <your-app-domain> <service-instance> --hostname <cf-app>

Uninstalling the service instance and broker

$ cf delete-service <service-instance>
$ cf delete-service-broker apigee-edge

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

setup-microgateway.md

setup-microgateway.md

Setting Up Microgateway and a Cloud Foundry App in Separate Containers ("microgateway" plan)

Step 1: Install the Apigee service broker from source

Step 2: Install Apigee Edge Microgateway and Cloud Foundry app

Step 3: Bind the Cloud Foundry app's route to the Apigee service

bind-route-service reference

Unbinding the route service

Uninstalling the service instance and broker

Files

setup-microgateway.md

Latest commit

History

setup-microgateway.md

File metadata and controls

Setting Up Microgateway and a Cloud Foundry App in Separate Containers ("microgateway" plan)

Step 1: Install the Apigee service broker from source

Step 2: Install Apigee Edge Microgateway and Cloud Foundry app

Step 3: Bind the Cloud Foundry app's route to the Apigee service

bind-route-service reference

Unbinding the route service

Uninstalling the service instance and broker