Update repo documentation and dependencies (#249)

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

Author: justaugustus

WORKSPACE

@@ -18,12 +18,23 @@ load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
 http_archive(
     name = "io_bazel_rules_go",
     urls = [
-        "https://storage.googleapis.com/bazel-mirror/github.com/bazelbuild/rules_go/releases/download/0.18.7/rules_go-0.18.7.tar.gz",
-        "https://github.com/bazelbuild/rules_go/releases/download/0.18.7/rules_go-0.18.7.tar.gz",
+        "https://storage.googleapis.com/bazel-mirror/github.com/bazelbuild/rules_go/releases/download/0.19.1/rules_go-0.19.1.tar.gz",
+        "https://github.com/bazelbuild/rules_go/releases/download/0.19.1/rules_go-0.19.1.tar.gz",
     ],
-    sha256 = "45409e6c4f748baa9e05f8f6ab6efaa05739aa064e3ab94e5a1a09849c51806a",
+    sha256 = "8df59f11fb697743cbb3f26cfb8750395f30471e9eabde0d174c3aebc7a1cd39",
 )
 
+git_repository(
+    name = "com_google_protobuf",
+    commit = "6a59a2ad1f61d9696092f79b6d74368b4d7970a3",  # v3.9.0
+    remote = "https://github.com/protocolbuffers/protobuf",
+    shallow_since = "1562856725 -0700",
+)
+
+load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
+
+protobuf_deps()
+
 http_archive(
     name = "io_bazel_rules_docker",
     sha256 = "87fc6a2b128147a0a3039a2fd0b53cc1f2ed5adb8716f50756544a572999ae9a",

cmd/clusterctl/examples/azure/BUILD.bazel

@@ -62,6 +62,7 @@ pkg_tar(
         "machine-deployment.yaml.template",
         "provider-components-base.yaml",
         "//docs:getting-started.md",
+        "//docs:manifests.md",
     ],
     modes = {
         "addons.yaml": "0644",
@@ -75,6 +76,7 @@ pkg_tar(
         "machine-deployment.yaml.template": "0644",
         "provider-components-base.yaml": "0644",
         "//docs:getting-started.md": "0644",
+        "//docs:manifests.md": "0644",
         ".gitignore": "0644",
     },
     package_dir = "azure",

cmd/clusterctl/examples/azure/machine-deployment.yaml.template

@@ -1,7 +1,7 @@
 apiVersion: "cluster.k8s.io/v1alpha1"
 kind: MachineDeployment
 metadata:
-  name: ${CLUSTER_NAME}-machinedeployment
+  name: ${CLUSTER_NAME}-md
   labels:
     cluster.k8s.io/cluster-name: ${CLUSTER_NAME}
 spec:

docs/BUILD.bazel

@@ -14,4 +14,5 @@
 
 exports_files([
     "getting-started.md",
+    "manifests.md",
 ])

docs/development.md

@@ -13,6 +13,7 @@
   - [Dev images](#dev-images)
     - [Container registry](#container-registry)
 - [Developing](#developing)
+  - [Modules and dependencies](#modules-and-dependencies)
   - [Manual Testing](#manual-testing)
     - [Setting up the environment](#setting-up-the-environment)
     - [Building and pushing dev images](#building-and-pushing-dev-images)
@@ -143,17 +144,20 @@ Ensure kind has been reset:
 make kind-reset
 ```
 
-`make create-cluster` will launch a bootstrap cluster and then run the generated
-manifests creating a target cluster in Azure.
+**Before continuing, please review the [documentation on manifests][manifests] to understand which manifests to use for various cluster scenarios.**
 
-If you're interested in creating the cluster with verbose logging, you can instead run:
+Launch a bootstrap cluster and then run the generated manifests creating a target cluster in Azure:
+- Use `make create-cluster` to create a single control plane, single node cluster
+- Use `make create-cluster-ha` to create a multi-node control plane, with no nodes
+
+If you're interested in creating the cluster with verbose logging or further customize the manifests, you can instead run:
 
 ```bash
 time clusterctl create cluster -v 10 \
 --provider azure \
 --bootstrap-type kind \
--m ./cmd/clusterctl/examples/azure/out/machines.yaml \
--c ./cmd/clusterctl/examples/azure/out/cluster.yaml \
+-m ./cmd/clusterctl/examples/azure/out/<machine-manifest> \
+-c ./cmd/clusterctl/examples/azure/out/<cluster-manifest> \
 -p ./cmd/clusterctl/examples/azure/out/provider-components.yaml \
 -a ./cmd/clusterctl/examples/azure/out/addons.yaml
 ```
@@ -204,4 +208,5 @@ If you then want to use these mocks with `go test ./...`, run
 [kind]: https://sigs.k8s.io/kind
 [azure_cli]: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest
 [bazel]: https://docs.bazel.build/versions/master/install.html
+[manifests]: /docs/manifests.md
 [pyenv]: https://github.com/pyenv/pyenv

docs/getting-started.md

@@ -20,6 +20,7 @@
 - [Using the cluster](#using-the-cluster)
 - [Troubleshooting](#troubleshooting)
   - [Bootstrap running, but resources aren't being created](#bootstrap-running-but-resources-arent-being-created)
+  - [Resources are created but control plane is taking a long time to become ready](#resources-are-created-but-control-plane-is-taking-a-long-time-to-become-ready)
 
 <!-- /TOC -->
 
@@ -87,7 +88,7 @@ A set of sane defaults are utilized when generating manifests via `./azure/gener
 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 LOCATION="eastus"
 export RESOURCE_GROUP="kubecuddles"
 
 # Cluster settings.
@@ -106,9 +107,11 @@ Now that the deployment has been customized, the next step is to generate the re
 ./azure/generate-yaml.sh
 ```
 
+**Please review `manifests.md` to understand which manifests to use for various cluster scenarios.**
+
 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.
+Verify that the manifests reflect the expected settings before continuing.
 
 ### Creating a cluster
 
@@ -118,11 +121,17 @@ You can now start the Cluster API controllers and deploy a new cluster in Azure:
 clusterctl create cluster -v 4 \
   --bootstrap-type kind \
   --provider azure \
-  -m ./azure/out/machines.yaml \
-  -c ./azure/out/cluster.yaml \
+  -m ./azure/out/<machine-manifest> \
+  -c ./azure/out/<cluster-manifest> \
   -p ./azure/out/provider-components.yaml \
   -a ./azure/out/addons.yaml
+```
+
+Here is some example output from `clusterctl`:
 
+<details>
+
+```
 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
@@ -219,6 +228,7 @@ I0324 23:53:58.997892   27739 createbootstrapcluster.go:36] Cleaning up bootstra
 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" ...
 ```
+</details>
 
 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"`.
 

docs/manifests.md

@@ -0,0 +1,47 @@
+# Manifests
+
+Cluster API Provider Azure provides several manifest templates to assist with provisioning Kubernetes clusters.
+
+- `cluster.yaml.template`
+- `cluster-network-spec.yaml.template`
+- `controlplane-machine.yaml.template`
+- `controlplane-machines-ha.yaml.template`
+- `credentials.yaml.template`
+- `machines.yaml.template`
+- `machine-deployment.yaml.template`
+
+After running `generate-yaml.sh`, the provided templates will be transformed into usable Kubernetes manifests.
+
+You will not require all of the manifests to successfully create a cluster.
+This will provide some guidance on which manifests to use and when.
+
+## Cluster
+
+### Default network configuration
+
+Use `cluster.yaml`.
+
+### (Unsupported) Existing virtual network
+
+Use `cluster-network-spec.yaml`.
+
+
+## Machine
+
+### Single control plane, single node
+
+Use `machines.yaml`.
+
+### Single control plane, without nodes
+
+Use `controlplane-machine.yaml`.
+
+### Multi-node control plane
+
+Use `controlplane-machines-ha.yaml`.
+
+### Machine deployment (single replica)
+
+**This manifest should only be applied to a cluster _after_ a control plane has been deployed.**
+
+Use `machine-deployment.yaml`.

docs/releasing.md

@@ -2,13 +2,32 @@
 
 ## Pre-flight
 
+- Identify a known good commit on the release branch
+- Tag the repository with a release candidate tag and push the tag
+   - An [OWNER](/OWNERS) runs `git tag -s <version>-rc.n`, inserts the changelog and pushes the tag with `git push <version>-rc.n`
 - 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
+- Review the development, getting started documentation, generation scripts, and update as necessary
+- Run `make release-artifacts`, with the appropriate environment variables:
+  ```
+  REGISTRY="quay.io/k8s-staging" \
+  PULL_POLICY="IfNotPresent" \
+  MANAGER_IMAGE_TAG="<version>-rc.n" \
+  make release-artifacts
+  ```
+- Build and push a container image to the staging repository using the release candidate tag (`<version>-rc.n`):
+  ```
+  REGISTRY="quay.io/k8s-staging" \
+  MANAGER_IMAGE_TAG="<version>-rc.n" \
+  time make docker-build
+
+  REGISTRY="quay.io/k8s-staging" \
+  MANAGER_IMAGE_TAG="<version>-rc.n" \
+  time make docker-push
+  ```
+- Run through the "Getting Started" instructions using the artifacts generated in these steps to validate that they result in a working cluster
+- Commit and PR any required changes before continuing the release process ([example](https://github.com/kubernetes-sigs/cluster-api-provider-azure/pull/249))
+
+## (Unused) Semi-automatic
 
 1. Make sure your repo is clean by git's standards
 2. Run `go run cmd/release/main.go -remote <upstream-remote-name> -version v0.x.y`, replacing the [version][versioning], as appropriate
@@ -20,16 +39,31 @@
 ## Manual
 
 1. Tag the repository and push the tag
-   - An [OWNER](/OWNERS) runs `git tag -s $VERSION` and inserts the changelog and pushes the tag with `git push $VERSION`
+   - An [OWNER](/OWNERS) runs `git tag -s <version>` and inserts the changelog and pushes the tag with `git push <version>`
 2. Create a draft release in GitHub and associate it with the tag that was just created
 3. Checkout the tag and make sure git is in a clean state
-4. Run `make release-artifacts`
+4. Run `make release-artifacts`, with the appropriate environment variables:
+   ```
+   REGISTRY="quay.io/k8s" \
+   PULL_POLICY="IfNotPresent" \
+   MANAGER_IMAGE_TAG="<version>" \
+   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) 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
+7.  Write the [release notes](#release-notes) and make sure the binaries uploaded return the correct version
+8.  Build and push a container image to the staging repository using the release candidate tag (`<version>`):
+    ```
+    REGISTRY="quay.io/k8s" \
+    MANAGER_IMAGE_TAG="<version>" \
+    time make docker-build
+
+    REGISTRY="quay.io/k8s" \
+    MANAGER_IMAGE_TAG="<version>" \
+    time make docker-push
+    ```
+11. Publish release
+12. [Announce][release-announcement] the release
 
 ## Versioning
 
@@ -85,12 +119,12 @@ The markdown is shared in the Kubernetes slack in the channel #cluster-api-azure
 ### Minor/Patch Releases
 
 1. Announce the release in Kubernetes Slack on the #cluster-api-azure channel.
-2. An announcement email is sent to `[email protected]` and `[email protected]` with the subject `[ANNOUNCE] cluster-api-provider-azure $VERSION has been released`
+2. An announcement email is sent to `[email protected]` and `[email protected]` with the subject `[ANNOUNCE] cluster-api-provider-azure <version> has been released`
 
 ### Major Releases
 
 1. Follow the communications process for [pre-releases](#pre-releases)
-2. An announcement email is sent to `[email protected]` with the subject `[ANNOUNCE] cluster-api-provider-azure $VERSION has been released`
+2. An announcement email is sent to `[email protected]` with the subject `[ANNOUNCE] cluster-api-provider-azure <version> has been released`
 
 
 [release-announcement]: #communication