neutron api #293

Neutron is a virtual network service for OpenStack, and a part of
Netstack. Just like OpenStack Nova provides an API to dynamically
request and configure virtual servers, Neutron provides an API to
dynamically request and configure virtual networks. These networks
connect "interfaces" from other OpenStack services (e.g., virtual NICs
from Nova VMs). The Neutron API supports extensions to provide
advanced network capabilities (e.g., QoS, ACLs, network monitoring,
etc.)
.
This charm provides the OpenStack Neutron API service.

Overview

This principle charm provides the OpenStack Neutron API service which
was previously provided by the nova-cloud-controller charm.

When this charm is related to the nova-cloud-controller charm the
nova-cloud controller charm will shutdown its api service, de-register
it from keystone and inform the compute nodes of the new neutron url.

Usage

To deploy (partial deployment only):

juju deploy neutron-api
juju deploy neutron-openvswitch

juju add-relation neutron-api mysql
juju add-relation neutron-api rabbitmq-server
juju add-relation neutron-api neutron-openvswitch
juju add-relation neutron-api nova-cloud-controller

This charm also supports scale out and high availability using the
hacluster charm:

juju deploy hacluster neutron-hacluster
juju add-unit neutron-api
juju set neutron-api vip=<VIP FOR ACCESS>
juju add-relation neutron-hacluster neutron-api

HA/Clustering

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 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 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.

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.

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.

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

Restrictions

This charm only support deployment with OpenStack Icehouse or better.

Internal DNS for Cloud Guests

The charm supports enabling internal DNS resolution for cloud guests in
accordance with the OpenStack DNS integration guide. To enable internal
DNS resolution, the 'enable-ml2-dns' option must be set to True. When
enabled, the domain name specified in the 'dns-domain' will be advertised
as the nameserver search path by the dhcp agents.

The Nova compute service will leverage this functionality when enabled.
When ports are allocated by the compute service, the dns_name of the port
is populated with a DNS sanitized version of the instance's display name.
The Neutron DHCP agents will then create host entries in the dnsmasq's
configuration files matching the dns_name of the port to the IP address
associated with the port.

Note that the DNS nameserver provided to the instance by the DHCP agent
depends on the tenant's network setup. The Neutron DHCP agent only advertises
itself as a nameserver when the Neutron subnet does not have nameservers
configured. If additional nameservers are needed and internal DNS is desired,
then the IP address of the DHCP port should be added to the subnet's
list of configured nameservers.

For more information refer to the OpenStack documentation on
DNS Integration.

Network Space support

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.

API endpoints can be bound to distinct network spaces supporting the
network 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:

juju deploy neutron-api --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:

neutron-api:
  charm: cs:xenial/neutron-api
  num_units: 1
  bindings:
    public: public-space
    admin: admin-space
    internal: internal-space
    shared-db: internal-space

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.

Additional Middleware Requests by Neutron Plugin Charms

Some neutron plugins may require additional middleware to be added
to api-paste.ini. In order to support that a subordinate may pass
extra_middleware via the neutron-plugin-api-subordinate relation.

Relation data to be set by subordinates:
{'extra_middleware': [{
'type': 'middleware_type',
'name': 'middleware_name',
'config': {
'setting_1': 'value_1',
'setting_2': 'value_2'}}]}

It would not be correct to do that from your own plugin as this
requires the neutron-api service restart which should be handled in
this charm.

The developer guide for Neutron contains a description of the startup
process which makes it clear that api-paste.ini is parsed only once
in neutron-api's lifetime (see the "WSGI Application" section):

https://git.openstack.org/cgit/openstack/neutron/tree/doc/source/devref/api_layer.rst#n49

For the api-paste.ini format in general, please consult PasteDeploy
repository docs/index.txt, "Config Format" section:
https://bitbucket.org/ianb/pastedeploy

Classes in loadwsgi.py contain config_prefixes that can be used for
middleware types - these are the prefixes the charm code validates
passed data against:

https://bitbucket.org/ianb/pastedeploy/src/4b27133a2a7db58b213ae55b580039c11d2055c0/paste/deploy/loadwsgi.py?at=default&fileviewer=file-view-default

Configuration

ssl_key
(string)
                            SSL key to use with certificate specified as ssl_cert.
                        
haproxy-server-timeout
(int)
                            Server timeout configuration in ms for haproxy, used in HA
configurations. If not provided, default value of 30000ms is used.

                        
haproxy-queue-timeout
(int)
                            Queue timeout configuration in ms for haproxy, used in HA
configurations. If not provided, default value of 5000ms is used.

                        
enable-dvr
(boolean)
                            Enable Distributed Virtual Routing (juno and above).

                        
config-flags
(string)
                            Comma-separated list of key=value config flags. These values will be
placed in the neutron.conf [DEFAULT] section.
.
WARNING: this is not the recommended way to configure the underlying
services that this charm installs and is used at the user's own risk.
This option is mainly provided as a stop-gap for users that either
want to test the effect of modifying some config or who have found
a critical bug in the way the charm has configured their services
and need it fixed immediately. We ask that whenever this is used,
that the user consider opening a bug on this charm at
http://bugs.launchpad.net/charm-neutron-api providing an explanation of
why the config was needed so that we may consider it for inclusion as a
natively supported config in the the charm.

                        
vsd-auth-resource
(string)
                            Nuage VSD authentication resource
                        
/me
mem-password
(string)
                            The Midokura Enterprise MidoNet password credentials to access the
repository.

                        
neutron-external-network
(string)
                            Name of the external network for floating IP addresses provided by
Neutron.

                        
ext_net
neutron-plugin
(string)
                            Neutron plugin to use for network management; supports
.
  ovs - OpenvSwitch Plugin
  vsp - Nuage Networks VSP
  nsx - VMWare NSX
  Calico - Project Calico Networking
  midonet - MidoNet
  plumgrid - PLUMgrid
.

                        
ovs
ha-mcastport
(int)
                            Default multicast port number that will be used to communicate between
HA Cluster nodes.

                        
5424
ha-bindiface
(string)
                            Default network interface on which HA cluster will bind to communication
with the other members of the HA Cluster.

                        
eth0
l2-population
(boolean)
                            Populate the forwarding tables of virtual switches (LinuxBridge or OVS),
to decrease broadcast traffics inside the physical networks fabric while
using overlays networks (VXLan, GRE).

                        
True
overlay-network-type
(string)
                            Overlay network types to use, valid options include:
.
  gre
  vxlan
.
Multiple types can be provided - field is space delimited. To disable
overlay networks set to the empty string ''

                        
gre
vsd-auth-ssl
(boolean)
                            SSL authentication of the Nuage VSD Server
                        
True
openstack-origin
(string)
                            Repository from which to install. May be one of the following:
distro (default), ppa:somecustom/ppa, a deb url sources entry,
or a supported Ubuntu Cloud Archive e.g.
.
cloud:<series>-<openstack-release>
cloud:<series>-<openstack-release>/updates
cloud:<series>-<openstack-release>/staging
cloud:<series>-<openstack-release>/proposed
.
See https://wiki.ubuntu.com/OpenStack/CloudArchive for info on which
cloud archives are available and supported.
.
NOTE: updating this setting to a source that is known to provide
a later version of OpenStack will trigger a software upgrade unless
action-managed-upgrade is set to True.

                        
distro
quota-floatingip
(int)
                            Number of floating IPs allowed per tenant. A negative value means
unlimited.

                        
50
extra-key
(string)
                            Optional key for archive containing additional packages.
                        
quota-member
(int)
                            Number of pool members allowed per tenant. A negative value means
unlimited. The default is unlimited because a member is not a real
resource consumer on Openstack. However, on back-end, a member is a
resource consumer and that is the reason why quota is possible.

                        
-1
os-internal-network
(string)
                            The IP address and netmask of the OpenStack Internal network (e.g.
192.168.0.0/24)
.
This network will be used for internal endpoints.

                        
network-device-mtu
(int)
                            The MTU size for interfaces managed by neutron. If unset or set to
0, no value will be applied. This value will be provided to
neutron-plugin-api relations.
.
NOTE: This option is deprecated and will be removed in Newton.
Please use the system-wide global-physnet-mtu setting which the
agents will take into account when wiring VIFs.

                        
nagios_context
(string)
                            Used by the nrpe-external-master subordinate charm. A string that will
