Modules
A Module is a unit of Alloy configuration, which combines all the other concepts, containing a mix of configuration blocks, instantiated components, and custom component definitions.
The module passed as an argument to the run
command is called the main configuration.
Modules can be imported to enable the reuse of custom components defined by that module.
Import modules
A module can be imported, allowing the custom components defined by that module to be used by other modules, called the importing module.
Modules can be imported from multiple locations using one of the import
configuration blocks:
import.file
: Imports a module from a file on disk.import.git
: Imports a module from a file located in a Git repository.import.http
: Imports a module from the response of an HTTP request.import.string
: Imports a module from a string.
Warning
You can’t import a module that contains top-level blocks other thandeclare
orimport
.
Modules are imported into a namespace where the top-level custom components of the imported module are exposed to the importing module.
The label of the import block specifies the namespace of an import.
For example, if a configuration contains a block called import.file "my_module"
, then custom components defined by that module are exposed as my_module.CUSTOM_COMPONENT_NAME
. Imported namespaces must be unique across a given importing module.
If an import namespace matches the name of a built-in component namespace, such as prometheus
, the built-in namespace is hidden from the importing module, and only components defined in the imported module may be used.
Warning
If you choose a label that corresponds to an existing component for animport
or adeclare
block, the component is shadowed and you won’t be able to use it in your configuration. For example, if you use the labelimport.file "mimir"
, you won’t be able to use the existing components that start withmimir
such asmimir.rules.kubernetes
because it refers to the module imported via theimport
block.
Example
This example module defines a component to filter out debug-level and info-level log lines:
You can save this module to a file called helpers.alloy
and import it:
Security
Since modules can load an arbitrary configuration from a potentially remote source, it’s important to carefully consider the security of your solution. The best practice is to ensure that the Alloy configuration can’t be changed by attackers. This includes the main Alloy configuration files as well as modules fetched from remote locations such as Git repositories or HTTP servers.