Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Release notes for Grafana Agent Operator
The release notes provide information about deprecations and breaking changes in Grafana Agent static mode Kubernetes operator.
For a complete list of changes to Grafana Agent, with links to pull requests and related issues when available, refer to the Changelog.
Note
These release notes are specific to the Static mode Kubernetes Operator. Other release notes for the different Grafana Agent variants are contained on separate pages:
v0.33
Symbolic links in Docker containers removed
We’ve removed the deprecated symbolic links to /bin/agent*
in Docker
containers, as planned in v0.31. In case you’re setting a custom entrypoint,
use the new binaries that are prefixed with /bin/grafana*
.
v0.31
Breaking change: binary names are now prefixed with grafana-
As first announced in v0.29, the grafana-operator
release binary names is now
prefixed with grafana-
:
agent-operator
is nowgrafana-agent-operator
.
For the grafana/agent-operator
Docker container, the entrypoint is now
/bin/grafana-agent-operator
. A symbolic link from /bin/agent-operator
to
the new binary has been added.
Symbolic links will be removed in v0.33. Custom entrypoints must be updated prior to v0.33 to use the new binaries before the symbolic links get removed.
v0.29
Deprecation: binary names will be prefixed with grafana-
in v0.31.0
The agent-operator
binary name has been deprecated and will be renamed to
grafana-agent-operator
in the v0.31.0 release.
As part of this change, the Docker container for the v0.31.0 release will include symbolic links from the old binary names to the new binary names.
There is no action to take at this time.
v0.24
Breaking change: Grafana Agent Operator supported Agent versions
The v0.24.0 release of Grafana Agent Operator can no longer deploy versions of Grafana Agent prior to v0.24.0.
v0.19
Rename of Prometheus to Metrics (Breaking change)
As a part of the deprecation of “Prometheus,” all Operator CRDs and fields with “Prometheus” in the name have changed to “Metrics.”
This includes:
- The
PrometheusInstance
CRD is nowMetricsInstance
(referenced bymetricsinstances
and notmetrics-instances
within ClusterRoles). - The
Prometheus
field of theGrafanaAgent
resource is nowMetrics
PrometheusExternalLabelName
is nowMetricsExternalLabelName
This is a hard breaking change, and all fields must change accordingly for the operator to continue working.
Note that old CRDs with the old hyphenated names must be deleted (kubectl delete crds/{grafana-agents,prometheus-instances}
) for ClusterRoles to work
correctly.
To do a zero-downtime upgrade of the Operator when there is a breaking change,
refer to the new agentctl operator-detatch
command: this will iterate through
all of your objects and remove any OwnerReferences to a CRD, allowing you to
delete your Operator CRDs or CRs.
Rename of CRD paths (Breaking change)
prometheus-instances
and grafana-agents
have been renamed to
metricsinstances
and grafanaagents
respectively. This is to remain
consistent with how Kubernetes names multi-word objects.
As a result, you will need to update your ClusterRoles to change the path of resources.
To do a zero-downtime upgrade of the Operator when there is a breaking change,
refer to the new agentctl operator-detatch
command: this will iterate through
all of your objects and remove any OwnerReferences to a CRD, allowing you to
delete your Operator CRDs or CRs.
Example old ClusterRole:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: grafana-agent-operator
rules:
- apiGroups: [monitoring.grafana.com]
resources:
- grafana-agents
- prometheus-instances
verbs: [get, list, watch]
Example new ClusterRole:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: grafana-agent-operator
rules:
- apiGroups: [monitoring.grafana.com]
resources:
- grafanaagents
- metricsinstances
verbs: [get, list, watch]