docs/user: Standardize install-config property documentation

This is a bit more accessible than pointing folks at Godocs, since it allows us to focus on the YAML property names (while Godocs understandably focus on Go property names) and YAML renderings. Also break up our old "one big example" install-config.yaml into a minimal per-platform example and a series of small extentions excercising groups of properties. The vSphere docs are based heavily on [1]. Also drop proxy.md. It was added in e7edbf7 (Add proxy configuration to bootstrap node, 2019-06-24, #1832), but: * Proxy testing and Squid configuration information belongs in openshift/release, not in the installer repository. * docs/user/customization.md now contains a more complete proxy-config fragment. OpenStack computeFlavor precedence is based on [2]. [1]: https://github.com/openshift/openshift-docs/blob/enterprise-4.2/modules/installation-vsphere-config-yaml.adoc Last touched by commit openshift/openshift-docs@25afc76 , 2019-08-19 [2]: #2162 (comment)
openshift · Sep 9, 2019 · a947609 · a947609
1 parent a42ba5b
commit a947609
Show file tree

Hide file tree

Showing 13 changed files with 346 additions and 147 deletions.
diff --git a/docs/dev/proxy.md b/docs/dev/proxy.md
diff --git a/docs/user/aws/customization.md b/docs/user/aws/customization.md
@@ -1,18 +1,50 @@
 # AWS Platform Customization
 
-The following options are available when using AWS:
+Beyond the [platform-agnostic `install-config.yaml` properties](../customization.md#platform-customization), the installer supports additional, AWS-specific properties.
 
-- `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
+## Cluster-scoped properties
+
+* `amiID` (optional string): The AMI that should be used to boot machines for the cluster.
+    If set, the AMI should belong to the same region as the cluster.
+* `region` (required string): The AWS region where the cluster will be created.
+* `userTags` (optional object): Additional keys and values that the installer will add as tags to all resources that it creates.
+    Resources created by the cluster itself may not include these tags.
+* `defaultMachinePlatform` (optional object): Default [AWS-specific machine pool properties](#machine-pools) which applies to [machine pools](../customization.md#machine-pools) that do not define their own AWS-specific properties.
+
+## Machine pools
+
+* `rootVolume` (optional object): Defines the root volume for EC2 instances in the machine pool.
+    * `iops` (optional integer): The amount of provisioned [IOPS][volume-iops].
+        This is only valid for `type` `io1`.
+    * `size` (optional integer): Size of the root volume in gibibytes (GiB).
+    * `type` (optional string):  The [type of volume][volume-type].
+* `type` (optional string): The [EC2 instance type][instance-type].
+* `zones` (optional array of strings): The availability zones used for machines in the pool.
 
 ## 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.
+Some example `install-config.yaml` are shown below.
+For examples of platform-agnostic configuration fragments, see [here](../customization.md#examples).
+
+### Minimal
+
+An example minimal AWS install config is:
+
+```yaml
+apiVersion: v1
+baseDomain: example.com
+metadata:
+  name: test-cluster
+platform:
+  aws:
+    region: us-west-2
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
+
+### Custom machine pools
+
+An example AWS install config with custom machine pools:
 
 ```yaml
 apiVersion: v1
@@ -40,20 +72,14 @@ compute:
   replicas: 5
 metadata:
   name: test-cluster
-networking:
-  clusterNetwork:
-  - cidr: 10.128.0.0/14
-    hostPrefix: 23
-  machineCIDR: 10.0.0.0/16
-  serviceNetwork:
-  - 172.30.0.0/16
-  networkType: OpenShiftSDN
 platform:
   aws:
     region: us-west-2
-    userTags:
-      adminContact: jdoe
-      costCenter: 7536
 pullSecret: '{"auths": ...}'
 sshKey: ssh-ed25519 AAAA...
 ```
+
+[availablity-zones]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html
+[instance-type]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html
+[volume-iops]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html
+[volume-type]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
diff --git a/docs/user/azure/customization.md b/docs/user/azure/customization.md
@@ -1,15 +1,46 @@
 # Azure Platform Customization
 
+Beyond the [platform-agnostic `install-config.yaml` properties](../customization.md#platform-customization), the installer supports additional, Azure-specific properties.
+
+## Cluster-scoped properties
+
 The following options are available when using Azure:
 
-- `machines.platform.azure.type` - the VM instance type
-- `machines.platform.azure.osDisk.diskSizeGB` - The Azure OS disk size in Gigabytes
-- `platform.azure.region` - the Azure region (location) that the installer will use when creating resource group and resources
-- `platform.azure.baseDomainResourceGroupName` - the Azure Resource Group that has the public DNS zone for base domain
+* `region` (required string): The Azure region where the cluster will be created.
+* `baseDomainResourceGroupName` (required string): The resource group where the Azure DNS zone for the base domain is found.
+* `defaultMachinePlatform` (optional object): Default [Azure-specific machine pool properties](#machine-pools) which applies to [machine pools](../customization.md#machine-pools) that do not define their own Azure-specific properties.
+
+## Machine pools
+
+* `osDisk` (optional object):
+    * `diskSizeGB` (optional integer): The size of the disk in gigabytes (GB).
+* `type` (optional string): The Azure instance type.
 
 ## 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.
+Some example `install-config.yaml` are shown below.
+For examples of platform-agnostic configuration fragments, see [here](../customization.md#examples).
+
+### Minimal
+
+An example minimal Azure install config is:
+
+```yaml
+apiVersion: v1
+baseDomain: example.com
+metadata:
+  name: test-cluster
+platform:
+  azure:
+    region: centralus
+    baseDomainResourceGroupName: os4-common
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
+
+### Custom machine pools
+
+An example Azure install config with custom machine pools:
 
 ```yaml
 apiVersion: v1
@@ -32,14 +63,6 @@ compute:
   replicas: 5
 metadata:
   name: test-cluster
-networking:
-  clusterNetwork:
-  - cidr: 10.128.0.0/14
-    hostPrefix: 23
-  machineCIDR: 10.0.0.0/16
-  serviceNetwork:
-  - 172.30.0.0/16
-  networkType: OpenShiftSDN
 platform:
   azure:
     region: centralus

diff --git a/docs/user/customization.md b/docs/user/customization.md
@@ -12,16 +12,155 @@ The most simple customization is exposed by the installer as an interactive seri
 
 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:
+The `install-config.yaml` generated by the installer will not have all of the available fields populated, so they may need to be manually added if they are needed.
+
+The following `install-config.yaml` properties are available:
+
+* `apiVersion` (required string): The API version for the `install-config.yaml` content.
+    The current version (as described in this documentation) is `v1`.
+    The installer may also support older API versions.
+* `additionalTrustBundle` (optional string): a PEM-encoded X.509 certificate bundle that will be added to the nodes' trusted certificate store.
+* `baseDomain` (required string): The base domain to which the cluster should belong.
+* `controlPlane` (optional [machine-pool](#machine-pools)): The configuration for the machines that comprise the control plane.
+* `compute` (optional array of [machine-pools](#machine-pools)): The configuration for the machines that comprise the compute nodes.
+* `imageContentSources` (optional array of objects): Sources and repositories for the release-image content.
+    Each entry in the array is an object with the following properties:
+    * `source` (required string): The repository that users refer to, e.g. in image pull specifications.
+    * `mirrors` (optional array of strings): One or more repositories that may also contain the same images.
+* `metadata` (required object): Kubernetes resource ObjectMeta, from which only the `name` parameter is consumed.
+    * `name` (required string): The name of the cluster.
+        DNS records for the cluster are all subdomains of `{{.metadata.name}}.{{.baseDomain}}`.
+* `networking` (optional object): The configuration for the pod network provider in the cluster.
+    * `clusterNetwork` (optional array of objects): The IP address pool for pods.
+        The default is 10.128.0.0/14 with a host prefix of /23.
+        * `cidr` (required [IP network](#ip-networks)): The IP block address pool.
+        * `hostPrefix` (required integer): The prefix size to allocate to each node from the CIDR.
+        For example, 24 would allocate 2^8=256 adresses to each node.
+    * `machineCIDR` (optional [IP network](#ip-networks)): The IP address pool for machines.
+        The default is 10.0.0.0/16 for all platforms other than libvirt.
+        For libvirt, the default is 192.168.126.0/24.
+    * `networkType` (optional string): The type of network to install.
+        The default is [OpenShiftSDN][openshift-sdn].
+    * `serviceNetwork` (optional array of [IP networks](#ip-networks)): The IP address pool for services.
+        The default is 172.30.0.0/16.
+* `platform` (required object): The configuration for the specific platform upon which to perform the installation.
+    * `aws` (optional object): [AWS-specific properties](aws/customization.md#cluster-scoped-properties).
+    * `azure` (optional object): [Azure-specific properties](azure/customization.md#cluster-scoped-properties).
+    * `openstack` (optional object): [OpenStack-specific properties](openstack/customization.md#cluster-scoped-properties).
+    * `vsphere` (optional object): [vSphere-specific properties](vsphere/customization.md#cluster-scoped-properties).
+* `proxy` (optional object): The proxy settings for the cluster.
+    If unset, the cluster will not be configured to use a proxy.
+    * `httpProxy` (optional string): The URL of the proxy for HTTP requests.
+    * `httpsProxy` (optional string): The URL of the proxy for HTTPS requests.
+    * `noProxy` (optional string): A comma-separated list of domains and [CIDRs][cidr-notation] for which the proxy should not be used.
+* `pullSecret` (required string): The secret to use when pulling images.
+* `sshKey` (optional string): The public Secure Shell (SSH) key to provide access to instances.
+
+### IP networks
+
+IP networks are represented as strings using [Classless Inter-Domain Routing (CIDR) notation][cidr-notation] with a traditional IP address or network number, followed by the "/" (slash) character, followed by a decimal value between 0 and 32 that describes the number of significant bits.
+For example, 10.0.0.0/16 represents IP addresses 10.0.0.0 through 10.0.255.255.
+
+### Machine pools
+
+The following machine-pool properties are available:
+
+* `hyperthreading` (optional string): Determines the mode of hyperthreading that machines in the pool will utalize.
+    Valid values are `Enabled` (the default) and `Disabled`.
+* `name` (required string): The name of the machine pool.
+* `platform` (optional object): Platform-specific machine-pool configuration.
+    * `aws` (optional object): [AWS-specific properties](aws/customization.md#machine-pools).
+    * `azure` (optional object): [Azure-specific properties](azure/customization.md#machine-pools).
+    * `openstack` (optional object): [OpenStack-specific properties](openstack/customization.md#machine-pools).
+    * `vsphere` (optional object): [vSphere-specific properties](vsphere/customization.md#machine-pools).
+* `replicas` (optional integer): The machine count for the machine pool.
+
+### Examples
+
+While all complete `install-config.yaml` will contain platform-specific sections, the following example fragments demonstrate platform-agnostic options:
+
+### Additional trust bundle
+
+```yaml
+apiVersion: v1
+additionalTrustBundle: |
+  -----BEGIN CERTIFICATE-----
+  ...base-64-encoded, DER Certificate Authority cert...
+  -----END CERTIFICATE-----
+
+  -----BEGIN CERTIFICATE-----
+  ...base-64-encoded, DER Certificate Authority cert...
+  -----END CERTIFICATE-----
+baseDomain: example.com
+metadata:
+  name: test-cluster
+platform: ...
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
 
-- [AWS][aws-customization]
-- [Azure][azure-customization]
-- [OpenStack][openstack-customization]
+### Custom machine pools
+
+An example install config with custom machine pools to grow the size of the worker pool and disable hyperthreading:
+
+```yaml
+apiVersion: v1
+baseDomain: example.com
+controlPlane:
+  name: master
+  hyperthreading: Disabled
+compute:
+- name: worker
+  hyperthreading: Disabled
+  replicas: 5
+metadata:
+  name: test-cluster
+platform: ...
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
 
-[aws-customization]: aws/customization.md
-[azure-customization]: azure/customization.md
-[godocs]: https://godoc.org/github.com/openshift/installer/pkg/types#InstallConfig
-[openstack-customization]: openstack/customization.md
+### Custom networking
+
+An example install config with custom networking:
+
+```yaml
+apiVersion: v1
+baseDomain: example.com
+metadata:
+  name: test-cluster
+networking:
+  clusterNetworks:
+  - cidr: 10.128.0.0/14
+    hostPrefix: 23
+  machineCIDR: 10.0.0.0/16
+  networkType: OpenShiftSDN
+  serviceNetwork:
+  - 172.30.0.0/16
+platform: ...
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
+
+### Proxy
+
+An example install config routing outgoing traffic through a proxy:
+
+```yaml
+apiVersion: v1
+baseDomain: example.com
+metadata:
+  name: test-cluster
+proxy:
+  httpsProxy: https://username:password@proxy.example.com:123/
+  httpProxy: https://username:password@proxy.example.com:123/
+  noProxy: 123.example.com,10.88.0.0/16
+platform: ...
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+```
+
+If your proxy certificate is signed by a certificate authority which RHCOS does not trust by default, you may also wish to configure [an additional trust bundle](#additional-trust-bundle).
 
 ## Kubernetes Customization (unvalidated)
 
@@ -194,12 +333,6 @@ For example:
     worker-edab0895c59dba7a566f4b955d87d964                     3.11.0-744-g5b05d9d3-dirty   2.2.0             137m
     ```
 
-[default-kubelet-service]: https://github.com/openshift/machine-config-operator/blob/master/templates/master/01-master-kubelet/_base/units/kubelet.yaml
-[machine-config-operator]: https://github.com/openshift/machine-config-operator#machine-config-operator
-[machine-config-pool]: https://github.com/openshift/machine-config-operator/blob/master/docs/MachineConfigController.md#machinepool
-[machine-config]: https://github.com/openshift/machine-config-operator/blob/master/docs/MachineConfiguration.md
-[master-machine-config-pool]: https://github.com/openshift/machine-config-operator/blob/master/manifests/master.machineconfigpool.yaml
-
 ## 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.
@@ -237,4 +370,11 @@ An example `worker.ign` is shown below. It has been modified to increase the HTT
 }
 ```
 
+[cidr-notation]: https://tools.ietf.org/html/rfc4632#section-3.1
+[default-kubelet-service]: https://github.com/openshift/machine-config-operator/blob/master/templates/master/01-master-kubelet/_base/units/kubelet.yaml
 [ignition]: https://coreos.com/ignition/docs/latest/
+[machine-config-operator]: https://github.com/openshift/machine-config-operator#machine-config-operator
+[machine-config-pool]: https://github.com/openshift/machine-config-operator/blob/master/docs/MachineConfigController.md#machinepool
+[machine-config]: https://github.com/openshift/machine-config-operator/blob/master/docs/MachineConfiguration.md
+[master-machine-config-pool]: https://github.com/openshift/machine-config-operator/blob/master/manifests/master.machineconfigpool.yaml
+[openshift-sdn]: https://github.com/openshift/sdn