Add/update documentation for machine setup configs (kubernetes-sigs#120)

* Update gcp-deployer contributing doc for path references and
gcp-deployer create command

* Update gcp-deployer readme with machine setup configs changes

* Update cluster-api contributing with configurable machine setup info

* Update cluster-api contributing

* Add note about default --machinesetup value

CONTRIBUTING.md

@@ -62,6 +62,28 @@ When a cluster is first created with a cluster config file, there is no master n
 * The machine controller creates resources (Machines etc)
 * Pivot the apiserver and the machine controller in to the cluster.
 
+#### Configurable Machine Setup
+
+While not mandatory, it is suggested for new providers to support configurable machine setups for creating new machines. 
+This is to allow flexibility in what startup scripts are used and what versions are supported instead of hardcoding startup scripts into the machine controller.
+You can find an example implementation for GCE [here](https://github.com/kubernetes-sigs/cluster-api/blob/master/cloud/google/machinesetup/config_types.go).
+
+##### GCE Implementation
+
+For GCE, a [yaml file](https://github.com/kubernetes-sigs/cluster-api/blob/master/gcp-deployer/machine_setup_configs.yaml) holds the list of valid machine setup configs, 
+and the yaml file is volume mounted into the machine controller using a ConfigMap named `machine-setup`. 
+
+A [config type](https://github.com/kubernetes-sigs/cluster-api/blob/master/cloud/google/machinesetup/config_types.go#L45) defines a set of parameters that can be taken from the machine object being created, and maps those parameters to startup scripts and other relevant information. 
+In GCE, the OS, machine roles, and version info are the parameters that map to a GCP image path and metadata (which contains the startup script).
+
+When creating a new machine, there should be a check for whether the machine setup is supported. 
+This is done by looking through the valid configs parsed out of the yaml for a config with matching parameters.
+If a match is found, then the machine can be created with the startup script found in the config.
+If no match is found, then the given machine configuration is not supported.
+Getting the script onto the machine and running it on startup is a provider specific implementation detail. 
+
+More details can be found in the [design doc](https://docs.google.com/document/d/1OfykBDOXP_t6QEtiYBA-Ax7nSpqohFofyX-wOxrQrnw/edit?ts=5ae11208#heading=h.xgjl2srtytjt), but note that it is GCE specific.
+
 ### A specific Machine can be deleted, freeing external resources associated with it.
 
 When the client deletes a Machine object, your controller's reconciler should trigger the deletion of the Machine that backs that machine. The delete is provider specific, but usually requires deleting the VM and freeing up any external resources (like IP).

gcp-deployer/CONTRIBUTING.md

@@ -74,14 +74,14 @@ If you need to rebuild container image for the extension APIServer and Controlle
 
 2. Clone Repo Locally
 ```bash
-$ cd $GOPATH/src/k8s.io/
-$ git clone https://github.com/<GITHUB_USERNAME>/kube-deploy.git
+$ cd $GOPATH/src/sigs.k8s.io/
+$ git clone https://github.com/<GITHUB_USERNAME>/cluster-api.git
 ```
 
 ## Build
 
 ```bash
-$ cd $GOPATH/src/k8s.io/kube-deploy/cluster-api/gcp-deployer/
+$ cd $GOPATH/src/sigs.k8s.io/cluster-api/gcp-deployer/
 $ go build
 ```
 
@@ -109,7 +109,7 @@ NOTE: that the image will be pushed to `gcr.io/$(GCLOUD_PROJECT)/apiserver-contr
 2. Rebuild gcp-deployer
 
 	```bash
-    $ cd $GOPATH/src/k8s.io/kube-deploy/cluster-api/gcp-deployer/
+    $ cd $GOPATH/src/sigs.k8s.io/cluster-api/gcp-deployer/
 	$ go build
 	```
 
@@ -137,7 +137,7 @@ ERROR: (gcloud.config.get-value) Section [core] has no property [project].
 1. Create a cluster
 
 	```bash
-	$ ./gcp-deployer create -c cluster.yaml -m machines.yaml
+	$ ./gcp-deployer create -c cluster.yaml -m machines.yaml -s machine_setup_configs.yaml
 	```
 [Optional]To verify API server has been deployed successfully, you can the following command to double check.
 

gcp-deployer/README.md

@@ -13,14 +13,15 @@ Follow the steps listed at [CONTRIBUTING.md](CONTRIBUTING.md) to:
 
 ### Limitation
 
-gcp-deployer tool only supports Kubernetes version 1.8 or newer.
+gcp-deployer tool only supports Kubernetes version 1.9 or newer.
 
 ### Creating a cluster
 
 1. *Optional* update `machines.yaml` to give your preferred GCP zone in
 each machine's `providerConfig` field.
 1. *Optional*: Update `cluster.yaml` to set a custom cluster name.
-1. Create a cluster: `./gcp-deployer create -c cluster.yaml -m machines.yaml`
+1. Create a cluster: `./gcp-deployer create -c cluster.yaml -m machines.yaml -s machine_setup_configs.yaml`.
+    1. **Note**: The `--machinesetup` or `-s` flag is set to `machine_setup_configs.yaml` by default.
 
 During cluster creation, you can watch the machine resources get created in Kubernetes,
 see the corresponding virtual machines created in GCP, and then finally see nodes
@@ -50,7 +51,7 @@ You can add machines to your cluster using `kubectl apply` or `kubectl create`.
 
 #### Upgrading your cluster
 
-By default, your cluster will initially be running Kubernetes version 1.7.4. You
+By default, your cluster will initially be running Kubernetes version 1.9.4. You
 can upgrade the control plane or nodes using `kubectl edit` or you can run the
 [upgrader tool](../tools/upgrader)
 to upgrade your entire cluster with a single command.
@@ -84,3 +85,16 @@ controller manager as a pod inside the cluster. Like other resources in Kubernet
 controller as part of controller manager is responsible to reconcile the actual vs. desired machine
 state. Bootstrapping and in-place upgrading is handled by
 [kubeadm](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/).
+
+### Machine Setup Configs
+
+The `machine_setup_configs.yaml` file defines what machine setups are supported 
+(i.e. what machine definitions are allowed in `machines.yaml`). 
+Here is an [example yaml](machine_setup_configs.yaml) with a master config and a node config.
+You are free to edit this file to support other machine setups (i.e. different versions, images, or startup scripts).
+The yaml is unmarshalled into a [machinesetup.configList](../cloud/google/machinesetup/config_types.go).
+
+#### Startup Scripts
+Right now, the startup scripts must be bash scripts. 
+There is a set of environment variables that is concatenated to the beginning of the startup script.
+You can find them [here](../cloud/google/metadata.go) and use them in your startup script as needed.