Hosted Targets tasks

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

Undeploying a Hosted Targets proxy

When you undeploy an Edge proxy that includes a Hosted Targets application, the associated Hosted Targets app is undeployed, but the underlying application image is not deleted. If you redeploy the proxy, the Hosted Targets app is redeployed.

Deleting a Hosted Targets proxy

After you delete a Hosted Targets proxy, the underlying runtime instances will stop running within some amount of time. The application code will persist, however.

Accessing log files

Log files are useful for debugging and troubleshooting. You can view two types of log files for a Hosted Targets deployment:

Build log - Shows you output related to deploying and building a Hosted Targets app.
Runtime log - Shows you output related to the running Hosted Targets app. Runtime logs are scoped to the environment and show log information for the currently deployed proxy revision.

Accessing logs from the Edge UI

Go to: apigee.com/edge
Enter your login credentials and click Sign In.
Select Develop > API Proxies in the side navigation menu.
Select the proxy for which you want to view logs.
Click the Develop tab.
To see the build log, click Build Logs.
Build logs are not scoped to an environment. They are the same no matter which environment you deployed to.
To see the runtime log, click Runtime Logs.

Accessing logs with the API

You can also use an Edge API to retrieve Hosted Targets logs. For details, see Get Cached Node.js Logs.

Using a private npm repository

This section explains how to deploy a Node.js proxy to Hosted Targets in cases where you use a private NPM repository in your development environment.

What you need to know about using a private repository

When you deploy a Node.js app to Edge, all of your project's dependencies are imported automatically as part of the deployment process. Essentially, Hosted Targets runs npm install on your code when it is deployed. However, if you use a private NPM repository in your development environment, the private dependencies cannot be resolved in the Cloud. In this case, the solution is to use the --bundled-dependencies option when you use the deployment utility apigeetool. See also Deploy Node.js from your system to Edge.

When you use the --bundled-dependencies flag on apigeetool, your Node.js app will be uploaded to Hosted Targets and any local/private files that are listed in the bundledDependencies array in package.json are zipped and uploaded with the bundle.

Be sure that your bundled dependencies follow this directory structure structure within the ZIP file:

node_modules/
  bundle-dependency-name/
  ... (sources)

Note that if a proxy bundle that you deploy exceeds 15MB in size, a deployment error can occur. Because of this reason, it's best never to include a node_modules directory in your deployment. Let Hosted Targets do the work of importing the dependencies.

Although not a common situation, be aware that if you mirror a public NPM repository internally, your deployment will fail if your deployment bundle includes a .npmrc or package-lock.json file that points to your private mirror. In this case, be sure to omit .npmrc or package-lock.json from your proxy bundle that you intend to deploy.

Deploying with a private NPM repository

To use modules provided from a private NPM repository, follow these steps:

If you are using bundled dependencies, you must specify a runtimeVersion 6 or newer in your application's app.yaml file (the manifest file). For example:

  runtime: node
  runtimeVersion: 6
  application: my-express-app
  env:
    - name: NODE_ENV
      value: production
    - name: LOG_LEVEL
      value: 3

The reason for this setting is that there is a known Node.js bug in the NPM client shipped with newer versions of Node.js. When this restriction is no longer necessary, this note will be updated accordingly.

Log into npm:
```
npm login
```
Get an npm auth token:

Locate your .npmrc (should be in ~/.npmrc).
In your .npmrc, note the token at the end of the line that looks like this:

//registry.npmjs.org/:_authToken=****

Or use the npm token <list | create | revoke> commands to list, create, or revoke an auth token. See the npm-token documentation for more details.

Access the Key Value Maps configuration page, as described below.
Edge

To access the Key Value Maps configuration page using the Edge UI:
1. Sign in to apigee.com/edge.
2. Select Admin > Environments > Key Value Maps in the left navigation bar.
Classic Edge (Private Cloud)

Note: The Classic Edge UI is available with Edge for Private Cloud only.

