Documentation Grafana Alloy Reference Configuration blocks import.http

import.http

import.http retrieves a module from an HTTP server.

Use import.http to load Alloy configuration from a remote HTTP server. The remote file must define configuration inside a declare block. Alloy evaluates imported modules as reusable components, so the remote file must not include top-level global configuration blocks such as logging or remotecfg. Global configuration belongs in the local configuration file that imports the module. You must configure command-line flags outside the module. Alloy periodically polls the URL to detect and apply configuration changes.

Refer to Load configuration from remote sources for more information.

Usage

Alloy Copy

import.http "<LABEL>" {
  url = <URL>
}

Arguments

You can use the following arguments with import.http:

Blocks

You can use the following blocks with import.http:

The > symbol indicates deeper levels of nesting. For example, client > basic_auth refers to a basic_auth block defined inside a client block.

client

The client block configures settings for connecting to the HTTP server.

authorization

The authorization block configures custom authorization for polling the configured URL.

basic_auth

The basic_auth block configures basic authentication for polling the configured URL.

oauth2

The oauth2 block configures OAuth 2.0 authorization for polling the configured URL.

tls_config

The tls_config block configures TLS settings for connecting to HTTPS servers.

Behavior when the remote server is unavailable

• Initial evaluation in this process: A failed fetch means the configuration that imports the remote module fails to evaluate, so nothing that only the remote module would define runs.
• After at least one successful fetch in this process: A failed poll keeps the running configuration on the last successfully loaded module in memory; Alloy retries at each poll_frequency interval.

The first evaluation happens when Alloy evaluates import.http during startup or when it reapplies configuration after a change. If that fetch fails, there’s no remote module content from this process to fall back on.

Remote module contents aren’t persisted across process restarts. On a cold start or restart, Alloy must again successfully complete the initial fetch. If the remote server is unavailable at that time, evaluation of the configuration that uses import.http fails.

Alloy writes configuration retrieval errors to the logs in all of these cases, which you can use for troubleshooting and alerting.

Monitor configuration fetch failures

To detect configuration update problems early, monitor for repeated fetch failures:

• Check collector logs for repeated HTTP errors when retrieving remote modules.
• Investigate persistent 4xx errors, which indicate authentication or URL configuration issues.
• Investigate persistent 5xx errors, which indicate remote server problems.
• Verify network connectivity and proxy configuration if requests time out.

If configuration updates are critical for your deployment, consider adding alerting based on log monitoring or collector health checks.

Example

This example imports custom components from an HTTP response and instantiates a custom component for adding two numbers.

Create a module file and host it on your HTTP server:

Alloy Copy

declare "add" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

In your local configuration file, import the remote module and use the declared component:

Alloy Copy

import.http "math" {
  url = <SERVER_URL>
}

math.add "default" {
  a = 15
  b = 45
}

Load configuration from a remote HTTP server

You can use import.http to load an Alloy configuration containing standard components from a remote HTTP server.

The following example shows how to load a Prometheus scrape configuration from a remote server.

Create a module file and host it on your HTTP server:

Alloy Copy

declare "scrape" {
  argument "targets" {}
  argument "forward_to" {}

  prometheus.scrape "default" {
    targets    = argument.targets.value
    forward_to = argument.forward_to.value
  }
}

In your local configuration file, import the remote module and use the declared component:

Alloy Copy

import.http "remote" {
  url            = "http://config-server.example.com/prometheus_scrape.alloy"
  poll_frequency = "5m"
}

prometheus.remote_write "default" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

remote.scrape "app" {
  targets    = [{"__address__" = "localhost:8080"}]
  forward_to = [prometheus.remote_write.default.receiver]
}