Merge branch 'master' of https://github.com/coreos/tectonic-installer …

…into digitalocean

Documentation/install/bare-metal/metal-terraform.md

@@ -1,19 +1,19 @@
-# Install Tectonic on Bare-Metal with Terraform
+# Install Tectonic on bare metal with Terraform
 
-Following this guide will deploy a Tectonic cluster on virtual or physical hardware.
+Use this guide to deploy a Tectonic cluster on virtual or physical hardware using the command line and Terraform.
 
 ## Prerequisites
 
-* Terraform: Tectonic Installer includes and requires a specific version of Terraform. This is included in the Tectonic Installer tarball. See the [Tectonic Installer release notes][release-notes] for information about which Terraform versions are compatible.
-* [Matchbox v0.6+](https://github.com/coreos/matchbox/releases) installation with the gRPC API enabled. See [installation](https://coreos.com/matchbox/docs/latest/deployment.html).
-* Matchbox TLS client credentials
-* PXE network boot environment with DHCP, TFTP, and DNS services. See [network-setup](https://coreos.com/matchbox/docs/latest/network-setup.html).
-* DNS records for the Kubernetes controller(s) and Tectonic Ingress worker(s). See [DNS](https://coreos.com/tectonic/docs/latest/install/bare-metal#networking).
+For a complete list of requirements, see [Bare Metal Installation requirements][bare-requirements].
+
+* [Tectonic Account][account].
+* The Terraform version included in the Tectonic Installer tarball. See the [Tectonic Installer release notes][release-notes] for information about which Terraform versions are compatible.
+* [Matchbox v0.6+][matchbox-latest] installation with TLS client credentials and the gRPC API enabled.
+* [PXE network boot environment][network-setup] with DHCP, TFTP, and DNS services.
+* [DNS][dns] records for the Kubernetes controller(s) and Tectonic Ingress worker(s).
 * Machines with BIOS options set to boot from disk normally, but PXE prior to installation.
 * Machines with known MAC addresses and stable domain names.
-* Tectonic Account - Register for a [Tectonic Account][register], which is free for up to 10 nodes. You will need to provide the cluster license and pull secret below.
-* `ipmitool` or `virt-install` will be used to actually boot the machines.
-* A SSH keypair whose private key is present in your system's ssh-agent.
+* A SSH keypair whose private key is present in your system's [ssh-agent][ssh-agent].
 
 ## Getting Started
 
@@ -49,7 +49,7 @@ Next, get the modules that Terraform will use to create the cluster resources:
 $ terraform get ./platforms/metal
 ```
 
-Now we're ready to specify our cluster configuration.
+Now, specify the cluster configuration.
 
 ## Customize the deployment
 
@@ -69,7 +69,7 @@ Customizations should be made to `build/${CLUSTER}/terraform.tfvars`. Edit the f
 * `tectonic_matchbox_client_key`
 * `tectonic_matchboc_ca`
 
-Edit additional variables to specify DNS records, list machines, and set a SSH key and Tectonic Console email and password.
+Edit additional variables to specify DNS records, list machines, and set an SSH key and Tectonic Console email and password.
 
 Several variables are currently required, but their values are not used.
 
@@ -106,7 +106,7 @@ ipmitool -H node1.example.com -U USER -P PASS power on
 
 Terraform will wait for the disk installation and reboot to complete and then be able to copy credentials to the nodes to bootstrap the cluster. You may see `null_resource.kubeconfig.X: Still creating...` during this time.
 
-Run `terraform apply` until all tasks complete. Your Tectonic cluster should be ready. If you encounter any issues, check the known issues and workarounds below.
+Run `terraform apply` until all tasks complete. Your Tectonic cluster should be ready. If you encounter any issues, check the [Tectonic troubleshooting guides][troubleshooting].
 
 ## Access the cluster
 
@@ -123,17 +123,16 @@ $ kubectl cluster-info
 
 For more information on working with installed clusters, see [Scaling Tectonic bare metal clusters][scale-metal], and [Uninstalling Tectonic][uninstall].
 
-## Known issues and workarounds
-
-See the [troubleshooting][troubleshooting] document for workarounds for bugs that are being tracked.
-
 
 [conventions]: ../../conventions.md
 [generic]: ../../generic-platform.md
-[register]: https://account.coreos.com/signup/summary/tectonic-2016-12
 [account]: https://account.coreos.com
 [vars]: ../../variables/config.md
 [troubleshooting]: ../../troubleshooting/faq.md
 [uninstall]: uninstall.md
 [scale-metal]: ../../admin/bare-metal-scale.md
 [release-notes]: https://coreos.com/tectonic/releases/
+[ssh-agent]: requirements.md#ssh-agent
+[bare-requirements]: requirements.md
+[network-setup]: https://coreos.com/matchbox/docs/latest/network-setup.html
+[matchbox]: https://coreos.com/matchbox/docs/latest/

Documentation/install/bare-metal/requirements.md

@@ -2,7 +2,16 @@
 
 The Tectonic Installer creates bare metal Tectonic clusters within networks with PXE infrastructure and the `matchbox` service.
 
-For more information about `matchbox`, refer to the [`matchbox` documentation][matchbox].
+Installation requires the following items, which are discussed in more detail below:
+
+* [Tectonic Account][account]. Register for a Tectonic Account, which is free for up to 10 nodes. The cluster license and pull secret are required during installation of Tectonic.
+* Terraform. Tectonic Installer includes and requires a specific version of Terraform. This is included in the Tectonic Installer tarball. See the [Tectonic Installer release notes][release-notes] for information about which Terraform versions are compatible.
+* [Matchbox v0.6+][matchbox-latest] installation with TLS client credentials and the gRPC API enabled. For more information, see the Matchbox [installation guide][matchbox-install].
+* PXE network boot environment with DHCP, TFTP, and DNS services. For more information, see [Network setup][network-setup].
+* DNS records for the Kubernetes controller(s) and Tectonic Ingress worker(s). See [DNS][dns].
+* Machines with BIOS options set to boot from disk normally, but PXE prior to installation. `ipmitool` or `virt-install` will be used to actually boot the machines.
+* Machines with known MAC addresses and stable domain names.
+* A SSH keypair whose private key is present in your system's [ssh-agent][ssh-agent].
 
 ## Tectonic Installer
 
@@ -104,9 +113,14 @@ The provisioner must:
 * Serve CoreOS PXE and install images
 
 
+[account]: https://account.coreos.com
 [daemonset]: https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/
 [reprovision]: uninstall.md
-[matchbox-dnsmasq]: https://github.com/coreos/matchbox/tree/master/contrib/dnsmasq
 [matchbox]: https://coreos.com/matchbox
+[matchbox-dnsmasq]: https://github.com/coreos/matchbox/tree/master/contrib/dnsmasq
+[matchbox-install]: https://coreos.com/matchbox/docs/latest/deployment.html
+[matchbox-latest]: https://github.com/coreos/matchbox/releases
 [quay.io]: https://quay.io
 [ssh-agent]: https://www.freebsd.org/cgi/man.cgi?query=ssh-agent&sektion=1
+[network-setup]: https://coreos.com/matchbox/docs/latest/network-setup.html
+[dns]: bare-metal#networking

Documentation/install/vmware/vmware-terraform.md

@@ -11,9 +11,8 @@ Generally, the VMware platform templates adhere to the standards defined by the
 1. Resize the Virtual Machine Disk size to 30 GB or larger
 1. Convert the Container Linux image into a Virtual Machine template.
 1. Pre-Allocated IP addresses for the cluster and pre-create DNS records
-1. Register for Tectonic [Account][account]
 
-## DNS and IP address allocation
+### DNS and IP address allocation
 
 Prior to the start of setup create required DNS records. Below is a sample table of 3 etcd nodes, 2 master nodes and 2 worker nodes. 
 
@@ -33,19 +32,45 @@ Prior to the start of setup create required DNS records. Below is a sample table
 
 See [Tectonic on Baremetal DNS documentation][baremetaldns] for general DNS Requirements.
 
-## Getting Started
+### Tectonic Account
 
-Below steps need to be executed on machine that has network connectivity to VMware vCenter API and SSH access to Tectonic Master Server(s).
+Register for a [Tectonic Account][register], which is free for up to 10 nodes. You must provide the cluster license and pull secret during installation.
 
-First, [download][downloadterraform] and install Terraform. 
+### ssh-agent
 
-After downloading, source this new binary in the `$PATH` of the machine. Run this command to add it to path:
+Ensure `ssh-agent` is running:
+```
+$ eval $(ssh-agent)
+```
 
+Add the SSH key that will be used for the Tectonic installation to `ssh-agent`:
 ```
-$ export PATH=/path/to/terraform:$PATH
+$ ssh-add <path-to-ssh-key>
 ```
 
-Now we're ready to specify our cluster configuration.
+Verify that the SSH key identity is available to the ssh-agent:
+```
+$ ssh-add -L
+```
+
+Reference the absolute path of the **_public_** component of the SSH key in `tectonic_vmware_ssh_authorized_key`.
+
+Without this, terraform is not able to SSH copy the assets and start bootkube.
+Also make sure that the SSH known_hosts file doesn't have old records of the API DNS name (fingerprints will not match).
+
+## Getting Started
+
+The following steps must be executed on a machine that has network connectivity to VMware vCenter API and SSH access to Tectonic Master Server(s).
+
+### Download and extract Tectonic Installer
+
+Open a new terminal, and run the following commands to download and extract Tectonic Installer.
+
+```bash
+$ curl -O https://releases.tectonic.com/tectonic-1.7.1-tectonic.1.tar.gz # download
+$ tar xzvf tectonic-1.7.1-tectonic.1.tar.gz # extract the tarball
+$ cd tectonic
+```
 
 ## Customize the deployment
 
@@ -156,7 +181,7 @@ To delete Tectonic cluster, run:
 $ terraform destroy ../../platforms/vmware
 ```
 
-[account]: https://account.coreos.com
+[register]: https://account.coreos.com
 [baremetaldns]: https://coreos.com/tectonic/docs/latest/install/bare-metal/#dns 
 [conventions]: ../../conventions.md
 [generic]: ../../generic-platform.md