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:
The PipelineService defines the RPCs for managing pipelines.
Method Name
Request Type
Response Type
Description
GetPipeline
GetPipelineRequest
Pipeline
Returns a pipeline by ID
GetPipelineID
GetPipelineIDRequest
GetPipelineIDResponse
Returns a pipeline ID by name
ListPipelines
ListPipelinesRequest
Pipelines
Returns all pipelines
CreatePipeline
CreatePipelineRequest
Pipeline
Creates a new pipeline and returns it
UpdatePipeline
UpdatePipelineRequest
Pipeline
Updates an existing pipeline and returns it
UpsertPipeline
UpsertPipelineRequest
Pipeline
Creates a new pipeline or updates an existing one and returns it
DeletePipeline
DeletePipelineRequest
DeletePipelineResponse
Deletes a pipeline by ID
ListPipelinesRevisions
ListPipelinesRevisionsRequest
PipelineRevisions
Returns all pipeline revisions
ListPipelineRevisions
ListPipelineRevisionsRequest
PipelineRevisions
Returns all pipeline revisions for a single pipeline by ID
GetPipelineRevision
GetPipelineRevisionRequest
PipelineRevision
Returns a pipeline revision by revision ID
Endpoints
CreatePipelineRequest
CreatePipelineRequest is the request to create a new pipeline.
Field
Type
Label
Description
pipeline
Pipeline
required
The pipeline to create
validate_only
bool
optional
If set, validates the request and previews the response, but doesn’t create the actual resource
DeletePipelineRequest
DeletePipelineRequest is the request to delete a pipeline by its ID.
Field
Type
Label
Description
id
string
required
ID of the pipeline to delete
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.
Field
Type
Label
Description
id
string
required
ID of the pipeline to get
GetPipelineIDRequest
GetPipelineIDRequest is the request to retrieve a pipeline ID by its name.
Field
Type
Label
Description
name
string
required
Name of the pipeline to get the ID for
GetPipelineIDResponse
GetPipelineIDResponse is the response to retrieving a pipeline ID.
Field
Type
Label
Description
id
string
ID of the pipeline
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.
Field
Type
Label
Description
name
string
required
Name of the pipeline which is the unique identifier for the pipeline
contents
string
required
Configuration contents of the pipeline to be used by collectors
matchers
list(string)
Used to match against collectors and assign pipelines to them; follows the syntax of Prometheus Alertmanager matchers
created_at
google.protobuf.Timestamp
optional
Timestamp when the pipeline was created
updated_at
google.protobuf.Timestamp
optional
Timestamp when the pipeline was last updated
enabled
bool
optional
Whether the pipeline is enabled for collectors
id
string
optional
Server-assigned ID of the pipeline
Pipelines
Pipelines represents a list of pipelines.
Field
Type
Label
Description
pipelines
list(Pipeline)
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.
Field
Type
Label
Description
pipeline
Pipeline
required
Contents of the pipeline to update
validate_only
bool
optional
If set, validates the request and previews the response, but doesn’t update the actual resource
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.
Field
Type
Label
Description
pipeline
Pipeline
required
Pipeline to create or update
ListPipelinesRevisionsRequest
ListPipelinesRevisionsRequest is the request to get the full list of pipelines revisions, excluding contents.
ListPipelineRevisionsRequest
ListPipelineRevisionsRequest is the request to retrieve pipeline revisions by pipeline ID.
Field
Type
Label
Description
id
string
required
ID of the pipeline to get
GetPipelineRevisionRequest
GetPipelineRevisionRequest is the request to retrieve a pipeline revision by revision ID.
Field
Type
Label
Description
revision_id
string
required
ID of the pipeline revision to get
PipelineRevision
A PipelineRevision represents a point in time for a Pipeline.
Field
Type
Label
Description
revision_id
string
required
Server-assigned ID of the pipeline revision
snapshot
Pipeline
required
The pipeline at the point in time of the revision
created_at
google.protobuf.Timestamp
required
Timestamp when the pipeline revision was created
operation
PipelineRevision.Operation
required
The operation that was performed on the pipeline which created the revision
PipelineRevision.Operation
Value
Description
UNSPECIFIED
Unknown revision operation
INSERT
The pipeline was created at the time of this revision
UPDATE
The pipeline was updated at the time of this revision
DELETE
The pipeline was deleted at the time of this revision
PipelineRevisions
PipelineRevisions represents a list of pipeline revisions.
Field
Type
Label
Description
pipeline_revisions
list(PipelineRevision)
List of pipeline revisions
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.
alloy
--- config.alloy ---
prometheus.exporter.self"alloy"{}prometheus.scrape"alloy"{targets = prometheus.exporter.self.alloy.targets
forward_to =[prometheus.remote_write.grafanacloud.receiver]scrape_interval ="60s"}prometheus.remote_write"grafanacloud"{// Must match the uniquely-identifiable ID set up in the remotecfg block.external_labels ={"collector_id"= constants.hostname}endpoint{url = <SERVICE_URL>
basic_auth{username = <USERNAME>
password_file = <PASSWORD_FILE>
}}}
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.
The revision RPCs allow for revisiting the history of changes to pipeline
objects for a user.
ListPipelinesRevisions lists all changes in chronological order alongside the
operation that initiated them. For brevity, the response omits the
configuration contents of the pipeline in each snapshot.
Similarly, ListPipelineRevisions allows for viewing the state of a single
pipeline ID at every point in time it was changed, along with a full snapshot
of the pipeline object.