be prepended to instance name to set the host name in nagios. So for
instance the hostname would be something like 'juju-myservice-0'. If
you are running multiple environments with the same services in them
this allows you to differentiate between them.

                        
juju
mem-username
(string)
                            The Midokura Enterprise MidoNet username credentials to access the
repository.

                        
rabbit-vhost
(string)
                            Rabbitmq vhost name.
                        
openstack
dns-domain
(string)
                            Specifies the dns domain name that should be used for building instance
hostnames. An empty option or the value of 'openstacklocal' will cause
the dhcp agents to broadcast the default domain of openstacklocal and
will not enable internal cloud dns resolution. This value should end
with a '.', e.g. 'cloud.example.org.'.

                        
openstack.example.
enable-sriov
(boolean)
                            Enable SR-IOV networking support across Neutron and Nova.

                        
debug
(boolean)
                            Enable debug logging.
                        
haproxy-connect-timeout
(int)
                            Connect timeout configuration in ms for haproxy, used in HA
configurations. If not provided, default value of 5000ms is used.

                        
vip_iface
(string)
                            Default network interface to use for HA vip when it cannot be
automatically determined.

                        
eth0
default-tenant-network-type
(string)
                            The default type for a tenant network e.g. vxlan, vlan, gre etc

                        
nsx-controllers
(string)
                            Space delimited addresses of NSX controllers
                        
max-l3-agents-per-router
(int)
                            Maximum number of l3 agents to host a router. Only used when enable-l3ha
is True.

                        
2
global-physnet-mtu
(int)
                            MTU of the underlying physical network. Neutron uses this value to
calculate MTU for all virtual network components. For flat and
VLAN networks, neutron uses this value without modification. For
overlay networks such as VXLAN, neutron automatically subtracts
the overlay protocol overhead from this value.
.
NOTE: This options is available starting from Mitaka release.

                        
1500
nuage-packages
(string)
                            Its [nuage-openstack-neutron nuagenetlib] for Nuage VSP >=3.2R4 & KILO
and [nuage-neutron python-nuagenetlib] of Nuage VSP <=3.0 & JUNO

                        
nuage-openstack-neutron nuagenetlib
vsd-cms-name
(string)
                            This is required only for 3.2 R4 and above releases of Nuage and Kilo.
Please give Maas env id so that it is unique per openstack cluster. This
name is used to create th CMS ID on Nuage-VSD which should be unique per
OSP cluster. Your Deployment will fail if this config is not provided.

                        
calico-origin
(string)
                            Repository from which to install Calico packages. If set, must be
a PPA URL, of the form ppa:somecustom/ppa. Changing this value
after installation will force an immediate software upgrade.

                        
nsx-tz-uuid
(string)
                            This is uuid of the default NSX Transport zone that will be used for
creating tunneled isolated Neutron networks. It needs to be created in
NSX before starting Neutron with the nsx plugin.

                        
enable-ml2-port-security
(boolean)
                            Enable port security extension for ML2 plugin (>= kilo).
                        
prefer-ipv6
(boolean)
                            If True enables IPv6 support. The charm will expect network interfaces
to be configured with an IPv6 address. If set to False (default) IPv4
is expected.
.
NOTE: these charms do not currently support IPv6 privacy extension. In
order for this charm to function correctly, the privacy extension must be
disabled and a non-temporary address must be configured/available on
your network interface.

                        
os-admin-network
(string)
                            The IP address and netmask of the OpenStack Admin network (e.g.
192.168.0.0/24)
.
This network will be used for admin endpoints.

                        
nsx-password
(string)
                            Password to connect to NSX controllers with
                        
admin
vlan-ranges
(string)
                            Space-delimited list of <physical_network>:<vlan_min>:<vlan_max> or
<physical_network> specifying physical_network names usable for VLAN
provider and tenant networks, as well as ranges of VLAN tags on each
available for allocation to tenant networks.

                        
physnet1:1000:2000
vni-ranges
(string)
                            Space-delimited list of <vxlan_min>:<vxlan_max> for VXLAN provider.

                        
1001:2000
openstack-origin-git
(string)
                            Specifies a default OpenStack release name, or a YAML dictionary
