Hosted Targets reference

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Environment variable limits

Hosted Targets limits the size and number of environment variables that you can set in the Hosted Targets runtime environment.

1000: Maximum length of a single environment variable.
100: Maximum number of environment variables that you can set.

For information about setting environment variables, see The manifest file.

Environment variables set in the application runtime

When you deploy a Hosted Targets application, the following environment variables are set and are available to your application at runtime:

APIGEE_ENVIRONMENT - The environment where the Hosted Target proxy is deployed.
APIGEE_ORGANIZATION - The organization where the Hosted Target proxy is deployed.
PORT - The port where the Hosted Target application must listen.

System resource allocation

Each Hosted Targets instance receives the following resources:

256 MB memory
1.2 GHz CPU

Scaling

This section describes how Hosted Targets applications scale, depending on the type of Edge account you have.

A Trial version of Apigee Edge is limited to one Hosted Targets instance per proxy.
Paid Apigee Edge accounts receive automatic scaling based on request rate, response latencies, and other application metrics per proxy.
Hosted Targets apps deployed to both paid and trial versions of Apigee Edge scale to zero on periods of inactivity. In this case, you may notice slower response times for a brief period. See also Known issues

The manifest file

To gather runtime information for building and deploying the hosted application, Edge looks for a manifest file named app.yaml in the resources/hosted directory. This file contains information necessary to build and deploy the Hosted Targets application.

Manfiest file syntax

runtime: node
runtimeVersion: version_number
command: command_name
args: argument_array
env:
  - name: variable_name
    value: literal_value
  - name: variable_name
    valueRef:
      name: kvm_name
      key: kvm_value

Manifest file elements

A app.yaml manifest file includes these elements:

runtime - (Required) Specifies the type of application you are deploying. You must specify node.
runtimeVersion - (Optional) The version of the runtime that your application uses. Default: Node.js LTS (v10.x). Refer to the Docker official repository for Node for other options.
command - (Optional) Lets you specify a command to run other than the default command used to start your application. Default: Node.js=npm
args - (Optional) Array of command line arguments to pass to the application (specified in standard YAML array syntax). Typically, these are added to the default command. The default is start. For example, by default the Node.js app will be passed the command npm start.
env - (Optional) An array of environment variables (name/value pairs) to set in the Hosted Targets runtime environment. These variables are available to your deployed Hosted Targets app.
Hosted Targets limits the size and number of environment variables that you can set. See Limits

name - The variable name.
value | valueRef - You have two options. You can set a literal value or reference a value stored in a Key Value Map. The Key Value Map must already exist in your Edge environment. See Working with Key Value Maps
- If you use value, then you must specify a variable name and a literal value. For example:
```
runtime: node
env:
 - name: NODE_ENV
   value: production
```
- If you use valueRef, then you must supply the name of a Key Value Map (KVM) that you previously created in Edge and a key. For example:
```
runtime: node
env:
  - name: DB_ENV
    value: production
  - name: DB_PASSWORD
    valueRef:
      name: hosted-kvm
      key: db-password
```
  The KVM lookup is scoped to the environment. KVM organization and application/proxy scope are not supported. The KVM values are injected into the KVM once when the Node.js app starts. Modifying the KVM later will have no effect. The KVM option let you store sensitive information in the Edge encrypted KVM, rather than placing it in the proxy bundle itself. See Working with Key Value Maps.

Example manifest files

This section contains example manifest files for Node.js applications. A manifest file is required to deploy a Hosted Targets app, and must be located in the apiproxy/resources/hosted directory, and the filename must be app.yaml.

Remember that you do not need to include a node_modules directory with a Hosted Targets Node.js app. Upon deployment, Hosted Targets runs npm install to pull in any dependencies specified in the package.json file.

Following are example app.yaml (manifest) files for Node.js apps.

Example that specifies an literal environment variable:

 runtime: node
 env:
   - name: NODE_ENV
     value: production

Example with a start command, command-line arguments, and an environment variable.

 runtime: node
 command: ./node_modules/pm2/bin/pm2
 env:
   - name: NODE_ENV
     value: production
 args:
   - app.js

Example that specifies a Key Value Map (KVM) reference:

For more information about KVM access, see The Manifest file.

runtime: node
env:
  - name: DB_ENV
    value: production
  - name: DB_PASSWORD
    valueRef:
      name: hosted-kvm
      key: db-password

Sample Hosted Targets applications on GitHub

Apigee provides sample proxies on GitHub with Hosted Targets applications written in Node.js. You can clone this repo and follow the README instructions to deploy any of the proxies.

Prerequisites

To deploy the samples, you must have two tools installed on your system:

apigeetool -- A command line tool for deploying Edge proxies.
get_token - A command line tool for obtaining an authorization token required by apigeetool.

If you want to test samples locally, you must also have you must have Node.js installed.

Obtaining the sample repo

In a browser, go to https://github.com/apigee/api-platform-samples.
Click Clone or download and pull the repo to your local system, using your preferred method.
cd to <your install dir>/api-platform-samples/doc-samples/hosted-targets
Once the repo is downloaded, you can cd to any of the sample directories and follow the README instructions to deploy a sample proxy to Edge. The deploy command is shown below. Simply replace the indicated parameters with ones for your Apigee account:

get_token && apigeetool deployproxy \
  -o YOUR_ORGANIZATION \
  -e YOUR_ENVIRONMENT \
  --json \
  --token "$(< ~/.sso-cli/valid_token.dat)"\
  --api NAME_OF_THE_PROXY \
  --directory .

Example: Executing a sample app

Clone the samples repository

cd ~/myhome
git clone https://github.com/apigee/api-platform-samples.git
cd ~/myhome/api-platform-samples/doc-samples/hosted-targets
cd node-hosted-hello

Test the application locally

You must have Node.js installed to do this local test.

 PORT=8081 node apiproxy/resources/hosted/index.js
 curl http://localhost:8081

Example output:

{"date":"2018-03-12T21:45:22.161Z","msg":"Hello, World!"}

Deploy the proxy

 get_token && apigeetool deployproxy \
   -o myorg \
   -e test \
   --json \
   --token "$(< ~/.sso-cli/valid_token.dat)"\
   --api node-hosted-hello \
   --directory .

Test the deployment

The deployment may take a few minutes to complete. If you get a deployment error, execute the deploy command again.

curl http://myorg-test.apigee.net/node-hosted-hello

Example output:

{"date":"2018-03-23T18:59:18.668Z","msg":"Hello, World!"

Known Issues

Network Latencies - Now that the Node.js application no longer runs in the MP’s JVM, there is now a network hop between the MP and the deployment. Of course this comes at a cost but initial benchmarks show it to be well within a reasonable amount
Slow API Responses - The infrastructure running your applications automatically scales based on need. This means your application can actually scale down to zero instances and if that is the case, the next API request will take a little longer than typical API requests since the infrastructure is spinning up the instance(s) to process the request(s).
Deployment error - If you receive a deployment error when deploying a Hosted Targets proxy, try redeploying the proxy. In some cases, the deployment can time out and if you redeploy, the problem will resolve itself.