Manage Your NGINX Integrations

Use the Integrations Overview page to view and manage your NGINX Integrations

Overview

Create Integrations to give NGINX Controller permission to deploy and manage instances on external systems, such as AWS, and forward data to external services like Datadog, Splunk and Syslog.

Create an AWS Integration

AWS Integration Requirements

To create an Integration for AWS, you need to configure an AWS IAM user with the following roles:

"ec2:*Instance*",
"ec2:*Tags*"

In addition, you’ll need to copy and save the following AWS security credentials to use when creating an AWS Integration:

  • access key ID
  • secret access key ID

Add an AWS Integration

To create an AWS Integration, take the following steps:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Integrations.
  4. On the Integrations menu, select the Create Integration quick action.
  5. Add a name.
  6. (Optional) Add a display name.
  7. (Optional) Add a description.
  8. (Optional) Add tags.
  9. In the Integration Type list, select AWS_INTEGRATION.
  10. (Optional) Add the service endpoint URI.
  11. In the Credential Type list, select AWS_ACCESS_KEY.
  12. Add the access key ID .
  13. Add the secret access key ID .
  14. Select Submit.

Create a Datadog Integration

Datadog Integration Requirements

NGINX Controller sends data to the Datadog API; NGINX Controller does not use an agent. Datadog requires that NGINX Controller present an access token with the data to authenticate the service.

  1. Log into the Datadog web interface .
  2. On the navigation menu, select Integrations > APIs.
  3. Expand the API Keys pane.
  4. If you already have a key available, you can use it. If you don’t, or if you want to create a different key , you can do so by typing a key name and clicking <strong>Create API key</strong> .
  5. Copy and save the API key you want to use. You’ll configure NGINX Controller with this value later.
Note:
Datadog restricts the creation of API keys to Admin users. You may need to contact your administrator to get a new key.

Add a Datadog Integration

Take the following steps to create an Integration for Datadog:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Integrations.
  4. On the Integrations menu, select the Create Integration quick action.
  5. Add a name.
  6. (Optional) Add a display name.
  7. (Optional) Add a description.
  8. (Optional) Add tags.
  9. In the Integration Type list, select GENERIC_INTEGRATION.
  10. In the Endpoint URI box, add the API endpoint for your Datadog region. For example, https://api.datadoghq.com/api/v1/series for metrics or https://http-intake.logs.datadoghq.com/v1/input for events.
  11. In the Credential Type list, select API_KEY.
  12. In the API Key box, add the Datadog API Key .
  13. Select Submit.

Create a Splunk Integration

Splunk Integration Requirements

(Optional) If you want to forward metrics and you haven’t already created a Splunk Index for metrics, take the steps below to add one. You can do the same for events, although you could also use the existing, default “main” index.

  1. Open the Splunk web interface and log in.
  2. Select Settings, then select Indexes.
  3. Select New Index.
  4. Add a Name.
  5. For the Index Data Type, select Metrics or Events.
  6. Select Save.

Set up Splunk to Monitor Data:

  1. Open the Splunk web interface and log in.
  2. On the Explore Splunk Enterprise menu, select Add Data.
  3. Select Monitor as the data method.
  4. On the Add Data Select Source page, select HTTP Event Collector.
  5. Add a Name.
  6. Add a Description.
  7. Select Next.
  8. On the Add Data Input Settings page, select one or more of the available Splunk Indexes with the appropriate Index Data Type.
  9. Select Review.
  10. On the summary page, copy and save the token value. You’ll configure NGINX Controller with this value later.

Add a Splunk Integration

Take the following steps to create an Integration for Splunk:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Integrations.
  4. On the Integrations menu, select the Create Integration quick action.
  5. Add a name.
  6. (Optional) Add a display name.
  7. (Optional) Add a description.
  8. (Optional) Add tags.
  9. In the Integration Type list, select GENERIC_INTEGRATION.
  10. In the Endpoint URI box, add the Splunk collector URL.
  11. In the Credential Type list, select API_KEY.
  12. In the API Key box, add the Splunk token value .
  13. Select Submit.

Create a Syslog Integration

Syslog Integration Requirements

Confirm that your Syslog server meets the following requirements:

Network protocol

The syslog server should be able to receive data via one of the following protocols:

  • TCP - for unencrypted connections.
  • TLS - for encrypted connections. Validation of the Certificate Authority (CA) and mutual TLS are currently not supported.

Syslog Format

  • The forwarder produces RFC-5424 -compliant messages.

  • For delimiting, the octet count is added to every syslog message. See RFC-5425 for details.

Example of a message sent by the forwarder in syslog format:

<6>1 2019-09-10T06:40:15+02:00 controller.fqdn.svc nginx_controller 1 ngxctrl [dimensions alias="my_system" category="agent event" counter="1" instance="" instance.tags="tag1,tag2" level="INFO" local_id="d23c85484ee760ee5f4619c0434e1968b5290964487541da0889964eb783613c" location="" message="nginx stub_status detected, https://127.0.0.1:443/basic_status" parent_hostname="d0784771a503" root_uuid="49946669ca315d45bae1d6c05de9bd7e"] nginx stub_status detected, https://127.0.0.1:443/basic_status

Example configuration for Syslog-NG

The example of syslog-ng.conf that receives messages over TLS:

@version: 3.29
@include "scl.conf"

source s_network { default-network-drivers( tls(key-file("/key.pem") cert-file("/cert.pem") peer-verify(optional-trusted))

<span style="color:#75715e"># the optional flag that enables the access to $RAWSMSG</span>
flags<span style="color:#f92672">(</span>store-raw-message<span style="color:#f92672">)</span>
<span style="color:#f92672">)</span>;

};

destination d_remote { file("/var/log/controller.events.log");

<span style="color:#75715e"># if you want to see the raw message with all dimensions:</span>
file<span style="color:#f92672">(</span><span style="color:#e6db74">&#34;/var/log/controller.events.raw.log&#34;</span> template<span style="color:#f92672">(</span><span style="color:#e6db74">&#34;</span><span style="color:#e6db74">${</span>RAWMSG<span style="color:#e6db74">}</span><span style="color:#e6db74">\n&#34;</span><span style="color:#f92672">))</span>;

};

log { source(s_network); destination(d_remote); };

Add a Syslog Integration

Take the following steps to create an Integration for syslog:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Integrations.
  4. On the Integrations menu, select the Create Integration quick action.
  5. Add a name.
  6. (Optional) Add a display name.
  7. (Optional) Add a description.
  8. (Optional) Add tags.
  9. In the Integration Type list, select GENERIC_INTEGRATION.
  10. In the Endpoint URI box, add the TCP endpoint for your syslog. Syslog’s URL can be provided in two formats:
    • tcp://hostname[:port] for unencrypted TCP connections (example: tcp://192.168.0.1:601).
    • tcp+tls://hostname[:port] for encrypted TCP connections with TLS (example: tcp+tls://192.168.0.1:6514)
  11. In the Credential Type list, select UNAUTHENTICATED.
  12. Select Submit.

View, Edit, and Delete Integrations

Take the following steps to view, edit, or delete an Integration:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Integrations.
  4. On the Integrations menu, select Overview.
  5. To view the details for an Integration, choose the Integration from the list. This opens a side panel where you can view the Integration’s linked Locations .
  6. To edit an Integration, choose the Integration from the list, then select Edit (pencil icon).
  7. To delete an Integration, choose the Integration from the list, then select Delete (trash icon).

What’s Next


This documentation applies to the following versions of NGINX Controller Documentation: 3.6, 3.7, 3.8, 3.9, 3.10, 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17 and 3.18.