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
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].
<!-- LINKS -->
[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

30
config.yaml
View File

@ -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: