From 15bb201ed7be31b0995512d5aeb3b6d170160578 Mon Sep 17 00:00:00 2001 From: pascal-fischer <32096965+pascal-fischer@users.noreply.github.com> Date: Mon, 8 Jan 2024 17:24:12 +0100 Subject: [PATCH] Add docs for event streaming (#123) --- misc/event-streaming/api.md | 153 ++++++++++++++++++++++++ misc/event-streaming/event-streaming.md | 39 ++++++ 2 files changed, 192 insertions(+) create mode 100644 misc/event-streaming/api.md create mode 100644 misc/event-streaming/event-streaming.md diff --git a/misc/event-streaming/api.md b/misc/event-streaming/api.md new file mode 100644 index 00000000..e2cd5692 --- /dev/null +++ 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 ' \ + --header 'Content-Type: application/json' \ + --data '{ + "platform": "datadog", + "config": { + "api_url": "https://http-intake.logs.datadoghq.eu/api/v2/logs", + "api_key": "" + }, + "enabled": true +}' +``` + +Response +```json +{ + "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/ \ + --header 'Accept: application/json' \ + --header 'Authorization: Token ' +``` + +Response +```json +{ + "id": , + "client_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 ' +``` + +Response +```json +[ + { + "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/ \ + --header 'Accept: application/json' \ + --header 'Authorization: Token ' \ + --header 'Content-Type: application/json' \ + --data '{ + "platform": "datadog", + "config": { + "api_url": "https://http-intake.logs.datadoghq.com/api/v2/logs", + "api_key": "" + }, + "enabled": true + }' +``` + +Response +```json +{ + "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/ \ + --header 'Accept: application/json' \ + --header 'Authorization: Token ' +``` +Response +```json +{} +``` diff --git a/misc/event-streaming/event-streaming.md b/misc/event-streaming/event-streaming.md new file mode 100644 index 00000000..56742fed --- /dev/null +++ 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 ' \ + --header 'Content-Type: application/json' \ + --data '{ + "platform": "datadog", + "config": { + "api_url": "https://http-intake.logs.datadoghq.eu/api/v2/logs", + "api_key": "" + }, + "enabled": true +}' +``` + +>For further management of your event-streaming integration refer to the [event streaming API documentation](api.md). \ No newline at end of file