merge

docs/openstack-clouds.md

@@ -8,6 +8,46 @@ There are a lot of ways you can go to connect to your cluster. This example will
 mkdir -p ~/.config/openstack
 ```
 
+## Token Caching
+
+In the following examples authentication caching is able by default in config, however, to make this work on most modern operating systems you will need to install the `keyring` package. Installing the `keyring` is simple and can be done across a number of operating systems with the default package manager.
+
+#### MacOS
+
+``` shell
+brew install keyring
+```
+
+#### Ubuntu or Debian
+
+``` shell
+apt install python3-keyring
+```
+
+#### Enterprise Linux
+
+``` shell
+dnf install python3-keyring
+```
+
+#### Source
+
+!!! tip
+
+    Users may want to use a Virtual Environment so that they do not have any risk of hurting their default Python environment. For more information on seting up a venv please visit the python [documentation](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-and-using-virtual-environments) on working with virtual environments.
+
+``` shell
+python -m pip install keyring
+```
+
+##### Microsoft Windows Example
+
+Ensure that the C:\Python27\Scripts directory is defined in the PATH environment variable, and use the easy_install command from the setuptools package:
+
+``` shell
+C:> py -m pip install keyring
+```
+
 ## Generate the cloud config file from within the environment
 
 ``` shell
@@ -67,14 +107,7 @@ clouds:
 
 ### Simple example for public access with Multi-factor Authentication
 
-!!! note
-
-    Multi-factor authentication will prompt you for a token for every CLI interaction, unless you have caching enabled, where tokens can be cached for a set amount of time.
-
 ``` yaml
-cache:
-  auth: true
-  expiration_time: 3600
 clouds:
   regionone-mfa:
     auth_type: "v3multifactor"
@@ -92,4 +125,36 @@ clouds:
       - RegionOne
     interface: public
     identity_api_version: "3"
+  regionone-token:
+    auth_type: "v3token"
+    auth:
+      auth_url: https://$YOUR_KEYSTONE_HOST/v3
+      project_name: $PROJECT_NAME
+      project_domain_name: $PROJECT_DOMAIN_NAME
+    region_name:
+      - RegionOne
+    interface: public
+    identity_api_version: "3"
+```
+
+When working with MFA enabled accounts we generally recommend a two step process. While a single multi-factor enabled cloud account is more than enough to run commands within the cloud, the client will require a one time use token every time a command is executed. For this reason we recommend two cloud stanzas which provide a much better over all user experience with working with MFA.
+
+#### Step one - MFA
+
+``` shell
+export OS_TOKEN=$(openstack --os-cloud regionone-mfa token issue -c id -f value)
+```
+
+!!! Note
+
+    This command will prompt you for your TOTP key before returning a valid token.
+
+This command will return the token ID and store the value within an environment variable which will be used within Step Two.
+
+#### Step Two - Token Auth
+
+Run project specific commands within the defined token
+
+``` shell
+openstack --os-cloud regionone-token ...
 ```

docs/openstack-load-balancer.md