listing the git repositories to install from.
.
The default Openstack release name may be one of the following, where
the corresponding OpenStack github branch will be used:
  * liberty
  * mitaka
  * newton
  * master
.
The YAML must minimally include the following repositories, and may
also include repositories for other dependencies:
  repositories:
  - {name: requirements,
     repository: 'git://github.com/openstack/requirements',
     branch: master}
  - {name: networking-hyperv,
     repository: 'git://github.com/openstack/networking-hyperv',
     branch: master}
  - {name: neutron-fwaas,
     repository: 'git://github.com/openstack/neutron-fwaas',
     branch: master}
  - {name: neutron-lbaas,
     repository: 'git://github.com/openstack/neutron-lbaas',
     branch: master}
  - {name: neutron-vpnaas,
     repository: 'git://github.com/openstack/neutron-vpnaas',
     branch: master}
  - {name: neutron,
     repository: 'git://github.com/openstack/neutron',
     branch: master}
  release: master

                        
quota-router
(int)
                            Number of routers allowed per tenant. A negative value means unlimited.

                        
10
quota-pool
(int)
                            Number of pools allowed per tenant. A negative value means unlimited.

                        
10
os-admin-hostname
(string)
                            The hostname or address of the admin endpoints created for neutron-api
in the keystone identity provider.
.
This value will be used for admin endpoints. For example, an
os-admin-hostname set to 'neutron-api.admin.example.com' with ssl enabled
will create a internal endpoint for neutron-api:
.
https://neutron-api.admin.example.com:9696/

                        
plumgrid-username
(string)
                            Username to access PLUMgrid Director
                        
plumgrid
database-user
(string)
                            Username for Neutron database access (if enabled).
                        
neutron
verbose
(boolean)
                            Enable verbose logging.
                        
path-mtu
(int)
                            Maximum size of an IP packet (MTU) that can traverse the
underlying physical network infrastructure without fragmentation
when using an overlay/tunnel protocol. This option allows
specifying a physical network MTU value that differs from the
default global-physnet-mtu value.

                        
vip
(string)
                            Virtual IP(s) to use to front API services in HA configuration.
.
If multiple networks are being used, a VIP should be provided for each
network, separated by spaces.

                        
use-syslog
(boolean)
                            Setting this to True will allow supporting services to log to syslog.

                        
quota-security-group-rule
(int)
                            Number of security group rules allowed per tenant. A negative value means
unlimited

                        
100
vsd-cms-id
(string)
                            CMS ID is used as an authentication token from VSD to CMS.
This value is being generated via nuage scripts and can be set pre/post
deployment.

                        
vsd-base-uri
(string)
                            Nuage VSD API endpoint URI
                        
/nuage/api/v3_0
midonet-origin
(string)
                            'mem-1.8', 'mem-1.9',
'midonet-2015.06'
.
NOTE: updating this setting to a source that is known to provide a later
      version of MidoNet (do not change between MEM and MidoNet) will
      trigger a software upgrade.

                        
midonet-2015.06
os-public-network
(string)
                            The IP address and netmask of the OpenStack Public network (e.g.
192.168.0.0/24)
.
This network will be used for public endpoints.

                        
plumgrid-virtual-ip
(string)
                            IP address of PLUMgrid Director
                        
extra-source
(string)
                            Optional source for archive containing additional packages.
                        
quota-security-group
(int)
                            Number of security groups allowed per tenant. A negative value means
unlimited.

                        
10
vsd-auth
(string)
                            Username Password to connect to Nuage VSD Server
                        
csproot:csproot
os-public-hostname
(string)
                            The hostname or address of the public endpoints created for neutron-api
in the keystone identity provider.
.
This value will be used for public endpoints. For example, an
os-public-hostname set to 'neutron-api.example.com' with ssl enabled
will create the following endpoint for neutron-api:
.
https://neutron-api.example.com:9696/

                        
action-managed-upgrade
(boolean)
                            If True enables openstack upgrades for this charm via juju actions.
You will still need to set openstack-origin to the new repository but
instead of an upgrade running automatically across all units, it will
wait for you to execute the openstack-upgrade action for this charm on
each unit. If False it will revert to existing behavior of upgrading
all units on config change.

                        
nsx-l3-uuid
(string)
                            This is uuid of the default NSX L3 Gateway Service.
                        
