1Using OpenStack Network
2=======================
3
4Before working with the Network service, you'll need to create a connection
5to your OpenStack cloud by following the :doc:`connect` user guide. This will
6provide you with the ``conn`` variable used in the examples below.
7
8.. contents:: Table of Contents
9   :local:
10
11The primary resource of the Network service is the network.
12
13List Networks
14-------------
15
16A **network** is an isolated `Layer 2 <https://en.wikipedia.org/wiki/Data_link_layer>`_
17networking segment. There are two types of networks, project and provider
18networks. Project networks are fully isolated and are not shared with other
19projects. Provider networks map to existing physical networks in the data
20center and provide external network access for servers. Only an OpenStack
21administrator can create provider networks. Networks can be connected via
22routers.
23
24.. literalinclude:: ../examples/network/list.py
25   :pyobject: list_networks
26
27Full example: `network resource list`_
28
29List Subnets
30------------
31
32A **subnet** is a block of IP addresses and associated configuration state.
33Subnets are used to allocate IP addresses when new ports are created on a
34network.
35
36.. literalinclude:: ../examples/network/list.py
37   :pyobject: list_subnets
38
39Full example: `network resource list`_
40
41List Ports
42----------
43
44A **port** is a connection point for attaching a single device, such as the
45`NIC <https://en.wikipedia.org/wiki/Network_interface_controller>`_
46of a server, to a network. The port also describes the associated network
47configuration, such as the `MAC <https://en.wikipedia.org/wiki/Media_access_control>`_
48and IP addresses to be used on that port.
49
50.. literalinclude:: ../examples/network/list.py
51   :pyobject: list_ports
52
53Full example: `network resource list`_
54
55List Security Groups
56--------------------
57
58A **security group** acts as a virtual firewall for servers. It is a container
59for security group rules which specify the type of network traffic and
60direction that is allowed to pass through a port.
61
62.. literalinclude:: ../examples/network/list.py
63   :pyobject: list_security_groups
64
65Full example: `network resource list`_
66
67List Routers
68------------
69
70A **router** is a logical component that forwards data packets between
71networks. It also provides
72`Layer 3 <https://en.wikipedia.org/wiki/Network_layer>`_ and
73`NAT <https://en.wikipedia.org/wiki/Network_address_translation>`_
74forwarding to provide external network access for servers on project networks.
75
76.. literalinclude:: ../examples/network/list.py
77   :pyobject: list_routers
78
79Full example: `network resource list`_
80
81List Network Agents
82-------------------
83
84A **network agent** is a plugin that handles various tasks used to
85implement virtual networks.  These agents include neutron-dhcp-agent,
86neutron-l3-agent, neutron-metering-agent, and neutron-lbaas-agent,
87among others.
88
89.. literalinclude:: ../examples/network/list.py
90   :pyobject: list_network_agents
91
92Full example: `network resource list`_
93
94Create Network
95--------------
96
97Create a project network and subnet. This network can be used when creating
98a server and allows the server to communicate with others servers on the
99same project network.
100
101.. literalinclude:: ../examples/network/create.py
102   :pyobject: create_network
103
104Full example: `network resource create`_
105
106Open a Port
107-----------
108
109When creating a security group for a network, you will need to open certain
110ports to allow communication via them. For example, you may need to enable
111HTTPS access on port 443.
112
113.. literalinclude:: ../examples/network/security_group_rules.py
114   :pyobject: open_port
115
116Full example: `network security group create`_
117
118Accept Pings
119------------
120
121In order to ping a machine on your network within a security group,
122you will need to create a rule to allow inbound ICMP packets.
123
124.. literalinclude:: ../examples/network/security_group_rules.py
125   :pyobject: allow_ping
126
127Full example: `network security group create`_
128
129Delete Network
130--------------
131
132Delete a project network and its subnets.
133
134.. literalinclude:: ../examples/network/delete.py
135   :pyobject: delete_network
136
137Full example: `network resource delete`_
138
139.. _network resource create: https://opendev.org/openstack/openstacksdk/src/branch/master/examples/network/create.py
140.. _network resource delete: https://opendev.org/openstack/openstacksdk/src/branch/master/examples/network/delete.py
141.. _network resource list: https://opendev.org/openstack/openstacksdk/src/branch/master/examples/network/list.py
142.. _network security group create: https://opendev.org/openstack/openstacksdk/src/branch/master/examples/network/security_group_rules.py
143