---
title: "Configure components | Grafana Cloud documentation"
description: "Learn how to declare and configure components"
---

# Configure components

Components are the defining feature of Alloy. They’re reusable pieces of business logic that perform a single task, such as retrieving secrets or collecting Prometheus metrics. You can wire them together to form programmable pipelines of telemetry data.

To build effective configurations, you need to understand how to define components, set their arguments, and connect them using exports.

## Basic component syntax

You create [components](/docs/grafana-cloud/send-data/alloy/reference/components) by defining a top-level block with a component name and a user-specified label.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
COMPONENT_NAME "LABEL" {
  // Component configuration goes here
}
```

For example, this creates a `local.file` component with the label “`config`”:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
local.file "config" {
  filename = "/etc/app/settings.yaml"
}
```

The [*component controller*](/docs/grafana-cloud/send-data/alloy/get-started/components/component-controller) schedules components, reports their health and debug status, re-evaluates their arguments, and provides their exports.

## Arguments and exports

Most user interactions with components center around two basic concepts: *arguments* and *exports*.

### Arguments

*Arguments* are settings that modify a component’s behavior. They can include attributes or nested unlabeled blocks, some of which you must provide and others that are optional. Optional arguments that aren’t set use their default values.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
local.file "targets" {
  filename = "/etc/alloy/targets"  // Required argument

  // Optional arguments
  poll_frequency = "1m"
  is_secret = false
}
```

### Exports

*Exports* are zero or more output values that other components can refer to. They can be of any Alloy type.

The `local.file.targets` component from the previous example exposes the file content as a string in its exports. You’ll learn how to reference these exports in [Expressions](/docs/grafana-cloud/send-data/alloy/get-started/expressions).

## Configuration blocks

Some components use nested blocks to organize related settings.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.remote_write "production" {
  endpoint {
    url = "https://prometheus.example.com/api/v1/write"

    basic_auth {
      username = "metrics"
      password_file = "/etc/secrets/password"
    }
  }

  queue_config {
    capacity = 10000
    batch_send_deadline = "5s"
  }
}
```

In this example:

- `endpoint` is a block that configures the remote endpoint
- `basic_auth` is a nested block within `endpoint`
- `queue_config` is another top-level block within the component

## Component references

To wire components together, use the exports of one as the arguments to another by using references. References can only appear in component arguments.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
local.file "api_key" {
  filename = "/etc/secrets/api.key"
}

prometheus.remote_write "production" {
  endpoint {
    url = "https://prometheus.example.com/api/v1/write"

    basic_auth {
      username = "metrics"
      password = local.file.api_key.content  // Reference to component export
    }
  }
}
```

Each time the file contents change, the `local.file` component updates its exports. The component sends the updated value to the `prometheus.remote_write` component’s `password` field.

### Reference syntax

To reference a component export, combine three parts with periods:

- Component name: `local.file`
- Component label: `api_key`
- Export name: `content`
- Result: `local.file.api_key.content`

Each argument and exported field has an underlying [type](/docs/grafana-cloud/send-data/alloy/get-started/expressions/types_and_values). Alloy checks the expression type before assigning a value to an attribute.

## Multiple component instances

You can create multiple instances of the same component type by using different labels:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.scrape "api" {
  targets = [{"__address__" = "api.example.com:8080"}]
  forward_to = [prometheus.remote_write.production.receiver]
}

prometheus.scrape "database" {
  targets = [{"__address__" = "db.example.com:9090"}]
  forward_to = [prometheus.remote_write.production.receiver]
}
```

Both scrape configurations send metrics to the same `prometheus.remote_write` component.

## Component rules

Components can’t form cycles. This means that a component can’t reference itself directly or indirectly. This prevents infinite loops from forming in your configuration.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
// INVALID: Component can't reference itself
local.file "self_reference" {
  filename = local.file.self_reference.content
}
```

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
// INVALID: Cyclic reference between components
local.file "a" {
  filename = local.file.b.content
}

local.file "b" {
  filename = local.file.a.content
}
```

## Next steps

Now that you understand how to configure components, learn about more advanced topics:

- [Build data pipelines](/docs/grafana-cloud/send-data/alloy/get-started/components/build-pipelines) - Connect components together to create data processing workflows
- [Component controller](/docs/grafana-cloud/send-data/alloy/get-started/components/component-controller) - Understand how Alloy manages components at runtime
- [Expressions](/docs/grafana-cloud/send-data/alloy/get-started/expressions) - Write dynamic configuration using component references and functions
- [Component reference](/docs/grafana-cloud/send-data/alloy/reference/components) - Explore all available components and their arguments and exports

For practical examples, try the [tutorials](/docs/grafana-cloud/send-data/alloy/tutorials) to build complete data collection pipelines.