| .. Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| .. http://www.apache.org/licenses/LICENSE-2.0 |
| |
| .. Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| |
| Microsoft PSRP Operators |
| ======================================= |
| |
| The |
| `PowerShell Remoting Protocol (PSRP) |
| <https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-psrp/>`__ |
| protocol is required whenever a user wants to execute commands on a Windows |
| server from a client using a native PowerShell runspace. |
| |
| The :class:`~airflow.providers.microsoft.psrp.operators.psrp.PsrpOperator` |
| operator implements such client capabilities, enabling the |
| scheduling of Windows jobs from Airflow. Internally, it makes use of |
| the `pypsrp <https://pypi.org/project/pypsrp/>`__ client library. |
| |
| Compared to |
| :class:`~airflow.providers.microsoft.winrm.operators.winrm.WinRMOperator`, |
| using PSRP extends the remoting capabilities in Windows, providing |
| better session control and close integration with the PowerShell |
| ecosystem (i.e., .NET Runspace interface): |
| |
| * Run multiple commands in a single session |
| * Reuse the runspace to create multiple sessions |
| * Work with PowerShell objects instead of just text |
| * Use constrained endpoints using JEA (Just-Enough-Administration) |
| * Ability to use the .NET Runspace interface |
| |
| |
| Using the Operator |
| ^^^^^^^^^^^^^^^^^^ |
| |
| When instantiating the |
| :class:`~airflow.providers.microsoft.psrp.operators.psrp.PsrpOperator` |
| operator, you must provide a cmdlet, command or script using one of the |
| following named arguments: |
| |
| .. list-table:: Provide one of the following arguments to the operator |
| :widths: 10 15 20 |
| :header-rows: 1 |
| |
| * - Argument name |
| - Description |
| - Examples |
| * - cmdlet |
| - Invoke a PowerShell cmdlet. |
| - ``Copy-Item``, ``Restart-Computer`` |
| * - command |
| - Carries out the specified command using the |
| `cmd <https://docs.microsoft.com/en-us/windows-server/ |
| administration/windows-commands/cmd>`__ command interpreter. |
| - ``robocopy C:\Logfiles\* C:\Drawings /S /E`` |
| * - powershell |
| - Run a PowerShell script. |
| - ``Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings" -Recurse`` |
| |
| |
| Output |
| ###### |
| |
| PowerShell provides multiple output streams. |
| |
| In general, the operator logs a record using the built-in logging |
| mechanism for records that arrive on these streams using a job status |
| polling mechanism. The success stream (i.e., stdout or shell output) |
| is handled differently, as explained in the following: |
| |
| When :doc:`XComs <apache-airflow:concepts/xcoms>` are enabled and when |
| the operator is used with a native PowerShell cmdlet or script, the |
| shell output is converted to JSON using the ``ConvertTo-Json`` cmdlet |
| and then decoded on the client-side by the operator such that the |
| operator's return value is compatible with the serialization required |
| by XComs. |
| |
| When XComs are not enabled (that is, ``do_xcom_push`` is set to |
| false), the shell output is instead logged like the other output |
| streams and will appear in the task instance log. |
| |
| |
| Secure strings |
| ############## |
| |
| The operator adds a template filter ``securestring`` which will encrypt |
| the value and make it available in the remote session as a |
| `SecureString |
| <https://docs.microsoft.com/en-us/dotnet/api/system.security.securestring>`__ |
| type. This ensures for example that the value is not accidentally |
| logged. |
| |
| Using the template filter requires the DAG to be configured to |
| :ref:`render fields as native objects |
| <concepts:templating-native-objects>` (the default is to coerce all |
| values into strings which won't work here because we need a value |
| which has been tagged to be serialized as a secure string). Use |
| ``render_template_as_native_obj=True`` to enable this. |