Proxying a Cloud Foundry app (microgateway-coresident plan)

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

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

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:

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

    $ cf create-service apigee-edge microgateway-coresident 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 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:
    

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.

  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. 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_CONFIG_DIR: config
        APIGEE_MICROGATEWAY_CUST_PLUGINS: plugins
        APIGEE_MICROGATEWAY_PROCESSES: 2
        APIGEE_MICROGATEWAY_CUSTOM: |
                                    { 
                                      "policies": {
                                         "oauth": {
                                            "allowNoAuthorization": false, 
                                            "allowInvalidAuthorization": false
                                          },
                                          "spikearrest": {
                                            "timeUnit": "minute", 
                                            "allow": 10
                                          }
                                        },
                                      "sequence": ["oauth", "spikearrest"]
                                    }
      

      To support Cloud Foundry application health checks, make sure your applications block includes the health-check-type and health-check-http-endpoint properties:

      health-check-type: http
      health-check-http-endpoint: /healthcheck
      

      The sequence property must also include a reference to the healthcheck plugin, as shown here:

      "sequence": ["healthcheck", "oauth", "spikearrest"]
      

      For more on health checks, see Using Application Health Checks.

      The following describes the manifest properties:

      Variable Description
      APIGEE_MICROGATEWAY_CONFIG_DIR Location of your Apigee Microgateway configuration directory.
      APIGEE_MICROGATEWAY_CUST_PLUGINS Location of your Apigee Microgateway plugins directory.
      APIGEE_MICROGATEWAY_PROCESSES The number of child processes that Apigee Microgateway should start. If your Microgateway performance is poor, setting this value higher might improve it.
      APIGEE_MICROGATEWAY_CUSTOM “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.
      APIGEE_MICROGATEWAY_NODEJS_FILENAME Name of a Node.js .tar file in the lib/ directory, which is located in the microgateway_decorator buildpack. In this case, the local install will be used to run the Microgateway instead of downloading Node.js.
      APIGEE_MICROGATEWAY_NODEJS_URL A custom URL from which to download the Node.js used to run Microgateway.
      APIGEE_MICROGATEWAY_NODEJS_VERSION The version of Node.js used to run Microgateway. This is downloaded from https://nodejs.org.
      APIGEE_MICROGATEWAY_VERSION The version of Microgateway to use.
    • Configure the Microgateway YAML file to include the necessary plugins. For example if we added a spikearrest plugin:

      ...
      plugins:
          dir: ../plugins
          sequence:
            - oauth
            - spikearrest
      spikearrest:
        timeUnit: minute
        allow: 10
      oauth:
        allowNoAuthorization: false
        allowInvalidAuthorization: false
      
  4. 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. Remove the following or any other buildpack tags from the manifest:

      buildpack: nodejs_buildpack
      
    2. If you have custom buildpacks, add the following line to the “env” section:

      env:
        ...
        APIGEE_MICROGATEWAY_CUST_PLUGINS: '<plugin-directory>'
      
  5. To use a custom Node.js version to run Microgateway, configure the decorator in one of the following ways:

    • To use a Node.js tar.gz from a location accessible via http or https other than https://nodejs.org:

      env:
          # APIGEE_MICROGATEWAY_PROXY: edgemicro_cf-test.local.pcfdev.io
          APIGEE_MICROGATEWAY_CONFIG_DIR: config
          APIGEE_MICROGATEWAY_NODEJS_URL: https://mycustomdomain.com/mynoderoot/versions/node-v8.11.3-linux-x64.tar.gz
          # APIGEE_MICROGATEWAY_PROCESSES: 2
          # APIGEE_MICROGATEWAY_CUSTOM: | {...} --> uncomment if applicable
      
    • To select a specific Node.js version from https://nodejs.org:

      env:
          # APIGEE_MICROGATEWAY_PROXY: edgemicro_cf-test.local.pcfdev.io
          APIGEE_MICROGATEWAY_CONFIG_DIR: config
          APIGEE_MICROGATEWAY_NODEJS_VERSION: 8.11.3
          # APIGEE_MICROGATEWAY_PROCESSES: 2
          # APIGEE_MICROGATEWAY_CUSTOM: | {...} --> uncomment if applicable
      
    • To use the default Node.js version of 8.11.3 from https://nodejs.org:

      env:
          # APIGEE_MICROGATEWAY_PROXY: edgemicro_cf-test.local.pcfdev.io
          APIGEE_MICROGATEWAY_CONFIG_DIR: config
          # APIGEE_MICROGATEWAY_PROCESSES: 2
          # APIGEE_MICROGATEWAY_CUSTOM: | {...} --> uncomment if applicable
      
    • To use a specific version of Node.js used from the decorator, then include the Node.js .tar file in the lib/ directory which is located in the microgateway_decorator buildpack. In this case, the local install will be used to run Microgateway instead of downloading Nodejs.

      env:
          # APIGEE_MICROGATEWAY_PROXY: edgemicro_cf-test.local.pcfdev.io
          APIGEE_MICROGATEWAY_CONFIG_DIR: config
          APIGEE_MICROGATEWAY_NODEJS_FILENAME: node-v6.11.3-linux-x64.tar.gz
          # APIGEE_MICROGATEWAY_PROCESSES: 2
          # APIGEE_MICROGATEWAY_CUSTOM: | {...} --> uncomment if applicable
      
  6. To use a custom Microgateway version, configure the decorator in one of the following ways. If you don't include APIGEE_MICROGATEWAY_VERSION, then it will use version 2.5.8 in the GitHub repository.

    • To use a specific version of Edge Microgateway, include this environment variable. This will execute a git clone on the https://github.com/apigee-internal/microgateway repository.

      env:
          # APIGEE_MICROGATEWAY_PROXY: edgemicro_cf-test.local.pcfdev.io
          APIGEE_MICROGATEWAY_VERSION: 2.5.19
          APIGEE_MICROGATEWAY_CONFIG_DIR: config
          # APIGEE_MICROGATEWAY_NODEJS_LOCAL_INSTALL: false
          # APIGEE_MICROGATEWAY_PROCESSES: 2
          # APIGEE_MICROGATEWAY_CUSTOM: | {...} --> uncomment if applicable
      
    • To use specific version of Edge Microgateway installed from the decorator, then clone the repository into the lib/ directory which is located in the microgateway_decorator buildpack. In this case, the decorator will use the locally cloned repository instead of cloning from github.com.

      env:
          # APIGEE_MICROGATEWAY_PROXY: edgemicro_cf-test.local.pcfdev.io
          APIGEE_MICROGATEWAY_VERSION: 2.5.19
          APIGEE_MICROGATEWAY_CONFIG_DIR: config
          # APIGEE_MICROGATEWAY_NODEJS_LOCAL_INSTALL: false
          # APIGEE_MICROGATEWAY_PROCESSES: 2
          # APIGEE_MICROGATEWAY_CUSTOM: | {...} --> uncomment if applicable
      
  7. Ensure that your Cloud Foundry app isn't running on port 8080, nor on the port specified by the PORT environment variable.

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

    $ cf push <cf-app-name> --no-start
    

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 edgemicro 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. 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 <span>https:</span>//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. Bind the app to the Apigee service instance.

    Use the bind-service command with JSON that specifies parameters.

    The following example does two things: it creates an API proxy on the specified 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. This command authenticates with Apigee Edge using the token in the specified .dat file:

    $ cf bind-service <cf-app-name> <service name> \
    -c '{"org":<microgateway-org>,"env":<microgateway-env>,
      "bearer":"'$(cat ~/.sso-cli/valid_token.dat)'",
      "action":"proxy bind",
      "protocol":"http",
      "edgemicro_key":<microgateway-config-key>,
      "edgemicro_secret":<microgateway-config-secret>,
      "target_app_port":<cf-app-port>}'
    
  3. Start the Cloud Foundry app and microgateway-decorator along with it.

    $ cf v3-push <cf-app-name> -b microgateway_decorator -b <language buildpack (e.g nodejs_builpdack)>
    
    • If you are using the v3.0.0 decorator with Java, run:

      $ cf start APP-NAME
      
  4. Log into Edge and note that the proxy has been created. Then follow the instructions to create a product with your newly created proxy. You can now configure standard Apigee Edge policies on that proxy.

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.

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

bind-service reference

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

$ cf bind-service <cf-app-name> <service name> \
    -c '{"org":<microgateway-org>,"env":<microgateway-env>,
      "bearer":"'$(cat ~/.sso-cli/valid_token.dat)'",
      "action":"proxy bind",
      "protocol":"http",
      "edgemicro_key":<microgateway-config-key>,
      "edgemicro_secret":<microgateway-config-secret>,
      "target_app_port":<cf-app-port>}'

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:
  • 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
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.

Unbinding the service

The unbind-service command accepts two parameters.

$ cf unbind-service <cf-app-name> <service name>

Uninstalling the service instance and broker

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