How to execute local commands in a provider

Use Case

Local providers need to execute commands to inspect and manage local resources.

Describe the Solution You Would Like

There was a Commands API in early versions of the Resource API, which ticked a number of boxes around ease-of-use, safety, platform-awareness, and integration with Resource API patterns. That iteration was built on the childprocess gem which - due to its dependency on FFI - was not acceptable to ship in the puppet agent.

Having a dedicated Resource API layer would also enable us to do advanced checks like verifying noop-correctness (see PDK-565 for examples).

Describe Alternatives You've Considered

• recommend folks to use exec/open3 directly. steep learning curve, easy to misuse, especially on windows.
• recommend Puppet::Util::Execution.

Additional Context

Originally filed as https://tickets.puppetlabs.com/browse/PDK-847 .

@kreeuwijk said

As someone who has only just started to [dip my toes|https://github.com/kreeuwijk/puppet-patch_mgmt/blob/master/lib/puppet/provider/patch_win/patch_win.rb] into the types & providers development space, let me give you an outside perspective to what the experience is today for a starting Puppet developer:

TLDR: The learning curve is still very, very steep if you're not a skilled Ruby developer. The Resource API needs to do more to make provider development easier.

While the PDK has helped in creating the skeleton for new types & providers, the main aspect of executing actions is still mostly left to the knowledge of the developer:

• Running external processes (bash, powerhshell) and doing error handling & output capture
• Transforming external process output into consumable puppet resources
• Interacting with external APIs

I've spent all day yesterday researching a useable way to execute some Powershell code in a custom provider, after I learned that the Puppet::ResourceApi:Command is no longer part of the Resource API (even though the apt-key2 example that the Resource API documentation points to, still has it in its code). I've tried to use Open3 but found it too difficult and cumbersome, and finally gave up and used exec() to at least get something working.

The Resource API should take care of this basic need for me. It should provide a generalized way to execute external code (bash, batch, powershell, etc) and provide core capabilities like error handling, context awareness and output capturing. Right now I don't even know how to preserve context awareness since I can't use Puppet::ResourceApi:Command.

I would like to see clearer guidance on how to execute commands/processes with the Resource API in the state that it's in today, and how to handle context awareness in relationship to that. Then hopefully this guidance can be updated later when we do have a generalized & easier way to deal with this challenge.

Start by reviewing the existing Resource API command references, the apt-key2 example mentioned in the issue, and Puppet::Util::Execution. Determine whether the intended outcome is clearer current guidance or a new Resource API layer for local process execution. Done requires an agreed scope covering command execution, output and error handling, platform context, and noop behavior.