search close

IBM Cloud Install

access_time Updated Sep 21, 2021

The Signal Sciences agent can be easily deployed with IBM Cloud application runtimes. The installation process is compatible with any of the language buildpacks.

This is a supply-buildpack for Cloud Foundry that provides integration with the Signal Sciences agent for any programming language supported by the platform, and requiring zero application code changes.

Installation

  1. Application developers will need to specify the buildpack with the cf push command:

     cf push YOUR-APP -b https://github.com/signalsciences/sigsci-cloudfoundry-buildpack.git -b APP_BUILDPACK
    
  2. Set your agent’s access key and secret using the cf set-env command. Example:

    cf set-env <application name> SIGSCI_ACCESSKEYID <key>
    cf set-env <application name> SIGSCI_SECRETACCESSKEY <secret>
    
    • The Agent Access Key and Agent Secret Key for your site are listed within the Signal Sciences console by going to Agents > View agent keys:

      The 'View agent keys' button.
    • The Agent Access Key and Agent Secret Key will be visible within the modal window:
      The agent keys window.

  3. Run cf push as you normally would to deploy your application.

Additional Configuration Options

The Signal Sciences agent can be configured with environment variables using the cf command:

cf set-env YOUR-APP <variable name> "<value>"

To have these changes take effect, you must at least re-stage your app:

cf restage YOUR-APP

Server Hostname

Each time you deploy your application, IBM Cloud will automatically assign a new random name for the agent. If you’d prefer to specify an agent name for each deployment, set the SIGSCI_SERVER_HOSTNAME environment variable:

cf set-env <application name> SIGSCI_SERVER_HOSTNAME <agent name>

Reverse Proxy Upstream

If you would like to define upstream host(s) that the Agent will proxy requests to, use the SIGSCI_REVERSE_PROXY_UPSTREAM option. This variable is optional with a default value of 127.0.0.1:8081:

cf set-env <application name> SIGSCI_REVERSE_PROXY_UPSTREAM <ip:port>

Access Logs

If you would like to enable the agent’s access logging, set the SIGSCI_REVERSE_PROXY_ACCESSLOG environment variable:

cf set-env <application name> SIGSCI_REVERSE_PROXY_ACCESSLOG /tmp/sigsci_access.log

Agent Version

By default the buildpack will install the latest version of the Signal Sciences agent. If you prefer to specify which agent version to install, set the SIGSCI_AGENT_VERSION environment variable:

cf set-env <application name> SIGSCI_AGENT_VERSION 4.7.0

Health Checks

Currently, IBM Cloud does not support HTTP health checks native to Cloud Foundry so if the application process crashes while the Signal Sciences agent is still running, IBM Cloud may not detect that the application is in an unhealthy state. The latest release of the Signal Sciences Cloud Foundry installer script can be configured to implement health checking that will stop the agent process if the application process is in an unhealthy state.

There are two environment variables that enable/configure health checking.

SIGSCI_HC - set this to “true” to enable health checking. Example:

cf set-env <application name> SIGSCI_HC true

SIGSCI_HC_CONFIG - set this environment variable to configure the health check. If you do not set this environment variable the default settings will be used.

Default health check settings: check the “/“ path every 5 seconds, if the agent listener returns a 502 for 5 sequential checks then the health check fails. Additionally, if the application process does not return a 200 response for 3 sequential tries the health check fails.

To specify custom health check settings, the SIGSCI_HC_CONFIG value is a string that consists of several fields delimited by :.

SIGSCI_HC_CONFIG fields:

<frequency>:<endpoint>:<listener status>:<listener warning>:<upstream status>:<upstream warning>
Field Description
frequency How often to perform the check in seconds, example: every 5 seconds
endpoint Which endpoint to check for both the listener and upstream process
listener status The status code that not healthy and will trigger stopping the agent
listener warning The number of times the check can fail before stopping the agent
upstream status The status code that is healthy, any other code will trigger stopping the agent
upstream warning The number of times the check can fail before stopping the agent

As an example, the default settings looks like this: 5:/:502:5:200:3

An example custom setting: check the “/health.html“ path every 10 seconds, if the agent listener returns a 502 for 10 sequential tries the health check fails or if the application process does not return a 200 for 5 sequential tries the health check fails - looks like this: 10:/health.html:502:10:200:5.

Require Agent

By default the installer script will allow the application to start even if the Signal Sciences agent fails to start. If you prefer to ensure that your application never starts with out being protected by the Signal Sciences agent, use the SIGSCI_REQUIRED environment variable. Example:

cf set-env <application name> SIGSCI_REQUIRED true

Additional configuration options are listed on the agent configuration page