Create a Monitoring Pipeline Instance

To create or update a Pipeline, you need to provide the complete Pipeline configuration. If you wish to create a new Pipeline or modify an existing one with a specified ID, you should include all necessary details in your request. Optional fields will be automatically populated with default values or left empty if not provided. To ensure that the Pipeline is created or updated correctly, perform a PUT request with the full Pipeline data.

Pipeline authentication for secure metric ingestion

To ensure secure and authorized metric data submission, each Monitoring Pipeline is assigned a unique key upon creation. This key acts as a credential for metric exporters or agents pushing data to the pipeline's HTTP endpoint.

For security reasons, the API key is not returned in the response after creating a pipeline. It's crucial to store the key securely during pipeline creation for future reference.

Key points

• The key is included in the metadata section of the pipeline response (see "key": "momSrlgAAEmaYEvBsMr^HsYn" in the example).

• Metric exporters or agents must be configured to include this key in their requests to the pipeline's HTTP endpoint for successful data ingestion.

• This mechanism safeguards the pipeline from unauthorized data submissions and maintains data integrity within the Monitoring Service.

Best practices

• Store the pipeline key securely for authorized metric sources only.

• Avoid sharing or exposing the key publicly.

• Consider rotating pipeline keys periodically for enhanced security.

To create a Monitoring Pipeline, perform a POST request.

Request

curl --location \
--request POST 'https://monitoring.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $TOKEN' \
--data '{
  "metadata": {},
  "properties": {
    "name": "Pipeline1"
  }
}'

Request Body Parameters

Below is the list of mandatory body parameters for creating a Pipeline:

Body Parameters	Required	Type	Description	Example
metadata	no	object	Metadata	{}
properties	yes	object	A pipeline consists of the generic rules and configurations of a monitoring pipeline instance.	{ "name": "Pipeline1" }
properties.name	yes	string	Name of your Pipeline.	Pipeline1

Request Header Parameters

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters	Required	Type	Description
Authorization	yes	string	The Bearer token enables requests to authenticate using a JSON Web Token (JWT). The token can be generated using the Authentication API.
Content-Type	yes	string	Set this to application/json.

Response

The following is a sample response. The values returned by each response differ based on the request.

{
  "id": "f72521ba-1590-5998-bf96-6eb997a5887d",
  "type": "pipeline",
  "href": "/pipelines/f72521ba-1590-5998-bf96-6eb997a5887d",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "key": "momSrlgAAEmaYEvBsMr^HsYn",
    "grafanaEndpoint": "https://grafana.jf9ejf8t6hrt.logging.de-txl.ionos.com",
    "httpEndpoint": "https://f8ss7fgr7s-metrics.jf9ejf8t6hrt.monitoring.de-txl.ionos.com"
  },
  "properties": {
    "name": "Pipeline1"
  }
}

Result: A Monitoring Pipeline is successfully created.