feat(config): add public opentelemetry.sdk.configuration namespace

.changelog/5269.added

@@ -0,0 +1 @@
+`opentelemetry-sdk`: declarative config loader now recursively converts parsed dicts into typed dataclass instances, including nested dataclasses, lists of dataclasses, and enum values. End-to-end YAML/JSON → SDK configuration now works via the factory functions.

.changelog/5270.added

@@ -0,0 +1 @@
+`opentelemetry-sdk`: add `configure_sdk(config)` to the declarative configuration API. Single entry point that takes a parsed `OpenTelemetryConfiguration`, builds the resource, and applies the tracer/meter/logger providers and propagator globally. Honors the top-level `disabled` flag.

.changelog/5271.added

@@ -0,0 +1 @@
+`opentelemetry-sdk`: the SDK configurator now honors the `OTEL_CONFIG_FILE` environment variable. When set, the SDK loads and applies the referenced declarative configuration file (YAML or JSON) in place of the env-var-based init path.

.changelog/5276.added

@@ -0,0 +1 @@
+`opentelemetry-sdk`: add public `opentelemetry.sdk.configuration` module that re-exports `configure_sdk`, `load_config_file`, `OpenTelemetryConfiguration`, and `ConfigurationError`. `load_config_file` is resolved lazily so the file-configuration extras (pyyaml, jsonschema) remain optional for callers that build an `OpenTelemetryConfiguration` programmatically.

.codespellrc

@@ -1,4 +1,4 @@
 [codespell]
 # skipping auto generated folders
 skip = ./.tox,./.mypy_cache,./docs/_build,./target,*/LICENSE,./venv,.git,./opentelemetry-semantic-conventions,*-requirements*.txt
-ignore-words-list = ans,ue,ot,hist,ro
+ignore-words-list = ans,ue,ot,hist,ro,astroid

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/__init__.py

