diff --git a/README.md b/README.md index ca01777c..f5b36768 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,133 @@ # Overview -Cloud controller node for OpenStack nova. Contains nova-schedule, nova-api, -nova-network and nova-objectstore. +The nova-cloud-controller charm deploys a suite of OpenStack Nova services: -If console access is required then console-proxy-ip should be set to a client -accessible IP that resolves to the nova-cloud-controller. If running in HA mode -then the public vip is used if console-proxy-ip is set to local. Note: The -console access protocol is baked into a guest when it is created, if you change -it then console access for existing guests will stop working +* [nova-api][upstream-nova-api] +* [nova-conductor][upstream-nova-conductor] +* [nova-scheduler][upstream-nova-scheduler] # Usage +## Configuration + +This section covers common and/or important configuration options. See file +`config.yaml` for the full list of options, along with their descriptions and +default values. See the [Juju documentation][juju-docs-config-apps] for details +on configuring applications. + +#### `cache-known-hosts` + +Controls whether or not the charm will use the current cache for hostname/IP +resolution queries for nova-compute units. This occurs whenever information +that is passed over the `nova-compute:cloud-compute` relation changes (e.g. a +nova-compute unit is added). The default value is 'true'. See section [SSH host +lookup caching][anchor-ssh-caching] for details. + +#### `console-proxy-ip` + +Sets a client accessible proxy IP address that allows for VM console access. It +should route to the nova-cloud-controller unit when the application is not +under HA. When it is, the value of 'local' will point to the VIP. + +Ensure that option `console-access-protocol` is set to a value other than +'None'. + +VNC clients should be configured accordingly. In the case of a VIP, it will +need to be determined. + +#### `console-access-protocol` + +Specifies the protocol to use when accessing the console of a VM. Supported +values are: 'None', 'spice', 'xvpvnc', 'novnc', and 'vnc' (for both xvpvnc and +novnc). Type 'xvpvnc' is not supported with UCA release 'bionic-ussuri' or with +series 'focal' or later. + +> **Caution**: VMs are configured with a specific protocol at creation time. + Console access for existing VMs will therefore break if this value is changed + to something different. + +#### `network-manager` + +Defines the network manager for the cloud. Supported values are: + +* 'FlatDHCPManager' for nova-network (the default) +* 'FlatManager' - for nova-network +* 'Neutron' - for a full SDN solution + +When using 'Neutron' the [neutron-gateway][neutron-gateway-charm] charm should +be used to provide L3 routing and DHCP Services. + +#### `openstack-origin` + +States the software sources. A common value is an OpenStack UCA release (e.g. +'cloud:bionic-ussuri' or 'cloud:focal-wallaby'). See [Ubuntu Cloud +Archive][wiki-uca]. The underlying host's existing apt sources will be used if +this option is not specified (this behaviour can be explicitly chosen by using +the value of 'distro'). + +## Deployment + +These deployment instructions assume the following applications are present: +keystone, rabbitmq-server, neutron-api, nova-compute, and a cloud database. + +File ``ncc.yaml`` contains an example configuration: + +```yaml + nova-cloud-controller: + network-manager: Neutron + openstack-origin: cloud:focal-wallaby +``` + +Nova cloud controller is often containerised. Here a single unit is deployed to +a new container on machine '3': + + juju deploy --to lxd:3 --config ncc.yaml nova-cloud-controller + +> **Note**: The cloud's database is determined by the series: prior to focal + [percona-cluster][percona-cluster-charm] is used, otherwise it is + [mysql-innodb-cluster][mysql-innodb-cluster-charm]. In the example deployment + below mysql-innodb-cluster is used. + +Join nova-cloud-controller to the cloud database: + + juju deploy mysql-router ncc-mysql-router + juju add-relation ncc-mysql-router:db-router mysql-innodb-cluster:db-router + juju add-relation ncc-mysql-router:shared-db nova-cloud-controller:shared-db + +Five additional relations can be added: + + juju add-relation nova-cloud-controller:identity-service keystone:identity-service + juju add-relation nova-cloud-controller:amqp rabbitmq-server:amqp + juju add-relation nova-cloud-controller:neutron-api neutron-api:neutron-api + juju add-relation nova-cloud-controller:cloud-compute nova-compute:cloud-compute + +### TLS + +Enable TLS by adding a relation to an existing vault application: + + juju add-relation nova-cloud-controller:certificates vault:certificates + +See [Managing TLS certificates][cdg-tls] in the +[OpenStack Charms Deployment Guide][cdg] for more information on TLS. + +> **Note**: This charm also supports TLS configuration via charm options + `ssl_cert`, `ssl_key`, and `ssl_ca`. + +## Actions + +This section covers Juju [actions][juju-docs-actions] supported by the charm. +Actions allow specific operations to be performed on a per-unit basis. To +display action descriptions run `juju actions --schema nova-cloud-controller`. +If the charm is not deployed then see file `actions.yaml`. + +* `archive-data` +* `clear-unit-knownhost-cache` +* `openstack-upgrade` +* `pause` +* `resume` +* `security-checklist` +* `sync-compute-availability-zones` + ## High availability When more than one unit is deployed with the [hacluster][hacluster-charm] @@ -57,80 +174,72 @@ configuration: shared-db: internal-space ``` -NOTE: Spaces must be configured in the underlying provider prior to attempting -to use them. +> **Note**: Spaces must be configured in the underlying provider prior to + attempting to use them. -NOTE: Existing deployments using os-*-network configuration options will -continue to function; these options are preferred over any network space -binding provided 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. -## Default Quota Configuration +## Charm-managed quotas -This charm supports default quota settings for projects. This feature is only -available from OpenStack Icehouse and later releases. +The charm can optionally set project quotas, which affect both new and existing +projects. These quotas are set with the following configuration options: -The default quota settings do not overwrite post-deployment CLI quotas set by -operators. Existing projects whose quotas were not modified will adopt the new -defaults when a config-changed hook occurs. Newly created projects will also -adopt the defaults set in the charm's config. +* `quota-cores` +* `quota-count-usage-from-placement` +* `quota-injected-files` +* `quota-injected-file-size` +* `quota-injected-path-size` +* `quota-instances` +* `quota-key-pairs` +* `quota-metadata-items` +* `quota-ram` +* `quota-server-groups` +* `quota-server-group-members` -By default, the charm's quota configs are not set and OpenStack projects have -the below default values: +Given that OpenStack quotas can be set in a variety of ways, the order of +precedence (from higher to lower) for the enforcing of quotas is: - quota-instances : 10 - quota-cores : 20 - quota-ram : 51200 - quota-metadata_items : 128 - quota-injected_files : 5 - quota-injected_file_content_bytes : 10240 - quota-injected_file_path_length : 255 - quota-key_pairs : 100 - quota-server_groups : 10 (available since Juno) - quota-server_group_members : 10 (available since Juno) +1. quotas set by the operator manually +1. quotas set by the nova-cloud-controller charm +1. default quotas of the OpenStack service -## SSH knownhosts caching +For information on OpenStack quotas see [Manage quotas][upstream-nova-quotas] +in the Nova documentation. -This section covers the option involving the caching of SSH host lookups -(knownhosts) on each nova-compute unit. Caching of SSH host lookups speeds up -deployment of nova-compute units when first deploying a cloud, and when adding -a new unit. +## SSH host lookup caching -There is a Boolean configuration key `cache-known-hosts` that ensures that any -given host lookup to be performed just once. The default is `true` which means -that caching is performed. +Caching SSH known hosts reduces 'cloud-compute' hook execution time. It does +this by reducing the number of lookups performed by the nova-cloud-controller +charm during SSH connection negotiations when distributing a new unit's SSH +keys among existing units of the same application group. These keys are needed +for VM migrations to succeed. -> **Note**: A cloud can be deployed with the `cache-known-hosts` key set to - `false`, and be set to `true` post-deployment. At that point the hosts will - have been cached. The key only controls whether the cache is used or not. +The cache is populated (or refreshed) when option `cache-known-hosts` is set to +'false', in which case DNS lookups are always performed. The cache is queried +by the charm when it is set to 'true', where a lookup is only performed (adding +the result to the cache) when the cache is unable satisfy the query. -If the above key is set, a new Juju action `clear-unit-knownhost-cache` is -provided to clear the cache. This can be applied to a unit, service, or an -entire nova-cloud-controller application. This would be needed if DNS -resolution had changed in an existing cloud or during a cloud deployment. Not -clearing the cache in such cases could result in an inconsistent set of -knownhosts files. +When a modification is made to DNS resolution, the `clear-unit-knownhost-cache` +action should be used. This action refreshes the charm's cache and updates the +`known_hosts` file on the nova-compute units. Information can be updated +selectively by targeting a specific unit, an application group, or all +application groups: -This action will cause DNS resolution to be performed (for -unit/service/application), thus potentially triggering a relation-set on the -nova-cloud-controller unit(s) and subsequent changed hook on the related -nova-compute units. + juju run-action --wait nova-cloud-controller/0 clear-unit-knownhost-cache target=nova-compute/2 + juju run-action --wait nova-cloud-controller/0 clear-unit-knownhost-cache target=nova-compute + juju run-action --wait nova-cloud-controller/0 clear-unit-knownhost-cache -The action is used as follows, based on unit, service, or application, -respectively: +When nova-cloud-controller is under HA, the same invocation must be run on all +nova-cloud-controller units. - juju run-action nova-cloud-controller/0 clear-unit-knownhost-cache target=nova-compute/2 - juju run-action nova-cloud-controller/0 clear-unit-knownhost-cache target=nova-compute - juju run-action nova-cloud-controller/0 clear-unit-knownhost-cache +## Policy overrides -In a high-availability setup, the action must be run on all -`nova-cloud-controller` units. - -## 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. +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. @@ -145,15 +254,21 @@ Here are the essential commands (filenames are arbitrary): juju attach-resource nova-cloud-controller policyd-override=overrides.zip juju config nova-cloud-controller use-policyd-override=true -See appendix [Policy Overrides][cdg-appendix-n] in the [OpenStack Charms +See appendix [Policy overrides][cdg-appendix-n] in the [OpenStack Charms Deployment Guide][cdg] for a thorough treatment of this feature. +# Documentation + +The OpenStack Charms project maintains two documentation guides: + +* [OpenStack Charm Guide][cg]: for project information, including development + and support notes +* [OpenStack Charms Deployment Guide][cdg]: for charm usage information + # Bugs Please report bugs on [Launchpad][lp-bugs-charm-nova-cloud-controller]. -For general charm questions refer to the OpenStack [Charm Guide][cg]. - [cg]: https://docs.openstack.org/charm-guide @@ -162,3 +277,16 @@ For general charm questions refer to the OpenStack [Charm Guide][cg]. [lp-bugs-charm-nova-cloud-controller]: https://bugs.launchpad.net/charm-nova-cloud-controller/+filebug [cdg-ha-apps]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-ha.html#ha-applications [hacluster-charm]: https://jaas.ai/hacluster +[neutron-gateway-charm]: https://jaas.ai/neutron-gateway +[upstream-nova-quotas]: https://docs.openstack.org/nova/latest/admin/quotas.html +[juju-docs-actions]: https://jaas.ai/docs/actions +[juju-docs-config-apps]: https://juju.is/docs/configuring-applications +[wiki-uca]: https://wiki.ubuntu.com/OpenStack/CloudArchive +[anchor-ssh-caching]: #ssh-host-lookup-caching +[percona-cluster-charm]: https://jaas.ai/percona-cluster +[mysql-innodb-cluster-charm]: https://jaas.ai/mysql-innodb-cluster +[vault-charm]: https://jaas.ai/vault +[cdg-tls]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-certificate-management.html +[upstream-nova-api]: https://docs.openstack.org/nova/latest/cli/nova-api.html +[upstream-nova-conductor]: https://docs.openstack.org/nova/latest/cli/nova-conductor.html +[upstream-nova-scheduler]: https://docs.openstack.org/nova/latest/cli/nova-scheduler.html diff --git a/config.yaml b/config.yaml index b255107e..bbef82d5 100644 --- a/config.yaml +++ b/config.yaml @@ -147,25 +147,23 @@ options: type: boolean default: true description: | - If true then the charm will cache host and ip lookups for a unit when - populating the knownhosts file for nova-compute service. This is a known - performance issue around maintaining the knownhosts files for each - nova-compute service, and caching is a strategy to reduce the hook - execution time when the 'cloud-compute' relation changes. If false, then - no caching is performed. Changing from true to false will NOT cause new - lookups to be performed. + Caching is a strategy to reduce the hook execution time when + 'cloud-compute' relation data changes. . - To clear the caches and force new lookups to be performed, the action - 'clear-unit-knownhost-cache' should be used. + If true, the charm will query the cache as needed and only perform a + lookup (and add a cache entry) when an entry is not available in the + cache. . - This config flag is new. If there are any DNS issues during the - deployment onto different platforms then the knownhost lookups may be - inconsistent. Thus it may be preferred to keep the flag false during - deployment and then switch to true after deployment. + If false, the charm will not query the cache, lookups will always be + performed, and the cache will be populated (or refreshed). . - Note that the charm keeps a record of the lookups for each unit - regardless of the setting of this flag. The cache is only used if the - flag is true. + If there is a possibility that DNS resolution may change during a cloud + deployment then lookups may be inconsistent. In this case it may be + preferable to keep the option false and only change it to true post + deployment. + . + The 'clear-unit-knownhost-cache' action refreshes the cache (with forced + lookups) and updates the knownhost file on nova-compute units. console-access-protocol: type: string default: