Aws-cdk: Document how `--plugin` works, features, and how/why to implement custom plugins

[0xdevalias]

I noticed that the CDK CLI help makes reference to a --plugin option, but beyond this description, couldn't find much more documentation about it:

--plugin, -p         Name or path of a node package that extend the CDK
                       features. Can be specified multiple times         [array]

When searching the repo, I found the following references:

• https://github.com/awslabs/aws-cdk/blob/master/packages/aws-cdk/bin/cdk.ts#L41
• https://github.com/awslabs/aws-cdk/blob/master/packages/aws-cdk/bin/cdk.ts#L132-L156
• https://github.com/awslabs/aws-cdk/blob/master/packages/aws-cdk/lib/plugin.ts#L6-L19

Based on the contract defined in plugins.ts I can see what a plugin would have to look like, and how it is loaded. When a plugin is initialised it receives an instance of PluginHost, but as best I can tell this only seems to give them access to registerCredentialProviderSource.

So I guess my question at the moment is: is that all a plugin can do? Is it able to get access to/add/modify other things at the moment (or in the future will it be able to?)

[eladb]

Yes, at the moment, the toolkit can only be extended around credential providers, but we are open to requests for other extensibility points. @Doug-AWS @RomainMuller, could you please add a little doc section on toolkit plugins in the tools topic?

[RomainMuller]

I'm looking into writing some basic documentation for the existing functionality (as well as hinting that we're happy to add more as the needs arise).

[0xdevalias]

Doco looks great! Much clearer. Thanks! :)

[kcwinner]

Any roadmap for additional plugin support? Working on something that would be nice to hook in. I can can just write an external package for javascript but would be cooler with more native support.

[rrrix]

Hi @RomainMuller, I think this got lost in the ether somewhere. :( Maybe when the docs moved from this repository to github.com/awsdocs/aws-cdk-guide?

I don't see any documentation related to Plugins on the "main" CDK tools page: https://docs.aws.amazon.com/cdk/latest/guide/tools.html

Nor in the related GitHub repo: https://github.com/awsdocs/aws-cdk-guide/blob/master/doc_source/tools.md

A search for "plugin" on the CDK Docs site returns only the single mention on the Tools page for the CLI argument.