Add documentation of all OpenStack provider opts (#6047)

Add documentation of all OpenStack provider options including an
indication as to which items are required versus optional and which
configuration blocks they must appear in.

Also adds a section detailing which services are required/expected by
the OpenStack provider implementation.

https://github.com/kubernetes/website/issues/5980

docs/concepts/cluster-administration/cloud-providers.md

@@ -58,14 +58,41 @@ The information for the annotations for AWS is taken from the comments on [aws.g
 
 # OpenStack
 This section describes all the possible configurations which can
-be used when using OpenStack with Kubernetes.
+be used when using OpenStack with Kubernetes. The OpenStack cloud provider
+implementation for Kubernetes supports the use of these OpenStack services from
+the underlying cloud, where available:
+
+Service                  | API Version(s) | Required
+-------------------------+----------------+----------
+Block Storage (Cinder)   | V1†, V2        | No
+Compute (Nova)           | V2             | No
+Identity (Keystone)      | V2‡,  V3         | Yes
+Load Balancing (Neutron) | V1§, V2        | No
+
+† Block Storage V1 API support is deprecated, support for Block Storage V3 will
+  be added in the future.
+‡ Identity V2 API support is deprecated and will be removed from the provider in
+a future release. As of the "Queens" release OpenStack will no longer expose the
+Identity V2 API.
+§ Load Balancing V1 API support is deprecated and will be removed from the
+provider in a future release.
+
+Service discovery is achieved by listing the service catalog managed by
+OpenStack Identity (Keystone) using the `auth-url` provided in the provider
+configuration. The provider will gracefully degrade in functionality when
+OpenStack services other than Keystone are not available and simply disclaim
+support for impacted features. Certain features are also enabled or disabled
+based on the list of extensions published by Neutron in the underlying cloud.
 
 ## cloud.conf
 Kubernetes knows how to interact with OpenStack via the file cloud.conf. It is the file that will provide Kubernetes with credentials and location for the OpenStack auth endpoint.
 You can create a cloud.conf file by specifying the following details in it
 
-### Minimal configuration
+### Typical configuration
-This is an example of a minimal configuration that touches the values that most often need to be set:
+This is an example of a typical configuration that touches the values that most
+often need to be set. It points the provider at the OpenStack cloud's Keystone
+endpoint, provides details for how to authenticate with it, and configures the
+load balancer:
 
 ```yaml
 [Global]
@@ -80,28 +107,89 @@ subnet-id=6937f8fa-858d-4bc9-a3a5-18d2c957166a
 ```
 
 #### Global
-* `username`: Refers to the username of a valid user set in keystone.
+These configuration options for the OpenStack provider pertain to its global
-* `password`:Refers to the password of a valid user set in keystone.
+configuration and should appear in the `[Global]` section of the `cloud.conf`
-* `auth-url`: The URL of the keystone API used to authenticate. On OpenStack control panels, this can be found at Access and Security > API Access > Credentials.
+file:
-* `tenant-id`: Used to specify the id of the project where you want to create your resources.
+
-* `domain-id`: Used to specify the id of the domain your user belongs to.
+* `auth-url` (Required): The URL of the keystone API used to authenticate. On
+  OpenStack control panels, this can be found at Access and Security > API
+  Access > Credentials.
+* `username` (Required): Refers to the username of a valid user set in keystone.
+* `password` (Required): Refers to the password of a valid user set in keystone.
+* `tenant-id` (Required): Used to specify the id of the project where you want
+  to create your resources.
+* `tenant-name` (Optional): Used to specify the name of the project where you
+  want to create your resources.
+* `trust-id` (Optional): Used to specify the identifier of the trust to use for
+  authorization. A trust represents a user's (the trustor) authorization to
+  delegate roles to another user (the trustee), and optionally allow the trustee
+  to impersonate the trustor. Available trusts are found under the
+  `/v3/OS-TRUST/trusts` endpoint of the Keystone API.
+* `domain-id` (Optional): Used to specify the id of the domain your user belongs
+  to.
+* `domain-name` (Optional): Used to specify the name of the domain your user
+  belongs to.
+* `region` (Optional): Used to specify the identifier of the region to use when
+  running on a multi-region OpenStack cloud. A region is a general division of
+  an OpenStack deployment. Although a region does not have a strict geographical
+  connotation, a deployment can use a geographical name for a region identifier
+  such as `us-east`. Available regions are found under the `/v3/regions`
+  endpoint of the Keystone API.
+* `ca-file` (Optional): TODO
+
+When using Keystone V3 - which changes tenant to project the `tenant-id` value 
+is automatically mapped to the project construct in the API.
 
 ####  Load Balancer
-* `subnet-id`: Used to specify the id of the subnet you want to create your loadbalancer on. Can be found at Network > Networks. Click on the respective network to get its subnets.
+These configuration options for the OpenStack provider pertain to the load
+balancer and should appear in the `[LoadBalancer]` section of the `cloud.conf`
+file:
 
-### Optional configuration
+* `lb-version` (Optional): Used to override automatic version detection. Valid
+  values are `v1` or `v2`. Where no value is provided automatic detection will
+  select the highest supported version exposed by the underlying OpenStack
+  cloud.
+* `subnet-id` (Optional): Used to specify the id of the subnet you want to
+  create your loadbalancer on. Can be found at Network > Networks. Click on the
+  respective network to get its subnets.
+* `floating-network-id` (Optional): If specified, will create a floating IP for
+  the load balancer.
+* `lb-method` (Optional): Used to specify algorithm by which load will be
+  distributed amongst members of the load balancer pool. The value can be
+  `ROUND_ROBIN`, `LEAST_CONNECTIONS`, or `SOURCE_IP`. The default behavior if
+  none is specified is `ROUND_ROBIN`.
+* `create-monitor` (Optional): Indicates whether or not to create a health
+  monitor for the Neutron load balancer. Valid values are `true` and `false`.
+  The default is `false`. When `true` is specified then `monitor-delay`,
+  `monitor-timeout`, and `monitor-max-retries` must also be set.
+* `monitor-delay` (Optional): The time, in seconds, between sending probes to
+  members of the load balancer.
+* `monitor-timeout` (Optional): Maximum number of seconds for a monitor to wait
+  for a ping reply before it times out. The value must be less than the delay
+  value.
+* `monitor-max-retries` (Optional): Number of permissible ping failures before
+  changing the load balancer member's status to INACTIVE. Must be a number
+  between 1 and 10.
+* `manage-security-groups` (Optional): Determines whether or not the load
+  balancer should automatically manage the security group rules. Valid values
+  are `true` and `false`. The default is `false`. When `true` is specified
+  `node-security-group` must also be supplied.
+* `node-security-group` (Optional): ID of the security group to manage.
 
 #### Block Storage
+These configuration options for the OpenStack provider pertain to block storage
+and should appear in the `[BlockStorage]` section of the `cloud.conf` file:
 
-Kubernetes uses the OpenStack service catalog to locate services it knows how to
+* `bs-version` (Optional): Used to override automatic version detection. Valid
-use including Cinder Block Storage. The cloud provider configuration does
+  values are `v1`, `v2`, `v3` and `auto`. When `auto` is specified automatic
-however include an additional option for influencing the way the block storage
+  detection will select the highest supported version exposed by the underlying
-API is used:
+  OpenStack cloud. The default value if none is provided is `auto`.
-
+* `trust-device-path` (Optional): In most scenarios the block device names
-* `bs-version`: Refers to the version of the block storage API to use. Valid
+  provided by Cinder (e.g. /dev/vda) can not be trusted. This boolean toggles
-  values are `v1`, `v2`, `v3` and `auto`. The `auto` value is the default and
+  this behavior. Setting it to `true` results in trusting the block device names
-  will use the newest version of the block storage API supported by the
+  provided by Cinder. The default value of `false` results in the discovery of
-  underlying OpenStack cloud.
+  the device path based on it's serial number and /dev/disk/by-id mapping and is
+  the recommended approach.
 
 If deploying Kubernetes versions <= 1.8 on an OpenStack deployment that uses
 paths rather than ports to differentiate between endpoints it may be necessary
@@ -119,6 +207,15 @@ provider configuration:
 [BlockStorage]
 bs-version=v2
 ```
+
+#### Router
+These configuration options for the OpenStack provider pertain to routing and
+should appear in the `[Router]` section of the `cloud.conf` file:
+
+* `router-id` (Optional): If the underlying cloud's Neutron deployment supports
+  the `extraroutes` extension then use `router-id` to specify a router to add
+  routes to.
+
 {% endcapture %}
 
 {% include templates/concept.md %}