Add docs for event streaming (#123)

netbirdio · Jan 8, 2024 · 15bb201 · 15bb201
1 parent f0873a2
commit 15bb201
Show file tree

Hide file tree

Showing 2 changed files with 192 additions and 0 deletions.
diff --git a/misc/event-streaming/api.md b/misc/event-streaming/api.md
@@ -0,0 +1,153 @@
+# Event-Streaming Integration API Documentation
+
+## Introduction
+This reference provides detailed information on managing event-streaming integrations via NetBird Cloud API.
+
+## Authentication
+Authentication is required for all API requests. Please refer to the [authentication guideline](https://docs.netbird.io/how-to/access-netbird-public-api) for how to create and authenticate API calls using Personal Access Tokens (PAT).
+
+## Event Streaming Endpoints
+
+### Create Integration
+Request:
+- `platform`: A string representing the platform name. For Datadog, the value is `datadog`.
+- `config`: A JSON object containing the configuration parameters for the respective platform.
+  - Datadog
+    - `api_url`: The URL of the Datadog HTTP API endpoint. This URL differs based on the region. To find the correct URL, refer to the [Datadog documentation](https://docs.datadoghq.com/api/latest/logs/#send-logs).
+    - `api_key`: The API key for the Datadog HTTP API endpoint. This key can be created in the [Datadog Console](https://app.datadoghq.com/organization-settings/api-keys).
+- `enabled`: A flag to enable/disable the integration.
+
+```shell
+curl --request POST \
+  --url https://api.netbird.io/api/integrations/event-streaming \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+      "platform": "datadog",
+      "config": {
+        "api_url": "https://http-intake.logs.datadoghq.eu/api/v2/logs",
+        "api_key": "<API_KEY>"
+      },
+      "enabled": true
+}'
+```
+
+Response
+```json
+{
+  "id": <ID>,
+  "account_id": "<ACCOUNT_ID>",
+  "enabled": true,
+  "platform": "datadog",
+  "created_at": "2024-01-04T14:03:26.634554Z",
+  "updated_at": "2024-01-04T14:03:26.634554Z",
+  "config": {
+    "api_key": "****",
+    "api_url": "https://http-intake.logs.datadoghq.eu/api/v2/logs"
+  }
+}
+```
+
+### Get Integration by ID
+Request
+```shell
+curl --request GET \
+  --url https://api.netbird.io/api/integrations/event-streaming/<ID> \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>'
+```
+
+Response
+```json
+{
+  "id": <ID>,
+  "client_id": "<CLIENT_ID>",
+  "tenant_id": "<TENANT_ID>",
+  "sync_interval": 300,
+  "enabled": true
+}
+```
+
+### Get All Integrations By AccountID
+Request
+```shell
+curl --request GET \
+  --url https://api.netbird.io/api/integrations/event-streaming \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>'
+```
+
+Response
+```json
+[
+  {
+    "id": <ID>,
+    "account_id": "<ACCOUNT_ID>",
+    "enabled": true,
+    "platform": "datadog",
+    "created_at": "2024-01-04T15:03:26.634554+01:00",
+    "updated_at": "2024-01-04T15:03:26.634554+01:00",
+    "config": {
+      "api_key": "****",
+      "api_url": "https://http-intake.logs.datadoghq.eu/api/v2/logs"
+    }
+  }
+]
+```
+
+### Update Integration
+Updates the selected parameters for a specific integration.
+
+Request:
+- `platform`: A string representing the platform name. For Datadog, the value is `datadog`.
+- `config`: A JSON object containing the configuration parameters for the respective platform.
+    - Datadog
+        - `api_url`: The URL of the Datadog HTTP API endpoint. This URL differs based on the region. To find the correct URL, refer to the [Datadog documentation](https://docs.datadoghq.com/api/latest/logs/#send-logs).
+        - `api_key`: The API key for the Datadog HTTP API endpoint. This key can be created in the [Datadog Console](https://app.datadoghq.com/organization-settings/api-keys).
+- `enabled`: A flag to enable/disable the integration.
+
+```shell
+curl --request PUT \
+  --url https://api.netbird.io/api/integrations/event-streaming/<ID> \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+      "platform": "datadog",
+      "config": {
+        "api_url": "https://http-intake.logs.datadoghq.com/api/v2/logs",
+        "api_key": "<API_KEY>"
+      },
+      "enabled": true
+  }'
+```
+
+Response
+```json
+{
+  "id": <ID>,
+  "account_id": "<ACCOUNT_ID>",
+  "enabled": true,
+  "platform": "datadog",
+  "created_at": "2024-01-04T14:03:26.634554Z",
+  "updated_at": "2024-01-04T14:03:26.634554Z",
+  "config": {
+    "api_key": "****",
+    "api_url": "https://http-intake.logs.datadoghq.eu/api/v2/logs"
+  }
+}
+```
+
+### Delete Integration
+Request
+```shell
+curl --request DELETE \
+  --url https://api.netbird.io/api/integrations/event-streaming/<ID> \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>'
+```
+Response
+```json
+{}
+```
diff --git a/misc/event-streaming/event-streaming.md b/misc/event-streaming/event-streaming.md
@@ -0,0 +1,39 @@
+# Introduction
+
+This document provides step-by-step instructions and best practices for setting up NetBird activity event streaming integrations to different third-party services.
+
+## Datadog
+
+Before you start creating and configuring a Datadog event-streaming integration, ensure that you have the following:
+- A Datadog account with the permissions to create and manage API keys. If you don't have the required permissions, ask your Datadog administrator to grant them to you.
+
+#### Step 1: Create a Datdog API key
+- Navigate to the [API Keys](https://app.datadoghq.eu/organization-settings/api-keys) page
+- Click `+ New Key` at the top
+- Give it a descriptive name like `NetBird Event Streaming`
+- Click `Create Key`
+- Copy the key. You will need this key when configuring an integration in NetBird.
+#### Step 2: Create an event-streaming integration in NetBird
+Use the NetBird API to create the integration. For this you can use the following cURL command with updated parameters:
+- `platform`: A string representing the platform name. For Datadog use `datadog`.
+- `config.api_url`: The URL of the Datadog HTTP API endpoint. This URL differs based on the region. To find the correct URL, refer to the [Datadog documentation](https://docs.datadoghq.com/api/latest/logs/#send-logs).
+- `config.api_key`: The API key for the Datadog HTTP API endpoint. This key can be created in the [Datadog Console](https://app.datadoghq.com/organization-settings/api-keys).
+- `enabled`: A flag to enable/disable the integration.
+
+```shell
+curl --request POST \
+  --url https://api.netbird.io/api/integrations/event-streaming \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+      "platform": "datadog",
+      "config": {
+        "api_url": "https://http-intake.logs.datadoghq.eu/api/v2/logs",
+        "api_key": "<API_KEY>"
+      },
+      "enabled": true
+}'
+```
+
+>For further management of your event-streaming integration refer to the [event streaming API documentation](api.md).