proxying-microgateway-coresident.html.md.erb

---
title: Proxying a PCF App with Apigee Edge Microgateway ("microgateway-coresident" plan)
owner: Partners
---

<strong><%= modified_date %></strong>

This topic describes how to push a sample app to Pivotal Cloud Foundry (PCF), create an Apigee Edge service instance using Apigee Edge Microgateway, and bind the application to it. After binding the application to the Apigee Edge service instance, requests to the app will be forwarded to an Apigee Edge API proxy for management.

> In the process described here, the PCF app and Microgateway are in the same Cloud Foundry container. For a process that has them in separate containers, see [Proxying a PCF App with Apigee Edge Microgateway ("microgateway" plan)](proxying-microgateway.html).

Before performing the procedures in this topic, you must [install and configure](installing.html) the Apigee Edge Service Broker for PCF tile.

## <a id="create-instance"></a>Step 1: Create a Service Instance

Perform the following steps to create an instance of the Apigee Edge service:

1. List the Marketplace services and locate the Apigee Edge service:

    <pre class="terminal">
    $ cf marketplace
    Getting services from marketplace in org example / space development as user<span>@</span>example.com...
    OK

    service          plans                     description
    apigee-edge      org, microgateway, microgateway-coresident         Apigee Edge API Platform
    </pre>

1. Create an instance of the Apigee Edge service. Select the `microgateway-coresident` service plan to have Apigee Edge Microgateway run in the same container as your Cloud Foundry app.

    <pre class="terminal">$ cf create-service apigee-edge microgateway-coresident YOUR-SERVICE-INSTANCE -c \
    '{"org":"YOUR-ORG", "env":"YOUR-ENV"}'</pre>

1. Use the `cf service` command to display information about the service instance:

    <pre class="terminal">
    $ cf service YOUR-SERVICE-INSTANCE

    Service instance: YOUR-SERVICE-INSTANCE
    Service: apigee-edge
    Bound apps:
    Tags:
    Plan: org
    Description: Apigee Edge API Platform
    Documentation url: http://apigee.com/docs/
    Dashboard: https://enterprise.apigee.com/platform/#/

    Last Operation
    Status: create succeeded
    Message:
    Started: 2016-10-27T20:47:43Z
    Updated:
    </pre>

## <a name="install-microgateway"></a>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.