To access the Key Value Maps configuration page using the Classic Edge UI:
1. Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.
2. Select APIs > Environment Configuration > Key Value Maps in the top navigation bar.
Click + Key Value Map.
In the New Key Value Map dialog, enter a name and select Encrypted.
Add an Encrypted Key Value Map for each environment that you plan to use.
Click Add.
Add the auth token you previously located or created as a new entry in each of the KVMs that you just created.
In your app.yaml file add an entry that references the KVM and key associated with the npm auth token. It should look something like this:

env:
- name: NPM_TOKEN
 valueRef:
   name: npm_store
   key: private_token

Where:

The top level name attribute corresponds to the name of the environment variable that will be created.
The name under valueRef corresponds to the KVM you created previously.
The key attribute corresponds to the key that maps to the npm token you added to the KVM.

Create a .npmrc file in the same directory as your package.json. This file should look similar to this:
```
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
```
or if you’re not using registry.npmjs.org you can set the scope in the .npmrc file by adding a line like this @myscope:registry=https://mycustomregistry.example.org See also the npmrc documentation.
Upload or update your Node.js proxy with the .npmrc file and app.yaml files included.
Make sure your new or updated proxy deploys and works with the desired private repository module.
If the proxy does not deploy, check the build logs to see if it failed on installing the private npm module. If so:

Under the develop tab, make sure the .npmrc is present.
Make sure your token is valid (try installing the module locally with the token present in the kvm).
If you are using a custom scope, make sure that is set.

Specifying the NPM version for bundled dependencies

By default, NPM v4 is used to install bundled dependencies in the Hosted Targets environment. However, if you want to use a different NPM version, you can specify it in the NPM_VERSION environment variable. You can set this variable in the application's manifest file. See Manifest file elements for details.

Apigee uses NPM v4 by default because of an issue with NPM versions greater than v4. This issue is documented in the NPM community article npm install for package with local dependency fails. If you set NPM_VERSION to an NPM version greater than v4, the dependency installation can fail.

If you use bundled dependencies, and if you do not specify NPM_VERSION, Hosted Targets uses NPM v4 by default. If you do not use bundled dependencies, the version of NPM that is included in your specified Node.js runtime is used.

Bundled depencencies example

For an example that demonstrates the bundled dependencies feature with Hosted Targets, see How to create a Node.js application with Hosted Functions using custom modules.

Add a health check endpoint

You have the option of implementing a health check endpoint for your Node.js application. Apigee uses this endpoint when your Node.js application starts to check that the application is up and running in the container.

By default, the endpoint that Apigee expects is /health. You can change the default endpoint, by specifying the endpoint in an environment variable named HOSTED_TARGET_HEALTH_CHECK_PATH. You can set this variable in the application's manifest file. See Manifest file elements for details.

Implementing a health check endpoint is not required. However, if you do implement a health check endpoint, note the following:

If your application exits when Apigee hits the endpoint, the application will not start up as expected.
It is okay if your endpoint returns a 404 Not Found HTTP status. The /health or HOSTED_TARGET_HEALTH_CHECK_PATH is only used to check if your application is running. The actual response is ignored.

Change the NPM cache location

Newer versions of Node.js use a version of NPM that use /root/.npm for the NPM cache. This location presents a problem for Hosted Targets because that directory location is read-only since the Hosted Target runtime uses a tmpfs filesystem where only /tmp is writable. To work around this issue you can set the npm_config_cache environment variable in your application's app.yamlfile (the manifest file) to a directory within /tmp. For example:

  runtime: node
  application: my-express-app
  env:
    - name: npm_config_cache
      value: /tmp/.npm
    - name: NODE_ENV
      value: production
    - name: LOG_LEVEL
      value: 3

Run your application without NPM

By default, Hosted Targets uses npm start to run your Hosted Target application. But in the previous task we discussed a problem with using NPM as newer versions will attempt to use /root/.npm for the NPM cache, which is unwritable and results in your Hosted Target failing to start. While the previous task will work arond this problem, another option would be to run your application without NPM. To do this, you can use the command and args values in your application's app.yamlfile (the manifest file) to run your Hosted Target directly using node index.js. For example:

  runtime: node
  application: my-express-app
  command: node
  args:
    - index.js
  env:
    - name: NODE_ENV
      value: production
    - name: LOG_LEVEL
      value: 3

Of course, you can use whatever command you deem fit and node index.js is just an example.