{"id":20260400,"url":"https://github.com/influxdata/telegraf-operator","last_synced_at":"2025-03-22T11:09:55.308Z","repository":{"id":37440660,"uuid":"224845097","full_name":"influxdata/telegraf-operator","owner":"influxdata","description":"telegraf-operator helps monitor application on Kubernetes with Telegraf ","archived":false,"fork":false,"pushed_at":"2025-03-13T00:26:42.000Z","size":502,"stargazers_count":82,"open_issues_count":26,"forks_count":36,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-14T13:06:25.800Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/influxdata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-29T11:54:31.000Z","updated_at":"2024-12-31T02:59:23.000Z","dependencies_parsed_at":"2022-08-03T03:46:17.301Z","dependency_job_id":"28a1b7b0-7fee-4b71-9e9f-fb3398fb3310","html_url":"https://github.com/influxdata/telegraf-operator","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Ftelegraf-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Ftelegraf-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Ftelegraf-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Ftelegraf-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/influxdata","download_url":"https://codeload.github.com/influxdata/telegraf-operator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244806562,"owners_count":20513461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T11:19:26.763Z","updated_at":"2025-03-22T11:09:55.252Z","avatar_url":"https://github.com/influxdata.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegraf-operator\n\n[![Docker Repository on Quay](https://quay.io/repository/influxdb/telegraf-operator/status \"Docker Repository on Quay\")](https://quay.io/repository/influxdb/telegraf-operator)\n[![CircleCI](https://circleci.com/gh/influxdata/telegraf-operator/tree/master.svg?style=svg)](https://circleci.com/gh/influxdata/telegraf-operator/tree/master)\n\n# The motto\nEasy things should be easy. Adding monitoring to your application has never been as easy as now.\n\nDoes your application exposes prometheus metrics? then adding `telegraf.influxdata.com/port: \"8080\"` annotation to the pod is the only thing you need to add telegraf scraping to it\n\n# Why telegraf-operator?\n\nNo one likes monitoring/observability, everybody wants to deploy applications but the burden of adding monitoring, fixing it, maintaining it should not weight that much.\n\n# Getting started with telegraf-operator\n\nReleasing docker images at: [Quay](https://quay.io/repository/influxdb/telegraf-operator?tag=latest\u0026tab=tags)\n\n## Installing telegraf-operator in your Kubernetes cluster\n\n### Helm chart\n\nAn up to date version of `telegraf-operator` can be installed by using the [InfluxData Helm Repository](https://helm.influxdata.com/).\n\nSimply run:\n\n```shell\nhelm repo add influxdata https://helm.influxdata.com/\nhelm upgrade --install telegraf-operator influxdata/telegraf-operator\n```\n\nTo change one or more settings, please use the `--set` option - such as:\n\n```shell\nhelm upgrade --install telegraf-operator influxdata/telegraf-operator \\\n  --set certManager.enable=true\n```\n\nThe `certManager.enable` setting will use [`cert-manager`](https://cert-manager.io/) CRDs to generate TLS certificates for the webhook admission controller used by `telegraf-operator`. Please note that this requires [`cert-manager`](https://cert-manager.io/) to be installed in the cluster to work.\n\nIt is recommended to use a [values file](https://helm.sh/docs/chart_template_guide/values_files/) instead of setting name-values.\n\nIt's also recommended to configure the [`classes.data`](https://github.com/influxdata/helm-charts/blob/62b039f/charts/telegraf-operator/values.yaml#L10-L18) values, which specify the telegraf-operator classes and how gathered data should be stored or persisted. Classes are described in more details in [Global configuration - classes](#global-configuration---classes) section.\n\nFor example:\n\n```yaml\nclasses:\n  data:\n    default: |\n      [[outputs.file]]\n        files = [\"stdout\"]\n```\n\nThis will cause telegraf for `default` class of monitored workloads to write their data to standard output of the telegraf container.\n\nAll of the available settings can be found in the [`values.yaml`](https://github.com/influxdata/helm-charts/blob/master/charts/telegraf-operator/values.yaml) file bundled with the Helm chart.\n\nInformation about the Helm chart can also be found at [https://artifacthub.io/packages/helm/influxdata/telegraf-operator](https://artifacthub.io/packages/helm/influxdata/telegraf-operator).\n\n### OperatorHub\n\nAn up to date version of `telegraf-operator` is also available from [OperatorHub.io](https://operatorhub.io/).\n\nPlease follow instructions at [https://operatorhub.io/operator/telegraf-operator](https://operatorhub.io/operator/telegraf-operator) for installing `telegraf-operator`.\n\n## Adding annotations to workloads\n\nIn order for `telegraf-operator` to monitor a workload, one or more annotations need to be added to the pod. The `telegraf.influxdata.com/class` annotation specifies which class of workload it is. It also needs information on how to scrape data. For prometheus metrics the annotation is `telegraf.influxdata.com/ports`, which specifies port or ports to scrape at. The default path is `/metrics` and can be changed.\n\nBy default `telegraf-operator` comes with an example `default` class configured to write to an in-cluster instance of InfluxDB.\n\nFor `Deployment`, `StatefulSet` and most other Kubernetes objects, this should be added to `.spec.template.metadata.annotations` section - such as:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\n# ...\nspec:\n  # ...\n  template:\n    metadata:\n      annotations:\n        telegraf.influxdata.com/class: \"default\"\n        telegraf.influxdata.com/ports: \"8080\"\n    spec:\n      # ...\n```\n\nPlease see [Pod-level annotations](#pod-level-annotations) for more details on all annotations `telegraf-operator` supports.\n\n## Adding telegraf-operator in development mode\n\nFor development purposes, the repository provides a development version that can be installed by running:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/influxdata/telegraf-operator/master/deploy/dev.yml \n```\n\nThe command above deploys telegraf-operator, using a separate `telegraf-operator` namespace and registering webhooks that will inject a telegraf sidecar to all newly created pods.\n\nIn order to use `telegraf-operator`, what's also needed is to define where metrics should be sent.\nThe [examples/classes.yml](examples/classes.yml) file provides a set of classes that can be used to get started.\n\nTo create sample set of classes, simply run:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/influxdata/telegraf-operator/master/examples/classes.yml\n```\n\n## Installing InfluxDB for data retrieval\n\nIn order to see the data, you can also deploy [InfluxDB](https://github.com/influxdata/influxdb/) v1 in your cluster, which also comes with [Chronograf](https://www.influxdata.com/time-series-platform/chronograf/), providing a web UI for InfluxDB v1.\n\nTo set it up in your cluster, simply run:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/influxdata/telegraf-operator/master/deploy/influxdb.yml \n```\n\nAfter that, every new pod (created directly or by creating a deployment or statefulset) in your cluster will have include telegraf container for retrieving data.\n\n## Installing a sample application with telegraf-operator based monitoring set up\n\nYou can try it by running one of our samples - such as a redis server. Simply do:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/influxdata/telegraf-operator/master/examples/redis.yml\n```\n\nYou can verify the telegraf container is present by doing:\n\n```shell\nkubectl describe pod -n redis redis-0\n```\n\nThe output should include a `telegraf` container.\n\nIn order to see the results in InfluxDB and Chronograf, you will need to set up port-forwarding and then access Chronograf from your browser:\n\n```shell\nkubectl port-forward --namespace=influxdb svc/influxdb 8888:8888\n```\n\nNext, go to [http://localhost:8888](http://localhost:8888) and continue to [Explore](http://localhost:8888/sources/0/chronograf/data-explorer) section to see your data \n\n# Configuration and usage\n\nTelegraf-operator consists of the following:\n\n* Global configuration - definition of where the metrics should be sent and other auxiliary configuration, specified as classes\n* Pod-level configuration - definition of how a pod can be monitored, such as ports for Prometheus scraping and additional configurations\n\n## Global configuration - classes\n\nTelegraf-operator is based on concepts of globally defined classes. Each class is a subset of Telegraf configuration and usually defines where Telegraf should be sending its outputs, along with other settings such as global tags.\n\nUsually classes are defined as a secret - such as in [classes.yml](examples/classes.yml) file - and each class maps to a key in a secret. For example:\n\n```\nstringData:\n  basic: |+\n    [[outputs.influxdb]]\n      urls = [\"http://influxdb.influxdb:8086\"]\n    [[outputs.file]]\n      files = [\"stdout\"]\n    [global_tags]\n      hostname = \"$HOSTNAME\"\n      nodename = \"$NODENAME\"\n      type = \"app\"\n```\n\nThe above defines that any pod whose Telegraf class is `basic` will have its metrics sent to a specific URL, which in this case is an InfluxDB v1 instance deployed in same cluster. Its metrics will also be logged by `telegraf` container for convenience. The data will also have `hostname`, `nodename` and `type` tags added for all metrics.\n\n## Hot reload\n\nAs of version 1.3.0, telegraf-operator supports detecting when the classes configuration has changed and update telegraf configuration for affected pods.\n\nThis functionality requires telegraf version 1.19, which is the first version that supports the new `--watch-config` option required for this feature.\n\nThe [development deployment example](deploy/dev.yml) has hot reload enabled. For Helm chart, version 1.3.0 or newer has to be used and `hotReload` should be set to true. It is set to false by default to avoid issues when using a version of telegraf prior to 1.19.0.\n\nIf deploying telegraf-operator in a different way, `telegraf-operator` should be run with `--telegraf-watch-config=inotify` option. The `args` section of the `telegraf-operator` Deployment should be added or modified and include the said options - such as:\n\n```\n          args:\n            - --enable-default-internal-plugin=true\n            - --telegraf-default-class=basic\n            - --telegraf-classes-directory=/config/classes\n            - --enable-istio-injection=true\n```\n\n## Pod-level annotations\n\nEach pod (either standalone or as part of deployment as well as statefulset) may also specify how it should be monitored using metadata.\n\nThe [redis.yml](examples/redis.yml) example adds annotation that enables the Redis plugin so that Telegraf will automatically retrieve metrics related to it.\n\n```\napiVersion: apps/v1\nkind: StatefulSet\n  # ...\nspec:\n  template:\n    metadata:\n      annotations:\n        telegraf.influxdata.com/inputs: |+\n          [[inputs.redis]]\n            servers = [\"tcp://localhost:6379\"]\n        telegraf.influxdata.com/class: basic\n      # ...\n    spec:\n      containers:\n      - name: redis\n        image: redis:alpine\n```\n\nPlease see [redis input plugin documentation](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/redis) for more details on how the plugin can be configured.\n\nThe `telegraf.influxdata.com/class` specifies that the `basic` class above should be used.\n\nUsers can configure the `inputs.prometheus` plugin by setting the following annotations. Below is an [example configuration](#example-prometheus-scraping), and the expected output.\n- `telegraf.influxdata.com/port`: is used to configure which port telegraf should scrape\n- `telegraf.influxdata.com/ports` : is used to configure which port telegraf should scrape, comma separated list of ports to scrape\n- `telegraf.influxdata.com/path` : is used to configure at which path to configure scraping to (a port must be configured also), will apply to all ports if multiple are configured\n- `telegraf.influxdata.com/scheme` : is used to configure at the scheme for the metrics to scrape, will apply to all ports if multiple are configured ( only `http` or `https` are allowed as values)\n- `telegraf.influxdata.com/interval` : is used to configure interval for telegraf scraping (Go style duration, e.g 5s, 30s, 2m .. )\n- `telegraf.influxdata.com/metric-version` : is used to configure which metrics parsing version to use (1, 2)\n- `telegraf.influxdata.com/namepass` : is used to configure scraped metrics to preserve configuration for `telegraf`, being a TOML value to add to telegraf configuration; all metrics are passed if not specified\n\n**NOTE**: all annotations should be formatted as strings - for example `telegraf.influxdata.com/port: \"8080\"`, `telegraf.influxdata.com/metric-version: \"2\"` or  `telegraf.influxdata.com/namepass: \"['metric1','metric2']\"`.\n\n### Example Prometheus Scraping\n\n```\napiVersion: apps/v1\nkind: StatefulSet\n  # ...\nspec:\n  template:\n    metadata:\n      annotations:\n        telegraf.influxdata.com/class: influxdb # User defined output class\n        telegraf.influxdata.com/interval: 30s\n        telegraf.influxdata.com/path: /metrics\n        telegraf.influxdata.com/port: \"8086\"\n        telegraf.influxdata.com/scheme: http\n        telegraf.influxdata.com/metric-version: \"2\"\n      # ...\n    spec:\n      containers:\n      - name: influxdb\n        image: quay.io/influxdb/influxdb:v2.0.4\n```\n\n#### Configuration Output\n\n```\n[[inputs.prometheus]]\n  urls = [\"http://127.0.0.1:8086/metrics\"]\n  interval = \"30s\"\n  metric_version = 2\n\n[[inputs.internal]]\n```\n\n\nAdditional pod annotations that can be used to configure the Telegraf sidecar:\n- `telegraf.influxdata.com/inputs` : is used to configure custom inputs for telegraf\n- `telegraf.influxdata.com/internal` : is used to enable telegraf \"internal\" input plugins for\n- `telegraf.influxdata.com/image` : is used to configure telegraf image to be used for the `telegraf` sidecar container\n- `telegraf.influxdata.com/class` : configures which kind of class to use (classes are configured on the operator)\n- `telegraf.influxdata.com/secret-env` : allows adding secrets to the telegraf sidecar in the form of environment variables\n- `telegraf.influxdata.com/env-configmapkeyref-\u003cVARIABLE_NAME\u003e` : allows adding configmap key references to the telegraf sidecar in the form of an environment variable\n- `telegraf.influxdata.com/env-fieldref-\u003cVARIABLE_NAME\u003e` : allows adding fieldref references to the telegraf sidecar in the form of an environment variable\n- `telegraf.influxdata.com/env-literal-\u003cVARIABLE_NAME\u003e` : allows adding a literal to the telegraf sidecar in the form of an environment variable\n- `telegraf.influxdata.com/env-secretkeyref-\u003cVARIABLE_NAME\u003e` : allows adding secret key references to the telegraf sidecar in the form of an environment variable\n- `telegraf.influxdata.com/requests-cpu` : allows specifying resource requests for CPU\n- `telegraf.influxdata.com/requests-memory` : allows specifying resource requests for memory\n- `telegraf.influxdata.com/limits-cpu` : allows specifying resource limits for CPU\n- `telegraf.influxdata.com/limits-memory` : allows specifying resource limits for memory\n- `telegraf.influxdata.com/istio-requests-cpu` : allows specifying resource requests for CPU for istio sidecar\n- `telegraf.influxdata.com/istio-requests-memory` : allows specifying resource requests for memory for istio sidecar\n- `telegraf.influxdata.com/istio-limits-cpu` : allows specifying resource limits for CPU for istio sidecar\n- `telegraf.influxdata.com/istio-limits-memory` : allows specifying resource limits for memory for istio sidecar\n- `telegraf.influxdata.com/volume-mounts` : allows specifying extra volumes mount into the telegraf sidecar, the value should be json formatted, eg: {\"volumeName\": \"mountPath\"}\n\n\n##### Example of extra additional options\n\n```\napiVersion: apps/v1\nkind: StatefulSet\n  # ...\nspec:\n  template:\n    metadata:\n      labels:\n        app: redis\n      annotations:\n        telegraf.influxdata.com/env-fieldref-NAMESPACE: metadata.namespace\n        telegraf.influxdata.com/env-fieldref-APP: metadata.labels['app']\n        telegraf.influxdata.com/env-configmapkeyref-REDIS_SERVER: configmap-name.redis.url\n        telegraf.influxdata.com/env-secretkeyref-PASSWORD: app-secret.redis.password\n        telegraf.influxdata.com/env-literal-VERSION: \"1.0\"\n        telegraf.influxdata.com/volume-mounts: {\"xxx-3080bfa7-log\":\"/opt/xxx/log\"}\n        telegraf.influxdata.com/inputs: |+\n          [[inputs.redis]]\n            servers = [\"$REDIS_SERVER\"]\n            password = \"$PASSWORD\"\n      # ...\n    spec:\n      containers:\n      # ...\n```\nThese annotations result in additional environment variables available for the telegraf container, which can be used in for example the tags.   \nAnd they can be used in the additional input configuration provided in the annotation as shown above.\n\n```\nstringData:\n  basic: |+\n    [global_tags]\n      hostname = \"$HOSTNAME\"\n      nodename = \"$NODENAME\"\n      namespace = \"$NAMESPACE\"\n      app = \"$APP\"\n      version = \"$VERSION\"\n```\n\n# Support\n\nThis operator is community supported. InfluxData provides no official support for their use.\n\nPull requests and issues are the responsibility of the project's moderator(s) which may include vetted individuals outside of the InfluxData organization. All issues should be reported and managed via GitHub (not via InfluxData's standard support process).\n\n# Contributing to telegraf-operator\n\nPlease read the [CONTRIBUTING](CONTRIBUTING.md) file for more details on how to get started with contributing to to `telegraf-operator`.\n\n# Maintainers\n\n- [gitirabassi](https://github.com/gitirabassi)\n- [rawkode](https://github.com/rawkode)\n- [wojciechka](https://github.com/wojciechka/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfluxdata%2Ftelegraf-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfluxdata%2Ftelegraf-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfluxdata%2Ftelegraf-operator/lists"}