fix: Release tooling and documentation for v0.1.0 (#151)

Signed-off-by: Stephen Augustus <[email protected]>

Author: justaugustus

Makefile

@@ -238,7 +238,7 @@ binaries-dev: ## Builds and installs all development binaries using go get
 	go get -v ./...
 
 .PHONY: create-cluster
-create-cluster: binaries-dev ## Create a development Kubernetes cluster on AWS using examples
+create-cluster: binaries-dev ## Create a development Kubernetes cluster on Azure using examples
 	clusterctl create cluster -v 4 \
 	--provider azure \
 	--bootstrap-type kind \

cmd/clusterctl/examples/azure/BUILD.bazel

@@ -50,6 +50,7 @@ pkg_tar(
         "addons.yaml",
         "cluster.yaml.template",
         "cluster-network-spec.yaml.template",
+        "credentials.yaml.template",
         "generate-yaml.sh",
         "machines.yaml.template",
         "provider-components-base.yaml",

cmd/clusterctl/examples/azure/generate-yaml.sh

@@ -49,7 +49,6 @@ export AZURE_CLIENT_SECRET_B64="$(echo -n "$AZURE_CLIENT_SECRET" | base64)"
 CLUSTER_TEMPLATE_FILE=${DIR}/cluster.yaml.template
 CLUSTER_NETWORKSPEC_TEMPLATE_FILE=${DIR}/cluster-network-spec.yaml.template
 CLUSTER_GENERATED_FILE=${OUTPUT_DIR}/cluster.yaml
-# TODO: Change the machine template once nodes are implemented
 MACHINES_TEMPLATE_FILE=${DIR}/machines.yaml.template
 MACHINES_GENERATED_FILE=${OUTPUT_DIR}/machines.yaml
 ADDONS_FILE=${OUTPUT_DIR}/addons.yaml

cmd/clusterctl/examples/azure/machines_no_node.yaml.template

@@ -37,7 +37,7 @@ github token for modifying release
 
 const (
 	// TODO(chuckha): figure this out based on directory name
-	repository = "cluster-api-provider-azure"
+	repository = "k8s"
 
 	// TODO move these into config
 	registry         = "quay.io"

cmd/release/main.go

@@ -8,12 +8,18 @@
 
 - [Requirements](#requirements)
   - [Optional](#optional)
-  - [Install the project](#install-the-project)
-    - [Release binaries](#release-binaries)
+- [Prerequisites](#prerequisites)
+  - [Install release binaries](#install-release-binaries)
     - [Building from master](#building-from-master)
-  - [Prepare your environment](#prepare-your-environment)
-  - [Usage](#usage)
-    - [Creating a Cluster](#creating-a-cluster)
+- [Deploying a cluster](#deploying-a-cluster)
+  - [Setting up the environment](#setting-up-the-environment)
+  - [Generating cluster manifests and example cluster](#generating-cluster-manifests-and-example-cluster)
+    - [Customizing the cluster deployment](#customizing-the-cluster-deployment)
+    - [Running the manifest generation script](#running-the-manifest-generation-script)
+  - [Creating a cluster](#creating-a-cluster)
+- [Using the cluster](#using-the-cluster)
+- [Troubleshooting](#troubleshooting)
+  - [Bootstrap running, but resources aren't being created](#bootstrap-running-but-resources-arent-being-created)
 
 <!-- /TOC -->
 
@@ -41,51 +47,203 @@
 [kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
 [kustomize]: https://github.com/kubernetes-sigs/kustomize
 
-### Install the project
+## Prerequisites
 
-#### Release binaries
-TODO. Coming soon!
+### Install release binaries
+
+Get the latest [release of `clusterctl`](https://github.com/kubernetes-sigs/cluster-api-provider-azure/releases) and place them in your PATH.
 
 #### Building from master
 
 If you're interested in developing cluster-api-provider-azure and getting the latest version from `master`, please follow the [development guide][development].
 
-### Prepare your environment
-An Azure Service Principal is needed for usage by the `clusterctl` tool and for populating the controller manifests. This utilizes [environment-based authentication](https://docs.microsoft.com/en-us/go/azure/azure-sdk-go-authorization#use-environment-based-authentication). The following environment variables should be set: `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` and `AZURE_CLIENT_SECRET`.
+## Deploying a cluster
+
+### Setting up the environment
+
+An Azure Service Principal is needed for usage by the `clusterctl` tool and for populating the controller manifests. This utilizes [environment-based authentication](https://docs.microsoft.com/en-us/go/azure/azure-sdk-go-authorization#use-environment-based-authentication).
+
+The following environment variables should be set:
+- `AZURE_SUBSCRIPTION_ID`
+- `AZURE_TENANT_ID`
+- `AZURE_CLIENT_ID`
+- `AZURE_CLIENT_SECRET`
 
 An alternative is to install [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) and have the project's script create the service principal automatically. _Note that the service principals created by the scripts will not be deleted automatically._
 
-### Usage
+### Generating cluster manifests and example cluster
+
+Download the cluster-api-provider-azure-examples.tar file and unpack it.
+
+```bash
+tar -xvf cluster-api-provider-azure-examples.tar
+```
+
+#### Customizing the cluster deployment
 
-#### Creating a Cluster
-1. Generate the `cluster.yaml`, `machines.yaml`, and `addons.yaml` files, and create the service principal if needed.
+A set of sane defaults are utilized when generating manifests via `./azure/generate-yaml.sh`, but these can be overridden by exporting environment variables.
 
-    ```bash
-    make clean # Clean up any previous manifests
+Here is a list of commonly overriden configuration parameters (the full list is available in `./azure/generate-yaml.sh`):
+```bash
+# Azure settings.
+export LOCATION="eastus2"
+export RESOURCE_GROUP="kubecuddles"
 
-    REGISTRY="<container-registry>" MANAGER_IMAGE_TAG="<image-tag>" RESOURCE_GROUP="<resource-group>" CLUSTER_NAME="<cluster-name>" make manifests # set CREATE_SP=TRUE if creating a new Service Principal is desired
-   
-    # If CREATE_SP=TRUE
-    source cmd/clusterctl/examples/azure/out/credentials.sh
-    ```
-2. Ensure kind has been reset:
-    ```bash
-    make kind-reset
-    ```
-3. Create the cluster.
+# Cluster settings.
+export CLUSTER_NAME="pony-unicorns"
 
-   **NOTE:** Kubernetes Version >= 1.11 is required to enable CRD subresources without needing a feature gate.
+# Machine settings.
+export CONTROL_PLANE_MACHINE_TYPE="Standard_B2ms"
+export NODE_MACHINE_TYPE="Standard_B2ms"
+```
 
-    ```bash
-    make create-cluster
-    ```
+#### Running the manifest generation script
 
-Once the cluster is created successfully, you can interact with the cluster using `kubectl` and the kubeconfig downloaded by the `clusterctl` tool.
+Now that the deployment has been customized, the next step is to generate the required manifests:
 
+```bash
+./azure/generate-yaml.sh
 ```
+
+Manually editing the generated manifests should not be required, but this is the stage where final customizations can be done.
+
+Verify that `./azure/out/cluster.yaml` and `./azure/out/machine.yaml` reflect the expected settings before continuing.
+
+### Creating a cluster
+
+You can now start the Cluster API controllers and deploy a new cluster in Azure:
+
+```bash
+clusterctl create cluster -v 4 \
+  --bootstrap-type kind \
+  --provider azure \
+  -m ./azure/out/machines.yaml \
+  -c ./azure/out/cluster.yaml \
+  -p ./azure/out/provider-components.yaml \
+  -a ./azure/out/addons.yaml
+
+I0324 23:19:37.110948   27739 decoder.go:224] decoding stream as YAML
+I0324 23:19:37.111615   27739 decoder.go:224] decoding stream as YAML
+I0324 23:19:37.115835   27739 createbootstrapcluster.go:27] Creating bootstrap cluster
+I0324 23:19:37.115883   27739 kind.go:69] Running: kind [create cluster --name=clusterapi]
+
+I0324 23:23:58.081879   27739 kind.go:72] Ran: kind [create cluster --name=clusterapi] Output: Creating cluster "clusterapi" ...
+ • Ensuring node image (kindest/node:v1.13.3) 🖼  ...
+ ✓ Ensuring node image (kindest/node:v1.13.3) 🖼
+ • [control-plane] Creating node container 📦  ...
+ ✓ [control-plane] Creating node container 📦
+ • [control-plane] Fixing mounts 🗻  ...
+ ✓ [control-plane] Fixing mounts 🗻
+ • [control-plane] Starting systemd 🖥  ...
+ ✓ [control-plane] Starting systemd 🖥
+ • [control-plane] Waiting for docker to be ready 🐋  ...
+ ✓ [control-plane] Waiting for docker to be ready 🐋
+ • [control-plane] Pre-loading images 🐋  ...
+ ✓ [control-plane] Pre-loading images 🐋
+ • [control-plane] Creating the kubeadm config file ⛵  ...
+ ✓ [control-plane] Creating the kubeadm config file ⛵
+ • [control-plane] Starting Kubernetes (this may take a minute) ☸  ...
+ ✓ [control-plane] Starting Kubernetes (this may take a minute) ☸
+Cluster creation complete. You can now use the cluster with:
+
 export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
-kubectl get clusters
-kubectl get machines
+kubectl cluster-info
+I0324 23:23:58.081925   27739 kind.go:69] Running: kind [get kubeconfig-path --name=clusterapi]
+I0324 23:23:58.149609   27739 kind.go:72] Ran: kind [get kubeconfig-path --name=clusterapi] Output: /home/fakeuser/.kube/kind-config-clusterapi
+I0324 23:23:58.150729   27739 clusterdeployer.go:78] Applying Cluster API stack to bootstrap cluster
+I0324 23:23:58.150752   27739 applyclusterapicomponents.go:26] Applying Cluster API Provider Components
+I0324 23:23:58.150774   27739 clusterclient.go:919] Waiting for kubectl apply...
+I0324 23:23:58.756964   27739 clusterclient.go:948] Waiting for Cluster v1alpha resources to become available...
+I0324 23:23:58.763134   27739 clusterclient.go:961] Waiting for Cluster v1alpha resources to be listable...
+I0324 23:23:58.771783   27739 clusterdeployer.go:83] Provisioning target cluster via bootstrap cluster
+I0324 23:23:58.777256   27739 applycluster.go:36] Creating cluster object test-1 in namespace "default"
+I0324 23:23:58.783757   27739 clusterdeployer.go:92] Creating control plane test-1-controlplane-0 in namespace "default"
+I0324 23:23:58.788974   27739 applymachines.go:36] Creating machines in namespace "default"
+I0324 23:23:58.801805   27739 clusterclient.go:972] Waiting for Machine test-1-controlplane-0 to become ready...
+<output snipped>
+I0324 23:44:38.804516   27739 clusterclient.go:972] Waiting for Machine test-1-controlplane-0 to become ready...
+I0324 23:44:38.811944   27739 clusterdeployer.go:97] Updating bootstrap cluster object for cluster test-1 in namespace "default" with control plane endpoint running on test-1-controlplane-0
+I0324 23:44:38.835236   27739 clusterdeployer.go:102] Creating target cluster
+I0324 23:44:38.835270   27739 getkubeconfig.go:38] Getting target cluster kubeconfig.
+I0324 23:44:38.840932   27739 getkubeconfig.go:59] Waiting for kubeconfig on test-1-controlplane-0 to become ready...
+I0324 23:44:38.846004   27739 applyaddons.go:25] Applying Addons
+I0324 23:44:38.846038   27739 clusterclient.go:919] Waiting for kubectl apply...
+I0324 23:44:40.794352   27739 clusterdeployer.go:120] Pivoting Cluster API stack to target cluster
+I0324 23:44:40.794449   27739 pivot.go:67] Applying Cluster API Provider Components to Target Cluster
+I0324 23:44:40.794495   27739 clusterclient.go:919] Waiting for kubectl apply...
+I0324 23:44:43.012086   27739 pivot.go:72] Pivoting Cluster API objects from bootstrap to target cluster.
+I0324 23:44:43.012155   27739 pivot.go:83] Ensuring cluster v1alpha1 resources are available on the source cluster
+I0324 23:44:43.012225   27739 clusterclient.go:948] Waiting for Cluster v1alpha resources to become available...
+I0324 23:44:43.015046   27739 clusterclient.go:961] Waiting for Cluster v1alpha resources to be listable...
+I0324 23:44:43.023466   27739 pivot.go:88] Ensuring cluster v1alpha1 resources are available on the target cluster
+I0324 23:44:43.023547   27739 clusterclient.go:948] Waiting for Cluster v1alpha resources to become available...
+I0324 23:44:43.190476   27739 clusterclient.go:961] Waiting for Cluster v1alpha resources to be listable...
+I0324 23:44:43.251215   27739 pivot.go:93] Parsing list of cluster-api controllers from provider components
+I0324 23:44:43.251262   27739 decoder.go:224] decoding stream as YAML
+I0324 23:44:43.269534   27739 pivot.go:101] Scaling down controller azure-provider-system/azure-provider-controller-manager
+I0324 23:44:43.402303   27739 pivot.go:101] Scaling down controller cluster-api-system/cluster-api-controller-manager
+I0324 23:44:43.409192   27739 pivot.go:107] Retrieving list of MachineClasses to move
+I0324 23:44:43.411218   27739 pivot.go:212] Preparing to copy MachineClasses: []
+I0324 23:44:43.411252   27739 pivot.go:117] Retrieving list of Clusters to move
+I0324 23:44:43.415212   27739 pivot.go:171] Preparing to move Clusters: [test-1]
+I0324 23:44:43.415246   27739 pivot.go:234] Moving Cluster default/test-1
+I0324 23:44:43.415269   27739 pivot.go:236] Ensuring namespace "default" exists on target cluster
+I0324 23:44:43.929506   27739 pivot.go:247] Retrieving list of MachineDeployments to move for Cluster default/test-1
+I0324 23:44:43.932485   27739 pivot.go:287] Preparing to move MachineDeployments: []
+I0324 23:44:43.932519   27739 pivot.go:256] Retrieving list of MachineSets not associated with a MachineDeployment to move for Cluster default/test-1
+I0324 23:44:43.935291   27739 pivot.go:331] Preparing to move MachineSets: []
+I0324 23:44:43.935325   27739 pivot.go:265] Retrieving list of Machines not associated with a MachineSet to move for Cluster default/test-1
+I0324 23:44:43.937558   27739 pivot.go:374] Preparing to move Machines: [test-1-controlplane-0]
+I0324 23:44:43.937592   27739 pivot.go:385] Moving Machine default/test-1-controlplane-0
+I0324 23:44:44.353159   27739 clusterclient.go:972] Waiting for Machine test-1-controlplane-0 to become ready...
+I0324 23:44:44.408896   27739 pivot.go:399] Successfully moved Machine default/test-1-controlplane-0
+I0324 23:44:44.434373   27739 pivot.go:278] Successfully moved Cluster default/test-1
+I0324 23:44:44.434407   27739 pivot.go:127] Retrieving list of MachineDeployments not associated with a Cluster to move
+I0324 23:44:44.436304   27739 pivot.go:287] Preparing to move MachineDeployments: []
+I0324 23:44:44.436327   27739 pivot.go:136] Retrieving list of MachineSets not associated with a MachineDeployment or a Cluster to move
+I0324 23:44:44.437964   27739 pivot.go:331] Preparing to move MachineSets: []
+I0324 23:44:44.437987   27739 pivot.go:145] Retrieving list of Machines not associated with a MachineSet or a Cluster to move
+I0324 23:44:44.439735   27739 pivot.go:374] Preparing to move Machines: []
+I0324 23:44:44.439780   27739 pivot.go:186] Preparing to delete MachineClasses: []
+I0324 23:44:44.439803   27739 pivot.go:158] Deleting provider components from source cluster
+I0324 23:44:57.831009   27739 clusterdeployer.go:125] Saving provider components to the target cluster
+I0324 23:44:58.696579   27739 clusterdeployer.go:133] Updating target cluster object with control plane endpoint running on test-1-controlplane-0
+I0324 23:44:58.846821   27739 clusterdeployer.go:138] Creating node machines in target cluster.
+I0324 23:44:58.886538   27739 applymachines.go:36] Creating machines in namespace "default"
+I0324 23:44:58.923186   27739 clusterclient.go:972] Waiting for Machine test-1-node-c426q to become ready...
+<output snipped>
+I0324 23:53:58.955885   27739 clusterclient.go:972] Waiting for Machine test-1-node-c426q to become ready...
+I0324 23:53:58.997577   27739 clusterdeployer.go:143] Done provisioning cluster. You can now access your cluster with kubectl --kubeconfig kubeconfig
+I0324 23:53:58.997892   27739 createbootstrapcluster.go:36] Cleaning up bootstrap cluster.
+I0324 23:53:58.997937   27739 kind.go:69] Running: kind [delete cluster --name=clusterapi]
+I0324 23:54:00.260254   27739 kind.go:72] Ran: kind [delete cluster --name=clusterapi] Output: Deleting cluster "clusterapi" ...
+```
+
+The created KIND cluster is ephemeral and is cleaned up automatically when done. During the cluster creation, the KIND configuration is written to a local directory and can be retrieved using `kind get kubeconfig-path --name="clusterapi"`.
+
+For a more in-depth look into what `clusterctl` is doing during this create step, please see the [clusterctl document](/docs/clusterctl.md).
+
+## Using the cluster
+
+The kubeconfig for the new cluster is created in the directory from where the above `clusterctl create` was run.
+
+Run the following command to point `kubectl` to the kubeconfig of the new cluster:
+```bash
+export KUBECONFIG=$(PWD)/kubeconfig
+```
+
+Alternatively, move the kubeconfig file to a desired location and set the `KUBECONFIG` environment variable accordingly.
+
+
+## Troubleshooting
+
+### Bootstrap running, but resources aren't being created
+
+Logs can be tailed using [`kubectl`][kubectl]:
+
+```bash
+export KUBECONFIG=$(kind get kubeconfig-path --name="clusterapi")
+kubectl logs azure-provider-controller-manager-0 -n azure-provider-system -f
 ```
 
 [development]: /docs/development.md

docs/getting-started.md

@@ -21,6 +21,11 @@
 clusterctl is a tool for bootstrapping a cluster for hosting the [cluster-api](https://github.com/kubernetes-sigs/cluster-api) components.
 See the [Getting Started Guide](https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/$VERSION/docs/getting-started.md).
 
+## Image
+
+<!-- Provide a link to the controller image in the container registry -->
+- [quay.io/k8s/cluster-api-azure-controller:0.x.y](https://quay.io/repository/k8s/cluster-api-azure-controller?tag=0.x.y&tab=tags)
+
 ## Limitations
 
 <!-- List limitations in new functionality -->

docs/release-notes-template.md

@@ -1,16 +1,21 @@
 # Release Process
 
-Before beginning the release process, review and discuss any potential modifications to the [support matrix/policy][support-policy].
+## Pre-flight
+
+- Review and discuss any potential modifications to the [support matrix/policy][support-policy]
+- Create a release commit e.g., `Release commit: v0.1.0`, by:
+  - Searching and replacing the previous image versions in the repo, specifically in:
+    - Makefile
+    - Release tool (`cmd/release/main.go`)
 
 ## Semi-automatic
 
 1. Make sure your repo is clean by git's standards
-2. If the controller has changed, it would be good to bump the version of the controller image. Look in `cmd/release/main.go`.
-3. Run `go run cmd/release/main.go -version v0.x.y`, replacing the [version][versioning], as appropriate
+2. Run `go run cmd/release/main.go -remote <upstream-remote-name> -version v0.x.y`, replacing the [version][versioning], as appropriate
+3. Write the [release notes](#release-notes) and make sure the binaries uploaded return the correct version
 4. Push the docker images that were generated with this release tool
-5. Edit the release notes and make sure the binaries uploaded return the correct version
-6. Publish release
-7. [Announce][release-announcement] the release
+5. Publish release
+6. [Announce][release-announcement] the release
 
 ## Manual
 
@@ -21,7 +26,7 @@ Before beginning the release process, review and discuss any potential modificat
 4. Run `make release-artifacts`
 5. Attach the tarball to the drafted release
 6. Attach `clusterctl` to the drafted release (for darwin and linux architectures)
-7. Write the [release notes](#release-notes)
+7. Write the [release notes](#release-notes) and make sure the binaries uploaded return the correct version
 8. Build and push the container image
 9. Publish release
 10. [Announce][release-announcement] the release