Skip to content

Latest commit

 

History

History
276 lines (204 loc) · 8.99 KB

otelcol.auth.basic.md

File metadata and controls

276 lines (204 loc) · 8.99 KB
canonical aliases description labels title
../otelcol.auth.basic/
Learn about otelcol.auth.basic
stage products
general-availability
oss
otelcol.auth.basic

otelcol.auth.basic

otelcol.auth.basic exposes a handler that other otelcol components can use to authenticate requests using basic authentication.

This component supports both server and client authentication.

{{< admonition type="note" >}} otelcol.auth.basic is a wrapper over the upstream OpenTelemetry Collector [basicauth][] extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

[basicauth]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/{{< param "OTEL_VERSION" >}}/extension/basicauthextension {{< /admonition >}}

You can specify multiple otelcol.auth.basic components by giving them different labels.

Usage

otelcol.auth.basic "<LABEL>" {
  username = "<USERNAME>"
  password = "<PASSWORD>"
}

Arguments

{{< admonition type="caution" >}} The top-level username and password arguments are deprecated and should not be used for new configurations. Use the client_auth block for client authentication and the htpasswd block for server authentication instead. {{< /admonition >}}

You can use the following arguments with otelcol.auth.basic:

Name Type Description Default Required
password secret (Deprecated) Password to use for basic authentication requests. no
username string (Deprecated) Username to use for basic authentication requests. no

Blocks

You can use the following block with otelcol.auth.basic:

Block Description Required
client_auth Configures client authentication credentials for exporters no
debug_metrics Configures the metrics that this component generates to monitor its state. no
htpasswd Configures server authentication using htpasswd format for receivers no

client_auth

The client_auth block configures credentials that client extensions (such as exporters) will use to authenticate to servers.

Name Type Description Default Required
password string Password to use for basic authentication requests yes
username string Username to use for basic authentication requests yes

{{< admonition type="note" >}} If both the client_auth block and the deprecated top-level username and password attributes are specified, the client_auth block takes precedence and the top-level attributes are ignored for client authentication. {{< /admonition >}}

debug_metrics

{{< docs/shared lookup="reference/components/otelcol-debug-metrics-block.md" source="alloy" version="<ALLOY_VERSION>" >}}

htpasswd

The htpasswd block configures how the server extensions (such as receivers) will authenticate incoming requests using the htpasswd format.

Name Type Description Default Required
file string Path to the htpasswd file to use for basic authentication requests "" no
inline string The htpasswd file content in inline format "" no

You can specify either file, inline, or both. When using inline, the format should be username:password with each user on a new line.

{{< admonition type="note" >}} When both the htpasswd block and the deprecated top-level username and password attributes are specified, the deprecated credentials are automatically appended to the inline content. This allows authentication using credentials from both the htpasswd configuration and the deprecated attributes.

If the same username appears in both the file and inline content, including appended deprecated credentials, the entry in the inline content takes precedence. {{< /admonition >}}

Exported fields

The following fields are exported and can be referenced by other components:

Name Type Description
handler capsule(otelcol.Handler) A value that other components can use to authenticate requests.

Component health

otelcol.auth.basic is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.basic doesn't expose any component-specific debug information.

Examples

Forward signals to exporters

This example configures otelcol.exporter.otlp to use basic authentication:

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.basic.creds.handler
  }
}

otelcol.auth.basic "creds" {
  username = "demo"
  password = sys.env("API_KEY")
}

Authenticating requests for receivers

These examples show how to perform basic authentication using the client_auth block for exporters or the htpasswd block for receivers.

Use client authentication

This example configures otelcol.exporter.otlp to use basic authentication using a single username and password combination

otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"
  }

  output {
    metrics = [otelcol.exporter.otlp.default.input]
    logs    = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth = otelcol.auth.basic.creds.handler
  }
}

otelcol.auth.basic "creds" {
  client_auth {
    username = "demo"
    password = sys.env("API_KEY")
  }
}

{{< admonition type="note" >}} To migrate from the deprecated username and password attributes, move them into the client_auth block for client authentication. {{< /admonition >}}

Use htpasswd file

This example configures otelcol.receiver.otlp to use basic authentication using an htpasswd file containing the users to use for basic auth:

otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"
    
    auth = otelcol.auth.basic.creds.handler
  }
  
  output {
    metrics = [otelcol.exporter.debug.default.input]
    logs    = [otelcol.exporter.debug.default.input]
    traces  = [otelcol.exporter.debug.default.input]
  }
}

otelcol.exporter.debug "default" {}

otelcol.auth.basic "creds" {
  htpasswd {
    file = "/etc/alloy/.htpasswd"
  }
}

Use htpasswd inline content

This example shows how to specify htpasswd content directly in the configuration:

otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"
    
    auth = otelcol.auth.basic.creds.handler
  }
  
  output {
    metrics = [otelcol.exporter.debug.default.input]
    logs    = [otelcol.exporter.debug.default.input]
    traces  = [otelcol.exporter.debug.default.input]
  }
}

otelcol.exporter.debug "default" {}

otelcol.auth.basic "creds" {
  htpasswd {
    inline = "user1:password1\nuser2:password2"
  }
}

{{< admonition type="note" >}} To make the migration from the deprecated username and password attributes easier, you can specify both the deprecated attributes and the htpasswd block in the same configuration. The deprecated attributes will be appended to the htpasswd content.

otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"
    
    auth = otelcol.auth.basic.creds.handler
  }
  
  output {
    metrics = [otelcol.exporter.debug.default.input]
    logs    = [otelcol.exporter.debug.default.input]
    traces  = [otelcol.exporter.debug.default.input]
  }
}

otelcol.exporter.debug "default" {}

otelcol.auth.basic "creds" {
  username = "demo"
  password = sys.env("API_KEY")
  
  htpasswd {
    file = "/etc/alloy/.htpasswd"
  }
}

{{< /admonition >}}