@@ -0,0 +1,130 @@
+# Openstack Load Balancers
+
+To read more about Openstack load balancers please visit the [upstream docs](https://docs.openstack.org/python-openstackclient/latest/cli/plugin-commands/octavia.html).
+
+### Create a Load Balancer
+
+``` shell
+openstack --os-cloud {user cloud name} loadbalancer create
+    [--name <name>]
+    [--description <description>]
+    [--vip-address <vip_address>]
+    [--vip-port-id <vip_port_id>]
+    [--vip-subnet-id <vip_subnet_id>]
+    [--vip-network-id <vip_network_id>]
+    [--vip-qos-policy-id <vip_qos_policy_id>]
+    [--additional-vip subnet-id=<name-or-uuid>[,ip-address=<ip>]]
+    [--project <project>]
+    [--provider <provider>]
+    [--availability-zone <availability_zone>]
+    [--enable | --disable]
+    [--flavor <flavor>]
+    [--wait]
+    [--tag <tag> | --no-tag]
+```
+
+### List Load Balancers
+
+``` shell
+openstack --os-cloud {user cloud name} loadbalancer list
+    [--sort-column SORT_COLUMN]
+    [--sort-ascending | --sort-descending]
+    [--name <name>]
+    [--enable | --disable]
+    [--project <project-id>]
+    [--vip-network-id <vip_network_id>]
+    [--vip-subnet-id <vip_subnet_id>]
+    [--vip-qos-policy-id <vip_qos_policy_id>]
+    [--vip-port-id <vip_port_id>]
+    [--provisioning-status {ACTIVE,ERROR,PENDING_CREATE,PENDING_UPDATE,PENDING_DELETE}]
+    [--operating-status {ONLINE,DRAINING,OFFLINE,DEGRADED,ERROR,NO_MONITOR}]
+    [--provider <provider>]
+    [--flavor <flavor>]
+    [--availability-zone <availability_zone>]
+    [--tags <tag>[,<tag>,...]]
+    [--any-tags <tag>[,<tag>,...]]
+    [--not-tags <tag>[,<tag>,...]]
+    [--not-any-tags <tag>[,<tag>,...]]
+```
+
+### Delete Load Balancers
+
+``` shell
+openstack --os-cloud {user cloud name} loadbalancer delete [--cascade] [--wait] <load_balancer>
+```
+
+### Show Load Balancer's Details
+
+``` shell
+openstack --os-cloud {user cloud name} loadbalancer show <load_balancer>
+```
+
+### Update Load Balancer
+
+``` shell
+openstack --os-cloud {user cloud name} loadbalancer set
+    [--name <name>]
+    [--description <description>]
+    [--vip-qos-policy-id <vip_qos_policy_id>]
+    [--enable | --disable]
+    [--wait]
+    [--tag <tag>]
+    [--no-tag]
+    <load_balancer>
+ ```
+
+### Create Load Balancer Listener
+
+``` shell
+openstack --os-cloud {user cloud name} loadbalancer listener create
+    [--name <name>]
+    [--description <description>]
+    --protocol
+    {TCP,HTTP,HTTPS,TERMINATED_HTTPS,UDP,SCTP,PROMETHEUS}
+    [--connection-limit <limit>]
+    [--default-pool <pool>]
+    [--default-tls-container-ref <container_ref>]
+    [--sni-container-refs [<container_ref> ...]]
+    [--insert-headers <header=value,...>]
+    --protocol-port <port>
+    [--timeout-client-data <timeout>]
+    [--timeout-member-connect <timeout>]
+    [--timeout-member-data <timeout>]
+    [--timeout-tcp-inspect <timeout>]
+    [--enable | --disable]
+    [--client-ca-tls-container-ref <container_ref>]
+    [--client-authentication {NONE,OPTIONAL,MANDATORY}]
+    [--client-crl-container-ref <client_crl_container_ref>]
+    [--allowed-cidr [<allowed_cidr>]]
+    [--wait]
+    [--tls-ciphers <tls_ciphers>]
+    [--tls-version [<tls_versions>]]
+    [--alpn-protocol [<alpn_protocols>]]
+    [--hsts-max-age <hsts_max_age>]
+    [--hsts-include-subdomains]
+    [--hsts-preload]
+    [--tag <tag> | --no-tag]
+    <loadbalancer>
+ ```
+
+### List Load Balancer Listeners
+
+``` shell
+openstack --os-cloud {user cloud name} loadbalancer listener list
+    [--sort-column SORT_COLUMN]
+    [--sort-ascending | --sort-descending]
+    [--name <name>]
+    [--loadbalancer <loadbalancer>]
+    [--enable | --disable]
+    [--project <project>]
+    [--tags <tag>[,<tag>,...]]
+    [--any-tags <tag>[,<tag>,...]]
+    [--not-tags <tag>[,<tag>,...]]
+    [--not-any-tags <tag>[,<tag>,...]]
+```
+
+### Delete Load Balancer Listeners
+
+``` shell
+openstack loadbalancer listener delete [--wait] <listener>
+```

mkdocs.yml

@@ -248,4 +248,5 @@ nav:
       - Openstack Swift: storage-swift-object-store.md
       - Openstack Snapshot: openstack-snapshot.md
       - Openstack Volumes: openstack-volumes.md
+      - Openstack Load Balancers: openstack-load-balancer.md
   - Blog: https://blog.rackspacecloud.com/