Merge pull request #409 from cprivitere/cprivitere/issue401

📖 Document usage of hardware reservations

README.md

@@ -10,8 +10,7 @@ This is the official [cluster-api](https://github.com/kubernetes-sigs/cluster-ap
 
 ![Packetbot works hard to keep Kubernetes cluster in a good shape](./docs/banner.png)
 
-
-### Requirements
+## Requirements
 
 To use the cluster-api to deploy a Kubernetes cluster to Equinix Metal, you need the following:
 
@@ -27,11 +26,11 @@ and [k3d](https://github.com/rancher/k3d).
 
 Once you have your cluster, ensure your `KUBECONFIG` environment variable is set correctly.
 
-### Getting Started
+## Getting Started
 
 You should then follow the [Cluster API Quick Start Guide](https://cluster-api.sigs.k8s.io/user/quick-start.html), selecting the 'Equinix Metal' tabs where offered.
 
-#### Defaults
+### Defaults
 
 If you do not change the generated `yaml` files, it will use defaults. You can look in the [templates/cluster-template.yaml](./templates/cluster-template.yaml) file for details.
 
@@ -42,30 +41,52 @@ If you do not change the generated `yaml` files, it will use defaults. You can l
 * `POD_CIDR`                     (defaults to `192.168.0.0/16`)
 * `SERVICE_CIDR`                 (defaults to `172.26.0.0/16`)
 * `WORKER_MACHINE_COUNT`         (defaults to `0`)
+
+### Reserved Hardware
+
+If you'd like to use reserved instances for your cluster, you need to edit your cluster yaml and add a hardwareReservationID field to your PacketMachineTemplates. That field can contain either a comma-separated list of hardware reservation IDs you'd like to use (which will cause it to ignore the facility and machineType you've specified), or just "next-available" to let the controller pick one that's available (that matches the machineType and facility you've specified). Here's an example:
+
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: PacketMachineTemplate
+metadata:
+  name: my-cluster-control-plane
+  namespace: default
+spec:
+  template:
+    spec:
+      billingCycle: hourly
+      machineType: c3.small.x86
+      os: ubuntu_18_04
+      sshKeys:
+      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDvMgVEubPLztrvVKgNPnRe9sZSjAqaYj9nmCkgr4PdK username@computer
+      tags: []
+      #If you want to specify the exact machines to use, provide a comma separated list of UUIDs
+      hardwareReservationID: "b537c5aa-2ef3-11ed-a261-0242ac120002,b537c5aa-2ef3-11ed-a261-0242ac120002"
+      #Or let the controller pick from available reserved hardware in the project that matches machineType and facility with `next-available`
+      #hardwareReservationID: "next-available"
+```
 
 ## Community, discussion, contribution, and support
 
 Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
 
+Equinix has a [cluster-api guide](https://metal.equinix.com/developers/guides/kubernetes-cluster-api/)
+
 You can reach the maintainers of this project at:
 
-* Chat with us on [Slack](http://slack.k8s.io/) in the [#cluster-api-provider-packet][#cluster-api-provider-packet slack] channel
+* Chat with us on [Slack](http://slack.k8s.io/) in the [#cluster-api-provider-packet](https://kubernetes.slack.com/archives/C8TSNPY4T) channel
 * Subscribe to the [SIG Cluster Lifecycle](https://groups.google.com/forum/#!forum/kubernetes-sig-cluster-lifecycle) Google Group for access to documents and calendars
 
-
 ## Development and Customizations
+
 The following section describes how to use the cluster-api provider for packet (CAPP) as a regular user.
 You do _not_ need to clone this repository, or install any special tools, other than the standard
 `kubectl` and `clusterctl`; see below.
 
 * To build CAPP and to deploy individual components, see [docs/BUILD.md](./docs/BUILD.md).
 * To build CAPP and to cut a proper release, see [docs/RELEASE.md](./docs/RELEASE.md).
 
-
-### Code of conduct
+## Code of conduct
 
 Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
-
-[owners]: https://git.k8s.io/community/contributors/guide/owners.md
-[Creative Commons 4.0]: https://git.k8s.io/website/LICENSE
-[#cluster-api-provider-packet slack]: https://kubernetes.slack.com/archives/C8TSNPY4T

docs/concepts/machine.md

@@ -1,77 +1,30 @@
 # PacketMachine CRD
 
 PacketMachine is the name of the resource that identifies a
-[Device](equinixMetalDeviceAPI) on Packet.
+[Device](https://metal.equinix.com/developers/api/devices/#devices-createdevice) on Packet.
 
 This is an example of it:
 
 ```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
 kind: PacketMachine
 metadata:
   name: "qa-controlplane-0"
 spec:
-  OS: "ubuntu_18_04"
+  os: "ubuntu_18_04"
   billingCycle: hourly
-  machineType: "t2.small"
+  machineType: "c3.small.x86"
   sshKeys:
-  - "your-sshkey-name"
+  - "Your SSH public key"
   tags: []
 ```
 
-It is a [Kubernetes Custom Resource Definition (CRD)](openapi-types) as everything
+It is a [Kubernetes Custom Resource Definition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) as everything
 else in the cluster-api land.
 
 The reported fields in the example are the most common one but you can see the
 full list of supported parameters as part of the OpenAPI definition available
 [here](../../config/crd/bases/infrastructure.cluster.x-k8s.io_packetclusters.yaml)
 searching for `kind: PacketMachine`.
 
-The `PacketMachine`, `PacketCluster`, and `PacketMachineTemplate` CRD specs are also documented at [docs.crds.dev](https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api-provider-packet).
-
-## Reserved instances
-
-Packet provides the possibility to [reserve
-hardware](equinix-metal-docs-reserved-hardware) in order to have to power you need
-always available.
-
-> Reserved hardware gives you the ability to reserve specific servers for a
-> committed period of time. Unlike hourly on-demand, once you reserve hardware,
-> you will have access to that specific hardware for the duration of the
-> reservation.
-
-You can specify the reservation ID using the field `hardwareReservationID`:
-
-```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
-kind: PacketMachine
-metadata:
-  name: "qa-controlplane-0"
-spec:
-  OS: "ubuntu_18_04"
-  facility:
-  - "dfw2"
-  billingCycle: hourly
-  machineType: "t2.small"
-  sshKeys:
-  - "your-sshkey-name"
-  hardwareReservationID: "d3cb029a-c5e4-4e2b-bafc-56266639685f"
-  tags: []
-```
-
-### pros and cons
-
-Hardware reservation is a great feature, this chapter is about the feature
-described above and nothing more.
-It covers a very simple use case, you have a set of machines that you created
-statically in the YAML and you like to have them using a reservation ID.
-
-It does not work in combination of PacketMachineTemplate and MachineDeployment
-where the pool of PacketMachine is dynamically managed by the cluster-api
-controllers. You can track progress on this scenario subscribing to the issue
-["Add support for reservation IDs with MachineDeployment #136"](github-issue-resid-dynamic) on GitHub.
-
-[equinixMetalDeviceAPI]: https://metal.equinix.com/developers/api/devices/#devices-createdevice
-[openapi-types]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
-[equinix-metal-docs-reserved-hardware]: https://metal.equinix.com/developers/docs/deploy/reserved/
-[github-issue-resid-dynamic]: https://github.com/packethost/cluster-api-provider-packet/issues/136
+The `PacketMachine`, `PacketCluster`, and `PacketMachineTemplate` CRD specs are also documented at [docs.crds.dev](https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api-provider-packet).

docs/contribution/e2e_test.md

@@ -60,4 +60,4 @@ export TAG=<my_tag>
 export SKIP_IMAGE_BUILD=1
 make docker-build-all docker-push-all
 ./scripts/ci-e2e-capi.sh
-```
+```