docs/user: Standardize install-config property documentation #2162
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,18 +1,50 @@ | ||
| # AWS Platform Customization | ||
|
|
||
| Beyond the [platform-agnostic `install-config.yaml` properties](../customization.md#platform-customization), the installer supports additional, AWS-specific properties. | ||
|
|
||
| ## 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. | ||
|
Contributor
There was a problem hiding this comment. hmm, object is probably not accurate here because it is map string->string, where objects are more like
Member
Author
There was a problem hiding this comment.
That's still a JSON object (YAML mapping), we just leave the set of valid keys more open-ended than for JSON objects backed by Go |
||
| 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 | ||
|
Contributor
There was a problem hiding this comment. nit: match with something similar to
Member
Author
There was a problem hiding this comment.
Do you mean "Machine pools" -> "Machine-pool properties"? Or something else? |
||
|
|
||
| * `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 | ||
|
|
||
| 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 | ||
| platform: | ||
| aws: | ||
| region: us-west-2 | ||
| 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 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... | ||
| ``` | ||
|
|
||
| ### 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... | ||
| ``` | ||
|
|
||
| ### 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:[email protected]:123/ | ||
| httpProxy: https://username:[email protected]: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 | ||
| ``` | ||
|
|
||
| ## 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 | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should string be surrounded with back ticks?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Like:
? I think it's fine without that; if we wanted to be formal we could link to the JSON RFC for string or the YAML string spec. But the YAML spec is pretty dense; I'm fine just leaving it as an informal "string" and expecting folks to figure it out. I'm also fine linking to the specs if you want me to file that as follow-up work.