How Calico Interprets Neutron API Calls

When running in an OpenStack deployment, Calico receives and interprets
certain Neutron API actions, in order to program those actions down into
the network. However, because Calico is substantially simpler than much
of what Neutron generally allows (see External Connectivity) and because it’s a purely layer 3 model (see The Calico Datapath, not all Neutron API calls will have the same effect as they would with other backends.

This document will go into detail on the full range of Neutron API
calls, and will discuss the effect they have on the network. It uses the
Networking API v2.0
document from OpenStack as a basis for listing the various objects that
the Neutron API uses: see that document for more information about what
Neutron expects more generally.

Networks

Networks are the basic networking concept in Neutron. A Neutron network
is considered to be roughly equivalent to a physical network in terms of
function: it defines a single layer 2 connectivity graph.

In vanilla Neutron, these can map to the underlay network in various
ways, either by being encapsulated over it or by being directly mapped
to it.

Generally speaking, Neutron networks can be created by all tenants. The
administrator tenant will generally create some public Neutron networks
that map to the underlay physical network directly for providing
floating IPs: other tenants will create their own private Neutron
networks as necessary.

In Calico, because all traffic is L3 and routed, the role of Neutron
network as L2 connectivity domain is not helpful. Therefore, in Calico,
Neutron networks are simply containers for subnets. Best practices for
operators configuring Neutron networks in Calico deployments can be
found in this document.

It is not useful for non-administrator tenants to create their own
Neutron networks. Although Calico will allow non-administrator tenants
to create Neutron networks, generally speaking administrators should use
Neutron quotas to prevent non-administrator tenants from doing this.

Network creation events on the API are no-op events in Calico: a
positive (2XX) response will be sent but no programming will actually
occur.

Extended Attributes: Provider Networks

Neutron Provider networks are not used in Calico deployments. Setting
provider network extended attributes will have no effect. See
this document to understand why Neutron provider networks are not
needed.

Subnets

Neutron subnets are child objects of Neutron networks. In vanilla
Neutron, a subnet is a collection of IP addresses and other network
configuration (e.g. DNS servers) that is associated with a single
Neutron network. A single Neutron network may have multiple Neutron
subnets associated with it. Each Neutron subnet represents either an
IPv4 or IPv6 block of addresses.

Best practices for configuring Neutron subnets in Calico deployments can
be found here.

In Calico, these roles for the Neutron subnet are preserved in their
entirety. All properties associated with these Neutron subnets are
preserved and remain meaningful except for:

host_routes

These have no effect, as the compute nodes will route traffic
immediately after it egresses the VM.

Ports

In vanilla Neutron, a port represents a connection from a VM to a single
layer 2 Neutron network. Obviously, the meaning of this object changes
in a Calico deployment: instead, a port is a connection from a VM to the
shared layer 3 network that Calico builds in Neutron.

All properties on a port work as normal, except for the following:

network_id

The network ID still controls which Neutron network the port is
attached to, and therefore still controls which Neutron subnets it
will be placed in. However, as per the note above,
the Neutron network that a port is placed in does not affect which
machines in the deployment it can contact.

Extended Attributes: Port Binding Attributes

The binding:host-id attribute works as normal. The following notes
apply to the other attributes:

binding:profile

This is unused in Calico.

binding:vnic_type

This field, if used, must be set to normal. If set to any
other value, Calico will not correctly function!

Quotas

Neutron quotas function unchanged.

In most deployments we recommend setting non-administrator tenant quotas
for almost all Neutron objects to zero. For more information, see here.

Security Groups

Security groups in vanilla OpenStack provide packet filtering processing
to individual ports. They can be used to limit the traffic a port may
issue.

In Calico, security groups have all the same function. Additionally,
they serve to provide the connectivity-limiting function that in vanilla
OpenStack is provided by Neutron networks.

All the attributes of security groups remain unchanged in Calico.

Layer 3 Routing: Routers and Floating IPs

Layer 3 routing objects are divided into two categories: routers and
floating IPs. Neither of these objects are supported by Calico: they
simply aren’t required. For more information, see this document.

Any attempt to create these objects will fail, as Calico does not set up
any Neutron L3 Agents.

LBaaS (Load Balancer as a Service)

Load Balancer as a Service does not function in a Calico network. Any
attempt to create one will fail.

NOTE

It is possible that in a future version of Calico LBaaS may be

functional. Watch this space.

Horizon

Horizon makes many provisioning actions available that mirror options on
the Neutron API. This section lists them, and indicates whether they can
be used or not, and any subtleties that might be present in them.

Much of the detail has been left out of this section, and is instead
present in the relevant Neutron API sections above: please consult them
for more.

Section: Project

Tab: Compute -> Instances

When launching instances, remember that security groups are used to
determine reachability, not networks. Choose networks based on whether
you need an external or an internal IP address, and choose security
groups based on the machines you’d like to talk to in the cloud. See
here for more.

Tab: Compute -> Access & Security

As noted above, tenants should ensure they configure their security
groups to set up their connectivity appropriately.

Tab: Network -> Network Topology

For the ‘Create Network’ button, see the Networks section.
For the ‘Create Router’ button, see the Layer 3 Routing section.

Tab: Network -> Networks

Tab: Network -> Routers

Tenants should be prevented from creating routers, as they serve no
purpose in a Calico network. See Layer 3 Routing for more.

Section: Admin

Tab: System Panel -> Networks

In the course of general operation administrators are not expected to
make changes to their networking configuration. However, for initial
network setup, this panel may be used to make changes. See
this document for details on how to achieve this setup.

Tab: System Panel -> Routers

Administrators should not create routers, as they serve no purpose in a
Calico network. See Layer 3 Routing for more.