Additional Scrape Configs

Now that your application is running on Kubernetes, you need Prometheus to discover and scrape its metrics endpoints. There are two main approaches to add new targets:

Less preferred: append raw Prometheus scrape jobs via the Helm chart additionalScrapeConfigs values. This works but is fragile across Prometheus upgrades.
Preferred: use ServiceMonitors (Prometheus Operator-native). ServiceMonitors are Kubernetes-native and generally more robust.

Below is a focused walkthrough of the less preferred approach so you can see exactly what to change when using additionalScrapeConfigs. This is not a full Prometheus tutorial, but it shows the precise values and files you’ll edit.

Using additionalScrapeConfigs appends full Prometheus scrape job definitions to the configuration generated by the Prometheus Operator. Because these entries are treated as user-provided config, Prometheus will not validate them for you — an invalid scrape job can prevent Prometheus from starting. Use this option only when ServiceMonitors are unsuitable.

Summary comparison

Approach	When to use	Pros	Cons
`additionalScrapeConfigs`	When you need fine-grained control over raw Prometheus scrape jobs or cannot use CRDs	Direct control; familiar Prometheus `scrape_config` format	Fragile across Prometheus upgrades; no operator validation
ServiceMonitor	Recommended with Prometheus Operator	Kubernetes-native; operator-managed; safer for upgrades	Requires Prometheus Operator & CRDs

References:

1. Export the Helm chart default values

Generate the default values for kube-prometheus-stack so you can edit them locally:

helm show values prometheus-community/kube-prometheus-stack > values.yaml

The produced values.yaml contains all the chart settings. You’ll add your extra Prometheus job definitions under additionalScrapeConfigs.

2. Find `additionalScrapeConfigs` in the values file

Search values.yaml for additionalScrapeConfigs. The chart documents the setting and includes a warning about upgrade compatibility. A representative excerpt looks like:

# Additional VolumeMounts on the output StatefulSet definition.
volumeMounts: []

## AdditionalScrapeConfigs allows specifying additional Prometheus scrape configurations.
## Scrape configurations are appended to the configurations generated by the Prometheus Operator.
## Job configurations must have the form as specified in the official Prometheus documentation:
## https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config
## As scrape configs are appended, the user is responsible to make sure it is valid. Note that using this
## feature may expose the possibility to break upgrades of Prometheus. It is advised to review Prometheus
## release notes to ensure that no incompatible scrape configs are going to break Prometheus after the upgrade.
## AdditionalScrapeConfigs can be defined as a list or as a templated string.
##
additionalScrapeConfigs: []
# Example:
# - job_name: kube-etcd
#   kubernetes_sd_configs:
#     - role: node
#   scheme: https
#   tls_config:
#     ca_file: /etc/prometheus/secrets/etcd-client-cert/etcd-ca
#     cert_file: /etc/prometheus/secrets/etcd-client-cert/etcd-client
#     key_file: /etc/prometheus/secrets/etcd-client-cert/etcd-client-key
#   relabel_configs:
#     - action: labelmap

Key point: the format is identical to entries you would place in a standalone prometheus.yml. You are appending full scrape jobs to Prometheus’ configuration.

3. Add your scrape job(s)

Under the additionalScrapeConfigs key, provide a YAML list of scrape jobs using Prometheus’ scrape_config syntax. For example, to add a job similar to the kube-etcd example, include:

additionalScrapeConfigs:
  - job_name: kube-etcd
    kubernetes_sd_configs:
      - role: node
    scheme: https
    tls_config:
      ca_file: /etc/prometheus/secrets/etcd-client-cert/etcd-ca
      cert_file: /etc/prometheus/secrets/etcd-client-cert/etcd-client
      key_file: /etc/prometheus/secrets/etcd-client-cert/etcd-client-key
    relabel_configs:
      - action: labelmap
        regex: __meta_kubernetes_node_label_(.+)

Tips when writing scrape jobs:

Ensure job_name is unique to avoid confusion.
Use kubernetes_sd_configs with the appropriate role (pod, service, node, endpoints) for discovery.
When using TLS or client certs, reference Kubernetes secrets mounted into the Prometheus pod (as shown above).
Double-check relabel_configs to avoid removing required labels or routing metrics unintentionally.

4. Apply the updated Helm values

Save your modified values.yaml and upgrade the Helm release (replace prometheus with your release name if different):

helm upgrade prometheus prometheus-community/kube-prometheus-stack -f values.yaml

Helm will update the Prometheus StatefulSet and associated configuration. If your appended scrape jobs are valid and targets are reachable, Prometheus should begin scraping them.

Because additionalScrapeConfigs injects raw Prometheus job definitions, a malformed job can prevent Prometheus from starting. Validate your scrape configs locally where possible, test with a non-production release, and review Prometheus release notes before upgrading the chart.

Next steps

ServiceMonitors are the recommended method when running the Prometheus Operator — they let you declare scrape targets via Kubernetes CRDs and are generally safer for upgrades and maintenance. See the Prometheus Operator ServiceMonitor docs for examples and best practices.

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

Additional Scrape Configs

1. Export the Helm chart default values

2. Find `additionalScrapeConfigs` in the values file

3. Add your scrape job(s)

4. Apply the updated Helm values

Next steps

Watch Video

​1. Export the Helm chart default values

​2. Find additionalScrapeConfigs in the values file

​3. Add your scrape job(s)

​4. Apply the updated Helm values

​Next steps

Watch Video

1. Export the Helm chart default values

2. Find `additionalScrapeConfigs` in the values file

3. Add your scrape job(s)

4. Apply the updated Helm values

Next steps