proxying-microgateway.html.md.erb

---
title: Proxying a VMware Tanzu App with Apigee Edge Microgateway ("microgateway" Plan)
owner: Partners
---

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

This topic describes how to push a sample app to VMware Tanzu, 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 VMware Tanzu app and Microgateway are in separate Cloud Foundry containers. For a process that has them in the same container, see [Proxying a VMware Tanzu App with Apigee Edge Microgateway ("microgateway-coresident" plan)](proxying-microgateway-coresident.html).

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


## <a id="push-sample"></a> Step 1: Push the Sample App

To push a sample application to VMware Tanzu, do the following: 

1. Clone the Apigee Edge GitHub repo:

    ```bash
    $ git clone <span>https:</span>//github.com/apigee/cloud-foundry-apigee.git
    ```

1. Change to the `org-and-microgateway-sample` directory of the cloned repo:
    
    ```bash
    $ cd cloud-foundry-apigee/samples/org-and-microgateway-sample
    ```

1. In the `org-and-microgateway-sample` directory, open `manifest.yml`.

1. Edit `manifest.yml` to change the `name` and `host` properties to values specific to your deployment. See the following example:

    ```yaml
    applications: 
    - name: sample-api 
      memory: 128M 
      instances: 1 
      host: sample-api-apigee 
      path: . 
      buildpack: nodejs_buildpack
    ```
    
1. Save the edited file.

1. Set your API endpoint to the Cloud Controller of your deployment.

    ```bash
    $ cf api api.YOUR-SYSTEM-DOMAIN
    Setting api endpoint to api.YOUR-SYSTEM-DOMAIN...
    OK
    API endpoint:  <span>https:</span>//api.YOUR-SYSTEM-DOMAIN (API version: 2.59.0)
    Not logged in. Use 'cf login' to log in.
    ```

1. Log in to your deployment and select an org and a space.

    ```bash
    $ cf login
    API endpoint: <span>https:</span>//api.YOUR-SYSTEM-DOMAIN
    Email> user<span>@</span>example.com
    Password>
    ```

1. Push the sample app to VMware Tanzu:
    
    ```bash
    $ cf push YOUR-SAMPLE-APP
    ```

1. Use `curl` to send a test request to the app you pushed:
    
    ```bash
    $ curl YOUR-SAMPLE-APP.YOUR-SYSTEM-DOMAIN
    {"hello":"hello from cf app"} 
    ```
    
    If you receive the above response, the sample app is running successfully.


## <a id="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. Clone the Apigee Microgateway repository.
    
    ```bash
    $ git clone https://github.com/apigee-internal/microgateway.git
    cd microgateway
    git checkout tags/v.2.5.4
    ```

1. Copy the configuration file to the following directory in your Cloud Foundry app: `<application-folder>/<config-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: 
          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'
        ```

1. Push Apigee Microgateway as its own app.

    ```bash
    $ cf push
    ```


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

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.

1. Get or update the authorization token using the Apigee SSO CLI script.
  1. Download the Apigee Edge scripts:
      ```bash
      $ curl https://login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"
      ```
  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 app.
      ```bash
      $ tar xvf ssocli-bundle.zip
      ```
  1. Create a `.sso-cli` directory in your user directory:
      ```bash
      $ mkdir ~/.sso-cli
      ```
  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.
      ```bash
      $ ./get\_token
      ```
    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. 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`](#bind-route-service-reference) 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:
    ```bash
    $ 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"
    ```bash
    $ 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](http://docs.apigee.com/microgateway/latest/setting-and-configuring-edge-microgateway#Part2) to create a product with your newly created proxy.


## <a id='bind-route-service-ref'></a> 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):

```bash
$ 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":"<microgateway_app_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:<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> |
| `micro` | Required. Route of the application acting as Edge Microgateway. | Required. |
| `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`. |


## <a id='unbinding-route-service'></a> Unbinding the Route Service

The unbind command does not accept any parameters

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


## <a id='uninstalling-instance-broker'></a> Uninstalling the Service Instance and Broker

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


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

Once you have 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.