Skip to content

Commit a1e0259

Browse files
author
Vipin Jain
committed
Merge pull request #147 from contiv/readme_update
readme cleanup
2 parents 8fcfaa5 + f1f39e8 commit a1e0259

File tree

3 files changed

+151
-92
lines changed

3 files changed

+151
-92
lines changed

‎CONTRIBUTING.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
## Contributing to Netplugin
2+
3+
There are many ways to contribute - report issues, suggest doc changes,
4+
submit bug fixes, propose design changes, discuss use cases, propose
5+
interop with other ecosystem software, or become a maintainer.
6+
7+
All contributions, big or small are welcome!
8+
9+
### Reporting Issues
10+
Usage or non code related issues can be reported by clicking `New Issue` on
11+
[netplugin's issues on github](https://github.com/contiv/netplugin/issues).
12+
A feature request can also be submitted as an issue.
13+
14+
However if there is an issue with running the netplugin binary, providing following
15+
information would shorten the debug time:
16+
- Version of container runtime (e.g. docker), state driver (e.g. etcd),
17+
netplugin version, driver (e.g. ovs), Operating System version, and other
18+
applicable information.
19+
- Steps to reproduce, if any
20+
- Backtrace, if applicable
21+
22+
### Suggesting a doc change, or submitting a bug fix
23+
Just go ahead and submit a PR, one of the maintainers would review the diffs
24+
and provide feedback. After discussions, as the changes look good, they will
25+
be merged into the master. Please make sure you run the unit and system tests
26+
before submitting the PR.
27+
28+
### Proposing a design change
29+
If you would like to refactor the code, propose a new design component, or
30+
introduce a significant change, please discuss it as an issue titled as
31+
`Proposal: ...` in order for people to provide feedback early enough.
32+
Making significant code changes before design discussion may waste
33+
time, therefore it is discouraged.
34+
35+
After design discussions:
36+
- Fork a private repo
37+
- Make the changes in the private repo
38+
- Add unit and system test cases for your code
39+
- Make sure existing tests and newly added tests pass
40+
- Merge your changes with the latest in the master branch
41+
- Re-run the unit and system tests
42+
- Submit a PR with the code changes
43+
- This would involve discussions and few adjustments may need to be made.
44+
It is encouraged to engage into discussions during the coding phase as well.
45+
- After `LGTM` from maintainers, re-run unit and system tests
46+
- One of the maintainers would merge your changes into the appropriate release candidate
47+
48+
49+
### Discussing use cases and requesting new features
50+
Bring up your use cases by submitting an issue. Describe the use case that
51+
is not handled in the latest version. Issues that seek new features should
52+
be titled as `Feature Request: ...`. It is encouraged to include diagrams
53+
(pics of hand drawn diagrams is just fine), or other details that best
54+
describes a use case.
55+
56+
### Becoming a maintainer
57+
Of course, play with the code, know is inside out - and you will know if you
58+
are ripe to become a maintainer. If you think you are ready, drop an eamil
59+
to any of the maintainers.
60+
61+
### Legal Stuff: Sign your work
62+
You must sign-off your work by adding your signature at the end of
63+
patch description. Your signature certifies that you wrote the patch or
64+
otherwise have the right to pass it on as an open-source patch.
65+
By signing off your work you ascertain following (from [developercertificate.org](http://developercertificate.org/)):
66+
67+
```
68+
Developer Certificate of Origin
69+
Version 1.1
70+
71+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
72+
660 York Street, Suite 102,
73+
San Francisco, CA 94110 USA
74+
75+
Everyone is permitted to copy and distribute verbatim copies of this
76+
license document, but changing it is not allowed.
77+
78+
Developer's Certificate of Origin 1.1
79+
80+
By making a contribution to this project, I certify that:
81+
82+
(a) The contribution was created in whole or in part by me and I
83+
have the right to submit it under the open source license
84+
indicated in the file; or
85+
86+
(b) The contribution is based upon previous work that, to the best
87+
of my knowledge, is covered under an appropriate open source
88+
license and I have the right under that license to submit that
89+
work with modifications, whether created in whole or in part
90+
by me, under the same open source license (unless I am
91+
permitted to submit under a different license), as indicated
92+
in the file; or
93+
94+
(c) The contribution was provided directly to me by some other
95+
person who certified (a), (b) or (c) and I have not modified
96+
it.
97+
98+
(d) I understand and agree that this project and the contribution
99+
are public and that a record of the contribution (including all
100+
personal information I submit with it, including my sign-off) is
101+
maintained indefinitely and may be redistributed consistent with
102+
this project or the open source license(s) involved.
103+
```
104+
105+
Then you just add a line to every git commit message:
106+
107+
Signed-off-by: Joe Smith <[email protected]>
108+
109+
Use your real name (sorry, no pseudonyms or anonymous contributions.)
110+
111+
If you set your `user.name` and `user.email` git configs, you can sign your
112+
commit automatically with `git commit -s`.
113+

‎README.md

+2-30
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Netplugin
44

5-
Generic network plugin (experimental) is designed to handle networking use
5+
Generic network plugin is designed to handle networking use
66
cases in clustered multi-host systems. It is specifically designed to handle:
77

88
- Multi-tenant environment where disjoint networks are offered to containers on the same host
@@ -13,22 +13,6 @@ cases in clustered multi-host systems. It is specifically designed to handle:
1313
- Integration with existing IPAM tools for migrating customers
1414
- Handle NIC's capabilities for acceleration (SRIOV/Offload/etc.)
1515

16-
The overall design is _not_ assumed to be complete, because of ongoing work in
17-
the docker community with regards to the suitable APIs to interface with
18-
network extensions like this. Regardless, flexibility in the design has been
19-
taken into consideration to allow using a different state driver for key-value
20-
synchronization, or a different flavor of a soft-switch i.e. linux-bridge, MAC
21-
VLAN, or OpenvSwitch.
22-
23-
The ability to specify the intent succinctly is the primary goal of the design
24-
and thus some of the specified user interface will change, and in some cases
25-
functionality will be enhanced to accommodate the same. Design details and
26-
future work is captured in a
27-
[docs/design.md](https://github.com/contiv/netplugin/blob/master/docs/Design.md).
28-
29-
Please do not use this code in production, until code goes through more testing
30-
and few critical open issues are resolved.
31-
3216
### Getting Started
3317

3418
This will provide you with a minimal experience of uploading the intent and
@@ -74,12 +58,7 @@ $ ping 11.1.0.2
7458

7559
The [docs/TwoHostMultiVlanDemo.md](docs/TwoHostMultiVlanDemo.md) walks through
7660
setting up a multi host demo network and deploy the following Vlan based
77-
network: ![VlanNetwork](./docs/VlanNetwork.jpg)
78-
79-
One can deploy the following Vxlan network by following the steps in the above
80-
demo and using [examples/two_hosts_multiple_vxlan_nets.json](examples/two_hosts_multiple_vxlan_nets.json)
81-
configuration file instead. Trying out the configuration is left as an exercise
82-
to the reader. ![VxlanNetwork](./docs/VxlanNetwork.jpg)
61+
network.
8362

8463
#### Multi-tenant network
8564

@@ -102,13 +81,6 @@ High level `make` targets:
10281
* `system-test`: run the networking/"sanity" tests. Specify
10382
`CONTIV_NODE_OS=centos` to test on centos instead of ubuntu.
10483

105-
#### Resource Allocation
106-
Various network resources like, IP-Subnets, VLAN/VXLAN-IDs, IP Addresses, can
107-
be automatically managed or they can be specified at network/endpoint
108-
granularity. To avoid any conflict with rest of the network, it is encouraged
109-
to specify the resource ranges, but when not specified, the resource-allocator
110-
can pick up the default values.
111-
11284
#### Kubernetes Integration
11385
The plugin code contains the netplugin code that interfaces with kublet to
11486
allow network plumbing before a container is scheduled on one of the minions.

‎docs/TwoHostMultiVlanDemo.md

+36-62
Original file line numberDiff line numberDiff line change
@@ -6,91 +6,65 @@ In this example we will simulate a two host cluster (with the two hosts being si
66

77
```
88
cd $GOPATH/src/github.com/contiv/netplugin
9-
CONTINV_NODES=2 make demo
9+
CONTIV_NODES=2 make build demo
1010
```
1111
12-
Note: User may simulate more hosts by setting the CONTINV_NODES variable to a desired number. Each host corresponds to a vagrant-vm, which are connected through their 'eth2' interface to a virtualbox bridge network for the container data traffic.
13-
12+
Note: User may simulate more hosts by setting the CONTIV_NODES variable to a desired number. Each host corresponds to a vagrant-vm, which are connected through their 'eth2' interface to a virtualbox bridge network for the container data traffic.
13+
1414
2. Once the make is done, start a separate ssh session to each node and run the netplugin:
1515
1616
```
17-
CONTINV_NODES=2 vagrant ssh netplugin-node1
18-
sudo $GOPATH/bin/netplugin -host-label host1
17+
CONTIV_NODES=2 vagrant ssh netplugin-node1
18+
sudo $GOPATH/bin/netmaster &
19+
sudo $GOPATH/bin/netplugin -host-label host1 &
1920
```
2021
```
21-
CONTINV_NODES=2 vagrant ssh netplugin-node2
22-
sudo $GOPATH/bin/netplugin -host-label host2
22+
CONTIV_NODES=2 vagrant ssh netplugin-node2
23+
sudo $GOPATH/bin/netplugin -host-label host2 &
2324
```
24-
3. Let's create 4 containers two on each vagrant node that we will add to the two networks viz. orange and purple later.
2525
26-
On netplugin-node1:
27-
```
28-
sudo docker run -it --name=myContainer1 --hostname=myContainer1 ubuntu /bin/bash
29-
sudo docker run -it --name=myContainer2 --hostname=myContainer2 ubuntu /bin/bash
30-
```
31-
On netplugin-node2:
32-
```
33-
sudo docker run -it --name=myContainer3 --hostname=myContainer1 ubuntu /bin/bash
34-
sudo docker run -it --name=myContainer4 --hostname=myContainer2 ubuntu /bin/bash
35-
```
36-
4. Now let's load the multi-host multi vlan configuration from the [../examples/two_hosts_multiple_vlans_nets.json](../examples/two_hosts_multiple_vlans_nets.json) file by issuing the following commands from one of the vagrant vms.
26+
3. Load the multi-host multi vlan configuration from the [../examples/two_hosts_multiple_vlans_nets.json](../examples/two_hosts_multiple_vlans_nets.json) file by issuing the following commands from one of the vagrant vms.
3727
3828
```
39-
CONTINV_NODES=2 vagrant ssh netplugin-node1
29+
CONTIV_NODES=2 vagrant ssh netplugin-node1
4030
cd $GOPATH/src/github.com/contiv/netplugin
4131
netdcli -cfg examples/two_hosts_multiple_vlans_nets.json
4232
```
43-
5. Now everything should be setup as per the diagram and we are good to test the connectivity.
4433
45-
Determine the IP addresses assigned to the container `myContainer3` and `myContainer4` by running command like `ifconfig` or `ip address show` from the container shells (opened in step 3).
46-
Note: the current implementation with ovs names the netdevices as 'port<number>'
34+
4. Launch 4 containers, two on each vagrant node that we will add to the two networks viz. orange and purple
4735
36+
On netplugin-node1:
4837
```
49-
root@myContainer3:/# ip address show
50-
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default
51-
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
52-
inet 127.0.0.1/8 scope host lo
53-
valid_lft forever preferred_lft forever
54-
inet6 ::1/128 scope host
55-
valid_lft forever preferred_lft forever
56-
7: eth0: <BROADCAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
57-
link/ether 02:42:ac:11:00:02 brd ff:ff:ff:ff:ff:ff
58-
inet 172.17.0.2/16 scope global eth0
59-
valid_lft forever preferred_lft forever
60-
inet6 fe80::42:acff:fe11:2/64 scope link
61-
valid_lft forever preferred_lft forever
62-
11: port2: <BROADCAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default
63-
link/ether 16:bd:b0:78:aa:26 brd ff:ff:ff:ff:ff:ff
64-
inet 11.1.2.2/24 scope global port2
65-
valid_lft forever preferred_lft forever
66-
inet6 fe80::14bd:b0ff:fe78:aa26/64 scope link
67-
valid_lft forever preferred_lft forever
68-
root@myContainer3:/#
38+
sudo docker run -itd --name=myContainer1 --hostname=myContainer1 ubuntu /bin/bash
39+
sudo docker run -itd --name=myContainer2 --hostname=myContainer2 ubuntu /bin/bash
6940
```
70-
71-
Go to the terminal for the container `myContainer1` and ping the ip for the container `myContainer3`. The ping succeeds as the containers belong to same vlan network.
72-
41+
On netplugin-node2:
7342
```
74-
root@myContainer1:/# ping -c3 11.1.2.2
75-
PING 11.1.2.2 (11.1.2.2) 56(84) bytes of data.
76-
64 bytes from 11.1.2.2: icmp_seq=1 ttl=64 time=3.15 ms
77-
64 bytes from 11.1.2.2: icmp_seq=2 ttl=64 time=1.36 ms
78-
64 bytes from 11.1.2.2: icmp_seq=3 ttl=64 time=9.54 ms
79-
80-
--- 11.1.2.2 ping statistics ---
81-
3 packets transmitted, 3 received, 0% packet loss, time 2003ms
82-
rtt min/avg/max/mdev = 1.365/4.688/9.541/3.509 ms
83-
root@myContainer1:/#
43+
sudo docker run -itd --name=myContainer3 --hostname=myContainer3 ubuntu /bin/bash
44+
sudo docker run -itd --name=myContainer4 --hostname=myContainer4 ubuntu /bin/bash
8445
```
8546
86-
Now from `myContainer1`, ping the ip for `myContainer4`. The ping fails as the containers belong to different vlan networks.
47+
5. Now everything should be setup as per the diagram and we are good to test the connectivity.
8748
49+
On netplugin-node1:
8850
```
89-
root@myContainer1:/# ping -c3 11.1.3.2
90-
PING 11.1.3.2 (11.1.3.2) 56(84) bytes of data.
51+
# ping from myContainer1 to myContainer3 should succeed (both belonging to orange network)
52+
$ docker exec -it myContainer1 /bin/bash
53+
< inside the container >
54+
$ ip addr
55+
$ ping 11.1.0.2
9156
92-
--- 11.1.3.2 ping statistics ---
93-
3 packets transmitted, 0 received, 100% packet loss, time 2016ms
57+
# ping from myContainer2 to myContainer4 should also succeed (both belonging to purple network)
58+
$ docker exec -it myContainer4 /bin/bash
59+
< inside the container >
60+
$ ip addr
61+
$ ping 11.1.1.2
9462
95-
root@myContainer1:/#
63+
# ping between containers belonging to different networks would fail
64+
# unless they belong to the same tenant and routing is enabled.
9665
```
66+
67+
Trying out VXLAN network is similar, except using [examples/two_hosts_multiple_vxlan_nets.json](examples/two_hosts_multiple_vxlan_nets.json)
68+
configuration file instead, and it emulates the connectivity as in the following diagram:
69+
70+
![VXLANNetwork](./VxlanNetwork.jpg)

0 commit comments

Comments
 (0)