From ed639be30fc21909271020974823f44fa13bb62b Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 5 Feb 2020 13:12:45 -0500 Subject: [PATCH] Refresh and refactor README Refresh and streamline the README. The local LVM storage method doesn't actually work without manual intervention. Bug filed and cited. Remove scenario involving separation of Cinder components as I cannot locate charms cinder-api and cinder-volume. Add cinder-ceph charm to the Ceph scenario. Refactor the HA and spaces sections. Other HA and space-aware charms will be identified and treated similarly. Add Actions section. Action 'rename-volume-host' doesn't make sense to me. I do not see a 'host' attribute for volumes. Is this a component of the 'os-vol-host-attr:host' attribute? Add Bugs section Change-Id: I863a64f243854ab2467f2042489485e35412727f --- README.md | 294 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 153 insertions(+), 141 deletions(-) diff --git a/README.md b/README.md index 96700bfb..d6041864 100644 --- a/README.md +++ b/README.md @@ -1,200 +1,201 @@ -Overview --------- +# Overview -This charm provides the Cinder volume service for OpenStack. It is intended to -be used alongside the other OpenStack components, starting with the Folsom -release. +This charm provides the Cinder volume service for OpenStack. It is intended to +be used alongside the other OpenStack components. -Cinder is made up of 3 separate services: an API service, a scheduler and a -volume service. This charm allows them to be deployed in different -combination, depending on user preference and requirements. +# Usage -This charm was developed to support deploying Folsom on both -Ubuntu Quantal and Ubuntu Precise. Since Cinder is only available for -Ubuntu 12.04 via the Ubuntu Cloud Archive, deploying this charm to a -Precise machine will by default install Cinder and its dependencies from -the Cloud Archive. +## Deployment -Usage ------ +Two deployment configurations will be shown. Both assume the existence of core +OpenStack services: mysql, rabbitmq-server, keystone, and +nova-cloud-controller. -Cinder may be deployed in a number of ways. This charm focuses on 3 main -configurations. All require the existence of the other core OpenStack -services deployed via Juju charms, specifically: mysql, rabbitmq-server, -keystone and nova-cloud-controller. The following assumes these services -have already been deployed. +### Storage backed by LVM-iSCSI -Basic, all-in-one using local storage and iSCSI -=============================================== +With this configuration, a block device (local to the cinder unit) is used as +an LVM physical volume. A logical volume is created (`openstack volume create`) +and exported to a cloud instance via iSCSI (`openstack server add volume`). -The api server, scheduler and volume service are all deployed into the same -unit. Local storage will be initialized as a LVM physical device, and a volume -group initialized. Instance volumes will be created locally as logical volumes -and exported to instances via iSCSI. This is ideal for small-scale deployments -or testing: +> **Note**: It is not recommended to use the LVM storage method for anything + other than testing or for small non-production deployments. - cat >cinder.cfg < **Important**: Make sure the designated block device exists and is not + currently in use. -Separating the volume service from the API service allows the storage pool -to easily scale without the added complexity that accompanies load-balancing -the API server. When we've exhausted local storage on volume server, we can -simply add-unit to expand our capacity. Future requests to allocate volumes -will be distributed across the pool of volume servers according to the -availability of storage space. +Deploy and add relations in this way: - cat >cinder.cfg < **Note**: It has been reported that the LVM storage method may not properly + initialise the physical volume and volume group. See bug + [LP #1862392][lp-bug-1862392]. -All 3 services can be deployed to the same unit, but instead of relying -on local storage to back volumes an external Ceph cluster is used. This -allows scalability and redundancy needs to be satisfied and Cinder's RBD -driver used to create, export and connect volumes to instances. This assumes -a functioning Ceph cluster has already been deployed using the official Ceph -charm and a relation exists between the Ceph service and the nova-compute -service. +### Storage backed by Ceph - cat >cinder.cfg < **Note**: The Ceph storage method is the recommended method for production + deployments. + +File `cinder.yaml` contains the following: + +```yaml cinder: block-device: None - END - juju deploy --config=cinder.cfg cinder - juju add-relation cinder ceph - juju add-relation cinder keystone - juju add-relation cinder mysql - juju add-relation cinder rabbitmq-server - juju add-relation cinder nova-cloud-controller +``` +Deploy and add relations as in the standard configuration (using the altered +YAML file). However, to use Ceph as the backend the intermediary cinder-ceph +charm is required: -Configuration -------------- + juju deploy cinder-ceph -The default value for most config options should work for most deployments. +Then add a relation from this charm to both Cinder and Ceph: -Users should be aware of three options, in particular: + juju add-relation cinder-ceph:storage-backend cinder:storage-backend + juju add-relation cinder-ceph:ceph ceph-mon:client -openstack-origin: Allows Cinder to be installed from a specific apt repository. - See config.yaml for a list of supported sources. +## High availability -block-device: When using local storage, a block device should be specified to - back a LVM volume group. It's important this device exists on - all nodes that the service may be deployed to. +This charm supports high availability. There are two mutually exclusive +HA/clustering strategies: -overwrite: Whether or not to wipe local storage that of data that may prevent - it from being initialized as a LVM physical device. This includes - filesystems and partition tables. *CAUTION* +- virtual IP(s) +- DNS -enabled-services: Can be used to separate cinder services between service - service units (see previous section) +In both cases, the hacluster subordinate charm is required. It provides the +corosync backend HA functionality. -HA/Clustering ---------------------- +### virtual IP(s) -There are two mutually exclusive high availability options: using virtual -IP(s) or DNS. In both cases, a relationship to hacluster is required which -provides the corosync back end HA functionality. +To use virtual IP(s) the clustered nodes and the VIP must be on the same +subnet. That is, the VIP must be a valid IP on the subnet for one of the node's +interfaces and each node has an interface in said subnet. The VIP becomes a +highly-available API endpoint. -To use virtual IP(s) the clustered nodes must be on the same subnet such that -the VIP is a valid IP on the subnet for one of the node's interfaces and each -node has an interface in said subnet. The VIP becomes a highly-available API -endpoint. +At a minimum, the configuration option `vip` must be defined. The value can +take on space-separated values if multiple networks are in use. Optionally, +options `vip_iface` or `vip_cidr` may be specified. -At a minimum, the config option 'vip' must be set in order to use virtual IP -HA. If multiple networks are being used, a VIP should be provided for each -network, separated by spaces. Optionally, vip_iface or vip_cidr may be -specified. +### DNS -To use DNS high availability there are several prerequisites. However, DNS HA -does not require the clustered nodes to be on the same subnet. -Currently the DNS HA feature is only available for MAAS 2.0 or greater -environments. MAAS 2.0 requires Juju 2.0 or greater. The clustered nodes must -have static or "reserved" IP addresses registered in MAAS. The DNS hostname(s) -must be pre-registered in MAAS before use with DNS HA. +DNS high availability does not require the clustered nodes to be on the same +subnet. -At a minimum, the config option 'dns-ha' must be set to true and at least one -of 'os-public-hostname', 'os-internal-hostname' or 'os-internal-hostname' must -be set in order to use DNS HA. One or more of the above hostnames may be set. +It does require: + +- an environment with MAAS 2.0 and Juju 2.0 (as minimum versions) +- clustered nodes with static or "reserved" IP addresses registered in MAAS +- DNS hostnames that are pre-registered in MAAS + +At a minimum, the configuration option `dns-ha` must be set to 'true' and at +least one of `os-admin-hostname`, `os-internal-hostname`, or +`os-public-hostname` must be set. The charm will throw an exception in the following circumstances: -If neither 'vip' nor 'dns-ha' is set and the charm is related to hacluster -If both 'vip' and 'dns-ha' are set as they are mutually exclusive -If 'dns-ha' is set and none of the os-{admin,internal,public}-hostname(s) are -set -Network Space support ---------------------- +- if neither `vip` nor `dns-ha` is set and the charm has a relation added to + hacluster +- if both `vip` and `dns-ha` are set +- if `dns-ha` is set and none of `os-admin-hostname`, `os-internal-hostname`, + or `os-public-hostname` are set -This charm supports the use of Juju Network Spaces, allowing the charm to be -bound to network space configurations managed directly by Juju. This is only -supported with Juju 2.0 and above. +## Network spaces + +This charm supports the use of Juju [network spaces][juju-docs-spaces] (Juju +`v.2.0`). This feature optionally allows specific types of the application's +network traffic to be bound to subnets that the underlying hardware is +connected to. + +> **Note**: Spaces must be configured in the backing cloud prior to deployment. API endpoints can be bound to distinct network spaces supporting the network -separation of public, internal and admin endpoints. +separation of public, internal, and admin endpoints. Access to the underlying MySQL instance can also be bound to a specific space using the shared-db relation. -To use this feature, use the --bind option when deploying the charm: +For example, providing that spaces 'public-space', 'internal-space', and +'admin-space' exist, the deploy command above could look like this: - juju deploy cinder --bind "public=public-space internal=internal-space admin=admin-space shared-db=internal-space" + juju deploy --config cinder.yaml cinder \ + --bind "public=public-space internal=internal-space admin=admin-space shared-db=internal-space" -Alternatively these can also be provided as part of a juju native bundle -configuration: +Alternatively, configuration can be provided as part of a bundle: +```yaml cinder: - charm: cs:xenial/cinder + charm: cs:cinder num_units: 1 bindings: public: public-space - admin: admin-space internal: internal-space + admin: admin-space shared-db: internal-space +``` -NOTE: Spaces must be configured in the underlying provider prior to attempting -to use them. +> **Note**: Existing cinder units configured with the `os-admin-network`, + `os-internal-network`, or `os-public-network` options will continue to honour + them. Furthermore, these options override any space bindings, if set. -NOTE: Existing deployments using os-*-network configuration options will -continue to function; these options are preferred over any network space -binding provided if set. +## Actions -Policy Overrides -================ +This section covers Juju [actions][juju-docs-actions] supported by the charm. +Actions allow specific operations to be performed on a per-unit basis. -Policy overrides is an **advanced** feature that allows an operator to override -the default policy of an OpenStack service. The policies that the service -supports, the defaults it implements in its code, and the defaults that a charm -may include should all be clearly understood before proceeding. +### openstack-upgrade + +Perform the OpenStack service upgrade. Configuration option +`action-managed-upgrade` must be set to 'True'. + +### pause + +Pause the cinder unit. This action will stop the Cinder service. + +### remove-services + +Remove unused services entities from the database after enabling HA with a +stateless backend such as the cinder-ceph application. + +### rename-volume-host + +Update the host attribute of volumes from currenthost to newhost. + +### resume + +Resume the cinder unit. This action will start the Cinder service if paused. + +### security-checklist + +Validate the running configuration against the OpenStack security guides +checklist. + +### volume-host-add-driver + +Update the 'os-vol-host-attr:host' volume attribute. Used for migrating volumes +to another backend. + +## Policy Overrides + +Policy overrides is an advanced feature that allows an operator to override the +default policy of an OpenStack service. The policies that the service supports, +the defaults it implements in its code, and the defaults that a charm may +include should all be clearly understood before proceeding. > **Caution**: It is possible to break the system (for tenants and other services) if policies are incorrectly applied to the service. @@ -212,7 +213,18 @@ Here are the essential commands (filenames are arbitrary): See appendix [Policy Overrides][cdg-appendix-n] in the [OpenStack Charms Deployment Guide][cdg] for a thorough treatment of this feature. +# Bugs + +Please report bugs on [Launchpad][lp-bugs-charm-cinder]. + +For general charm questions refer to the [OpenStack Charm Guide][cg]. + +[cg]: https://docs.openstack.org/charm-guide [cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide [cdg-appendix-n]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-policy-overrides.html +[juju-docs-spaces]: https://jaas.ai/docs/spaces +[juju-docs-actions]: https://jaas.ai/docs/actions +[lp-bugs-charm-cinder]: https://bugs.launchpad.net/charm-cinder/+filebug +[lp-bug-1862392]: https://bugs.launchpad.net/charm-cinder/+bug/1862392