Part of creation of provider

docs/book/provider_implementations/building_running_and_testing.md

@@ -0,0 +1,60 @@
+# Building
+
+## Fixup Makefile to include common Cluster API CRDs
+
+Apply the following patch:
+
+```bash
+diff --git a/Makefile b/Makefile
+index ac12c7e..cf44312 100644
+--- a/Makefile
++++ b/Makefile
+@@ -22,12 +22,15 @@ install: manifests
+
+ # Deploy controller in the configured Kubernetes cluster in ~/.kube/config
+ deploy: manifests
+-	kubectl apply -f config/crds
+-	kustomize build config/default | kubectl apply -f -
++	cat provider-components.yaml | kubectl apply -f -
+
+ # Generate manifests e.g. CRD, RBAC etc.
+ manifests:
+ 	go run vendor/sigs.k8s.io/controller-tools/cmd/controller-gen/main.go all
++	sed -i'' -e 's@^- manager_auth_proxy_patch.yaml.*@#&@' config/default/kustomization.yaml
++	kustomize build config/default/ > provider-components.yaml
++	echo "---" >> provider-components.yaml
++	kustomize build vendor/sigs.k8s.io/cluster-api/config/default/ >> provider-components.yaml
+
+ # Run go fmt against code
+ fmt:
+```
+
+## Build and push images
+
+Determine a location to upload your container and then build and push it:
+
+```bash
+export IMG=<your-docker-registry>/cluster-api-provider-solas
+dep ensure
+make
+make docker-build IMG=${IMG}
+make docker-push IMG=${IMG}
+```
+
+## Start minikube and deploy the provider
+
+```bash
+minikube start
+make deploy
+```
+
+## Verify deployment
+
+**TODO**: Should deploy a sample `Cluster` and `Machine` resource to verify 
+controllers are reconciling properly. This is troublesome however since before
+the actuator stubs are filled in, all we will see are messages to the effect of
+"TODO: Not yet implemented"..."
+
+```bash
+kubectl logs cluster-api-provider-solas-controller-manager-0 -n cluster-api-provider-solas-system  
+```

docs/book/provider_implementations/create_api.md

@@ -0,0 +1,72 @@
+{% method %}
+
+# Defining your API
+
+The API generated by Kubebuilder is just a shell, your actual API will likely have more fields defined on it.
+
+{% hint style="info" %}
+Kubernetes has a lot of conventions and requirements around API design. 
+The [Kubebuilder docs][apidesign] have some helpful hints on how to design your types.
+{% endhint %}
+
+[apidesign]: https://book.kubebuilder.io/cronjob-tutorial/api-design.html#designing-an-api
+
+
+Let's take a look at what was generated for us: 
+
+{% endmethod %}
+
+```go
+// MailgunClusterSpec defines the desired state of MailgunCluster
+type MailgunClusterSpec struct {
+	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+}
+
+// MailgunClusterStatus defines the observed state of MailgunCluster
+type MailgunClusterStatus struct {
+	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+}
+```
+
+Our API is based on Mailgun, so we're going to have some email based fields:
+
+```go
+type Priority string
+
+const (
+	// PriorityUrgent means do this right away
+	PriorityUrgent = Priority("Urgent")
+
+	// PriorityUrgent means do this immediately
+	PriorityExtremelyUrgent = Priority("ExtremelyUrgent")
+
+	// PriorityBusinessCritical means you absolutely need to do this now
+	PriorityBusinessCritical = Priority("BusinessCritical")
+)
+
+// MailgunClusterSpec defines the desired state of MailgunCluster
+type MailgunClusterSpec struct {
+	// Priority is how quickly you need this cluster
+	Priority Priority `json:"priority"`
+	// Request is where you ask extra nicely
+	Request string `json:"request"`
+    // Requester is the email of the person sending the request
+    Requester string
+
+}
+
+// MailgunClusterStatus defines the observed state of MailgunCluster
+type MailgunClusterStatus struct {
+	// MessageID is set to the message ID from Mailgun when our message has been sent
+	MessageID *string `json:"response"`
+}
+```
+
+As the deleted comments request, rune `make` to regenerate some of the generated data files afterwards.
+
+```bash
+git add .
+git commit -m "Added cluster types"
+```

docs/book/provider_implementations/generate_crds.md

@@ -0,0 +1,62 @@
+{% method %}
+### Create a repository
+
+{% sample lang="bash" %}
+```bash
+mkdir cluster-api-provider-cluster-api-provider-mailgun
+cd src/sigs.k8s.io/cluster-api-provider-mailgun
+git init
+```
+
+You'll then need to set up [go modules][gomod]
+
+{% sample lang="bash" %}
+```bash
+$ go mod init github.com/liztio/cluster-api-provider-mailgun
+go: creating new go.mod: module github.com/liztio/cluster-api-provider-mailgun
+```
+
+{% endmethod %}
+
+{% method %}
+### Generate scaffolding
+
+```bash
+kubebuilder init --domain cluster.x-k8s.io
+```
+
+`kubebuilder init` will create the basic repository layout, including a simple containerized manager. 
+It will also initialize the external go libraries that will be required to build your project.
+
+Commit your changes so far:
+
+```bash
+git commit -m "Generate scaffolding."
+```
+{% endmethod %}
+
+{% method %}
+### Generate provider resources for Clusters and Machines
+
+Here you will be asked if you want to generate resources and controllers.
+You'll want both of them:
+
+
+```
+Create Resource under pkg/apis [y/n]?
+y
+Create Controller under pkg/controller [y/n]?
+y
+```
+
+{% sample lang="bash" %}
+```bash
+kubebuilder create api --group infrastructure --version v1alpha3 --kind MailgunCluster
+kubebuilder create api --group infrastructure --version v1alpha3 --kind MailgunMachine
+```
+
+```bash
+git add .
+git commit -m "Generate Cluster and Machine resources."
+```
+{% endmethod %}

