diff --git a/docs/agent/features/environment-variables.md b/docs/agent/features/environment-variables.md new file mode 100644 index 0000000..de8fe97 --- /dev/null +++ b/docs/agent/features/environment-variables.md @@ -0,0 +1,163 @@ +# Environment Variables + +The Telemetry Forge Agent pre-populates a small set of runtime environment variables that you can always reference in Fluent Bit configuration files rather than have to set explicitly. + +If a variable is already set in the process environment, the agent keeps that value unchanged. + +These variables are available in Telemetry Forge Agent version 26.7.1 and later. + +## Supported variables + +| Variable | Description | Default when not provided in process environment | +| --- | --- | --- | +| HOSTNAME | Host identity used by the running process. | System hostname (when available) | +| OS_TYPE | Normalised operating system name. | `linux`, `macos`, `windows`, or `unknown` | +| AGENT_DISTRO | Build distribution metadata. | [Value from build metadata](#agent_distro), or `unknown` | +| AGENT_PACKAGE_TYPE | Build package type metadata. | [Value from build metadata](#agent_package_type), or `unknown` | +| AGENT_VERSION | Agent version metadata. | [Value from build metadata](#agent_version), or `unknown` | + +## Values currently used in agent builds + +These values are primarily for our [Fleet Manager](../../fleet-manager/index.md) but are available to all users as well. + +### AGENT_PACKAGE_TYPE + +Current build values: + +- `CONTAINER` (container image builds) +- `PACKAGE` (native package and installer builds) + +### AGENT_DISTRO + +Current production build values are set based on our [supported targets](../supported-platforms.md) for each release but examples include: + +- Container defaults: + - `debian/trixie` + - `ubi/10.2` +- Linux package build targets (release set): + - `almalinux/8` + - `almalinux/9` + - `almalinux/10` + - `amazonlinux/2023` + - `centos/6` + - `centos/7` + - `debian/bookworm` + - `debian/trixie` + - `ubuntu/22.04` + - `ubuntu/24.04` + - `ubuntu/26.04` + - `suse/15` +- Native package and installer platform values: + - `windows-x64` + - `macos-15` + - `macos-15-intel` + +### AGENT_VERSION + +Current build values: + +- Set from release/build metadata at build time +- Matches the agent release version (for example, `26.7.1`) +- See [Version Mapping](../version-mapping.md) for published version alignment + +## How values are resolved + +Resolution order for each variable: + +1. Existing process environment value is kept as-is. +2. If missing, the agent applies an internal preset configured at build time. +3. If build metadata is unavailable for AGENT_DISTRO, AGENT_PACKAGE_TYPE, or AGENT_VERSION, the value is `unknown`. + +## Use in Fluent Bit configuration + +You can reference the variables with [standard bash interpolation syntax](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/yaml/environment-variables-section#external-variables). + +```yaml +pipeline: + inputs: + - name: dummy + tag: env.test + dummy: '{"distro":"${AGENT_DISTRO}","package_type":"${AGENT_PACKAGE_TYPE}","version":"${AGENT_VERSION}","os":"${OS_TYPE}","hostname":"${HOSTNAME}"}' + + outputs: + - name: stdout + match: env.test +``` + +Expected output when run with the Universal Base Image (UBI) container: + +```text +[0] env.test: [[, {}], {"distro"=>"ubi/10.2", "package_type"=>"CONTAINER", "version"=>"26.7.1", "os"=>"linux", "hostname"=>"my-host"}] +``` + +If you use the one-off or container overrides below, the `distro`, `package_type`, and `version` fields reflect the override values. + +## GitOps multi-platform example + +You can use one Git repository for all operating systems and let `${OS_TYPE}` select the platform-specific configuration file automatically. + +Example repository layout: + +```text +fluent-bit-configs/ + platforms/ + linux/fluent-bit.yaml + windows/fluent-bit.yaml + macos/fluent-bit.yaml +``` + +Agent configuration: + +```yaml +service: + flush: 1 + log_level: info + +customs: + - name: git_config + repo: https://github.com/myorg/fluent-bit-configs.git + ref: main + path: platforms/${OS_TYPE}/fluent-bit.yaml + config_dir: /var/lib/fluent-bit/git-config + poll_interval: 60 +``` + +Path resolution examples: + +- Linux agent: `platforms/linux/fluent-bit.yaml` +- Windows agent: `platforms/windows/fluent-bit.yaml` +- macOS agent: `platforms/macos/fluent-bit.yaml` + +This lets you keep a single GitOps repository while still maintaining per-platform Fluent Bit configuration files. + +## Override examples + +### One-off process override + +```bash +AGENT_PACKAGE_TYPE=CONTAINER AGENT_DISTRO=ubuntu/24.04 AGENT_VERSION=26.7.1 \ + /opt/telemetryforge-agent/bin/fluent-bit -c ./fluent-bit.yaml +``` + +### Container override + +```bash +docker run --rm \ + -e AGENT_DISTRO=ubuntu/24.04 \ + -e AGENT_PACKAGE_TYPE=CONTAINER \ + -e AGENT_VERSION=26.7.1 \ + -v "$PWD/fluent-bit.yaml:/fluent-bit/etc/fluent-bit.yaml:ro" \ + ghcr.io/telemetryforge/agent:26.7.1 \ + -c /fluent-bit/etc/fluent-bit.yaml +``` + +### systemd service override + +Add to your service unit: + +```ini +[Service] +Environment=AGENT_DISTRO=rhel/9 +Environment=AGENT_PACKAGE_TYPE=PACKAGE +Environment=AGENT_VERSION=26.7.1 +``` diff --git a/docs/agent/features/index.md b/docs/agent/features/index.md index 9662606..4636b25 100644 --- a/docs/agent/features/index.md +++ b/docs/agent/features/index.md @@ -5,6 +5,7 @@ This section documents advanced features and capabilities of Fluent Bit. ## Configuration Management - **[Git Configuration Auto-Reload](git-config-auto-reload.md)** - Automatically reload Fluent Bit configuration from a Git repository when changes are detected +- **[Environment Variables](environment-variables.md)** - Runtime variables available for configuration ## Data Processing diff --git a/docs/agent/getting-started.md b/docs/agent/getting-started.md index e065190..4b7c036 100644 --- a/docs/agent/getting-started.md +++ b/docs/agent/getting-started.md @@ -1,3 +1,8 @@ +--- +hide: + - toc +--- + # Getting Started This quick guide helps you install Telemetry Forge Agent and run a minimal Fluent Bit pipeline that tails logs and prints them to stdout. @@ -220,6 +225,7 @@ All binaries and installers are available at [https://packages.telemetryforge.io - Replace `tail` or add your target input plugins. - Add any additional processing/filtering required. - Update the systemd service to use your specific configuration. +- Review [Environment Variables](./features/environment-variables.md) for `AGENT_DISTRO`, `AGENT_PACKAGE_TYPE`, `AGENT_VERSION`, `OS_TYPE`, and `HOSTNAME` usage. - Review our custom [GitOps plugin](./features/git-config-auto-reload.md) to simplify configuration management. - Review [Supported Platforms](./supported-platforms.md). - Review [Version Mapping](./version-mapping.md) to align with your upstream Fluent Bit baseline. diff --git a/docs/agent/index.md b/docs/agent/index.md index 1a97f4d..94c6c04 100644 --- a/docs/agent/index.md +++ b/docs/agent/index.md @@ -30,6 +30,7 @@ The Telemetry Forge Agent is an **enterprise-hardened distribution of Fluent Bit ## Documentation - [Getting Started](./getting-started.md) - Install and run a minimal pipeline with our agent +- [Environment Variables](./features/environment-variables.md) - Runtime variables available in Fluent Bit config interpolation - [Supported Platforms](./supported-platforms.md) - Verified operating system (OS) and architecture support - [Version Mapping](./version-mapping.md) - Agent to OSS Fluent Bit version alignment - [Security](./security.md) - Hardening features and Common Vulnerabilities and Exposures (CVE) management diff --git a/docs/agent/supported-platforms.md b/docs/agent/supported-platforms.md index d62e656..d5a8660 100644 --- a/docs/agent/supported-platforms.md +++ b/docs/agent/supported-platforms.md @@ -58,7 +58,7 @@ Packages as well as public VM images (or AMIs) are available for the following E | Alma Linux | 8, 9, 10 | RHEL–compatible without breaking changes from CentOS stream. | | Rocky Linux | 8, 9, 10 | RHEL–compatible without breaking changes from CentOS stream. | | SUSE Linux Enterprise Server (SLES) | 12, 15 | | -| Ubuntu LTS | 18.04, 20.04, 22.04, 24.04 | | +| Ubuntu LTS | 18.04, 20.04, 22.04, 24.04, 26.04 | | | Debian | 10,11,12,13 | | | Mariner/Azure Linux | 2,3 | | | Amazon Linux | 2023 | | diff --git a/mkdocs.yml b/mkdocs.yml index 4b2b0b6..84cea8c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ nav: - Getting Started: agent/getting-started.md - Features: - Overview: agent/features/index.md + - Environment Variables: agent/features/environment-variables.md - Record Deduplication: agent/features/record-deduplication.md - Log Sampling: agent/features/log-sampling.md - Git Configuration Auto-Reload: agent/features/git-config-auto-reload.md