Note
Fleet Management is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. For bug reports or questions, fill out our feedback form.
The Pipeline HTTP API
The Grafana Fleet Management Pipeline API allows you to perform CRUD operations on configuration pipelines.
For a full definition of the Pipeline API, refer to the .proto
file.
Base URL
You can find the base URL for the Pipeline API in the Grafana Cloud Fleet Management interface.
- In your Grafana Cloud stack, click Connections > Collector > Fleet Management in the left-side menu.
- On the Fleet Management interface, switch to the API tab.
- Find the URL in the Base URL section.
It looks like the following URL, where
<CLUSTER_NAME>
is the production cluster of your stack:
https://fleet-management-<CLUSTER_NAME>.grafana.net/pipeline.v1.PipelineService/
PipelineService
The PipelineService
defines the RPCs for managing pipelines.
Endpoints
CreatePipelineRequest
CreatePipelineRequest
is the request to create a new pipeline.
DeletePipelineRequest
DeletePipelineRequest
is the request to delete a pipeline by its ID.
DeletePipelineResponse
DeletePipelineResponse
is the response to deleting a pipeline.
This message is empty and the results of the deletion are defined by the HTTP status code of the response.
GetPipelineRequest
GetPipelineRequest
is the request to retrieve a pipeline by its ID.
GetPipelineIDRequest
GetPipelineIDRequest
is the request to retrieve a pipeline ID by its name.
GetPipelineIDResponse
GetPipelineIDResponse
is the response to retrieving a pipeline ID.
ListPipelinesRequest
ListPipelinesRequest
is the request to get the full list of pipelines, including their contents and matchers.
Pipeline
A Pipeline
is a self-contained piece of configuration that can be assigned to collectors based on matchers.
Pipelines
Pipelines
represents a list of pipelines.
UpdatePipelineRequest
UpdatePipelineRequest
is the request to update an existing pipeline.
This contents supplied in this request replace the existing pipeline contents, so any fields that are not set are removed.
If the pipeline does not already exist, this request returns a 404 ‘NOT_FOUND’ error.
UpsertPipelineRequest
UpsertPipelineRequest
is the request to create a new pipeline or update an existing one.
If the pipeline already exists, it is updated and like UpdatePipelineRequest
, any fields that are not set are removed.
Examples
Pipeline API requests and responses require proper escaping of the pipeline contents. For this reason, some use of jq
is helpful. In this example, the contents of the pipeline are saved in a file named config.alloy
.
To build a payload for the CreatePipeline
and UpsertPipeline
requests with properly escaped content, the following command is a good starting point.
It redirects the content to a create-pipeline.json
file for easier handling.
jq --arg contents "$(cat config.alloy)" \
--arg name "myname" \
--argjson matchers '["collector.os=linux", "team!=team-a"]' \
--argjson enabled true \
'.pipeline = {name: $name, contents: $contents, matchers: $matchers, enabled: $enabled}' \
<<< '{}' > create-pipeline.json
The CreatePipeline
response verifies what was created and also lists the unique ID for this pipeline.
curl -q \
-d @create-pipeline.json \
-u "user:pass" \
--header "Content-Type: application/json" \
-X POST https://fleet-management-prod-001.grafana.net/pipeline.v1.PipelineService/CreatePipeline
{
"name": "myname",
"contents": " ... pipeline contents ...",
"matchers": [
"collector.os=\"linux\"",
"team!=\"team-a\""
],
"enabled": true,
"id": "22234"
}
The ListPipelines
request takes an empty payload and returns all available pipelines.
You can use a similar jq
command to build an UpdatePipeline
request redirected to update-pipeline.json
, by adding the unique pipeline ID.
jq --arg contents "$(cat config.alloy)" \
--arg id "22234" \
--arg name "myname" \
--argjson matchers '["collector.os=linux", "team!=team-a"]' \
--argjson enabled true \
'.pipeline = {id: $id, name: $name, contents: $contents, matchers: $matchers, enabled: $enabled}' \
<<< '{}' > update-pipeline.json
The UpdatePipeline
response verifies what was updated.
curl -q \
-d @update-pipeline.json \
-u "user:pass" \
--header "Content-Type: application/json" \
-X POST https://fleet-management-prod-001.grafana.net/pipeline.v1.PipelineService/UpdatePipeline
{
"name": "myname",
"contents": " ... new pipeline contents ...",
"matchers": [
"collector.os=\"linux\"",
"team!=\"team-a\""
],
"enabled": true,
"id": "22234"
}
Finally, the GetPipeline
and DeletePipeline
requests require only an ID.