📖 Update new provider docs to be more current (#12085)

* docs: make the mkdir and cd use the same directory

Signed-off-by: cprivitere <[email protected]>

* docs: document staging the generated files to the git commit

Signed-off-by: cprivitere <[email protected]>

* docs: remove status subresource section
- created by default since kubebuilder 3.0 in 2020

Signed-off-by: cprivitere <[email protected]>

* docs: add comments back and remove reference to deleted comments
- referencing deleted comments is very confusing to understand

Signed-off-by: cprivitere <[email protected]>

* docs: update scaffold examples to current kubebuilder output

Signed-off-by: cprivitere <[email protected]>

* docs: point readers to where the files in question likely are

Signed-off-by: cprivitere <[email protected]>

* docs: replace Captain with Mailgun for consistency in example

Signed-off-by: cprivitere <[email protected]>

* docs: grammar and typo fix

Signed-off-by: cprivitere <[email protected]>

* docs: update examples to what you get from current kubebuilder version

Signed-off-by: cprivitere <[email protected]>

* docs: Improvements to consistency and functionality of example code

- Consistently refer to cluster as mailgunCluster
- Add that you need to import the cluster-api package to your project before you can use the util function
- Use mailgunCluster.ObjectMeta instead of a pointer in GetOwnerCluster call
- Add explanation that we need to wait for the Cluster API controller to set the ownerref before we can use the cluster object, update code to do that
- Show entire Reconcile function again after adding many lines to it

Signed-off-by: cprivitere <[email protected]>

* docs: update reconciler initiation to be like current kubebuilder provided scaffold

Signed-off-by: cprivitere <[email protected]>

* docs: correct typo of credentials manifest filename

Signed-off-by: cprivitere <[email protected]>

* docs: update and simplify image name section

- Provide directions that work with current kubebuilder output
- Provide simpler example overriding of image name
- Drop old no longer working example of image name patching
- Providing a more current example of how providers actually do this would involve teaching about CI/CD setups which seems out of scope for this document

Signed-off-by: cprivitere <[email protected]>

* docs: update cluster-api deployment section

- Old section didn't work anymore
- replace it with a link to the quick start guide
- Suggest/note that we assume the user will use kind and clusterctl init, which will install cert-manager automatically.
- Update Condition status example to match what a kubectl describe currently shows

Signed-off-by: cprivitere <[email protected]>

* docs: update example of runing provider in a local kind cluster

- Show how to load the image into kind
- Use a tag that isn't latest so kubernetes won't try to pull it from docker hub
- Update Conditions fields to current kubernetes output

Signed-off-by: cprivitere <[email protected]>

* docs: update tilt example

- Tilt example wasn't functional as it was
- Added go_main to point to where kubebuilder puts main.go
- Use make tilt-up instead of trying to build your own kind cluster to proerly set up tilt to use the local registry config showin in the example tilt files

Signed-off-by: cprivitere <[email protected]>

* docs: remove unneeded ctx from example

Signed-off-by: cprivitere <[email protected]>

* docs: simplify getowner introduction

Signed-off-by: cprivitere <[email protected]>

---------

Signed-off-by: cprivitere <[email protected]>

Author: cprivitere

docs/book/src/developer/providers/getting-started/building-running-and-testing.md

@@ -2,41 +2,20 @@
 
 ## Docker Image Name
 
-The patch in `config/manager/manager_image_patch.yaml` will be applied to the manager pod.
-Right now there is a placeholder `IMAGE_URL`, which you will need to change to your actual image.
-
-### Development Images
-It's likely that you will want one location and tag for release development, and another during development.
-
-The approach most Cluster API projects is using [a `Makefile` that uses `sed` to replace the image URL][sed] on demand during development.
-
-[sed]: https://github.com/kubernetes-sigs/cluster-api/blob/e0fb83a839b2755b14fbefbe6f93db9a58c76952/Makefile#L201-L204
-
-## Deployment
-
-### cert-manager
-
-Cluster API uses [cert-manager] to manage the certificates it needs for its webhooks.
-Before you apply Cluster API's yaml, you should [install `cert-manager`][cm-install]
-
-[cert-manager]: https://github.com/cert-manager/cert-manager
-[cm-install]: https://cert-manager.io/docs/installation/
+The IMG variable is used to build the Docker image and push it to a registry. The default value is `controller:latest`, which is a local image. You can change it to a remote image if you want to push it to a registry.
 
 ```bash
-kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<version>/cert-manager.yaml
+make docker-push IMG=ghcr.io/your-org/your-repo:dev
 ```
 
+## Deployment
+
 ### Cluster API
 
 Before you can deploy the infrastructure controller, you'll need to deploy Cluster API itself to the management cluster.
 
-You can use a precompiled manifest from the [release page][releases], run `clusterctl init`, or clone [`cluster-api`][capi] and apply its manifests using `kustomize`:
+Follow the [quick start guide](https://cluster-api.sigs.k8s.io/user/quick-start) up to and including the step of [creating the management cluster](https://cluster-api.sigs.k8s.io/user/quick-start#initialize-the-management-cluster). We will proceed presuming you created a cluster with kind and initalized cluster-api with `clusterctl init`.
 
-```bash
-cd cluster-api
-make envsubst
-kustomize build config/default | ./hack/tools/bin/envsubst | kubectl apply -f -
-```
 
 Check the status of the manager to make sure it's running properly:
 
@@ -45,11 +24,11 @@ kubectl describe -n capi-system pod | grep -A 5 Conditions
 ```
 ```bash
 Conditions:
-  Type              Status
-  Initialized       True
-  Ready             True
-  ContainersReady   True
-  PodScheduled      True
+  Type                        Status
+  PodReadyToStartContainers   True
+  Initialized                 True
+  Ready                       True
+  ContainersReady             True
 ```
 
 [capi]: https://github.com/kubernetes-sigs/cluster-api
@@ -66,24 +45,36 @@ labels:
     cluster.x-k8s.io/provider: infrastructure-mailgun
 ```
 
+If you're using kind for your management cluster, you can use the following command to build and push your image to the kind cluster's local registry. We need to use the IMG variable to override the default `controller:latest` image name with a specific version like `controller:0.1` to avoid having kubernetes try to pull the latest version of `controller` from docker hub.
+
+```bash
+cd cluster-api-provider-mailgun
+
+# Build the Docker image
+make docker-build IMG=controller:dev
+
+# Load the Docker image into the kind cluster
+kind load docker-image controller:dev
+```
+
 Now you can apply your provider as well:
 
 ```bash
 cd cluster-api-provider-mailgun
 
 # Install CRD and controller to current kubectl context
-make install deploy
+make install deploy IMG=controller:dev
 
 kubectl describe -n cluster-api-provider-mailgun-system pod | grep -A 5 Conditions
 ```
 
 ```text
 Conditions:
-  Type              Status
-  Initialized       True
-  Ready             True
-  ContainersReady   True
-  PodScheduled      True
+  Type                        Status
+  PodReadyToStartContainers   True 
+  Initialized                 True 
+  Ready                       True 
+  ContainersReady             True 
 ```
 
 [label_prefix]: https://github.com/kubernetes-sigs/cluster-api/search?q=%22infrastructure-%22
@@ -102,6 +93,7 @@ config:
   image: controller:latest # change to remote image name if desired
   label: CAPM
   live_reload_deps: ["main.go", "go.mod", "go.sum", "api", "controllers", "pkg"]
+  go_main: cmd/main.go # kubebuilder puts main.go under the cmd directory
 ```
 
 - Create file `tilt-settings.yaml` in the cluster-api directory:
@@ -116,15 +108,11 @@ enable_providers:
   - mailgun
 ```
 
-- Create a kind cluster. By default, Tiltfile assumes the kind cluster is named `capi-test`.
+- Bring tilt up by using the `make tilt-up` command in the cluster-api directory. This will ensure tilt is set up correctly to use a local registry for your image. You may need to `make tilt-clean` before this if you've been using tilt with other providers.
 
 ```bash
-kind create cluster --name capi-test
-
-# If you want a more sophisticated setup of kind cluster + image registry, try:
-# ---
-# cd cluster-api
-# hack/kind-install-for-capd.sh
+cd cluster-api
+make tilt-up
 ```
 
 - Run `tilt up` in the cluster-api folder

docs/book/src/developer/providers/getting-started/configure-the-deployment.md

@@ -53,7 +53,7 @@ As you might have noticed, we are reading variable values from a `ConfigMap` and
 You now have to add those to the manifest, but how to inject configuration in production?
 The convention many Cluster-API projects use is environment variables.
 
-`config/manager/configuration.yaml`
+`config/manager/credentials.yaml`
 
 ```yaml
 ---

docs/book/src/developer/providers/getting-started/controllers-and-reconciliation.md

@@ -1,6 +1,6 @@
 # Controllers and Reconciliation
 
-Right now, you can create objects with our API types, but those objects doesn't make any impact on your mailgun infrastrucrure. 
+Right now, you can create objects with your API types, but those objects don't make any impact on your mailgun infrastructure. 
 Let's fix that by implementing controllers and reconciliation for your API objects.
 
 From the [kubebuilder book][controller]:
@@ -25,17 +25,16 @@ Kubebuilder has created our first controller in `controllers/mailguncluster_cont
 // MailgunClusterReconciler reconciles a MailgunCluster object
 type MailgunClusterReconciler struct {
 	client.Client
-	Log logr.Logger
+	Scheme *runtime.Scheme
 }
 
 // +kubebuilder:rbac:groups=infrastructure.cluster.x-k8s.io,resources=mailgunclusters,verbs=get;list;watch;create;update;patch;delete
 // +kubebuilder:rbac:groups=infrastructure.cluster.x-k8s.io,resources=mailgunclusters/status,verbs=get;update;patch
 
 func (r *MailgunClusterReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
-	_ = context.Background()
-	_ = r.Log.WithValues("mailguncluster", req.NamespacedName)
+	_ = logf.FromContext(ctx)
 
-	// your logic here
+	// TODO(user): your logic here
 
 	return ctrl.Result{}, nil
 }
@@ -88,7 +87,7 @@ We're going to be sending mail, so let's add a few extra fields:
 // MailgunClusterReconciler reconciles a MailgunCluster object
 type MailgunClusterReconciler struct {
 	client.Client
-	Log       logr.Logger
+	Scheme *runtime.Scheme
 	Mailgun   mailgun.Mailgun
 	Recipient string
 }
@@ -102,7 +101,7 @@ Here's a naive example:
 ```go
 func (r *MailgunClusterReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 	ctx := context.Background()
-	_ = r.Log.WithValues("mailguncluster", req.NamespacedName)
+	_ = ctrl.LoggerFrom(ctx)
 
 	var cluster infrav1.MailgunCluster
 	if err := r.Get(ctx, req.NamespacedName, &cluster); err != nil {
@@ -117,8 +116,8 @@ By returning an error, you request that our controller will get `Reconcile()` ca
 That may not always be what you want - what if the object's been deleted? So let's check that:
 
 ```go
-    var cluster infrav1.MailgunCluster
-    if err := r.Get(ctx, req.NamespacedName, &cluster); err != nil {
+    var mailgunCluster infrav1.MailgunCluster
+    if err := r.Get(ctx, req.NamespacedName, &mailgunCluster); err != nil {
         // 	import apierrors "k8s.io/apimachinery/pkg/api/errors"
         if apierrors.IsNotFound(err) {
             return ctrl.Result{}, nil
@@ -127,19 +126,57 @@ That may not always be what you want - what if the object's been deleted? So let
     }
 ```
 
-Now, if this were any old `kubebuilder` project you'd be done, but in our case you have one more object to retrieve.
-Cluster API splits a cluster into two objects: the [`Cluster` defined by Cluster API itself][cluster].
-We'll want to retrieve that as well.
+Now that we have our own cluster object (`MailGunCluster`) that represents all the
+infrastructure provider specific details for our cluster, we also need to retrieve
+the upstream [`Cluster` object that is defined by Cluster API itself][cluster].
 Luckily, cluster API [provides a helper for us][getowner].
 
+First, you'll need to import the cluster-api package into our project if you haven't done so yet:
+
+```bash
+# In your Mailgun repository's root directory
+go get sigs.k8s.io/cluster-api
+go mod tidy
+```
+
+Now we can add in a call to the `GetOwnerCluster` function to retrieve the cluster object:
+
 ```go
-    cluster, err := util.GetOwnerCluster(ctx, r.Client, &mg)
+    // import sigs.k8s.io/cluster-api/util
+    cluster, err := util.GetOwnerCluster(ctx, r.Client, mailgunCluster.ObjectMeta)
     if err != nil {
         return ctrl.Result{}, err
-    
     }
 ```
 
+If our cluster was just created, the Cluster API controller may not have set the ownership reference on our object yet, so we'll have to return here and wait to do more with our cluster object until then. We can leave a log message noting that we're waiting for the main Cluster API controller to set the ownership reference. Here's what our `Reconcile()` function looks like now:
+
+```go
+func (r *MailgunClusterReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+    // We change the _ to `log` since we're going to log something now
+    log = ctrl.LoggerFrom(ctx)
+
+    var mailgunCluster infrav1.MailgunCluster
+    if err := r.Get(ctx, req.NamespacedName, &mailgunCluster); err != nil {
+        // import apierrors "k8s.io/apimachinery/pkg/api/errors"
+        if apierrors.IsNotFound(err) {
+            return ctrl.Result{}, nil
+        }
+        return ctrl.Result{}, err
+    }
+
+    // import sigs.k8s.io/cluster-api/util
+    cluster, err := util.GetOwnerCluster(ctx, r.Client, mailgunCluster.ObjectMeta)
+    if err != nil {
+        return ctrl.Result{}, err
+    }
+
+	if cluster == nil {
+		log.Info("Waiting for Cluster Controller to set OwnerRef on MailGunCluster")
+		return ctrl.Result{}, nil
+	}
+```
+
 ### The fun part
 
 _More Documentation: [The Kubebuilder Book][book] has some excellent documentation on many things, including [how to write good controllers!][implement]_
@@ -152,10 +189,10 @@ This is where your provider really comes into its own.
 In our case, let's try sending some mail:
 
 ```go
-subject := fmt.Sprintf("[%s] New Cluster %s requested", mgCluster.Spec.Priority, cluster.Name)
-body := fmt.Sprint("Hello! One cluster please.\n\n%s\n", mgCluster.Spec.Request)
+subject := fmt.Sprintf("[%s] New Cluster %s requested", mailgunCluster.Spec.Priority, cluster.Name)
+body := fmt.Sprintf("Hello! One cluster please.\n\n%s\n", mailgunCluster.Spec.Request)
 
-msg := mailgun.NewMessage(mgCluster.Spec.Requester, subject, body, r.Recipient)
+msg := r.mailgun.NewMessage(mailgunCluster.Spec.Requester, subject, body, r.Recipient)
 _, _, err = r.Mailgun.Send(msg)
 if err != nil {
     return ctrl.Result{}, err
@@ -172,28 +209,28 @@ This is an important thing about controllers: they need to be idempotent. This m
 So in our case, we'll store the result of sending a message, and then check to see if we've sent one before.
 
 ```go
-    if mgCluster.Status.MessageID != nil {
+    if mailgunCluster.Status.MessageID != nil {
         // We already sent a message, so skip reconciliation
         return ctrl.Result{}, nil
     }
 
-    subject := fmt.Sprintf("[%s] New Cluster %s requested", mgCluster.Spec.Priority, cluster.Name)
-    body := fmt.Sprintf("Hello! One cluster please.\n\n%s\n", mgCluster.Spec.Request)
+    subject := fmt.Sprintf("[%s] New Cluster %s requested", mailgunCluster.Spec.Priority, cluster.Name)
+    body := fmt.Sprintf("Hello! One cluster please.\n\n%s\n", mailgunCluster.Spec.Request)
 
-    msg := mailgun.NewMessage(mgCluster.Spec.Requester, subject, body, r.Recipient)
+    msg := r.Mailgun.NewMessage(mailgunCluster.Spec.Requester, subject, body, r.Recipient)
     _, msgID, err := r.Mailgun.Send(msg)
     if err != nil {
         return ctrl.Result{}, err
     }
 
     // patch from sigs.k8s.io/cluster-api/util/patch
-    helper, err := patch.NewHelper(&mgCluster, r.Client)
+    helper, err := patch.NewHelper(&mailgunCluster, r.Client)
     if err != nil {
         return ctrl.Result{}, err
     }
-    mgCluster.Status.MessageID = &msgID
-    if err := helper.Patch(ctx, &mgCluster); err != nil {
-        return ctrl.Result{}, errors.Wrapf(err, "couldn't patch cluster %q", mgCluster.Name)
+    mailgunCluster.Status.MessageID = &msgID
+    if err := helper.Patch(ctx, &mailgunCluster); err != nil {
+        return ctrl.Result{}, errors.Wrapf(err, "couldn't patch cluster %q", mailgunCluster.Name)
     }
 
     return ctrl.Result{}, nil
@@ -223,7 +260,7 @@ Right now, it probably looks like this:
 ```go
     if err = (&controllers.MailgunClusterReconciler{
         Client: mgr.GetClient(),
-        Log:    ctrl.Log.WithName("controllers").WithName("MailgunCluster"),
+        Scheme: mgr.GetScheme(),
     }).SetupWithManager(mgr); err != nil {
         setupLog.Error(err, "Unable to create controller", "controller", "MailgunCluster")
         os.Exit(1)
@@ -256,7 +293,7 @@ We're going to use environment variables for this:
 
     if err = (&controllers.MailgunClusterReconciler{
         Client:    mgr.GetClient(),
-        Log:       ctrl.Log.WithName("controllers").WithName("MailgunCluster"),
+        Scheme: mgr.GetScheme(),
         Mailgun:   mg,
         Recipient: recipient,
     }).SetupWithManager(mgr); err != nil {