docs/book/provider_implementations/naming.md

@@ -0,0 +1,71 @@
+# Repository Naming
+
+The naming convention for new Cluster API [_provider_ repositories][repo-naming]
+is generally of the form `cluster-api-provider-${env}`, where `${env}` is a,
+possibly short, name for the _environment_ in question. For example 
+`cluster-api-provider-gcp` is an implementation for the Google Cloud Platform,
+and `cluster-api-provider-aws` is one for Amazon Web Services. Note that an
+environment may refer to a cloud, bare metal, virtual machines, or any other
+infrastructure hosting Kubernetes. Finally, a single environment may include 
+more than one [_variant_][variant-naming]. So for example, 
+`cluster-api-provider-aws` may include both an implementation based on EC2 as 
+well as one based on their hosted EKS solution.
+
+
+{% hint style="info" %}
+## A note on Acronyms
+
+Because these names end up being so long, developers of Cluster API frequently refer to providers by acronyms. 
+Cluster API itself becomes [CAPI], pronounced "Cappy."
+cluster-api-provider-aws is [CAPA], pronounced "KappA."
+cluster-api-provider-gcp is [CAPG], pronounced "Cap Gee," [and so on][letterc].
+
+[CAPI] https://cluster-api.sigs.k8s.io/reference/glossary.html#capi
+[CAPA]: https://cluster-api.sigs.k8s.io/reference/glossary.html#capa
+[CAPG]: https://cluster-api.sigs.k8s.io/reference/glossary.html#capg
+[letterc]: https://cluster-api.sigs.k8s.io/reference/glossary.html#c
+{% endhint %}
+
+# Resource Naming
+
+{% panel style="info", title="Important" %}
+For the purposes of this guide we will create a provider for a 
+service named **mailgun**. Therefore the name of the repository will be 
+`cluster-api-provider-mailgun`.
+{% endpanel %}
+
+
+{% method %}
+
+Every Kubernetes resource has a *Group*, *Version* and *Kind* that uniquely 
+identifies it.
+
+* The resource *Kind* is the short name of the API, for example, 
+  `MailgunMachineSpec` and `MailgunMachineStatus` could be the provider specific
+  API for `Machine` resources.
+* The resource *Version* defines the stability of the API and its backward 
+  compatibility guarantees. Examples include v1alpha1, v1beta1, v1, etc.
+  and are governed by the Kubernetes API Deprecation Policy [^1].
+* The resource *Group* is similar to package in a language.  It disambiguates 
+  different APIs that may happen to have identically named *Kind*s.  Groups 
+  often contain a domain name, such as k8s.io. The domain for Cluster API
+  resources is `cluster.k8s.io`.
+
+{% sample lang="yaml" %}
+```yaml
+apiVersion: mailgun.cluster.k8s.io/v1alpha1
+kind: MailgunMachineSpec
+```
+
+{% sample lang="yaml" %}
+```yaml
+apiVersion: mailgun.cluster.k8s.io/v1alpha1
+kind: MailgunMachineStatus
+```
+{% endmethod %}
+
+[repo-naming]: https://github.com/kubernetes-sigs/cluster-api/issues/383
+[variant-naming]: https://github.com/kubernetes-sigs/cluster-api/issues/480
+
+[^1]: https://kubernetes.io/docs/reference/using-api/deprecation-policy/
+

docs/book/provider_implementations/overview.md

@@ -0,0 +1,43 @@
+# Overview
+
+In order to demonstrate how to develop a new Cluster API provider we will use 
+`kubebuilder` to create an example provider. For more information on `kubebuilder`
+and CRDs in general we highly recommend reading the [Kubebuilder Book][kubebuilder-book].
+Much of the information here was adapted directly from it. 
+## Prerequisites
+
+- Install [`kubectl`][kubectl-install]
+- Install [`kustomize`][install-kustomize]
+- Install [`kubebuilder`][install-kubebuilder]
+
+### tl;dr
+
+{% codegroup %}
+```bash::MacOS
+# Install kubectl
+brew install kubernetes-cli
+
+# Install kustomize
+brew install kustomize
+```
+```bash::Linux
+# Install kubectl
+KUBECTL_VERSION=$(curl -sf https://storage.googleapis.com/kubernetes-release/release/stable.txt)
+curl -fLO https://storage.googleapis.com/kubernetes-release/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl
+
+# Install kustomize
+OS_TYPE=linux
+curl -sf https://api.github.com/repos/kubernetes-sigs/kustomize/releases/latest |\
+  grep browser_download |\
+  grep ${OS_TYPE} |\
+  cut -d '"' -f 4 |\
+  xargs curl -f -O -L
+mv kustomize_*_${OS_TYPE}_amd64 /usr/local/bin/kustomize
+chmod u+x /usr/local/bin/kustomize
+```
+{% endcodegroup %}
+
+[kubebuilder-book]: https://book.kubebuilder.io/
+[kubectl-install]: http://kubernetes.io/docs/user-guide/prereqs/
+[install-kustomize]: https://github.com/kubernetes-sigs/kustomize/blob/master/docs/INSTALL.md
+[install-kubebuilder]:  https://book.kubebuilder.io/quick-start.html#installation