or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdversion-compatibility.mdwinrm-hook.mdwinrm-operator.md
tile.json

tessl/pypi-apache-airflow-providers-microsoft-winrm

Apache Airflow provider package for Windows Remote Management (WinRM) protocol integration enabling remote command execution on Windows systems

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/apache-airflow-providers-microsoft-winrm@3.11.x

To install, run

npx @tessl/cli install tessl/pypi-apache-airflow-providers-microsoft-winrm@3.11.0

index.mddocs/

Apache Airflow Microsoft WinRM Provider

Apache Airflow provider package for Windows Remote Management (WinRM) protocol integration. Enables Airflow workflows to execute commands and scripts on remote Windows systems through secure WinRM connections, supporting multiple authentication methods and comprehensive remote Windows administration capabilities.

Package Information

  • Package Name: apache-airflow-providers-microsoft-winrm
  • Language: Python
  • Installation: pip install apache-airflow-providers-microsoft-winrm
  • Requires: Apache Airflow ≥2.10.0, Python ≥3.10
  • Dependencies: pywinrm ≥0.5.0

Core Imports

from airflow.providers.microsoft.winrm.hooks.winrm import WinRMHook
from airflow.providers.microsoft.winrm.operators.winrm import WinRMOperator

Version compatibility utilities:

from airflow.providers.microsoft.winrm.version_compat import BaseHook, BaseOperator, get_base_airflow_version_tuple

Type imports for development:

from collections.abc import Sequence
from winrm.protocol import Protocol
from airflow.utils.context import Context

Basic Usage

Using WinRM Hook

from airflow.providers.microsoft.winrm.hooks.winrm import WinRMHook

# Create hook with connection ID
hook = WinRMHook(ssh_conn_id='winrm_default')

# Or create hook with direct parameters
hook = WinRMHook(
    remote_host='192.168.1.100',
    username='admin',
    password='password',
    transport='ntlm',
    remote_port=5985
)

# Execute command
return_code, stdout, stderr = hook.run('dir C:\\')

# Execute PowerShell script
return_code, stdout, stderr = hook.run(
    'Get-Process | Where-Object CPU -gt 100',
    ps_path='powershell'
)

Using WinRM Operator in DAG

from airflow import DAG
from airflow.providers.microsoft.winrm.operators.winrm import WinRMOperator
from datetime import datetime

dag = DAG(
    'winrm_example',
    start_date=datetime(2024, 1, 1),
    schedule_interval='@daily'
)

# Execute Windows command
win_cmd = WinRMOperator(
    task_id='check_windows_services',
    command='sc query',
    ssh_conn_id='winrm_default',
    dag=dag
)

# Execute PowerShell script
ps_script = WinRMOperator(
    task_id='get_system_info',
    command='Get-ComputerInfo | Select-Object WindowsProductName, TotalPhysicalMemory',
    ps_path='powershell',
    ssh_conn_id='winrm_default',
    dag=dag
)

Architecture

The provider follows Airflow's hook-operator pattern:

  • WinRMHook: Low-level interface for WinRM connections and command execution
  • WinRMOperator: High-level Airflow operator for task definitions in DAGs
  • Version Compatibility Layer: Ensures compatibility across Airflow versions 2.10+ and 3.0+

Capabilities

WinRM Connection and Authentication

Comprehensive WinRM connection management with support for multiple authentication methods, secure transports, and extensive configuration options for enterprise Windows environments.

class WinRMHook(BaseHook):
    def __init__(
        self,
        ssh_conn_id: str | None = None,
        endpoint: str | None = None,
        remote_host: str | None = None,
        remote_port: int = 5985,
        transport: str = "plaintext",
        username: str | None = None,
        password: str | None = None,
        service: str = "HTTP",
        keytab: str | None = None,
        ca_trust_path: str | None = None,
        cert_pem: str | None = None,
        cert_key_pem: str | None = None,
        server_cert_validation: str = "validate",
        kerberos_delegation: bool = False,
        read_timeout_sec: int = 30,
        operation_timeout_sec: int = 20,
        kerberos_hostname_override: str | None = None,
        message_encryption: str | None = "auto",
        credssp_disable_tlsv1_2: bool = False,
        send_cbt: bool = True,
    ) -> None: ...
    
    def get_conn(self) -> Protocol: ...
    def run(
        self,
        command: str,
        ps_path: str | None = None,
        output_encoding: str = "utf-8",
        return_output: bool = True,
    ) -> tuple[int, list[bytes], list[bytes]]: ...
    def test_connection(self) -> tuple[bool, str]: ...

WinRM Hook

Task Execution and Workflow Integration

Airflow operator for seamless integration of Windows remote commands into data pipeline workflows, with templating support and comprehensive error handling.

class WinRMOperator(BaseOperator):
    template_fields: Sequence[str] = ("command",)
    template_fields_renderers = {"command": "powershell"}
    
    def __init__(
        self,
        *,
        winrm_hook: WinRMHook | None = None,
        ssh_conn_id: str | None = None,
        remote_host: str | None = None,
        command: str | None = None,
        ps_path: str | None = None,
        output_encoding: str = "utf-8",
        timeout: int = 10,
        expected_return_code: int | list[int] | range = 0,
        **kwargs,
    ) -> None: ...
    
    def execute(self, context: Context) -> list | str: ...

WinRM Operator

Version Compatibility

Cross-version compatibility utilities ensuring seamless operation across different Airflow versions while maintaining consistent API access to base classes.

def get_base_airflow_version_tuple() -> tuple[int, int, int]: ...

AIRFLOW_V_3_0_PLUS: bool
AIRFLOW_V_3_1_PLUS: bool
BaseOperator: type
BaseHook: type

Version Compatibility

Security Features

  • Multiple Authentication Methods: plaintext, kerberos, ssl, ntlm, credssp
  • Certificate-based Authentication: Client certificates for SSL/TLS
  • Message Encryption: Automatic message encryption with transport support
  • Server Certificate Validation: Configurable certificate validation policies
  • Channel Binding: HTTPS channel binding support
  • Kerberos Integration: Full Kerberos delegation and hostname override support

Error Handling

The provider raises AirflowException for:

  • Connection failures to remote Windows hosts
  • Missing required connection parameters
  • Command execution failures with non-zero return codes
  • Authentication failures across all supported methods

WinRM operation timeouts are handled gracefully with automatic retries for long-running processes.