1. [Install and configure Apigee Edge Microgateway.](http://docs.apigee.com/microgateway/latest/installing-edge-microgateway)

1. Locate and make any desired changes to the configuration YAML file created in your Apigee Edge Microgateway installation, typically in the `.edgemicro` directory.

1. Copy the configuration file to the following directory in your Cloud Foundry app: `<application-folder>/<config-directory>`.

1. Complete plugin configuration in one of two ways:
    - Configure the plugins via the app manifest to include the APIGEE_MICROGATEWAY_CUSTOM environment variable. For example:
    
        ```
        env:
        ...
        APIGEE_MICROGATEWAY_CUSTOM: |
        {
            "policies":
            {
                "oauth":
                {
                    "allowNoAuthorization": false, 
                    "allowInvalidAuthorization": false,
                    "verify_api_key_url": "https://myorg-test.apigee.net/edgemicro-auth/verifyApiKey"
                },
                "spikearrest": 
                {
                    "timeUnit": "minute", 
                    "allow": 10
                }
            },
            "sequence": ["oauth", "spikearrest", "response-override"]
        }
        ```
        - “sequence” corresponds to the sequence order in the microgateway .yaml file (this will be added on to the end of any current sequence in the microgateway .yaml file with duplicates removed). 
        - “policies” correspond to any specific configuration needed by a plugin; for instance, “oauth” has the `"allowNoAuthorization": true` configuration. These policies will overwrite any existing policies in the microgateway .yaml file and add any that do not yet exist.     
    - Configure the microgateway .yaml file from step 2 to include the necessary plugins. For example if we added a “spikearrest” plugin:

        ```yaml
        ...
        plugins:
            dir: ../plugins
            sequence:
              - oauth
              - spikearrest
        spikearrest:
          timeUnit: minute
          allow: 10
        oauth:
          allowNoAuthorization: false
          allowInvalidAuthorization: false    
        ```

1. Copy any custom plugins’ root folders (with custom plugin specific package.json and index.js in the respective root folder) into the following directory in your Cloud Foundry app: <application-folder>/<plugin-directory>. 
1. Edit the application manifest as follows:

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

        ```yaml
        env: 
          APIGEE_MICROGATEWAY_CONFIG_DIR: '/app/<config-directory>'
          APIGEE_MICROGATEWAY_ENV: 'your-microgateway-env-name'
          APIGEE_MICROGATEWAY_ORG: 'your-microgateway-org-name'
        ```
    1. Remove the following or any other `buildpack` tags from the manifest:
      
        ```yaml
        buildpack: nodejs_buildpack
        ```

    1. If you have custom buildpacks, add the following line to the `env` section:

        ```yaml
        env: 
        ...
        APIGEE_MICROGATEWAY_CUST_PLUGINS: '<plugin-directory>'
        ```

1. Ensure that your Cloud Foundry app isn't running on port 8080, nor on the port specified by the PORT environment variable.

1. Push the Cloud Foundry app to your Cloud Foundry container.

    <pre class="terminal">
    cf push &lt;cf-app-name> --no-start</pre>

## <a id="bind-app-route"></a>Step 3: Bind the Cloud Foundry app to the Service Instance

In this step, you bind a Cloud Foundry app to the Apigee service instance you created. The `bind-service` command creates the proxy for you and binds the app to the service. By using `bind-service`, certain information (such as Edge Microgateway key and secret and chosen plan ID) will be shared with the target application. In addition, since `bind-route-service` is not being used, traffic won’t be routed anywhere but the target application container.

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

1. Get an auth token to use when binding your app to the Apigee service instance.
    1. Download the Apigee Edge scripts:

        <pre class="terminal">$ curl https://login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"</pre> 
    1. Unzip the `ssocli-bundle.zip` file. This includes `get_token`, a script that gets or updates a token that you use to authenticate with your Apigee Edge organization. You need this token to bind the Apigee Edge route service to your 
        <pre class="terminal">$ tar xvf ssocli-bundle.zip</pre>
    1. Create a `.sso-cli` directory in your user directory:
    <pre class="terminal">$ mkdir ~/.sso-cli</pre>
    1. Use the `get_token` script to create a token. When prompted, enter the Apigee Edge username and password you use to log in to your organization.
    <pre class="terminal">$ ./get\_token</pre>  
    The `get_token` script writes the token file into `~/.sso-cli`. For more about `get_token`, see the [Apigee documentation](http://docs.apigee.com/api-services/content/using-oauth2-security-apigee-edge-management-api).
1. Get the URL of the app 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`.

    <pre class="terminal">cf routes</pre>

1. Use the `bind-service` command to create an Apigee Edge API proxy and bind your Cloud Foundry app to the proxy. (See the reference on this page for more about this command.)
    <pre class="terminal">
    cf bind-service APP-NAME APIGEE-SERVICE \
    -c '{"org":MICROGATEWAY-ORG,"env":MICROGATEWAY-ENV,
      "bearer":"'$(cat ~/.sso-cli/valid_token.dat)'", 
      "action":"proxy bind", 
      "protocol":"https", 
      "target_route":CF-ROUTE-URL, 
      "edgemicro_key":MICROGATEWAY-KEY, 
      "edgemicro_secret":MICROGATEWAY-SECRET, 
      "target_port":CF-APP-PORT}'
    </pre>
    * For APIGEE-SERVICE, use the name of the Apigee Edge service instance you created earlier
    * For APP-NAME, use the name of the host you specified in your manifest.yml

    The output from `bind-service` should confirm that you have bound the service to your Apigee Microgateway service instance.
 
1. Start the Cloud Foundry app and microgateway-decorator along with it.

    <pre class="terminal">$ cf start APP-NAME</pre>
    
1. Log into Edge and note that the proxy has been created. Then follow [the instructions](http://docs.apigee.com/microgateway/latest/setting-and-configuring-edge-microgateway#Part2) to create a product with your newly created proxy. You can now configure standard Apigee Edge policies on that proxy.

### bind-service reference
When binding to an Apigee API proxy, the `bind-route-service` command follows this form (be sure to use quotes and command expansion, as shown here):
    
<pre class="terminal">
$ cf bind-service APP-NAME SERVICE-INSTANCE \
    cf start APP-NAME
    -c '{"org":MICROGATEWAY-ORG,"env":MICROGATEWAY-ENV,
      "bearer":"'$(cat ~/.sso-cli/valid_token.dat)'", 
      "action":"proxy bind", 
      "protocol":"https", 
      "target_route":CF-ROUTE-URL, 
      "edgemicro_key":MICROGATEWAY-KEY, 
      "edgemicro_secret":MICROGATEWAY-SECRET, 
      "target_port":CF-APP-PORT}'
</pre>

Parameters for the `-c` argument specify connection details:

Parameter | Purpose | Allowed Values
---- | ---- | ----
`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.
`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:<ul><li>`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)</li><li>username and password in clear text</li></ul>
`edgemicro_key` | The key for your Apigee Edge Microgateway configuration (returned when you configured the Apigee Microgateway). | The configuration key.
`edgemicro_secret` | The secret for your Apigee Edge Microgateway configuration (returned when you configured the Apigee Microgateway). | The configuration secret.
`env` | Apigee Edge environment to which the API proxy is (or will be) deployed | Your environment.
`org` | Apigee Edge organization hosting the API proxy to be called |  Your organization (must be reachable via the authentication token specified in he `bearer` parameter).
`protocol` | The protocol through which the proxy's target endpoint should be accessed by Cloud Foundry. | `http` or `https`; default is `https`.
`target_app_port` | Port for your Cloud Foundry app. This may not be 8080 nor the PORT environment variable. | The port number.
`target_app_route` | The URL for your Cloud Foundry app. | The app URL.


## <a id="test-binding"></a>Step 5: Test the Binding

Once you’ve bound your app’s path to the Apigee service (creating an Apigee proxy in the process), you can try it out with the sample app.

- From a command line run the curl command you ran earlier to make a request to your Cloud Foundry app you pushed, such as:

    <pre class="terminal">
    $ curl https://sample-api-apigee.cfapps.pivotal.io 
        {“hello”:“hello from cf app”}</pre>

    The console outputs the app’s response.

The new proxy is just a pass-through, but it is now ready for you or someone on your team to add policies to define security, traffic management, and more.