docs: add initial customization docs

docs/user/aws/customization.md

@@ -0,0 +1,58 @@
+# AWS Platform Customization
+
+The following options are available when using AWS:
+
+- `machines.platform.aws.iamRoleName` - the IAM role that will be assigned to the machines of this pool
+- `machines.platform.aws.rootVolume.iops` - the reserved IOPS of the root volume
+- `machines.platform.aws.rootVolume.size` - the size (in GiB) of the root volume
+- `machines.platform.aws.rootVolume.type` - the storage type of the root volume
+- `machines.platform.aws.type` - the EC2 instance type
+- `machines.platform.aws.zones` - a list of the availability zones that the installer will use when creating machines of this pool
+- `platform.aws.region` - the AWS region that the installer will use when creating resources
+- `platform.aws.userTags` - a map of keys and values that the installer will add as tags to all resources it creates
+
+## Examples
+
+An example `install-config.yaml` is shown below. This configuration has been modified to show the customization that is possible via the install config.
+
+```yaml
+apiVersion: v1beta1
+baseDomain: example.com
+machines:
+- name: master
+  platform:
+    aws:
+      zones:
+      - us-west-2a
+      - us-west-2b
+  replicas: 3
+- name: worker
+  platform:
+    aws:
+      iamRoleName: elastictranscoder-access
+      rootVolume:
+        iops: 4000
+        size: 500
+        type: io1
+      type: c5.9xlarge
+      zones:
+      - us-west-2c
+  replicas: 5
+metadata:
+  name: test-cluster
+networking:
+  clusterNetworks:
+  - cidr: 10.128.0.0/14
+    hostSubnetLength: 9
+  machineCIDR: 10.0.0.0/16
+  serviceCIDR: 172.30.0.0/16
+  type: OpenshiftSDN
+platform:
+  aws:
+    region: us-west-2
+    userTags:
+      adminContact: jdoe
+      costCenter: 7536
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```

docs/user/customization.md

@@ -0,0 +1,67 @@
+# Cluster Customization
+
+The OpenShift Installer allows for several different levels of customization. It is important to understand how and why each of these levels is exposed and the ramifications of making changes at each of these levels. This guide will attempt to walk through each of them and provide examples for why an administrator may want to make customizations.
+
+Cluster customization can be broken into four major levels: OpenShift, Kubernetes, Platform, and OS. These four levels are rough abstraction layers (OpenShift being the highest layer and OS being the lowest) and fall into either the validated or unvalidated buckets. The levels within the validated bucket (OpenShift and Platform) encompass customization that is safe to perform - installation and automatic updates will succeed regardless of the changes made (to a reasonable degree). The levels within the unvalidated bucket (Kubernetes and OS) encompass customization that is not necessarily safe - after introducing changes, installation and automatic updates may not succeed.
+
+## OpenShift Customization
+
+The most simple customization is exposed by the installer as an interactive series of prompts. These prompts are required and represent a high-level of customization. They are needed in order to get a running OpenShift cluster, but they aren't enough to get anything other than a vanilla deployment out of the box. Further customization is possible once the cluster has been provisioned, but isn't covered in this document as it is a "Day 2" operation.
+
+## Platform Customization
+
+While the default cluster size may be sufficient for some, many will need to make alterations. This can include increasing the number of machines in the control plane, changing the type of the virtual machines that will be used (e.g. AWS instances), or adjusting the CIDR range used for the Kubernetes service network. This level of customization is exposed via the installer's `install-config.yaml`. The install-config can be accessed by running `openshift-install create install-config`. This file can then be modified as needed before running a later target.
+
+The `install-config.yaml` generated by the installer will not have all of the available fields populated, so they will need to be manually added if they are needed. The full list of available fields can be found in the [Go Docs][godocs]. Documentation for each of the supported platforms can be found in their platform-specific section:
+
+- [AWS][aws-customization]
+
+[aws-customization]: aws/customization.md
+[godocs]: https://godoc.org/github.com/openshift/installer/pkg/types#InstallConfig
+
+## Kubernetes Customization (unvalidated)
+
+In addition to customizing OpenShift and aspects of the underlying platform, the installer allows arbitrary modification to the Kubernetes objects that are injected into the cluster. Note that there is currently no validation on the modifications that are made, so it is possible that the changes will result in a non-functioning cluster. The Kubernetes manifests can be viewed and modified using the `manifests` and `manifest-templates` targets.
+
+The `manifests` target will render the manifest templates and output the result into the asset directory. Perhaps the most common use for this target is to include additional manifests in the initial installation. These manifests could be added after the installation as a "Day 2" operation, but there may be cases where they are necessary beforehand.
+
+The `manifest-templates` target will output the unrendered manifest templates into the asset directory. This allows modification to the templates before they have been rendered, which may be useful to users who wish to reuse the templates between cluster deployments.
+
+## OS Customization (unvalidated)
+
+In rare circumstances, certain modifications to the bootstrap and other machines may be necessary. The installer provides the "ignition-configs" target, which allows arbitrary modification to the [Ignition Configs][ignition] used to boot these machines. Note that there is currently no validation on the modifications that are made, so it is possible that the changes will result in a non-functioning cluster.
+
+An example `worker.ign` is shown below. It has been modified to increase the HTTP timeouts used when fetching the generated worker config from the cluster. This isn't likely to be useful, but it does demonstrate what is possible.
+
+```json ignition
+{
+  "ignition": {
+    "version": "2.2.0",
+    "config": {
+      "append": [{
+        "source": "https://test-cluster-api.example.com:49500/config/worker"
+      }]
+    },
+    "security": {
+      "tls": {
+        "certificateAuthorities": [{
+          "source": "data:text/plain;charset=utf-8;base64,LS0tLS1CRU..."
+        }]
+      }
+    },
+    "timeouts": {
+      "httpResponseHeaders": 120
+    }
+  },
+  "passwd": {
+    "users": [{
+      "name": "core",
+      "sshAuthorizedKeys": [
+        "ssh-ed25519 AAAA..."
+      ]
+    }]
+  }
+}
+```
+
+[ignition]: https://coreos.com/ignition/docs/latest/

docs/user/overview.md

@@ -50,7 +50,7 @@ The following targets can be destroyed by the installer:
 
 ### Multiple Invocations
 
-In order to allow users to customize their installation, the installer can be invoked multiple times. The state is stored in a hidden file in the asset directory and contains all of the intermediate artifacts. This allows the installer to pause during the installation and wait for the user to modify intermediate artifacts.
+In order to allow users to [customize their installation](customization.md), the installer can be invoked multiple times. The state is stored in a hidden file in the asset directory and contains all of the intermediate artifacts. This allows the installer to pause during the installation and wait for the user to modify intermediate artifacts.
 
 For example, you can create an install config and save it in a cluster-agnostic location: