proxying-org.html.md.erb

---
title: Proxying a Pivotal Platform App with Apigee Edge ("org" plan)
owner: Partners
---

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

This topic describes how to push a sample app to Pivotal Platform, create an Apigee Edge service instance, 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.

Before performing the procedures in this topic, you must install and configure the Apigee Edge Service Broker for Pivotal Platform tile.


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

To push a sample application to Pivotal Platform, do the following:

1. Clone the Apigee Edge GitHub repo:
    ```bash
    $ git clone https://github.com/apigee/cloud-foundry-apigee.git
    ```

1. Change into the `sample-api` directory of the cloned repo:
    ```bash
    $ cd cloud-foundry-apigee/samples/org-and-microgateway-sample</pre>
    ```

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:  https://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: https://api.YOUR-SYSTEM-DOMAIN
  Email> user@example.com
  Password>
  ```

1. Push the sample app to Pivotal Platform:
    ```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="create-instance"></a> Step 2: 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:
    ```bash
    $ cf marketplace
    Getting services from marketplace in org example / space development as user@example.com...
    OK

    service          plans                                              description
    apigee-edge      org, microgateway, microgateway-coresident         Apigee Edge API Platform
    ```

1. Create an instance of the Apigee Edge service. Select either the `org` service plan.
    ```bash
    $ cf create-service apigee-edge org YOUR-SERVICE-INSTANCE -c \
    '{"org":"YOUR-ORG", "env":"YOUR-ENV"}'
    cf service YOUR-SERVICE-INSTANCE
    ```

1. Use the `cf service` command to display information about the service instance:
    ```bash
    $ cf service apigee-service

    Service instance: apigee-service
    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:
    ```


## <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 Edge proxy. The `bind-route-service` command creates the proxy for you and binds the route to it.

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

1. Get or update the 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](https://docs.apigee.com/api-platform/system-administration/using-oauth2).
        > 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).

1. Bind the app's route to the Apigee service instance with the domain and hostname.
    Use the [`bind-route-service`](#bind-route-service-reference) command. The following example does two things: it creates an API proxy on the `myorg` org and `test` environment, then binds the Apigee route service to the proxy. 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)'",
      "action":"proxy bind",
      "protocol":"https"}'
    ```

1. Log into Edge and note that the proxy has been created, and that requests to your app are being routed through Edge.
    You will find a proxy whose name matches the pattern specified by the APIGEE_PROXY_NAME_TEMPLATE variable you specified with your org and env mapping in the manifest. The proxy has been deployed to the environment you specified when you created your service instance.
    In the Edge management console, begin tracing the proxy, then send requests to your app. Trace will show the traffic routing through the proxy.
    You can now configure standard Apigee Edge policies on that 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>",
  "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> |
| `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`. |
| `host` | The host domain to which API calls are made. Specify a value only if your host domain is not the same as that given by your virtual host. | Your host domain name if different from your virtual host domain. For example: mycompany.net:9000 |


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

The `unbind-route-service` command does not accept any parameters.

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


## <a id='uninstalling-service-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'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 you invoked earlier.

1. Open the Apigee Edge management console.

1. In the management console, under **APIs > API proxies**, locate the name of the proxy you just created with `bind-route-service`. It's likely to have a name that ends with your domain value, such as `cfapps.pivotal.io`.

1. Click the new proxy's name to view its **Overview** page.

1. Click the **Trace** tab, then click the **Start Trace Session** button.

1. Back at the command line, run the `curl` command you ran earlier to make a request to your Cloud Foundry app you pushed, such as:
  ```bash
  $ curl https://sample-api-apigee.cfapps.pivotal.io
  {"hello":"hello from cf app"}
  ```
  As before, the console outputs the app's response.

1. Return to the Apigee Edge management console to see that your request has now been routed through the Edge proxy you created.

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.