0
# Apache Airflow Microsoft WinRM Provider
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: apache-airflow-providers-microsoft-winrm
7
- **Language**: Python
8
- **Installation**: `pip install apache-airflow-providers-microsoft-winrm`
9
- **Requires**: Apache Airflow ≥2.10.0, Python ≥3.10
10
- **Dependencies**: pywinrm ≥0.5.0
11

12
## Core Imports
13

14
```python
15
from airflow.providers.microsoft.winrm.hooks.winrm import WinRMHook
16
from airflow.providers.microsoft.winrm.operators.winrm import WinRMOperator
17
```
18

19
Version compatibility utilities:
20

21
```python
22
from airflow.providers.microsoft.winrm.version_compat import BaseHook, BaseOperator, get_base_airflow_version_tuple
23
```
24

25
Type imports for development:
26

27
```python
28
from collections.abc import Sequence
29
from winrm.protocol import Protocol
30
from airflow.utils.context import Context
31
```
32

33
## Basic Usage
34

35
### Using WinRM Hook
36

37
```python
38
from airflow.providers.microsoft.winrm.hooks.winrm import WinRMHook
39

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

43
# Or create hook with direct parameters
44
hook = WinRMHook(
45
    remote_host='192.168.1.100',
46
    username='admin',
47
    password='password',
48
    transport='ntlm',
49
    remote_port=5985
50
)
51

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

55
# Execute PowerShell script
56
return_code, stdout, stderr = hook.run(
57
    'Get-Process | Where-Object CPU -gt 100',
58
    ps_path='powershell'
59
)
60
```
61

62
### Using WinRM Operator in DAG
63

64
```python
65
from airflow import DAG
66
from airflow.providers.microsoft.winrm.operators.winrm import WinRMOperator
67
from datetime import datetime
68

69
dag = DAG(
70
    'winrm_example',
71
    start_date=datetime(2024, 1, 1),
72
    schedule_interval='@daily'
73
)
74

75
# Execute Windows command
76
win_cmd = WinRMOperator(
77
    task_id='check_windows_services',
78
    command='sc query',
79
    ssh_conn_id='winrm_default',
80
    dag=dag
81
)
82

83
# Execute PowerShell script
84
ps_script = WinRMOperator(
85
    task_id='get_system_info',
86
    command='Get-ComputerInfo | Select-Object WindowsProductName, TotalPhysicalMemory',
87
    ps_path='powershell',
88
    ssh_conn_id='winrm_default',
89
    dag=dag
90
)
91
```
92

93
## Architecture
94

95
The provider follows Airflow's hook-operator pattern:
96

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

101
## Capabilities
102

103
### WinRM Connection and Authentication
104

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

107
```python { .api }
108
class WinRMHook(BaseHook):
109
    def __init__(
110
        self,
111
        ssh_conn_id: str | None = None,
112
        endpoint: str | None = None,
113
        remote_host: str | None = None,
114
        remote_port: int = 5985,
115
        transport: str = "plaintext",
116
        username: str | None = None,
117
        password: str | None = None,
118
        service: str = "HTTP",
119
        keytab: str | None = None,
120
        ca_trust_path: str | None = None,
121
        cert_pem: str | None = None,
122
        cert_key_pem: str | None = None,
123
        server_cert_validation: str = "validate",
124
        kerberos_delegation: bool = False,
125
        read_timeout_sec: int = 30,
126
        operation_timeout_sec: int = 20,
127
        kerberos_hostname_override: str | None = None,
128
        message_encryption: str | None = "auto",
129
        credssp_disable_tlsv1_2: bool = False,
130
        send_cbt: bool = True,
131
    ) -> None: ...
132
    
133
    def get_conn(self) -> Protocol: ...
134
    def run(
135
        self,
136
        command: str,
137
        ps_path: str | None = None,
138
        output_encoding: str = "utf-8",
139
        return_output: bool = True,
140
    ) -> tuple[int, list[bytes], list[bytes]]: ...
141
    def test_connection(self) -> tuple[bool, str]: ...
142
```
143

144
[WinRM Hook](./winrm-hook.md)
145

146
### Task Execution and Workflow Integration
147

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

150
```python { .api }
151
class WinRMOperator(BaseOperator):
152
    template_fields: Sequence[str] = ("command",)
153
    template_fields_renderers = {"command": "powershell"}
154
    
155
    def __init__(
156
        self,
157
        *,
158
        winrm_hook: WinRMHook | None = None,
159
        ssh_conn_id: str | None = None,
160
        remote_host: str | None = None,
161
        command: str | None = None,
162
        ps_path: str | None = None,
163
        output_encoding: str = "utf-8",
164
        timeout: int = 10,
165
        expected_return_code: int | list[int] | range = 0,
166
        **kwargs,
167
    ) -> None: ...
168
    
169
    def execute(self, context: Context) -> list | str: ...
170
```
171

172
[WinRM Operator](./winrm-operator.md)
173

174
### Version Compatibility
175

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

178
```python { .api }
179
def get_base_airflow_version_tuple() -> tuple[int, int, int]: ...
180

181
AIRFLOW_V_3_0_PLUS: bool
182
AIRFLOW_V_3_1_PLUS: bool
183
BaseOperator: type
184
BaseHook: type
185
```
186

187
[Version Compatibility](./version-compatibility.md)
188

189
## Security Features
190

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

198
## Error Handling
199

200
The provider raises `AirflowException` for:
201
- Connection failures to remote Windows hosts
202
- Missing required connection parameters
203
- Command execution failures with non-zero return codes
204
- Authentication failures across all supported methods
205

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