IBM Cloud installation
Last updated 2023-05-04
The Signal Sciences agent can be 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
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_BUILDPACKLocate the Agent Keys for your Signal Sciences site:
Log in to the Signal Sciences console.
From the Sites menu, select a site if you have more than one site.
Click Agents in the navigation bar. The agents page appears.
Click View agent keys. The agent keys window appears.
Copy the Agent Access Key and Agent Secret Key.
Set your agent's access key and secret using the
cf set-env
command. Replaceyour-application-name
with the name of your application and replaceaccess-key-goes-here
andsecret-key-goes-here
with your agent keys:$ cf set-env your-application-name SIGSCI_ACCESSKEYID access-key-goes-here$ cf set-env your-application-name SIGSCI_SECRETACCESSKEY secret-key-goes-hereRun
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
, replacing OPTION
and VALUE
with the agent configuration option and its value:
$ cf set-env your-application-name OPTION "VALUE"
To have these changes take effect, you must at least re-stage your app:
$ cf restage your-application-name
Server hostname
Each time you deploy your application, IBM Cloud will automatically assign a new random name for the agent. To specify an agent name for each deployment, set the SIGSCI_SERVER_HOSTNAME
environment variable:
$ cf set-env your-application-name SIGSCI_SERVER_HOSTNAME agent-name
Reverse proxy upstream
To define upstream hosts that the Agent will proxy requests to, use the SIGSCI_REVERSE_PROXY_UPSTREAM
option, replacing ip:port
with the upstream host IP address and port. This variable is optional with a default value of 127.0.0.1:8081
:
$ cf set-env your-application-name SIGSCI_REVERSE_PROXY_UPSTREAM ip:port
Access logs
To enable the agent's access logging, set the SIGSCI_REVERSE_PROXY_ACCESSLOG
environment variable:
$ cf set-env your-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. To specify which agent version to install, set the SIGSCI_AGENT_VERSION
environment variable, replacing version-number
with the specific version number to install:
$ cf set-env <application name> SIGSCI_AGENT_VERSION version-number
Health checks
Currently, IBM Cloud does not support HTTP health checks native to Cloud Foundry. 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:
Set SIGSCI_HC
to true
to enable health checking:
$ cf set-env your-application-name SIGSCI_HC true
Set SIGSCI_HC_CONFIG
to configure the health check. If you do not set this environment variable the default settings will be used.
The default settings configure the health check to:
- Check the
/
path every 5 seconds. - If the agent listener returns a
502
for 5 sequential checks, then the health check fails. - If the application process does not return a
200
response for 3 sequential tries, then 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 (e.g., 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:
$ 5:/:502:5:200:3
Example custom health check settings
These example settings configure the health check to:
- Check the
/health.html
path every 10 seconds. - If the agent listener returns a
502
for 10 sequential tries the health check fails. - If the application process does not return a
200
for 5 sequential tries, the health check fails.
$ 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. To ensure that your application never starts without being protected by the Signal Sciences agent, use the SIGSCI_REQUIRED
environment variable:
$ cf set-env your-application-name SIGSCI_REQUIRED true
Additional configuration options
Additional configuration options are listed on the agent configuration page.
Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.