API-based cluster provider (vscode-kubernetes-tools#66)

CONTRIBUTING.md

@@ -10,8 +10,20 @@ contact [[email protected]](mailto:[email protected]) with any additio
 
 ## The 'Create Cluster' and 'Configure From Cluster' Commands
 
-The 'Create Cluster' and 'Configure from Cluster' commands rely on provider-specific tools or APIs for interacting with the cloud or cluster.  Unfortunately, we don't have a general-purpose, API-style extension point for implementing new cloud providers, because we don't know enough about how configuring different cluster types might work in different environments.
+The 'Create Cluster' and 'Configure from Cluster' commands rely on provider-specific tools or APIs for interacting with the cloud or cluster.  We have a basic extension point for implementing new cloud providers.  **This is currently experimental and we welcome feedback.**
 
-At the moment, the extension provides a generic (albeit fiddly) mechanism for managing a series of pages in a UI (example: displaying a list of accounts for the user to choose from), invoking tools or APIs for populating state to be used in constructing those pages (example: invoking the Azure CLI to get a list of subscriptions), and flowing choices and state between those pages (example: returning the selected account so that another tool can list the clusters in that account).  However, the cloud-specific pages and logic have to be built using artisanal TypeScript and built into this extension via pull request - we don't provide a nice way for you to externalise different providers.
+To implement a provider for the 'Create Cluster' and/or 'Configure from Cluster' commands, your extension needs to do the following:
 
-We'd be _really really happy_ to work with anyone wanting to implement providers for e.g. minikube, GKE, EKS, etc., both to help you understand how the existing implementation works, and to collaborate on simplifying and stabilising an extension mechanism.
+* Set itself for automatic activation (the `*` activation event).  We know this isn't great and would love to discuss a better approach.
+* Start a HTTP server listening on a port of your choice (see `port` below).  This HTTP server will serve up the HTML pages by which the user chooses a cluster or specifies creation settings.
+* Get the VS Code Kubernetes extension's API object via the `vscode.extensions.getExtension<T>` and `Extension<T>.activate()` functions.
+* The API object has a field named `clusterProviderRegistry`.  This is an object you can use to register the type(s) of cluster you support.  Call the registry's `register` method, passing an object with the following fields:
+  * `id` (string): an identifier for the type of cluster.  This needs to be unique across all providers, as we use it to dispatch the user's selected cluster type to the appropriate handler.  E.g. for Azure Kubernetes Service we use `aks`.
+  * `displayName` (string): the display name for the type of cluster.  E.g. for Azure Kubernetes Service we use (wait for it) `Azure Kubernetes Service`.
+  * `port` (number): the port on which your provider will serve the requisite configuration pages.
+  * `supportedActions` (string[]): an array of strings specifying which commands you support for this cluster type.  The supported commands are `configure` and `create` - any other strings in the array will be ignored.
+* When the user choose 'Create Cluster' or 'Configure from Cluster', the extension displays a list of all registered cluster types supporting the appropriate command (using the `displayName` attribute and filtering using the `supportedActions` attribute).
+* When the user selects a cluster type, the extension makes a HTTP GET request to `http://localhost:<port>/<action>?clusterType=<id>`, where `port` and `id` are the port and id associated with the cluster type in its registration, and `action` is `configure` or `create` according to which command the user is executing.
+* Your HTTP server must respond to this request with a suitable first page.  From this point on it is all in your hands, though typically your first page will gather some information, and have a link either to further information-gathering pages or to perform the action immediately.
+
+For an example of this, see the `components/clusterprovider/azure` directory.  If you have any questions or run into any problems, please post an issue - we'll be very happy to help.