Implementation:Astronomer Astronomer cosmos Cosmos Plugin

Metadata

Field	Value
Page Type	Implementation
Knowledge Sources	Repo (astronomer-cosmos), Doc (Cosmos Hosting Docs)
Domains	Data_Engineering, Documentation, UI
Last Updated	2026-02-07 14:00 GMT

Overview

Concrete tool for serving dbt documentation through the Airflow UI provided by the astronomer-cosmos library. The Cosmos plugin automatically registers a menu item and web endpoint in the Airflow UI that fetches dbt documentation artifacts from cloud storage and renders them in an iframe.

Description

The Cosmos plugin consists of multiple modules that handle Airflow version detection, storage type resolution, and version-specific web framework integration:

Plugin Entry Point

The cosmos/plugin/__init__.py module serves as the entry point for Airflow's plugin discovery system. It detects the Airflow version at import time and imports the appropriate plugin class (CosmosPlugin for Airflow 2.x or CosmosAF3Plugin for Airflow 3.x).

Airflow 2.x Implementation

The Airflow 2.x implementation uses Flask AppBuilder:

• DbtDocsView: A Flask AppBuilder BaseView subclass that exposes two endpoints:
  • /dbt_docs: Renders a template page containing an iframe that loads the dbt documentation.
  • /dbt_docs_index: Fetches and returns the raw documentation HTML from cloud storage.
• CosmosPlugin: Registers the DbtDocsView under the Browse menu category with the label dbt Docs.

Airflow 3.x Implementation

The Airflow 3.x implementation uses FastAPI:

• create_cosmos_fastapi_app(): A factory function that creates a FastAPI application with route handlers for serving documentation.
• CosmosAF3Plugin: Registers the FastAPI application at the /cosmos URL prefix.

Storage Resolution

The cosmos/plugin/storage.py module provides the get_storage_type_from_path() function that determines the cloud storage provider from the configured documentation path prefix (s3://, gs://, wasb://).

Code Reference

Source Location

Source	File	Lines
astronomer-cosmos repo	cosmos/plugin/airflow2.py	L126-210 (DbtDocsView, CosmosPlugin)
astronomer-cosmos repo	cosmos/plugin/airflow3.py	L127-308 (create_cosmos_fastapi_app, CosmosAF3Plugin)
astronomer-cosmos repo	cosmos/plugin/storage.py	L1-23 (get_storage_type_from_path)

Signatures

# Airflow 2.x (cosmos/plugin/airflow2.py)
class DbtDocsView(AppBuilderBaseView):
    default_view = "dbt_docs"

    @expose("/dbt_docs")
    def dbt_docs(self) -> str:
        ...

    @expose("/dbt_docs_index")
    def dbt_docs_index(self) -> str:
        ...


class CosmosPlugin(AirflowPlugin):
    name = "cosmos"
    appbuilder_views = [
        {
            "name": "dbt Docs",
            "category": "Browse",
            "view": DbtDocsView(),
        }
    ]


# Airflow 3.x (cosmos/plugin/airflow3.py)
def create_cosmos_fastapi_app() -> FastAPI:
    ...


class CosmosAF3Plugin(AirflowPlugin):
    name = "cosmos"
    fastapi_apps = [
        {
            "app": create_cosmos_fastapi_app(),
            "url_prefix": "/cosmos",
        }
    ]

Import

The plugin is auto-loaded by Airflow's plugin discovery mechanism. No explicit import is required. The entry point is registered in cosmos/plugin/__init__.py.

I/O Contract

Inputs (Configuration)

Parameter	Source	Required	Description
dbt_docs_dir	airflow.cfg [cosmos]	Yes	Cloud storage path where documentation artifacts are stored (e.g., s3://my-bucket/dbt_docs, gs://my-bucket/dbt_docs, wasb://my-container/dbt_docs).
dbt_docs_conn_id	airflow.cfg [cosmos]	Yes	Airflow connection ID for authenticating with the cloud storage provider.
dbt_docs_index_file_name	airflow.cfg [cosmos]	No	Name of the documentation index file to serve. Defaults to index.html. Set to static_index.html for statically generated docs.

Outputs

Output	Type	Description
Web endpoint	HTTP endpoint	Serves dbt documentation at /cosmos/dbt_docs (Airflow 3.x) or via the AppBuilder view (Airflow 2.x). Renders the documentation in an iframe within the Airflow UI.
Navigation menu item	UI element	Adds a dbt Docs entry under the Browse category in the Airflow navigation menu.

Configuration Example

airflow.cfg Settings

[cosmos]
dbt_docs_dir = s3://my-dbt-docs-bucket/dbt_docs/prod
dbt_docs_conn_id = aws_default
dbt_docs_index_file_name = index.html

GCS Configuration

[cosmos]
dbt_docs_dir = gs://my-dbt-docs-gcs-bucket/dbt_docs/prod
dbt_docs_conn_id = google_cloud_default
dbt_docs_index_file_name = index.html

Azure Configuration

[cosmos]
dbt_docs_dir = wasb://my-docs-container/dbt_docs/prod
dbt_docs_conn_id = wasb_default
dbt_docs_index_file_name = index.html

Static Index File

If using dbt's --static flag for documentation generation, configure the plugin to serve the static index:

[cosmos]
dbt_docs_dir = s3://my-dbt-docs-bucket/dbt_docs/prod
dbt_docs_conn_id = aws_default
dbt_docs_index_file_name = static_index.html

Environment Variable Override

These settings can also be configured via environment variables using the standard Airflow convention:

export AIRFLOW__COSMOS__DBT_DOCS_DIR="s3://my-dbt-docs-bucket/dbt_docs/prod"
export AIRFLOW__COSMOS__DBT_DOCS_CONN_ID="aws_default"
export AIRFLOW__COSMOS__DBT_DOCS_INDEX_FILE_NAME="index.html"

Related Pages

Implements Principle

• Principle:Astronomer_Astronomer_cosmos_Airflow_Plugin_Documentation_Hosting

Requires Environment

• Environment:Astronomer_Astronomer_cosmos_Python_Airflow_Runtime