manage-neutron-plugin-legacy-mode
(boolean)
                            If True neutron-server will install neutron packages for the plugin
configured.

                        
True
dns-ha
(boolean)
                            Use DNS HA with MAAS 2.0. Note if this is set do not set vip* settings.

                        
worker-multiplier
(float)
                            The CPU core multiplier to use when configuring worker processes for
this service. By default, the number of workers for each daemon is set
to twice the number of CPU cores a service unit has. When deployed in a
LXD container, this default value will be capped to 4 workers unless this
configuration option is set.

                        
harden
(string)
                            Apply system hardening. Supports a space-delimited list of modules
to run. Supported modules currently include os, ssh, apache and mysql.

                        
region
(string)
                            OpenStack region name.
                        
RegionOne
min-l3-agents-per-router
(int)
                            Minimum number of l3 agents to host a router. Only used when enable-l3ha
is True.

                        
2
quota-port
(int)
                            Number of ports allowed per tenant. A negative value means unlimited.

                        
50
vsd-netpart-name
(string)
                            Name of the Organization or Enterprise to create in Nuage VSD
                        
juju-enterprise
nsx-username
(string)
                            Username to connect to NSX controllers with
                        
admin
quota-health-monitors
(int)
                            Number of health monitors allowed per tenant. A negative value means
unlimited.
The default is unlimited because a health monitor is not a real resource
consumer on Openstack. However, on back-end, a member is a resource
consumer and that is the reason why quota is possible.

                        
-1
flat-network-providers
(string)
                            Space-delimited list of Neutron flat network providers.

                        
enable-l3ha
(boolean)
                            Enable L3 HA (juno and above).

                        
dhcp-agents-per-network
(int)
                            The number of dhcp agents to be deployed per network. Note that if the
Calico plugin is being used, this option has no effect.

                        
1
enable-ml2-dns
(boolean)
                            Enables the Neutron DNS extension driver (>= mitaka). When enabled,
ports attached to Nova instances will have DNS names assigned based
on the instance name.

                        
rabbit-user
(string)
                            Username used to access rabbitmq queue.
                        
neutron
vsd-organization
(string)
                            Name of the organization in Nuage VSD
                        
csp
quota-network
(int)
                            Number of networks allowed per tenant. A negative value means unlimited.

                        
10
nagios_servicegroups
(string)
                            A comma-separated list of nagios servicegroups. If left empty, the
nagios_context will be used as the servicegroup

                        
haproxy-client-timeout
(int)
                            Client timeout configuration in ms for haproxy, used in HA
configurations. If not provided, default value of 30000ms is used.

                        
quota-subnet
(int)
                            Number of subnets allowed per tenant. A negative value means unlimited.

                        
10
use-internal-endpoints
(boolean)
                            Openstack mostly defaults to using public endpoints for internal
communication between services. If set to True this option will
configure services to use internal endpoints where possible.

                        
quota-vip
(int)
                            Number of vips allowed per tenant. A negative value means unlimited.

                        
10
plumgrid-password
(string)
                            Password to access PLUMgrid Director
                        
plumgrid
ssl_cert
(string)
                            SSL certificate to install and use for API ports. Setting this value
and ssl_key will enable reverse proxying, point Neutron's entry in the
Keystone catalog to use https, and override any certificate and key
issued by Keystone (if it is configured to do so).

                        
database
(string)
                            Database name for Neutron (if enabled).
                        
neutron
vip_cidr
(int)
                            Default CIDR netmask to use for HA vip when it cannot be automatically
determined.

                        
24
ssl_ca
(string)
                            SSL CA to use with the certificate and key provided - this is only
required if you are providing a privately signed ssl_cert and ssl_key.

                        
os-internal-hostname
(string)
                            The hostname or address of the internal endpoints created for neutron-api
in the keystone identity provider.
.
This value will be used for internal endpoints. For example, an
os-internal-hostname set to 'neutron-api.internal.example.com' with ssl
enabled will create a internal endpoint for neutron-api:
.
https://neutron-api.internal.example.com:9696/

                        
vsd-server
(string)
                            Nuage VSD Server
                        
neutron-security-groups
(boolean)
                            Use Neutron for security group management.