openstack/charm-nova-cloud-controller
Code Issues Proposed changes

Overhaul README

Browse Source 
Overhaul the charm README.

  The section on SSH host lookup caching in particular
  received a lot of attention.

  Apart from formatting, the Spaces section was deliberately
  left untouched as improvements are part of a separate
  documentation effort.

Improve the 'cache-known-hosts' option entry in config.yaml.

Change-Id: I14019ad38a9c4976026c607daca9d768c692535c
This commit is contained in:
Peter Matulis 2021-09-15 17:38:41 -04:00
parent 222530b515
commit 7ac2d02060
2 changed files with 211 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

266
README.md
View File

@ -1,16 +1,133 @@
# Overview # Overview
Cloud controller node for OpenStack nova. Contains nova-schedule, nova-api, The nova-cloud-controller charm deploys a suite of OpenStack Nova services:
nova-network and nova-objectstore.
If console access is required then console-proxy-ip should be set to a client * [nova-api][upstream-nova-api]
accessible IP that resolves to the nova-cloud-controller. If running in HA mode * [nova-conductor][upstream-nova-conductor]
then the public vip is used if console-proxy-ip is set to local. Note: The * [nova-scheduler][upstream-nova-scheduler]
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
# Usage # 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 ## High availability
When more than one unit is deployed with the [hacluster][hacluster-charm] When more than one unit is deployed with the [hacluster][hacluster-charm]
@ -57,80 +174,72 @@ configuration:
shared-db: internal-space shared-db: internal-space
``` ```
NOTE: Spaces must be configured in the underlying provider prior to attempting > **Note**: Spaces must be configured in the underlying provider prior to
to use them. attempting to use them.
NOTE: Existing deployments using os-*-network configuration options will > **Note**: Existing deployments using `os-*-network` configuration options
continue to function; these options are preferred over any network space will continue to function; these options are preferred over any network space
binding provided if set. binding provided if set.
## Default Quota Configuration ## Charm-managed quotas
This charm supports default quota settings for projects. This feature is only The charm can optionally set project quotas, which affect both new and existing
available from OpenStack Icehouse and later releases. projects. These quotas are set with the following configuration options:
The default quota settings do not overwrite post-deployment CLI quotas set by * `quota-cores`
operators. Existing projects whose quotas were not modified will adopt the new * `quota-count-usage-from-placement`
defaults when a config-changed hook occurs. Newly created projects will also * `quota-injected-files`
adopt the defaults set in the charm's config. * `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 Given that OpenStack quotas can be set in a variety of ways, the order of
the below default values: precedence (from higher to lower) for the enforcing of quotas is:
quota-instances : 10 1. quotas set by the operator manually
quota-cores : 20 1. quotas set by the nova-cloud-controller charm
quota-ram : 51200 1. default quotas of the OpenStack service
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)
## 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 ## SSH host lookup caching
(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.
There is a Boolean configuration key `cache-known-hosts` that ensures that any Caching SSH known hosts reduces 'cloud-compute' hook execution time. It does
given host lookup to be performed just once. The default is `true` which means this by reducing the number of lookups performed by the nova-cloud-controller
that caching is performed. 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 The cache is populated (or refreshed) when option `cache-known-hosts` is set to
`false`, and be set to `true` post-deployment. At that point the hosts will 'false', in which case DNS lookups are always performed. The cache is queried
have been cached. The key only controls whether the cache is used or not. 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 When a modification is made to DNS resolution, the `clear-unit-knownhost-cache`
provided to clear the cache. This can be applied to a unit, service, or an action should be used. This action refreshes the charm's cache and updates the
entire nova-cloud-controller application. This would be needed if DNS `known_hosts` file on the nova-compute units. Information can be updated
resolution had changed in an existing cloud or during a cloud deployment. Not selectively by targeting a specific unit, an application group, or all
clearing the cache in such cases could result in an inconsistent set of application groups:
knownhosts files.
This action will cause DNS resolution to be performed (for juju run-action --wait nova-cloud-controller/0 clear-unit-knownhost-cache target=nova-compute/2
unit/service/application), thus potentially triggering a relation-set on the juju run-action --wait nova-cloud-controller/0 clear-unit-knownhost-cache target=nova-compute
nova-cloud-controller unit(s) and subsequent changed hook on the related juju run-action --wait nova-cloud-controller/0 clear-unit-knownhost-cache
nova-compute units.
The action is used as follows, based on unit, service, or application, When nova-cloud-controller is under HA, the same invocation must be run on all
respectively: nova-cloud-controller units.
juju run-action nova-cloud-controller/0 clear-unit-knownhost-cache target=nova-compute/2 ## Policy overrides
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
In a high-availability setup, the action must be run on all Policy overrides is an advanced feature that allows an operator to override the
`nova-cloud-controller` units. 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
## Policy Overrides 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 > **Caution**: It is possible to break the system (for tenants and other
services) if policies are incorrectly applied to the service. 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 attach-resource nova-cloud-controller policyd-override=overrides.zip
juju config nova-cloud-controller use-policyd-override=true 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. 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 # Bugs
Please report bugs on [Launchpad][lp-bugs-charm-nova-cloud-controller]. Please report bugs on [Launchpad][lp-bugs-charm-nova-cloud-controller].
For general charm questions refer to the OpenStack [Charm Guide][cg].
<!-- LINKS --> <!-- LINKS -->
[cg]: https://docs.openstack.org/charm-guide [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 [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 [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 [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

30
config.yaml
View File

@ -147,25 +147,23 @@ options:
type: boolean type: boolean
default: true default: true
description: | description: |
If true then the charm will cache host and ip lookups for a unit when Caching is a strategy to reduce the hook execution time when
populating the knownhosts file for nova-compute service. This is a known 'cloud-compute' relation data changes.
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.
. .
To clear the caches and force new lookups to be performed, the action If true, the charm will query the cache as needed and only perform a
'clear-unit-knownhost-cache' should be used. 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 If false, the charm will not query the cache, lookups will always be
deployment onto different platforms then the knownhost lookups may be performed, and the cache will be populated (or refreshed).
inconsistent. Thus it may be preferred to keep the flag false during
deployment and then switch to true after deployment.
. .
Note that the charm keeps a record of the lookups for each unit If there is a possibility that DNS resolution may change during a cloud
regardless of the setting of this flag. The cache is only used if the deployment then lookups may be inconsistent. In this case it may be
flag is true. 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: console-access-protocol:
type: string type: string
default: default: