Proxying a PCF App with Apigee Edge Microgateway ("microgateway" plan)

Page last updated:

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 separate Cloud Foundry containers. For a process that has them in the same container, see Proxying a PCF App with Apigee Edge Microgateway (“microgateway-coresident” plan).

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

Steps in these instructions use CF CLI with an Apigee plugin. To see corresponding CF CLI commands, see Mapping for Apigee and Cloud Foundry integration commands.

Step 1: Push the Sample App

Perform the following steps to push a sample application to PCF.

  1. Clone the Apigee Edge GitHub repo:

    $ git clone https://github.com/apigee/cloud-foundry-apigee.git

  2. Change to the org-and-microgateway-sample directory of the cloned repo:

    $ cd cloud-foundry-apigee/samples/org-and-microgateway-sample

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

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

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

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

    $ 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.
    

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

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

  8. Push the sample app to PCF:

    $ cf push YOUR-SAMPLE-APP

  9. Use curl to send a test request to the app you pushed:

    $ curl YOUR-SAMPLE-APP.YOUR-SYSTEM-DOMAIN
    {"hello":"hello from cf app"} 
    
    If you receive the above response, the sample app is running successfully.

Step 2: Install the Plugin

  1. Install the Apigee Broker Plugin as follows.

    $ cf install-plugin -r CF-Community "apigee-broker-plugin"
    Searching CF-Community for plugin apigee-broker-plugin... Plugin apigee-broker-plugin 0.1.1 found in: CF-Community Attention: Plugins are binaries written by potentially untrusted authors. Install and use plugins at your own risk. Do you want to install the plugin apigee-broker-plugin? [yN]: y Starting download of plugin binary from repository CF-Community... 7.85 MiB / 7.85 MiB [===========================================================================================================================================================================================================================================] 100.00% 11s Installing plugin Apigee-Broker-Plugin... OK Plugin Apigee-Broker-Plugin 0.1.1 successfully installed.

  2. Make sure the plugin is available by running the following command:

    $ cf -h
    …
    Commands offered by installed plugins:
      apigee-bind-mg,abm      apigee-unbind-mgc,auc    enable-diego
      apigee-bind-mgc,abc     apigee-unbind-org,auo    has-diego-enabled
      apigee-bind-org,abo     dea-apps                 migrate-apps
      apigee-push,ap          diego-apps               dev,pcfdev
      apigee-unbind-mg,aum    disable-diego
    

Step 3: 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:

    $ 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
    
  2. Create an instance of the Apigee Edge service. Select the microgateway service plan to have Apigee Edge Microgateway run in a separate container from your Cloud Foundry app.

    $ cf create-service apigee-edge microgateway YOUR-SERVICE-INSTANCE -c \
    '{"org":"YOUR-ORG", "env":"YOUR-ENV"}'
  3. Use the cf service command to display information about the service instance:

    $ cf service apigee-service
    
    Service instance: apigee-service
    Service: apigee-edge
    Bound apps:
    Tags:
    Plan: microgateway
    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:
    

Step 4: 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.

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

  3. Clone the Apigee Microgateway repository.

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

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

  5. Edit the application manifest as follows:

    1. 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'
      
  6. Push Apigee Microgateway as its own app.

    cf push

Step 5: Bind the App Route to the Service Instance

In this step, you bind a Cloud Foundry app to the Apigee service instance you created. The apigee-bind-mg command creates the proxy for you and binds the app to the service.

Each bind attempt requires authorization with Apigee Edge, with credentials passed as additional parameters to the apigee-bind-mg command. You can pass these credentials as arguments of the apigee-bind-mg command or by using a bearer token.

  1. If you’re using a bearer token to authenticate with Apigee Edge, get or update the token using the Apigee SSO CLI script. (If you’re instead using command-line arguments to authenticate with username and password, specify the credentials in the next step.)

    1. Download the Apigee Edge scripts:

      $ curl https://login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"
    2. 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.

      $ tar xvf ssocli-bundle.zip
    3. Create a .sso-cli directory in your user directory:

      $ mkdir ~/.sso-cli
    4. 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.

      $ ./get\_token

      The get_token script writes the token file into ~/.sso-cli. For more about get_token, see the Apigee documentation.

  2. Use the apigee-bind-mg 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.)

    You’ll need to run the command twice: once to create the proxy, then again to bind the service to the proxy. The proxy must be loaded by Microgateway instances before binding.

    When you use the command without arguments, you’ll be prompted for argument values. To use the command with arguments, see the command reference at the end of this topic. For help on the command, type cf apigee-bind-mg -h. Without arguments, you’ll be prompted for the following:

    Argument Description
    Apigee username Apigee user name. Not used if you pass a bearer token with the --bearer argument.
    Apigee password Apigee password. Not used if you pass a bearer token with the --bearer argument.
    Action to take Required. 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.
    Apigee environment Required. The Apigee environment where your proxy should be deployed.
    Apigee organization Required. The Apigee organization where your proxy should be created.
    Application to bind to Required. Name of the the Cloud Foundry application to bind to.
    Domain to bind to Required. Domain of the application to bind to.
    Route of the application acting as microgateway Required. Route of the application acting as Edge Microgateway.
    Target application protocol Optional. The application protocol, such as http or https.
    Service instance name to bind to Required. Name of the Apigee service to bind to.
    1. First, create the proxy. When prompted for the action to take, enter proxy.

      $ cf apigee-bind-mg

      The command creates an API proxy on the specified Apigee org and environment, then binds the Apigee service to the target app. The protocol parameter specifies the protocol through which the proxy’s target endpoint will be called. To do its work, this command authenticates with Apigee Edge using the credentials you specified.

      Cloud Foundry will report an error because 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.

    2. Next, bind the service to the proxy by running the command again. This time, for the action, specify bind for the action argument.

      $ cf apigee-bind-mg

      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.

apigee-bind-mg Reference

Use the apigee-bind-mg command to generate an API proxy on Apigee Edge and to bind the Cloud Foundry service to the proxy.

The command requires your Apigee Edge credentials in order to create and bind to an API proxy. You can specify credentials either with a bearer token or by giving a username and password at the command line. To use a token, you must provide the –bearer argument.

To be prompted for argument values (and provide a username and password at prompts), use the command without arguments.

$ cf apigee-bind-mg

To specify arguments on the command line, use the following syntax (be sure to use quotes and command expansion, as shown here):

$ cf apigee-bind-mg [--app APP_NAME] [--service SERVICE_INSTANCE] \
   [--apigee_org APIGEE_ORGANIZATION] [--apigee_env APIGEE_ENVIRONMENT] \
   [--micro MICROGATEWAY_APP_ROUTE] [--protocol TARGET_APP_PROTOCOL] 
   [--domain APP_DOMAIN] [--action ACTION] \
   [--user APIGEE_USERNAME] [--pass APIGEE_PASSWORD] \
   [--bearer APIGEE_BEARER_TOKEN]
Parameter Purpose Allowed Values
action Required. 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.
apigee_env Required. Apigee Edge environment to which the API proxy is (or will be) deployed Your environment.
apigee_org Required. Apigee Edge organization hosting the API proxy to be called Your organization (must be reachable via the authentication token specified in the bearer parameter)
app Required. Name of the the Cloud Foundry application to bind to. The app name.
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
domain Required. Domain of the application to bind to.
micro Required. Route of the application acting as Edge Microgateway. Required.
pass Apigee password. Not used if you pass a bearer token with the –bearer argument. Your password.
protocol The protocol through which the proxy should be accessed by Cloud Foundry http or https; default is https.
service Required. Name of the Apigee service to bind to. The service name.
user Apigee user name. Not used if you pass a bearer token with the –bearer argument. Your user name.

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:

    $ curl https://sample-api-apigee.cfapps.pivotal.io 
        {“hello”:“hello from cf app”}

    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.

Create a pull request or raise an issue on the source for this page in GitHub