@@ -37,6 +37,7 @@
 )
 from opentelemetry.sdk.environment_variables import (
     _OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED,
+    OTEL_CONFIG_FILE,
     OTEL_EXPORTER_OTLP_LOGS_PROTOCOL,
     OTEL_EXPORTER_OTLP_METRICS_PROTOCOL,
     OTEL_EXPORTER_OTLP_PROTOCOL,
@@ -677,4 +678,25 @@ class _OTelSDKConfigurator(_BaseConfigurator):
     """
 
     def _configure(self, **kwargs):
+        config_file = environ.get(OTEL_CONFIG_FILE)
+        if config_file:
+            # Imported lazily so that the SDK does not require the optional
+            # file-configuration extras (pyyaml, jsonschema) unless a config
+            # file is actually requested.
+            # pylint: disable=import-outside-toplevel
+            from opentelemetry.sdk._configuration._sdk import (  # noqa: PLC0415
+                configure_sdk,
+            )
+            from opentelemetry.sdk._configuration.file._loader import (  # noqa: PLC0415
+                load_config_file,
+            )
+
+            if kwargs:
+                _logger.warning(
+                    "%s is set; ignoring configurator kwargs: %s",
+                    OTEL_CONFIG_FILE,
+                    sorted(kwargs),
+                )
+            configure_sdk(load_config_file(config_file))
+            return
         _initialize_components(**kwargs)

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_conversion.py

@@ -0,0 +1,113 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Recursive dict-to-dataclass conversion for parsed config data.
+
+The YAML/JSON loader produces nested dicts. Factory functions expect typed
+dataclass instances (e.g. ``TracerProvider``, ``SpanProcessor``). This module
+walks each field's type annotation and converts nested dicts into their
+corresponding dataclass types.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import types
+import typing
+from collections.abc import Mapping
+from typing import Any, TypeVar, Union, get_args, get_origin
+
+_T = TypeVar("_T")
+
+
+def _unwrap_optional(type_hint: Any) -> Any:
+    """Strip ``None`` from a ``X | None`` / ``Optional[X]`` annotation.
+
+    Returns the unwrapped type, or the original hint if not a Union with None.
+    """
+    origin = get_origin(type_hint)
+    if origin is Union or origin is types.UnionType:
+        non_none = [t for t in get_args(type_hint) if t is not type(None)]
+        if len(non_none) == 1:
+            return non_none[0]
+    return type_hint
+
+
+def _convert_value(value: Any, type_hint: Any) -> Any:
+    """Convert a value according to its type hint.
+
+    Recursively converts dicts to dataclasses and lists of dicts to lists of
+    dataclasses. Other values (primitives, enums, ``dict[str, Any]`` aliases)
+    pass through unchanged.
+    """
+    if value is None:
+        return None
+
+    unwrapped = _unwrap_optional(type_hint)
+    origin = get_origin(unwrapped)
+
+    # list[X] — recurse on each element
+    if origin is list and isinstance(value, list):
+        args = get_args(unwrapped)
+        if args:
+            item_type = args[0]
+            return [_convert_value(item, item_type) for item in value]
+        return value
+
+    # Direct dataclass type — recurse
+    if (
+        isinstance(unwrapped, type)
+        and dataclasses.is_dataclass(unwrapped)
+        and isinstance(value, dict)
+    ):
+        return _dict_to_dataclass(value, unwrapped)
+
+    # Enum type — coerce string/value to the Enum member
+    if (
+        isinstance(unwrapped, type)
+        and issubclass(unwrapped, enum.Enum)
+        and not isinstance(value, unwrapped)
+    ):
+        return unwrapped(value)
+
+    return value
+
+
+def _dict_to_dataclass(data: Mapping[str, Any], cls: type[_T]) -> _T:
+    """Recursively convert a mapping to a dataclass instance.
+
+    For each key in ``data``:
+    - If it matches a known dataclass field, the value is converted according
+      to that field's type annotation (recursing for nested dataclasses).
+    - Unknown keys are passed through as kwargs; classes decorated with
+      ``@_additional_properties`` will capture them on the instance's
+      ``additional_properties`` attribute.
+
+    ``ClassVar`` fields (e.g. the ``additional_properties`` annotation on
+    decorated dataclasses) are ignored as expected.
+
+    Raises:
+        TypeError: If ``cls`` is not a dataclass type.
+    """
+    if not dataclasses.is_dataclass(cls):
+        raise TypeError(f"{cls.__name__} is not a dataclass")
+
+    # Annotated as ``dict[str, Any]`` so astroid stops tracing into
+    # ``typing.get_type_hints`` — under pylint 3.x that path leads into
+    # Python 3.14's ``annotationlib`` (which uses t-strings) and crashes.
+    hints: dict[str, Any] = dict(
+        typing.get_type_hints(cls, include_extras=False)
+    )
+    known_fields = {f.name for f in dataclasses.fields(cls)}
+    kwargs: dict[str, Any] = {}
+
+    for key, value in data.items():
+        if key in known_fields:
+            type_hint = hints.get(key)
+            kwargs[key] = _convert_value(value, type_hint)
+        else:
+            # Unknown key — @_additional_properties decorator will capture it.
+            kwargs[key] = value
+
+    return cls(**kwargs)

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_sdk.py

@@ -0,0 +1,64 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Top-level orchestrator for declarative SDK configuration.
+
+Takes a parsed ``OpenTelemetryConfiguration`` and applies it by calling
+each per-signal ``configure_*`` factory in order. This is the single
+entry point for "apply this config" on the declarative path.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from opentelemetry.sdk._configuration._logger_provider import (
+    configure_logger_provider,
+)
+from opentelemetry.sdk._configuration._meter_provider import (
+    configure_meter_provider,
+)
+from opentelemetry.sdk._configuration._propagator import configure_propagator
+from opentelemetry.sdk._configuration._resource import create_resource
+from opentelemetry.sdk._configuration._tracer_provider import (
+    configure_tracer_provider,
+)
+from opentelemetry.sdk._configuration.models import OpenTelemetryConfiguration
+
+_logger = logging.getLogger(__name__)
+
+
+def configure_sdk(config: OpenTelemetryConfiguration) -> None:
+    """Configure the global SDK from a parsed declarative configuration.
+
+    Builds a :class:`Resource` from ``config.resource`` and applies it to
+    each signal provider. Sets the global tracer provider, meter provider,
+    logger provider, and text map propagator from their respective config
+    sections. Sections absent from the config (``None``) leave the
+    corresponding global untouched — matching the spec's "noop default"
+    behavior.
+
+    Honors the top-level ``disabled`` flag: when true, no globals are set.
+
+    Args:
+        config: Parsed ``OpenTelemetryConfiguration`` (typically from
+            ``load_config_file``).
+
+    Example:
+        >>> from opentelemetry.sdk._configuration.file import (
+        ...     load_config_file, configure_sdk,
+        ... )
+        >>> config = load_config_file("otel-config.yaml")
+        >>> configure_sdk(config)
+    """
+    if config.disabled:
+        _logger.info(
+            "Declarative configuration has disabled=true; skipping SDK setup."
+        )
+        return
+
+    resource = create_resource(config.resource)
+    configure_tracer_provider(config.tracer_provider, resource)
+    configure_meter_provider(config.meter_provider, resource)
+    configure_logger_provider(config.logger_provider, resource)
+    configure_propagator(config.propagator)

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/file/__init__.py

@@ -27,6 +27,7 @@
     create_propagator,
 )
 from opentelemetry.sdk._configuration._resource import create_resource
+from opentelemetry.sdk._configuration._sdk import configure_sdk
 from opentelemetry.sdk._configuration._tracer_provider import (
     configure_tracer_provider,
     create_tracer_provider,
@@ -39,6 +40,7 @@
 
 __all__ = [
     "load_config_file",
+    "configure_sdk",
     "substitute_env_vars",
     "ConfigurationError",
     "EnvSubstitutionError",

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/file/_loader.py

@@ -9,6 +9,7 @@
 from pathlib import Path
 from typing import Any
 
+from opentelemetry.sdk._configuration._conversion import _dict_to_dataclass
 from opentelemetry.sdk._configuration._exceptions import ConfigurationError
 from opentelemetry.sdk._configuration.file._env_substitution import (
     substitute_env_vars,
@@ -172,10 +173,13 @@ def _validate_schema(data: dict) -> None:
 
 
 def _dict_to_model(data: dict[str, Any]) -> OpenTelemetryConfiguration:
-    """Convert dictionary to OpenTelemetryConfiguration model.
+    """Convert a parsed config dictionary to the full typed model tree.
 
-    Uses the generated dataclass from models.py. This provides basic
-    validation through dataclass field types.
+    Walks each field's type annotation, recursively converting nested
+    dicts to their corresponding dataclass types. The resulting
+    ``OpenTelemetryConfiguration`` is fully typed end-to-end, so factory
+    functions can rely on typed attribute access (e.g. ``config.sampler``,
+    ``config.processors[0].batch.exporter``).
 
     Args:
         data: Parsed configuration dictionary.
@@ -187,15 +191,9 @@ def _dict_to_model(data: dict[str, Any]) -> OpenTelemetryConfiguration:
         TypeError: If data doesn't match expected structure.
         ValueError: If values are invalid.
     """
-    # Construct the top-level model from the validated dict. Nested fields
-    # are stored as dicts rather than their dataclass types; factory functions
-    # in later PRs will handle the full recursive conversion when building
-    # SDK objects.
     try:
-        config = OpenTelemetryConfiguration(**data)
-        return config
+        return _dict_to_dataclass(data, OpenTelemetryConfiguration)
     except TypeError as exc:
-        # Provide more helpful error message
         raise TypeError(
             f"Configuration structure is invalid. "
             f"Check that all required fields are present and correctly typed: {exc}"

opentelemetry-sdk/src/opentelemetry/sdk/configuration/__init__.py

@@ -0,0 +1,56 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Public API for the OpenTelemetry SDK's declarative configuration.
+
+Load a parsed configuration from a YAML/JSON file and apply it to the
+process-global SDK providers:
+
+>>> from opentelemetry.sdk.configuration import (
+...     load_config_file, configure_sdk,
+... )
+>>> config = load_config_file("otel-config.yaml")
+>>> configure_sdk(config)
+
+Construct a configuration programmatically and apply it:
+
+>>> from opentelemetry.sdk.configuration import (
+...     OpenTelemetryConfiguration, configure_sdk,
+... )
+>>> configure_sdk(OpenTelemetryConfiguration(file_format="1.0-rc.1"))
+
+Loading from a file requires the optional ``[file-configuration]`` extras
+(``pyyaml`` and ``jsonschema``). ``configure_sdk`` itself has no extra
+dependencies — callers that construct an ``OpenTelemetryConfiguration``
+directly can use it without installing the extras.
+"""
+
+from opentelemetry.sdk._configuration._exceptions import ConfigurationError
+from opentelemetry.sdk._configuration._sdk import configure_sdk
+from opentelemetry.sdk._configuration.models import OpenTelemetryConfiguration
+
+
+def __getattr__(name: str):
+    # ``load_config_file`` lives behind the optional file-configuration
+    # extras (pyyaml, jsonschema). Resolve it lazily so importing this
+    # module does not require those extras for callers that only use
+    # ``configure_sdk`` with a programmatically built configuration.
+    if name == "load_config_file":
+        # pylint: disable=import-outside-toplevel
+        from opentelemetry.sdk._configuration.file._loader import (  # noqa: PLC0415
+            load_config_file,
+        )
+
+        return load_config_file
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# ``load_config_file`` is exposed via ``__getattr__`` rather than a module-level
+# binding so the file-configuration extras stay optional. Pylint's static
+# analysis doesn't see ``__getattr__`` and flags it as undefined; suppress.
+__all__ = [
+    "ConfigurationError",
+    "OpenTelemetryConfiguration",
+    "configure_sdk",
+    "load_config_file",  # pylint: disable=undefined-all-variable
+]

opentelemetry-sdk/src/opentelemetry/sdk/environment_variables/__init__.py

@@ -9,6 +9,18 @@
 Default: "false"
 """
 
+OTEL_CONFIG_FILE = "OTEL_CONFIG_FILE"
+"""
+.. envvar:: OTEL_CONFIG_FILE
+
+The :envvar:`OTEL_CONFIG_FILE` environment variable points the SDK at a
+declarative configuration file (YAML or JSON). When set, the file is the
+sole source of SDK configuration; other ``OTEL_*`` environment variables
+are ignored except where referenced via ``${env:VAR}`` substitution inside
+the file. See the OpenTelemetry declarative configuration specification
+for details.
+"""
+
 OTEL_RESOURCE_ATTRIBUTES = "OTEL_RESOURCE_ATTRIBUTES"
 """
 .. envvar:: OTEL_RESOURCE_ATTRIBUTES