From 3b93ede105f956a687a382903482b5a67cf9cd9c Mon Sep 17 00:00:00 2001 From: johnburn Date: Thu, 5 Oct 2017 18:39:23 -0700 Subject: [PATCH] updated readme's --- README.md | 4 +- docker/dev_sfc_controller/README.md | 205 ++++++++++++++++------------ 2 files changed, 119 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 0018cf2e..c9db2973 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ developed as extensions to [VPP][1]. with other containers or externally via veth interfaces. The VSwitch VPP creates the veth interfaces. -## SFC Toppologies +## SFC Topologies The SFC Controller supports the following topologies: ![SFC Topolgies](docs/imgs/sfc_topologies.png "SFC Topologies") @@ -95,7 +95,7 @@ docker exec -it sfc-controller sfcdump GoDoc can be browsed [online](https://godoc.org/github.com/ligato/sfc-controller). ## Next Steps -Read the README for the [Development Docker Image](docker/dev_sfc-controller/README.md) for more details. +Read the README for the [Development Docker Image](docker/dev_sfc_controller/README.md) for more details. ### Deployment: diff --git a/docker/dev_sfc_controller/README.md b/docker/dev_sfc_controller/README.md index 18b6c955..28fc00f1 100644 --- a/docker/dev_sfc_controller/README.md +++ b/docker/dev_sfc_controller/README.md @@ -1,26 +1,28 @@ ## Development Docker Image -This image can be used to get started with the vnf-agent Go code. It contains: +This image can be used to get started with the sfc-controller Go code. It +contains: -- The development environment with all libs & dependencies required to build VPP / Go code, -- A pre-built vpp ready to be used, -- A pre-built Go agent. +- The development environment with all libs & dependencies required + to build both the controller. -### Getting the Image -You can either download a pre-built image or build the image -yourself on your local machine. -For getting latest image, type: -docker pull dockerhub.cisco.com/vnf-docker-dev/dev_vpp_agent:latest -Or you can browse through images and pick one you want here: -https://engci-maven-master.cisco.com/artifactory/webapp/#/artifacts/browse/tree/General/vnf-docker-dev-local/dev_vpp_agent - - -#### Building Locally -To build the image on your local machine, type: +### Getting an Image from Dockerhub +For a quick start with the Development image, you can use pre-built +Development docker images that contain pre-built controller, and +tools, the Ligato source code, Git, and build tools for the controller. +The pre-built Development docker images are +available from [Dockerhub](https://hub.docker.com/r/ligato/dev-sfc-controller/), +or you can just type: ``` -sudo docker build -t dev_vpp_agent . +docker pull ligato/dev-sfc-controller ``` +Then you can start the downloaded Development image as described [here][1]. +### Building Locally +To build the docker image on your local machine, type: +``` +./build.sh +``` #### Verifying a Created or Downloaded Image You can verify the newly built or downloaded image as follows: @@ -28,57 +30,68 @@ You can verify the newly built or downloaded image as follows: docker images ``` -You should see something this: +You should see something like this: ``` REPOSITORY TAG IMAGE ID CREATED SIZE -dev_vpp_agent latest 0692f574f21a 11 minutes ago 3.58 GB +dev_sfc_controller latest 0692f574f21a 11 minutes ago 3.58 GB ... ``` -Get the details of the newly built image: +Get the details of the newly built or downloaded image: ``` -docker image inspect dev_vpp_agent -docker image history dev_vpp_agent +docker image inspect dev_sfc_controller +docker image history dev_sfc_controller ``` ---- -### Starting the Image -To start the image, type: -``` -sudo docker run -it --name vpp_agent --privileged --rm dev_vpp_agent bash -``` -To open another terminal: +### Shrinking the Image +dev_sfc_controller image can be shrunk by typing the command: + ``` -sudo docker exec -it vpp_agent bash +./shrink.sh ``` -### Running VPP and the Agent +This will build a new image with the name `dev_sfc_controller_shrink`, where +vpp sources and build related files have been removed (in total about 2GB). -**NOTE: The Agent will terminate if it cannot connect to VPP and -to an Etcd server. If the Agent can not connect to a Kafka broker, -Kafka-related APIs will report an error.** - -Start VPP in one of two modes: - - If you don't need (or don't have) DPDK, use "vpp lite": +The `shrink.sh` script is using docker export and import command, but due +[Docker issue](https://github.com/moby/moby/issues/26173) it will fail on +docker older than 1.13. ``` -vpp unix { interactive } plugins { plugin dpdk_plugin.so { disable } } +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +dev_sfc_controller latest 442771972e4a 8 hours ago 3.57 GB +dev_sfc_controller_shrink latest bd2e76980236 8 hours ago 1.68 GB ``` -Note: you most likely do not have DPDK support if you're doing development on your local laptop. +--- -- If you want DPDK (with no PCI devices), use: +### Starting the Image +By default, the sfc-controlelr will be started automatically +in the container. This is useful e.g. for deployments with Kubernetes, +as described in [this README](../../k8s/dev-setup/README.md). However, this option is +not really required for development purposes, and it can be overridden by +specifying a different container entry point, e.g. bash, as shown below. +To start the image, type: +``` +sudo docker run -it --name sfc_controller --privileged --rm dev_sfc_controller bash ``` -vpp unix { interactive } dpdk { no-pci } +To open another terminal into the image: ``` -Note that for DPDK, you would need to run the container in -privileged mode (add `--privileged` option to `docker run`). -For more options, please refer to the [VPP documentation](https://wiki.fd.io/view/VPP/Command-line_Arguments). +sudo docker exec -it sfc_controller bash +``` + +### Running the SFC Controller + +**NOTE: The controller will terminate if it cannot connect to an Etcd +server. If Kafka config is specified, a successful connection to Kafka is +also required. If Kafka config is not specified, the controler will run without +it, but all Kafka-related functionality will be disabled.** -To run the Agent, do the following: -- Edit `/opt/vnf-agent/dev/etcd.conf` to point the agent to an ETCD - server that runs outside of the VPP/Agent container. The +To run the controller, do the following: +- Edit `/opt/sfrc-controller/dev/etcd.conf` to point the controler to an ETCD + server that runs outside of the controller's container. The default configuration is: ``` @@ -88,14 +101,14 @@ endpoints: - "172.17.0.1:2379" ``` *Note that if you start Etcd in its own container on the same -host as the VPP/Agent container (as described below), you can +host as the controller's container (as described below), you can use the default endpoint configuration as is. ETCD is by default mapped onto the host at port 2379; the host's IP address will typically be 172.17.0.1, unless you change your Docker networking settings.* -- Edit `/opt/vnf-agent/dev/kafka.conf` to point the agent to a Kafka broker. - The default configuration is: +- Edit `/opt/sfc-controller/dev/kafka.conf` to point the agent to a Kafka broker. + The default configuration is: ``` addrs: @@ -109,9 +122,9 @@ be mapped onto the host at port 9092; the host's IP address will typically be 172.17.0.1, unless you change your Docker networking settings.* -- Start the Agent: +- Start the controller: ``` -vpp-agent --etcdv3-config=/opt/vnf-agent/dev/etcd.conf --kafka-config=/opt/vnf-agent/dev/kafka.conf +sfc-controller --etcdv3-config=/opt/sfc-controller/dev/etcd.conf --kafka-config=/opt/sfc-controller/dev/kafka.conf ``` ### Running Etcd Server on Local Host @@ -119,19 +132,13 @@ You can run an ETCD server in a separate container on your local host as follows: ``` sudo docker run -p 2379:2379 --name etcd --rm \ - quay.io/coreos/etcd:v3.0.16 /usr/local/bin/etcd \ + quay.io/coreos/etcd:v3.1.0 /usr/local/bin/etcd \ -advertise-client-urls http://0.0.0.0:2379 \ -listen-client-urls http://0.0.0.0:2379 ``` -(ETCD server will be available on your host OS IP (most likely `172.17.0.1` -in the default docker environment) on port `2379`) +The ETCD server will be available on your host OS IP (most likely +`172.17.0.1` in the default docker environment) on port `2379`. -Call the agent via ETCD using the testing client: -``` -cd $GOPATH/src/gitlab.cisco.com/ctao/vnf-agent/agent_plugins/ifplugin/examples/ -go run crud.go /opt/vnf-agent/dev/etcd.conf -ct -go run crud.go /opt/vnf-agent/dev/etcd.conf -mt -go run crud.go /opt/vnf-agent/dev/etcd.conf -dt ``` ### Running Kafka on Local Host @@ -141,49 +148,63 @@ sudo docker run -p 2181:2181 -p 9092:9092 --name kafka --rm \ --env ADVERTISED_HOST=172.17.0.1 --env ADVERTISED_PORT=9092 spotify/kafka ``` -### Rebuilding the Agent +### Rebuilding the Controller ``` -cd $GOPATH/src/gitlab.cisco.com/ctao/vnf-agent/ +cd $GOPATH/src/github.com/ligato/sfc-controller/ git pull # if needed +source setup-env.sh make make test # optional make install ``` -This should update the `agent` binary in yor `$GOPATH/bin` directory. +This should update the `sfc-controller` binary in yor `$GOPATH/bin` directory. ### Rebuilding of the container image: Use the `--no-cache` flag for `docker build`: ``` -sudo docker build --no-cache -t dev_vpp_agent . +sudo docker build --no-cache -t dev_sfc_controller . ``` ### Mounting of a host directory into the Docker container: Use `-v` option of the docker command: ``` -sudo docker run -v /host/folder:/container/folder -it --name vpp_agent --privileged --rm dev_vpp_agent bash +sudo docker run -v /host/folder:/container/folder -it --name sfc_controller --privileged --rm dev_sfc_controller bash ``` -E.g. if you have the vnf-agent code in `~/go/src/gitlab.cisco.com/ctao/vnf-agent/` -on your host OS, you can mount it as `/root/go/src/gitlab.cisco.com/ctao/vnf-agent/` +E.g. if you have the sfc controller code in `~/go/src/github.com/ligato/sfc-controller/` +on your host OS, you can mount it as `/root/go/src/github.com/ligato/sfc-controller/` in the container as follows: ``` -sudo docker run -v ~/go/src/gitlab.cisco.com/ctao/vnf-agent/:/root/go/src/gitlab.cisco.com/ctao/vnf-agent/ -it --name vpp_agent --rm dev_vpp_agent bash +sudo docker run -v ~/go/src/github.com/ligato/:/root/go/src/github.com/ligato/ -it --name sfc_controller --rm dev_sfc_controller bash ``` -Then you can modify the code on you host OS and us the container for building and testing it. +Then you can modify the code on you host OS and us the container for +building and testing it. --- ## Example: Using the Development Environment on a MacBook with Gogland -This section describes the setup of a lightweight, portable development environment on your local notebook (MacBook or MacBook Pro in this example). The MacBook will be the host for the Development Environment container and the folder containing the agent sources will be shared between the host and the container. Then, you can run the IDE, git, and other tools on the host and the compilations/testing in the container. +This section describes the setup of a lightweight, portable development +environment on your local notebook (MacBook or MacBook Pro in this example). +The MacBook will be the host for the Development Environment container +and the folder containing the agent sources will be shared between the +host and the container. Then, you can run the IDE, git, and other tools +on the host and the compilations/testing in the container. #### Prerequisites -1. Get [Docker for Mac](https://docs.docker.com/docker-for-mac/). If you don't have it already installed, follow the [install instructions](https://docs.docker.com/docker-for-mac/install/). +1. Get [Docker for Mac](https://docs.docker.com/docker-for-mac/). If you + don't have it already installed, follow these + [install instructions](https://docs.docker.com/docker-for-mac/install/). -2. Install Go and the [Gogland](https://www.jetbrains.com/go/) IDE. Go can be downloaded from this [repository](https://golang.org/dl/), and its install instructions are [here](https://golang.org/doc/install). Gogland download and install instructions are [here](https://www.jetbrains.com/go/download/). +2. Install Go and the [Gogland](https://www.jetbrains.com/go/) IDE. Go + can be downloaded from this [repository](https://golang.org/dl/), and + its install instructions are [here](https://golang.org/doc/install). + The download and install instructions for Gogland are + [here](https://www.jetbrains.com/go/download/). -2. Once you have Docker up & running on your Mac, build and verify the Development Environment container [as described above](#getting-the-image). +2. Once you have Docker up & running on your Mac, build and verify the + Development Environment container [as described above](#getting-the-image). #### Building and Running the Agent For the mixed host-container environment, the folder holding the @@ -199,32 +220,39 @@ through these steps. folder must be called `src`. So you will have: ` ~/go/src` - In the Go source folder, create the folder that will hold the - local clone of the vnf-agent repository. The path for the folder - must reflect the import path in Go source code. So, the vnf-agent + local clone of the vpp-agent repository. The path for the folder + must reflect the import path in Go source code. So, the vpp-agent repository folder will be created as follows: ``` cd ~/go/src - mkdir gitlab.cisco.com - mkdir gitlab.cisco.com/ctao + mkdir github.com + mkdir github.com/ligato ``` -- The agent repository is located at `http://gitlab.cisco.com/ctao/vnf-agent`. - Go into your local vnf-agent repo folder and checkout the Agent code: +- The controller repository is located at `https://github.com/ligato/sfc-controller`. + Go into your local vpp-agent repo folder and checkout the Agent code: ``` - cd gitlab.cisco.com/ctao - git clone http://gitlab.cisco.com/ctao/vnf-agent.git + cd github.com/ligato + git clone https://github.com/ligato/sfc-controller.git ``` - In Gogland, set `GOROOT` and `GOPATH` (`Preferences->Go->GOROOT`, `Preferences->Go->GOPATH`). Set `GOROOT` to where Go is installed (default: `/usr/local/go`) and the global `GOPATH` to the location of your Go home folder (`/Users/jmedved/Documents/Git/go-home/` in our example). -- Create a new project in Gogland (`File->New->Project`, ) will popup the project creation window. Enter your newly created Go home folder (`/Users/jmedved/Documents/Git/go-home/` in our example) as the location and accept the default value for the SDK. Click `Create`, and you should now be able to browse the Agent source code in Gogland. +- Create a new project in Gogland (`File->New->Project`, ) will popup the + project creation window. Enter your newly created Go home folder + (`/Users/jmedved/Documents/Git/go-home/` in our example) as the location + and accept the default value for the SDK. Click `Create`, and you + should now be able to browse the Agent source code in Gogland. -- Start the Development Environment container with the -v option, mounting the Go home folder in the container. With our example, and assuming that we want to mount our Go home folder into the `root/go-home` folder, type: +- Start the Development Environment container with the -v option, mounting + the Go home folder in the container. With our example, and assuming that + we want to mount our Go home folder into the `root/go-home` folder, type: ``` - sudo docker run -v ~/go/src/gitlab.cisco.com/ctao/vnf-agent/:/root/go/src/gitlab.cisco.com/ctao/vnf-agent/ -it --name vpp_agent --rm dev_vpp_agent bash + sudo docker run -v ~/go/src/github.com/ligato/:/root/go/src/github.com/ligato -it --name sfc_controller --rm dev_sfc_controller bash ``` -The above command will put you into the Development Environment container console. +The above command will put you into the Development Environment container +console. **In the container console**: @@ -234,13 +262,14 @@ The above command will put you into the Development Environment container consol export GOPATH=/root/go export PATH=/$GOPATH/bin:$PATH ``` -- Change directory into the vnf-agent folder and build & install the Agent: +- Change directory into the vpp-agent folder and build & install the Agent: ``` - cd /root/go-home/src/gitlab.cisco.com/ctao/vnf-agent + cd /root/go-home/src/github.com/ligato/sfc-controller make make install ``` - Use the newly built agent as described in Section - '[Running VPP and the Agent](#running-vpp-and-the-agent)'. + '[Running the controller](#running_the_sfc_controller)'. +[1]: #-starting-the-image \ No newline at end of file