Browse Source

Delete and move outdated docs

This is one part of the process of organizing the Kuryr docs
across Kuryr, Kuryr-Libnetwork, and Kuryr-Kubernetes. This
commit in particular deletes files that are being moved to
their appropriate directories and one file that is outdated.

Change-Id: I60881c2b22f7b3413e9a2223b818f57eaf2af82d
Depends-On: If0e23ffe10f798d2f9f5b37e1b996bd069715721
Darla Ahlert 2 years ago
parent
commit
d379968d79

+ 0
- 3
doc/source/devref/index.rst View File

@@ -35,10 +35,7 @@ Programming HowTos and Tutorials
35 35
     :maxdepth: 4
36 36
 
37 37
     goals_and_use_cases
38
-    libnetwork_remote_driver_design
39 38
     kuryr_mitaka_milestone
40
-    k8s_api_watcher_design
41
-
42 39
 
43 40
 Indices and tables
44 41
 ------------------

+ 0
- 1041
doc/source/devref/k8s_api_watcher_design.rst
File diff suppressed because it is too large
View File


+ 0
- 398
doc/source/devref/libnetwork_remote_driver_design.rst View File

@@ -1,398 +0,0 @@
1
-=======================================
2
-Libnetwork Remote Network Driver Design
3
-=======================================
4
-
5
-What is Kuryr
6
--------------
7
-
8
-Kuryr implements a `libnetwork remote network driver <https://github.com/docker/libnetwork/blob/master/docs/remote.md>`_
9
-and maps its calls to OpenStack `Neutron <https://wiki.openstack.org/wiki/Neutron>`_.
10
-It works as a translator between libnetwork's `Container Network Model <https://github.com/docker/libnetwork/blob/master/docs/design.md#the-container-network-model>`_ (CNM) and `Neutron's networking model <https://wiki.openstack.org/wiki/Neutron/APIv2-specification>`_.
11
-Kuryr also acts as a `libnetwork IPAM driver <https://github.com/docker/libnetwork/blob/master/docs/ipam.md>`_.
12
-
13
-Goal
14
-~~~~
15
-
16
-Through Kuryr any Neutron plugin can be used as libnetwork backend with no
17
-additional effort. Neutron APIs are vendor agnostic and thus all Neutron
18
-plugins will have the capability of providing the networking backend of Docker
19
-for a similar small plugging snippet as they have in nova.
20
-
21
-Kuryr also takes care of binding one of a veth pair to a network interface on
22
-the host, e.g., Linux bridge, Open vSwitch datapath and so on.
23
-
24
-
25
-Kuryr Workflow - Host Networking
26
---------------------------------
27
-Kuryr resides in each host that runs Docker containers and serves `APIs <https://github.com/docker/libnetwork/blob/master/docs/design.md#api>`_
28
-required for the libnetwork remote network driver. It is planned to use the
29
-`Adding tags to resources <https://review.openstack.org/#/c/216021/>`_
30
-new Neutron feature by Kuryr, to map between
31
-Neutron resource Id's and Docker Id's (UUID's)
32
-
33
-1. libnetwork discovers Kuryr via `plugin discovery mechanism <https://github.com/docker/docker/blob/master/docs/extend/plugin_api.md#plugin-discovery>`_ *before the first request is made*
34
-
35
-   - During this process libnetwork makes a HTTP POST call on
36
-     ``/Plugin.Activate`` and examines the driver type, which defaults to
37
-     ``"NetworkDriver"`` and ``"IpamDriver"``
38
-   - libnetwork also calls the following two API endpoints
39
-
40
-     1. ``/NetworkDriver.GetCapabilities`` to obtain the capability of Kuryr
41
-        which defaults to ``"local"``
42
-     2. ``/IpamDriver.GetDefaultAddressSpcaces`` to get the default address
43
-        spaces used for the IPAM
44
-
45
-2. libnetwork registers Kuryr as a remote driver
46
-
47
-3. A user makes requests against libnetwork with the network driver specifier for Kuryr
48
-
49
-   - i.e., ``--driver=kuryr`` or ``-d kuryr`` **and** ``--ipam-driver=kuryr``
50
-     for the Docker CLI
51
-
52
-4. libnetwork makes API calls against Kuryr
53
-
54
-5. Kuryr receives the requests and calls Neutron APIs with `Neutron client <http://docs.openstack.org/developer/python-neutronclient/>`_
55
-
56
-6. Kuryr receives the responses from Neutron and compose the responses for
57
-   libnetwork
58
-
59
-7. Kuryr returns the responses to libnetwork
60
-
61
-8. libnetwork stores the returned information to its key/value datastore
62
-   backend
63
-
64
-   - the key/value datastore is abstracted by `libkv <https://github.com/docker/libkv>`_
65
-
66
-
67
-Libnetwork User Workflow (with Kuryr as remote network driver) - Host Networking
68
----------------------------------------------------------------------------------
69
-1. A user creates a network ``foo`` with the subnet information::
70
-
71
-       $ sudo docker network create --driver=kuryr --ipam-driver=kuryr \
72
-         --subnet 10.0.0.0/16 --gateway 10.0.0.1 --ip-range 10.0.0.0/24 foo
73
-       286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364
74
-
75
-   This makes a HTTP POST call on ``/IpamDriver.RequestPool`` with the following
76
-   JSON data::
77
-
78
-       {
79
-           "AddressSpace": "global_scope",
80
-           "Pool": "10.0.0.0/16",
81
-           "SubPool": "10.0.0.0/24",
82
-           "Options": {},
83
-           "V6": false
84
-       }
85
-
86
-   The value of ``SubPool`` comes from the value specified in ``--ip-range``
87
-   option in the command above and value of ``AddressSpace`` will be ``global_scope`` or ``local_scope`` depending on value of ``capability_scope`` configuration option. Kuryr creates a subnetpool, and then returns
88
-   the following response::
89
-
90
-       {
91
-           "PoolID": "941f790073c3a2c70099ea527ee3a6205e037e84749f2c6e8a5287d9c62fd376",
92
-           "Pool": "10.0.0.0/24",
93
-       }
94
-
95
-   If the ``--gateway`` was specified like the command above, another HTTP POST
96
-   call against ``/IpamDriver.RequestAddress`` follows with the JSON data below::
97
-
98
-       {
99
-           "Address": "10.0.0.1",
100
-           "PoolID": "941f790073c3a2c70099ea527ee3a6205e037e84749f2c6e8a5287d9c62fd376",
101
-           "Options": {"RequestAddressType": "com.docker.network.gateway"},
102
-       }
103
-
104
-   As the IPAM driver Kuryr allocates a requested IP address and returns the
105
-   following response::
106
-
107
-       {
108
-           "Address": "10.0.0.1/24",
109
-           "Data": {}
110
-       }
111
-
112
-   Finally a HTTP POST call on ``/NetworkDriver.CreateNetwork`` with the
113
-   following JSON data::
114
-
115
-        {
116
-            "NetworkID": "286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364",
117
-            "IPv4Data": [{
118
-                "Pool": "10.0.0.0/24",
119
-                "Gateway": "10.0.0.1/24",
120
-                "AddressSpace": ""
121
-            }],
122
-            "IPv6Data": [],
123
-            "Options": {"com.docker.network.enable_ipv6", false, "com.docker.network.generic": {}}
124
-        }
125
-
126
-   The Kuryr remote network driver will then generate a Neutron API request to
127
-   create subnet with pool cidr and an underlying Neutron network. When the
128
-   Neutron subnet and network has been created, the Kuryr remote network driver
129
-   will generate an empty success response to the docker daemon. Kuryr tags the
130
-   Neutron network with the NetworkID from docker.
131
-
132
-2. A user launches a container against network ``foo``::
133
-
134
-       $ sudo docker run --net=foo -itd --name=container1 busybox
135
-       78c0458ba00f836f609113dd369b5769527f55bb62b5680d03aa1329eb416703
136
-
137
-   This makes a HTTP POST call on ``/IpamDriver.RequestAddress`` with the
138
-   following JSON data::
139
-
140
-        {
141
-            "Address": "",
142
-            "PoolID": "941f790073c3a2c70099ea527ee3a6205e037e84749f2c6e8a5287d9c62fd376",
143
-            "Options": {},
144
-        }
145
-
146
-   The IPAM driver Kuryr sends a port creation request to neutron and returns the following response with neutron provided ip address::
147
-
148
-       {
149
-           "Address": "10.0.0.2/24",
150
-           "Data": {}
151
-       }
152
-
153
-
154
-   Then another HTTP POST call on ``/NetworkDriver.CreateEndpoint`` with the
155
-   following JSON data is made::
156
-
157
-        {
158
-            "NetworkID": "286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364",
159
-            "Interface": {
160
-                "AddressIPv6": "",
161
-                "MacAddress": "",
162
-                "Address": "10.0.0.2/24"
163
-            },
164
-            "Options": {
165
-                "com.docker.network.endpoint.exposedports": [],
166
-                "com.docker.network.portmap": []
167
-            },
168
-            "EndpointID": "edb23d36d77336d780fe25cdb5cf0411e5edd91b0777982b4b28ad125e28a4dd"
169
-        }
170
-
171
-   The Kuryr remote network driver then generates a Neutron API request to
172
-   fetch port with the matching fields for interface in the request. Kuryr
173
-   then updates this port's name, tagging it with endpoint ID.
174
-
175
-   Following steps are taken:
176
-
177
-   1) On the endpoint creation Kuryr examines if there's a Port with CIDR
178
-      that corresponds to Address or AddressIPv6 requested.
179
-   2) If there's a Port, Kuryr tries to reuse it without creating a new
180
-      Port. Otherwise it creates a new one with the given address.
181
-   3) Kuryr tags the Neutron port with EndpointID.
182
-
183
-   When the Neutron port has been updated, the Kuryr remote driver will
184
-   generate a response to the docker daemon in following form:
185
-   (https://github.com/docker/libnetwork/blob/master/docs/remote.md#create-endpoint)::
186
-
187
-        {
188
-            "Interface": {"MacAddress": "08:22:e0:a8:7d:db"}
189
-        }
190
-
191
-
192
-   On receiving success response, libnetwork makes a HTTP POST call on ``/NetworkDriver.Join`` with
193
-   the following JSON data::
194
-
195
-        {
196
-            "NetworkID": "286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364",
197
-            "SandboxKey": "/var/run/docker/netns/052b9aa6e9cd",
198
-            "Options": null,
199
-            "EndpointID": "edb23d36d77336d780fe25cdb5cf0411e5edd91b0777982b4b28ad125e28a4dd"
200
-        }
201
-
202
-   Kuryr connects the container to the corresponding neutron network by doing
203
-   the following steps:
204
-
205
-   1) Generate a veth pair.
206
-   2) Connect one end of the veth pair to the container (which is running in a
207
-      namespace that was created by Docker).
208
-   3) Perform a neutron-port-type-dependent VIF-binding to the corresponding
209
-      Neutron port using the VIF binding layer and depending on the specific
210
-      port type.
211
-
212
-   After the VIF-binding is completed, the Kuryr remote network driver
213
-   generates a response to the Docker daemon as specified in the libnetwork
214
-   documentation for a join request.
215
-   (https://github.com/docker/libnetwork/blob/master/docs/remote.md#join)
216
-
217
-3. A user requests information about the network::
218
-
219
-       $ sudo docker network inspect foo
220
-        [
221
-            {
222
-                "Name": "foo",
223
-                "Id": "286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364",
224
-                "Scope": "local",
225
-                "Driver": "kuryr",
226
-                "EnableIPv6": false,
227
-                "IPAM": {
228
-                    "Driver": "kuryr",
229
-                    "Options": {},
230
-                    "Config": [{
231
-                        "Subnet": "10.0.0.0/16",
232
-                        "IPRange": "10.0.0.0/24",
233
-                        "Gateway": "10.0.0.1"
234
-                    }]
235
-                },
236
-                "Internal": false,
237
-                "Containers": {
238
-                    "78c0458ba00f836f609113dd369b5769527f55bb62b5680d03aa1329eb416703": {
239
-                        "endpoint": "edb23d36d77336d780fe25cdb5cf0411e5edd91b0777982b4b28ad125e28a4dd",
240
-                        "mac_address": "02:42:c0:a8:7b:cb",
241
-                        "ipv4_address": "10.0.0.2/24",
242
-                        "ipv6_address": ""
243
-                    }
244
-                },
245
-                "Options": {},
246
-                "Labels": {}
247
-            }
248
-        ]
249
-
250
-
251
-4. A user connects one more container to the network::
252
-
253
-       $ sudo docker network connect foo container2
254
-        d7fcc280916a8b771d2375688b700b036519d92ba2989622627e641bdde6e646
255
-
256
-       $ sudo docker network inspect foo
257
-        [
258
-            {
259
-                "Name": "foo",
260
-                "Id": "286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364",
261
-                "Scope": "local",
262
-                "Driver": "kuryr",
263
-                "EnableIPv6": false,
264
-                "IPAM": {
265
-                    "Driver": "kuryr",
266
-                    "Options": {},
267
-                    "Config": [{
268
-                        "Subnet": "10.0.0.0/16",
269
-                        "IPRange": "10.0.0.0/24",
270
-                        "Gateway": "10.0.0.1"
271
-                    }]
272
-                },
273
-                "Internal": false,
274
-                "Containers": {
275
-                    "78c0458ba00f836f609113dd369b5769527f55bb62b5680d03aa1329eb416703": {
276
-                        "endpoint": "edb23d36d77336d780fe25cdb5cf0411e5edd91b0777982b4b28ad125e28a4dd",
277
-                        "mac_address": "02:42:c0:a8:7b:cb",
278
-                        "ipv4_address": "10.0.0.2/24",
279
-                        "ipv6_address": ""
280
-                    },
281
-                    "d7fcc280916a8b771d2375688b700b036519d92ba2989622627e641bdde6e646": {
282
-                        "endpoint": "a55976bafaad19f2d455c4516fd3450d3c52d9996a98beb4696dc435a63417fc",
283
-                        "mac_address": "02:42:c0:a8:7b:cc",
284
-                        "ipv4_address": "10.0.0.3/24",
285
-                        "ipv6_address": ""
286
-                    }
287
-                },
288
-                "Options": {},
289
-                "Labels": {}
290
-            }
291
-        ]
292
-
293
-
294
-5. A user disconnects a container from the network::
295
-
296
-       $ CID=d7fcc280916a8b771d2375688b700b036519d92ba2989622627e641bdde6e646
297
-       $ sudo docker network disconnect foo $CID
298
-
299
-   This makes a HTTP POST call on ``/NetworkDriver.Leave`` with the following
300
-   JSON data::
301
-
302
-       {
303
-           "NetworkID": "286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364",
304
-           "EndpointID": "a55976bafaad19f2d455c4516fd3450d3c52d9996a98beb4696dc435a63417fc"
305
-       }
306
-
307
-   Kuryr remote network driver will remove the VIF binding between the
308
-   container and the Neutron port, and generate an empty response to the
309
-   Docker daemon.
310
-
311
-   Then libnetwork makes a HTTP POST call on ``/NetworkDriver.DeleteEndpoint`` with the
312
-   following JSON data::
313
-
314
-       {
315
-           "NetworkID": "286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364",
316
-           "EndpointID": "a55976bafaad19f2d455c4516fd3450d3c52d9996a98beb4696dc435a63417fc"
317
-       }
318
-
319
-   Kuryr remote network driver generates a Neutron API request to delete the
320
-   associated Neutron port, in case the relevant port subnet is empty, Kuryr
321
-   also deletes the subnet object using Neutron API and generate an empty
322
-   response to the Docker daemon::
323
-
324
-       {}
325
-
326
-   Finally libnetwork makes a HTTP POST call on ``/IpamDriver.ReleaseAddress``
327
-   with the following JSON data::
328
-
329
-       {
330
-           "Address": "10.0.0.3",
331
-           "PoolID": "941f790073c3a2c70099ea527ee3a6205e037e84749f2c6e8a5287d9c62fd376"
332
-       }
333
-
334
-   Kuryr remote IPAM driver generates a Neutron API request to delete the associated Neutron port.
335
-   As the IPAM driver Kuryr deallocates the IP address and returns the following response::
336
-
337
-       {}
338
-
339
-6. A user deletes the network::
340
-
341
-       $ sudo docker network rm foo
342
-
343
-   This makes a HTTP POST call against ``/NetworkDriver.DeleteNetwork`` with the
344
-   following JSON data::
345
-
346
-       {
347
-           "NetworkID": "286eddb51ebca09339cb17aaec05e48ffe60659ced6f3fc41b020b0eb506d364"
348
-       }
349
-
350
-   Kuryr remote network driver generates a Neutron API request to delete the
351
-   corresponding Neutron network and subnets. When the Neutron network and subnets has been deleted,
352
-   the Kuryr remote network driver  generate an empty response to the docker
353
-   daemon: {}
354
-
355
-   Then another HTTP POST call on ``/IpamDriver.ReleasePool`` with the
356
-   following JSON data is made::
357
-
358
-       {
359
-           "PoolID": "941f790073c3a2c70099ea527ee3a6205e037e84749f2c6e8a5287d9c62fd376"
360
-       }
361
-
362
-   Kuryr delete the corresponding subnetpool and returns the following response::
363
-
364
-       {}
365
-
366
-Mapping between the CNM and the Neutron's Networking Model
367
-----------------------------------------------------------
368
-
369
-Kuryr communicates with Neutron via `Neutron client <http://docs.openstack.org/developer/python-neutronclient/>`_
370
-and bridges between libnetwork and Neutron by translating their networking models.
371
-The following table depicts the current mapping between libnetwork and Neutron models:
372
-
373
-===================== ======================
374
-libnetwork            Neutron
375
-===================== ======================
376
-Network               Network
377
-Sandbox               Subnet, Port and netns
378
-Endpoint              Port
379
-===================== ======================
380
-
381
-libnetwork's Sandbox and Endpoint can be mapped into Neutron's Subnet and Port,
382
-however, Sandbox is invisible from users directly and Endpoint is only the
383
-visible and editable resource entity attachable to containers from users'
384
-perspective. Sandbox manages information exposed by Endpoint behind the scene
385
-automatically.
386
-
387
-
388
-Notes on implementing the libnetwork remote driver API in Kuryr
389
----------------------------------------------------------------
390
-
391
-1. DiscoverNew Notification:
392
-   Neutron does not use the information related to discovery of new resources such
393
-   as new nodes and therefore the implementation of this API method does nothing.
394
-
395
-2. DiscoverDelete Notification:
396
-   Neutron does not use the information related to discovery of resources such as
397
-   nodes being deleted and therefore the implementation of this API method does
398
-   nothing.

Loading…
Cancel
Save