Reference

Configuration blocks

import.http

General availability (GA) Open source

`import.http`

import.http retrieves a module from an HTTP server.

Usage

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

Arguments

You can use the following arguments with import.http:

Name	Type	Description	Default	Required
`url`	`string`	URL to poll.		yes
`headers`	`map(string)`	Custom headers for the request.	`{}`	no
`method`	`string`	Define the HTTP method for the request.	`"GET"`	no
`poll_frequency`	`duration`	Frequency to poll the URL.	`"1m"`	no
`poll_timeout`	`duration`	Timeout when polling the URL.	`"10s"`	no

Blocks

You can use the following blocks with import.http:

Block	Description	Required
`client`	HTTP client settings when connecting to the endpoint.	no
`client` > `authorization`	Configure generic authorization to the endpoint.	no
`client` > `basic_auth`	Configure `basic_auth` for authenticating to the endpoint.	no
`client` > `oauth2`	Configure OAuth 2.0 for authenticating to the endpoint.	no
`client` > `oauth2` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no
`client` >`tls_config`	Configure TLS settings for connecting to the endpoint.	no

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

`client`

The client block configures settings used to connect to the HTTP server.

Name	Type	Description	Default	Required
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive, and only one can be provided inside of a http_client_config block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_from_environment uses the environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO_PROXY. proxy_url and no_proxy must not be configured if proxy_from_environment is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`authorization`

The authorization block configures custom authorization to use when polling the configured URL.

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

The basic_auth block configures basic authentication to use when polling the configured URL.

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`oauth2`

The oauth2 block configures OAuth 2.0 authorization to use when polling the configured URL.

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

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

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

When min_version isn’t provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If min_version is provided, it must be set to one of the following strings:

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Example

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

module.alloy

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

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

main.alloy

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

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

Was this page helpful?

Suggest an edit in GitHub

Create a GitHub issue

Email docs@grafana.com

Help and support

Community

import.http

Usage

Arguments

Blocks

client

authorization

basic_auth

oauth2

tls_config

Example

Was this page helpful?

Related resources from Grafana Labs

`import.http`

`client`

`authorization`

`basic_auth`

`oauth2`

`tls_config`