Overhaul README
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
parent
222530b515
commit
7ac2d02060
266
README.md
266
README.md
|
|
@ -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
30
config.yaml
|
|
@ -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:
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue