Merge pull request circleci#2311 from circleci/fix-up-server-docs

Fix up server docs

Author: michelle-luna

jekyll/_cci2/aws.md

@@ -48,7 +48,7 @@ The following additional settings are required to support using private subnets
 Have available the following information and policies before starting the Preview Release installation:
 
 * If you use network proxies, contact your Account team before attempting to install CircleCI 2.0.
-* Plan to provision at least two AWS instances, one for the Services and one for your first set of Builders. Best practice is to use an `m4.2xlarge` instance with 8 CPUs and 32GB RAM for the Services as well as Builders instances.
+* Plan to provision at least two AWS instances, one for the Services and one for your first set of Nomad Clients. Best practice is to use an `m4.2xlarge` instance with 8 vCPUs and 32GB RAM for the Services as well as Nomad Clients instances.
 * AWS instances must have outbound access to pull Docker containers and to verify your license.
 * In order to provision required AWS entities with Terraform you need an IAM User with following permissions:
 ```
@@ -105,7 +105,9 @@ Have available the following information and policies before starting the Previe
 ## Installation with Terraform
 1. Clone the [Setup](https://github.com/circleci/enterprise-setup) repository (if you already have it cloned, make sure it is up-to-date and you are on the `master` branch: `git checkout master && get pull`).
 2. Run `make init` to init `terraform.tfvars` file (your previous `terraform.tfvars` if any, will be backed up in the same directory).
-3. Fill `terraform.tfvars` with appropriate values.
+3. Fill `terraform.tfvars` with appropriate AWS values for section 1. 
+4. Specify a `circle_secret_passphrase` in section 2, replacing `...` with alpha numeric characters. Passprhase cannot be empty.
+5. Specify the instance type for your Nomad Clients. By default, the value specified in the `terraform.tfvars` file for Nomad Clients is `m4.2xlarge` (8 vCPUs, 32GB RAM). To increase the number of concurrent CircleCI jobs that each Nomad Client can run, modify section 2 of the `terraform.tfvars` file to specify a larger `nomad_client_instance_type`. Refer to the AWS [Amazon EC2 Instance Types](https://aws.amazon.com/ec2/instance-types) guide for details. **Note:** The `builder_instance_type` is only used for 1.0 and is disabled by default in section 3. 
 4. Run `terraform apply` to provision.
 5. Go to the provided URL at the end of Terraform output and follow the instructions.
 6. Enter your license.

jekyll/_cci2/high-availability.md

@@ -295,9 +295,9 @@ Vault should be setup as follows:
 
 1. Pull down vault. No higher than 0.7 currently: 
  
-2. Put the vault binary somewhere on $PATH (optional but makes life easier)
+2. Put the vault binary somewhere on $PATH as a best practice.
 
-3. Create a config file like vault.hcl with the following:
+3. Create a `vault.hcl` config file with the following:
 
 ```
 storage "file" { # Note:  This can be set to consul if they are using HashiCorps consul for HA
@@ -311,28 +311,27 @@ listener "tcp" {
 }
 ```
 
-4. Start vault : `sudo vault server -config=/path/to/vault.hcl & `
+4. Start vault by running `sudo vault server -config=/path/to/vault.hcl & `.
 
-**Note:** You'll only need to do the below if you are setting up Vault as a test instance with HTTP
+**Note:** You'll only need to do the following if you are setting up vault as a test instance with HTTP.
 
-5.  `export VAULT_ADDR=http://127.0.0.1:8200`
+5. Run `export VAULT_ADDR=http://127.0.0.1:8200`.
 
-6. `sudo vault init` 
+6. Run `sudo vault init`. 
 
 7. Copy the unseal keys and the root key.  You’ll need these values. 
 
-8. Unseal vault using: `sudo vault unseal` . You'll have to run this command 3 times using 3 different unseal keys. 
+8. Unseal vault using: `sudo vault unseal` . You'll have to run this command three times using three different unseal keys. 
 
-9.  Now you need to auth.  Run: `sudo vault auth` The token here should be the root token that you copied earlier.
+9. Now you need to authenticate by running `sudo vault auth`. The token here should be the root token that you copied earlier.
 
-10. Once authed, you should now need to mount the transit mount: `sudo vault mount transit`
+10. Once authenticated, you should now mount the transit mount by running `sudo vault mount transit`.
 
-11. For CircleCI, you'll need to generate a token that can be renewed. You can generate this by running the following: `sudo vault token-create -period="1h"`  . Use the generated token as your vault token, that you'll need below. 
+11. For CircleCI, generate a token that can be renewed. Generate this by running the following: `sudo vault token-create -period="1h"`. Use the generated token as your vault token which you will also need below. 
 
-12. Seal vault: `sudo vault seal`
-
-Now, just proceed to Configuring Replicated, and you should be almost done with setting up CircleCI in HA mode. 
+12. Seal vault by running `sudo vault seal`.
 
+Proceed to Configuring Replicated, to continue with setting up CircleCI in HA mode. 
 
 
 ## Configuring Replicated

jekyll/_cci2/monitoring.md

@@ -1,34 +1,41 @@
 ---
 layout: classic-docs
-title: "Administrative Variables, Monitoring, and Logging"
+title: "Environment Variables, Auto Scaling, and Monitoring"
 category: [administration]
 order: 30
 ---
 
-This document is for System Administrators who are setting environment variables for installed Builders, gathering metrics for monitoring their CircleCI installation, and viewing logs:
+This document is for System Administrators who are setting environment variables for installed Nomad Clients, scaling their cluster, gathering metrics for monitoring their CircleCI installation, and viewing logs:
 
 * TOC
 {:toc}
 
-## Setting Environment Variables on Builders
+## Setting Environment Variables on Nomad Clients
 
-Several aspects of CircleCI Builder behavior can be customized by passing
+Several aspects of CircleCI Nomad Client behavior can be customized by passing
 environment variables into the builder process. 
 
-If you are using the [trial]({{site.baseurl}}/2.0/single-box/) installation
-option on a single VM, then you can create a file called `/etc/circle-installation-customizations`
-with entries like `export CIRCLE_OPTION_A=foo` to set environment variables.
+To set environment variables create a file called `/etc/circle-installation-customizations`
+with environment variable entries, for example, `export CIRCLE_OPTION_A=foo`. 
 
 ## System Monitoring 
 
 Enable the Cloudwatch by going to Replicated Admin > Settings > Monitoring > Enable Cloudwatch. **Note:** CloudWatch does **not** support monitoring of macOS containers.
 
 CloudWatch already monitors the health and basic checks for the EC2 instances, for example, CPU, memory, disk space, and basic counts with alerts. Consider upgrading machine types for the Services instance or decrease the number of containers per container if CPU or memory become a bottleneck.
 
+## Auto Scaling
+
+By default, an Auto Scaling group is created on your AWS account. Go to your EC2 Dashboard and select Auto Scaling Groups from the left side menu. Then, in the Instances tab, set the Desired and Minimum number to define the number Nomad Clients to spin up and keep available. Use the Scaling Policy tab of the Auto Scaling page to scale up your group automatically only at certain times, see below for best practices for defining policies. 
+
+Refer to the Shutting Down a Nomad Client section of the [Nomad]({{ site.baseurl }}/2.0/nomad/#shutting-down-a-nomad-client) document for instructions on draining and scaling down the Nomad Clients.
+
+### Auto Scaling Policy Best Practices
+
 There is a [blog post series](https://circleci.com/blog/mathematical-justification-for-not-letting-builds-queue/)
  wherein CircleCI engineering spent time running simulations of cost savings for the purpose of developing a general set of best practices for Auto Scaling. Consider the following best practices when setting up AWS Auto Scaling:
 
-1. In general, size your build cluster large enough to avoid queueing builds. That is, less than one second of queuing for most workloads and less than 10 seconds for workloads run on expensive hardware or at highest parallellism. Sizing to reduce queuing to zero is best practice because of the high cost of developer time, it is difficult to create a model in which developer time is cheap enough for under-provisioning to be cost-effective.
+1. In general, size your cluster large enough to avoid queueing builds. That is, less than one second of queuing for most workloads and less than 10 seconds for workloads run on expensive hardware or at highest parallellism. Sizing to reduce queuing to zero is best practice because of the high cost of developer time, it is difficult to create a model in which developer time is cheap enough for under-provisioning to be cost-effective.
 
 2. Create an Auto Scaling group with a Step Scaling policy that scales up during the normal working hours of the majority of developers and scales back down at night. Scaling up during the weekday normal working hours and back down at night is the best practice to keep queue times down during peak development without over provisioning at night when traffic is low. Looking at millions of builds over time, a bell curve during normal working hour emerges for most data sets.
 

jekyll/_cci2/nomad.md

@@ -63,15 +63,20 @@ Complete the following steps to get logs from the allocation of the specified jo
 
 1. Get the logs from the allocation with `nomad logs -stderr <allocation-id>`
 
+<!---
 ## Scaling the Nomad Cluster
-
 Nomad itself does not provide a scaling method for cluster, so you must implement one. This section provides basic operations regarding scaling a cluster.
+--->
 
 ### Scaling Up the Client Cluster
 
-Scaling up Nomad cluster is very straightforward. To scale up, you need to register new Nomad clients into the cluster. If a Nomad client knows the IP addresses of Nomad servers, then the client can register to the cluster automatically.
+Refer to the Auto Scaling section of the [Administrative Variables, Monitoring, and Logging](https://circleci.com/docs/2.0/monitoring/#auto-scaling) document for details about adding Nomad Client instances to an AWS auto scaling group and using a scaling policy to scale up automatically according to your requirements. 
 
+<!--- 
+commenting until we have non-aws installations?
+Scaling up Nomad cluster is very straightforward. To scale up, you need to register new Nomad clients into the cluster. If a Nomad client knows the IP addresses of Nomad servers, then the client can register to the cluster automatically.
 HashiCorp recommends using Consul or other service discovery mechanisms to make this more robust in production. For more information, see the following pages in the official documentation for [Clustering](https://www.nomadproject.io/intro/getting-started/cluster.html), [Service Discovery](https://www.nomadproject.io/docs/service-discovery/index.html), and [Consul Integration](https://www.nomadproject.io/docs/agent/configuration/consul.html).
+--->
 
 ### Shutting Down a Nomad Client
 
@@ -85,15 +90,10 @@ When you want to shutdown a Nomad client, you must first set the client to `drai
 
 `nomad node-status -self`
 
-Alternatively, you can drain a remote node with `nomad node-drain -enable -yes <node-id>`
+Alternatively, you can drain a remote node with `nomad node-drain -enable -yes <node-id>`.
 
 ### Scaling Down the Client Cluster
 
-To scale your Nomad cluster properly, you need a mechanism for clients to shutdown in `drain` mode first. Then, wait for all jobs to be finished before terminating the client.
-
-While there are many ways to achieve this, here is one example of implementing such mechanism by using AWS and ASG.
+To set up a mechanism for clients to shutdown in `drain` mode first and wait for all jobs to be finished before terminating the client, configure an ASG Lifecycle Hook that triggers a script when scaling down instances.
 
-1. Configure ASG Lifecycle Hook that triggers a script when scaling down instances.
-2. The script makes the instance in drain mode.
-3. The script monitors running jobs on the instance and waits for them to finish.
-4. Terminate the instance.
+The script should use the above commands to put the instance in drain mode, monitor running jobs on the instance, wait for them to finish and then terminate the instance.