Fix markdown

CONTRIBUTING.md

@@ -12,13 +12,12 @@ Please fill out either the individual or corporate Contributor License Agreement
 
 ## Finding Things That Need Help
 
-If you're new to the project and want to help, but don't know where to start, we have a semi-curated list of issues that should not need deep knowledge of the system. [Have a look and see if anything sounds interesting](https://github.com/kubernetes/kube-deploy/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+label%3Acluster-api). Alternatively, read some of the docs on other controllers and try to write your own, file and fix any/all issues that come up, including gaps in documentation!
+If you're new to the project and want to help, but don't know where to start, we have a semi-curated list of issues that should not need deep knowledge of the system. [Have a look and see if anything sounds interesting](https://github.com/kubernetes-sigs/cluster-api/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). Alternatively, read some of the docs on other controllers and try to write your own, file and fix any/all issues that come up, including gaps in documentation!
 
 ## Contributing a Patch
 
 1. If you haven't already done so, sign a Contributor License Agreement (see details above).
-1. [TODO](https://github.com/kubernetes/kube-deploy/issues/474): Read the [cluster-api development guide](https://github.com/kubernetes/kube-deploy/issues/474).
-1. Fork the desired repo, develop and test your code changes. (TODO: we don't have tests yet. See `cluster-api-gcp` README for manual testing for now.)
+1. Fork the desired repo, develop and test your code changes. 
 1. Submit a pull request.
 
 All changes must be code reviewed. Coding conventions and standards are explained in the official [developer docs](https://github.com/kubernetes/community/tree/master/contributors/devel). Expect reviewers to request that you avoid common [go style mistakes](https://github.com/golang/go/wiki/CodeReviewComments) in your PRs.
@@ -27,11 +26,70 @@ All changes must be code reviewed. Coding conventions and standards are explaine
 
 Cluster API maintainers may add "LGTM" (Looks Good To Me) or an equivalent comment to indicate that a PR is acceptable. Any change requires at least one LGTM.  No pull requests can be merged until at least one Cluster API maintainer signs off with an LGTM.
 
+## Cloud Provider Dev Guide
+
+### Overview
+
+The Cluster API is a Kubernetes project to bring declarative, Kubernetes-style APIs to cluster creation, configuration, and management. It provides optional, additive functionality on top of core Kubernetes.
+
+This document is meant to help OSS contributors implement support for providers (cloud or on-prem).
+
+As part of adding support for a provider (cloud or on-prem), you will need to:
+
+1.  Create tooling that conforms to the Cluster API (described further below)
+1.  A machine controller that can run independent of the cluster. This controller should handle the lifecycle of the machines, whether it's run in-cluster or out-cluster.
+
+The machine controller should be able to act on a subset of machines that form a cluster (for example using a label selector).
+
+### Resources
+
+*   [Cluster Management API KEP](https://github.com/kubernetes/community/blob/master/keps/sig-cluster-lifecycle/0003-cluster-api.md)
+*   [Cluster type](https://github.com/kubernetes-sigs/cluster-api/blob/master/cluster-api/pkg/apis/cluster/v1alpha1/cluster_types.go#L40)
+*   [Machine type](https://github.com/kubernetes-sigs/cluster-api/blob/master/cluster-api/pkg/apis/cluster/v1alpha1/machine_types.go#L42)
+
+### Boostrapping
+
+To minimize code duplication and maximize flexibility, bootstrap clusters with an external Cluster Management API Stack. A Cluster Management API Stack contains all the components needed to provide Kubernetes Cluster Management API for a cluster. [Bootstrap Process Design Details](https://docs.google.com/document/d/1CnzIXtitfbO6Y7ZxVWROGO8jr19t0vooDx-YQ7c2nbI/edit?usp=sharing).
+
+### A new Machine can be created in a declarative way
+
+**A new Machine can be created in a declarative way, including Kubernetes version and container runtime version. It should also be able to specify provider-specific information such as OS image, instance type, disk configuration, etc., though this will not be portable.**
+
+When a cluster is first created with a cluster config file, there is no master node or api server. So the user will need to bootstrap a cluster. While the implementation details are specific to the provider, the following guidance should help you:
+
+* Your tool should spin up the external apiserver and the machine controller.
+* POST the objects to the apiserver.
+* The machine controller creates resources (Machines etc)
+* Pivot the apiserver and the machine controller in to the cluster.
+
+### 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).
+
+### A specific Machine can be upgraded or downgraded
+
+These include:
+
+*   A specific Machine can have its kubelet version upgraded or downgraded.
+*   A specific Machine can have its container runtime changed, or its version upgraded or downgraded.
+*   A specific Machine can have its OS image upgraded or downgraded.
+
+A sample implementation for an upgrader is [provided here](https://github.com/kubernetes-sigs/cluster-api/blob/master/cluster-api/tools/upgrader/util/upgrade.go). Each machine is upgraded serially, which can amount to:
+
+```
+for machine in machines:
+    upgrade machine
+```
+
+The specific upgrade logic will be implement as part of the machine controller, and is specific to the provider. The user provided provider config will be in `machine.Spec.ProviderConfig`.
+
+Discussion around in-place vs replace upgrades [is here](https://github.com/kubernetes/community/blob/master/keps/sig-cluster-lifecycle/0003-cluster-api.md#in-place-vs-replace).
+
 ## Support Channels
 
 Whether you are a user or contributor, official support channels include:
 
-- GitHub issues: https://github.com/kubernetes/kube-deploy/issues/new
+- GitHub issues: https://github.com/kubernetes-sigs/cluster-api/issues/new
 - Slack: Chat with us on [Slack](http://slack.k8s.io/): #cluster-api
 - Email: [kubernetes-sig-cluster-lifecycle](https://groups.google.com/forum/#!forum/kubernetes-sig-cluster-lifecycle) mailing list
 

README.md

@@ -1,7 +1,41 @@
-# Cluster Lifecycle - Cluster API
+# Cluster API
+## What is the Cluster API?
 
-Home for the cluster api work, a subproject of sig-cluster-lifecycle
+The Cluster API is a Kubernetes project to bring declarative, Kubernetes-style
+APIs to cluster creation, configuration, and management. It provides optional,
+additive functionality on top of core Kubernetes.
 
-Note that this is the new home for the work contained in the [kube-deploy](https://github.com/kubernetes/kube-deploy/tree/master/cluster-api) repository.
+Note that Cluster API effort is still in the prototype stage while we get
+feedback on the API types themselves. All of the code here is to experiment with
+the API and demo its abilities, in order to drive more technical feedback to the
+API design. Because of this, all of the prototype code is rapidly changing.
 
-This repository will be updated as soon as possible!
+![Cluster API Architecture](architecture.png "Cluster API Architecture")
+
+To learn more, see the [Cluster API KEP][cluster-api-kep].
+
+## Get involved!
+
+* Join our Cluster API working group sessions
+  * Weekly on Wednesdays @ 11:00 PT (19:00 UTC) on [Zoom][zoomMeeting]
+  * Previous meetings: \[ [notes][notes] | [recordings][recordings] \]
+* Chat with us on [Slack](http://slack.k8s.io/): #cluster-api
+
+## Getting Started
+### Prerequisites
+* `kubectl` is required, see [here](http://kubernetes.io/docs/user-guide/prereqs/).
+
+### Prototype implementations
+* [gcp](https://github.com/kubernetes/kube-deploy/blob/master/cluster-api/gcp-deployer/README.md)
+
+## How to use the API
+
+To see how to build tooling on top of the Cluster API, please check out a few examples below:
+
+* [upgrader](tools/upgrader/README.md): a cluster upgrade tool.
+* [repair](tools/repair/README.md): detect problematic nodes and fix them.
+
+[cluster-api-kep]: https://github.com/kubernetes/community/blob/master/keps/sig-cluster-lifecycle/0003-cluster-api.md
+[notes]: https://docs.google.com/document/d/16ils69KImmE94RlmzjWDrkmFZysgB2J4lGnYMRN89WM/edit
+[recordings]: https://www.youtube.com/playlist?list=PL69nYSiGNLP29D0nYgAGWt1ZFqS9Z7lw4
+[zoomMeeting]: https://zoom.us/j/166836624

cluster-api/tools/repair/README.md

@@ -6,9 +6,9 @@ that can be built in a cloud-agnostic way.
 ## Build
 
 ```bash
-$ cd $GOPATH/src/k8s.io/
-$ git clone git@github.com:kubernetes/kube-deploy.git
-$ cd kube-deploy/cluster-api/tools/repair
+$ cd $GOPATH/src/sigs.k8s.io/
+$ git clone https://github.com/kubernetes-sigs/cluster-api
+$ cd cluster-api/cluster-api/tools/repair
 $ go build
 ```
 

cluster-api/tools/upgrader/README.md

@@ -7,9 +7,9 @@ top of the Cluster API in a completely cloud-agnostic way.
 ## Building
 
 ```bash
-$ cd $GOPATH/src/k8s.io/
-$ git clone git@github.com:kubernetes/kube-deploy.git
-$ cd kube-deploy/cluster-api/tools/upgrader
+$ cd $GOPATH/src/sigs.k8s.io/
+$ git clone https://github.com/kubernetes-sigs/cluster-api
+$ cd cluster-api/cluster-api/tools/upgrader
 $ go build
 ```