{"id":21675758,"url":"https://github.com/pantheontech/stonework","last_synced_at":"2025-08-21T11:32:36.366Z","repository":{"id":37382366,"uuid":"437911202","full_name":"PANTHEONtech/StoneWork","owner":"PANTHEONtech","description":"StoneWork - high-performance data plane, modular control plane solution.","archived":false,"fork":false,"pushed_at":"2024-06-26T19:28:58.000Z","size":1309,"stargazers_count":37,"open_issues_count":12,"forks_count":16,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-12-09T10:13:08.130Z","etag":null,"topics":["cloud-native","control-plane","data-plane","dpdk","ligato","network-automation","router","switch","vpp"],"latest_commit_sha":null,"homepage":"https://cdnf.io/cnf_list/stonework","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PANTHEONtech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-13T14:47:07.000Z","updated_at":"2024-11-30T16:33:57.000Z","dependencies_parsed_at":"2023-10-29T20:28:37.413Z","dependency_job_id":"3208bddf-2c2a-4864-bca6-91be209e8c1c","html_url":"https://github.com/PANTHEONtech/StoneWork","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PANTHEONtech%2FStoneWork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PANTHEONtech%2FStoneWork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PANTHEONtech%2FStoneWork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PANTHEONtech%2FStoneWork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PANTHEONtech","download_url":"https://codeload.github.com/PANTHEONtech/StoneWork/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230511479,"owners_count":18237657,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-native","control-plane","data-plane","dpdk","ligato","network-automation","router","switch","vpp"],"created_at":"2024-11-25T14:10:33.063Z","updated_at":"2024-12-19T23:13:17.819Z","avatar_url":"https://github.com/PANTHEONtech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StoneWork\n\n [![CI](https://github.com/PANTHEONtech/StoneWork/actions/workflows/ci.yml/badge.svg)](https://github.com/PANTHEONtech/StoneWork/actions/workflows/ci.yml)\n [![stable](https://img.shields.io/github/release/PANTHEONtech/StoneWork.svg?label=latest%20release\u0026logo=github)](https://github.com/PANTHEONtech/StoneWork/releases/latest)\n [![ligato/vpp-agent](https://img.shields.io/badge/image-ghcr.io/pantheontech/stonework-blue.svg?logo=docker\u0026logoColor=white)](https://github.com/PANTHEONtech/StoneWork/pkgs/container/stonework)\n\nA **high-performance** data plane, **modular** control plane solution.\n\nStoneWork is used by PANTHEON.tech to integrate [its cloud-native network functions][cdnf-io] on top of a single shared\n[FD.io VPP][VPP] data plane instance, to achieve the *best possible* resource\nutilization. \n\nThis network appliance, however, is not a step back from distributed chained/meshed microservices, to monolithic architecture. \n\nInstead, the integration is:\n- Dynamic \n- Based on container orchestration\n- CNF discovery\n- Sharing of network namespaces and \n- Re-use of data paths for packet punting between CNFs\n\n## Features\n\n* High-performance [VPP][VPP]-based **data plane**\n* Management agent build on top of [Ligato VPP-Agent][ligato-vpp-agent]\n* Suitable for both **cloud \u0026 bare-metal** deployments\n* Can be deployed as either *multiple* interconnected instances (service function\n  chaining), or *a set* of control/management plane microservices that use a\n  single VPP instance for data plane (this is a trade-off between flexibility\n  and resource utilization)\n* **Northbound APIs** are modeled with protobuf and accessible over `gRPC`, `REST`,\n  `K8s CRD`or through a key-value DB (`etcd`, `redis`, ...)\n* Wide-range of **networking features**, natively implemented in VPP, e.g.:\n    * High-performance device drivers (DPDK, RDMA, virtio)\n    * Routing, switching\n    * Tunneling (VXLAN, GRE, IP-IP)\n    * ACL-based filtering and routing\n    * NAT44, NAT64\n    * Segment routing\n    * VPN (Wireguard, IPSec)\n    * Bridge domains, VRFs (multi-tenancy)\n* **Management features** provided by the Linux network stack:\n    * Routes, ARPs\n    * iptables\n    * Namespaces, VRFs (multi-tenancy)\n* Dynamically (at run-time) **extensible** with additional features provided by\n  [CNFs from PANTHEON.tech][cdnf-io]\n\n## Examples\n\nBefore using StoneWork, we recommend reading this README and related\ndocumentation in the StoneWork [distribution folder][docs]. \n\nIf you are **new to StoneWork**, it may be easier to first\nexplore and run the provided examples, rather than trying to create deployment\nmanifests from scratch.\n\nExamples of deployment manifests and configurations for various use-cases can be found under the [examples sub-directory][examples].\n\nThe [Getting Started][getting-started] example will guide you through your first StoneWork\ndeployment.\n\n\n## Configuration\n\nConfiguration for StoneWork consists of two tasks:\n\n#### 1. VPP Startup Configuration\n\nThe VPP Startup Configuration comprises configuration options, which are set\nbefore VPP is started. They *cannot* be changed at the run-time, either by a\nmanagement plane API or the VPP CLI). For StoneWork, the default VPP startup\nconfiguration file is packaged in the image, under `/etc/vpp/vpp.conf`. \n\nSome of the [examples][examples] override the default configuration with a customized\nversion of `vpp.conf`mounted into the container using volumes. Typically, the\nonly configuration section that may require customization is the `dpdk` stanza,\nwhere PCI addresses of NICs, used by VPP, should be listed. \n\nRun the `lshw-class network -businfo` command to view the available network devices\nand their respective PCI addresses. For example, if the PCI addresses of\ninterfaces were `0000:00:08.0` and `0000:00:09.0` (e.g. inside and outside\nnetwork), then the `dpdk` configuration would be:\n```\ndpdk {\n    dev 0000:00:08.0 {\n        name eth0\n    }\n    dev 0000:00:09.0 {\n        name eth1\n    }\n}\n```\nInterface names can be selected arbitrarily, for example `eth0` and `eth1`'\nin the above example.\n\nMore information about attaching physical interfaces into VPP can be found\n[here][vpp-pci].\n\n#### 2. Protobuf-modeled Network Configuration\n\nStoneWork's network configuration (VPP, Linux, CNFs) is modeled using\nGoogle Protocol Buffers. \n\nA summary of all configuration items and their\nattributes, with descriptions, can be found [here][config] (in markdown; also\navailable as a single [PDF document][config-pdf]). \n\nA [JSON Schema][config-jsonschema] is provided as well, and can be used to validate input\nconfiguration before it is submitted. \n\nSome text editors, for example\n[VS Code][vscode-jsonschema], can even load the Schema and provide\nautocomplete suggestions based on it, thus making the process of preparing\ninput configuration a lot easier. \n\nThe original protobuf files, from which the\ndocumentation and schema were generated, can be found in the `/api` folder inside\nthe StoneWork distribution. There is also the `/api/models.spec.yaml` file,\nwhich contains one YAML document with metadata for every configuration model.\n\nThese metadata are used to associate a configuration model with the corresponding\nprotobuf definitions.\n\nNetwork configuration is submitted into the control-plane agent either via:\n\n- a **[CLI][agentctl]** (YAML formatted), written into a key-value datastore (e.g.\n`etcd`; JSON-formatted) \n\n- or applied programmatically over **gRPC** (serialized by\nprotobuf) or REST (JSON) APIs. The initial configuration that should be applied\nimmediately after StoneWork starts up can be mounted into the container under\n`/etc/stonework/config/day0-config.yaml` (YAML formatted).\n\nEach of the attached [examples][examples] has a sub-directory named `config`,\nwhere you can find configuration stanzas to learn from. Each example contains\nthe startup configuration `day0-config.yaml`. \n\nAdditional `*.yaml` files are used to show how run-time configuration can be modified over CLI. Please\nrefer to each examples `README.md` file for more information.\n\n\n## Installation\n\nThe following steps will guide you through the StoneWork **installation process**.\nThe distribution package contains the **StoneWork Docker image** (`stonework.image`),\ndocumentation (`*.md`) and some examples to get you started.\n\n#### Requirements\n\n1. StoneWork requires an **Ubuntu VM** or a **bare-metal server** running Ubuntu, preferably version **22.04 (Jammy Jellyfish)**.\n\n\n2. Next, Docker and Docker Compose plugin must be installed.\n\n   Official manual for installing Docker and Docker Compose can be found [here][install-docker] and [here][install-compose] respectively.\n\n3. **(DPDK Only)** Install/Enable Drivers\n   \n   Depending on the type of NICs that VPP of StoneWork should bind to, you may\n   have to install/enable the corresponding drivers. \n   \n   For example, in a VM environment, the [Virtual Function I/O (VFIO)][vfio] is preferred over the\n   UIO framework for better performance and more security. In order to load a VFIO\n   driver, run:\n   ```\n   $ modprobe vfio-pci\n   $ echo \"vfio-pci\" \u003e /etc/modules-load.d/vfio.conf\n   ```\n   Check with:\n   ```\n   $ lsmod | grep vfio_pci\n   vfio_pci               45056  0\n   ```\n   More information about Linux network I/O drivers that are compatible with\n   DPDK (used by VPP), can be found [here][dpdk-linux-drivers].\n\n\n4. **(DPDK Only)** Check Network Interfaces\n   \n   Make sure that the network interfaces are not already used by the Linux\n   kernel, or else VPP/DPDK will not be able to grab them. Run `ip link set\n   dev {device} down` for each device to un-configure it from Linux. Preferably\n   disable the interfaces using configuration files to make the changes\n   persistent (e.g. inside `/etc/network/interfaces`).\n\n\n5. **(DPDK Only)** Huge Pages\n   \n   In order to optimize memory access, VPP/DPDK uses [Huge Pages][hugepages],\n   which have to be allocated before deploying StoneWork.\n   For example, to allocate 512 Huge Pages (1024MiB memory for default 2M\n   hugepage size), run:\n   ```\n   $ echo \"vm.nr_hugepages=512\" \u003e\u003e /etc/sysctl.conf\n   $ sysctl -p\n   ```\n   Detailed recommendations on allocations of Huge Pages for VPP can be found\n   [here][vpp-hugepages].\n\n\n6. Finally, the StoneWork image has to be loaded so that\n   Docker/Docker Compose/K8s is able to provision a container instance. Run:\n   ```\n   $ docker load \u003c./stonework.image\n   ```\n\n## Deployment\n\nStoneWork is deployed using [Docker Compose][compose] version 3.3 or\nnewer. StoneWork itself is only a single container (with VPP and StoneWork agent\ninside), but every CNF that is deployed alongside it runs in a **separate\ncontainer**, hence the use of Compose. \n\nThe following is a template for the\n`docker-compose.yaml` file, used to describe deployment in the language of\nDocker Compose. The template contains detailed comments, that explain the meaning\nof attributes contained in the template and how they work in StoneWork. \n\nAngle brackets are used to mark placeholders that have to be replaced with appropriate\nactual values in the target deployment.\n\n```yaml\nversion: '3.3'\n\n# Volume shared between StoneWork and every CNF deployed alongside it.\n# CNFs and StoneWork use it to discover each other.\nvolumes:\n  runtime_data: {}\n\nservices:\n  stonework:\n    container_name: stonework\n    image: \"ghcr.io/pantheontech/stonework:22.10\"\n    # StoneWork runs in the privileged mode to be able to perform administrative network operations.\n    privileged: true\n    # StoneWork runs in the PID namespace of the host so that it can read PIDs of CNF processes.\n    pid: \"host\"\n    environment:\n      # Set log level (i.e. only log entries with that severity or anything above it will be printed).\n      # Supported values: Trace, Debug, Info, Warning, Error, Fatal and Panic.\n      INITIAL_LOGLVL: \"debug\"\n      # MICROSERVICE_LABEL is used to mark container with StoneWork.\n      MICROSERVICE_LABEL: \"stonework\"\n      # By default etcd datastore is used as the source of the configuration.\n      # Env. variable ETCD_CONFIG with empty value is used to disable etcd\n      # and use CLI (agentctl) or gRPC as the primary source of the configuration.\n      ETCD_CONFIG: \"\"\n    ports:\n      # Expose HTTP and gRPC APIs.\n      - \"9111:9111\"\n      - \"9191:9191\"\n    volumes:\n      # /run/stonework must be shared between StoneWork and every CNF.\n      - runtime_data:/run/stonework\n      # /sys/bus/pci and /dev are mounted for StoneWork to be able to access PCI devices over DPDK.\n      - /sys/bus/pci:/sys/bus/pci\n      - /dev:/dev\n      # Docker socket is mounted so that StoneWork can obtain container metadata for every CNF.\n      - /run/docker.sock:/run/docker.sock\n      # To customize vpp startup configuration, create your own version of vpp.conf (here called vpp-startup.conf),\n      # put it next to this docker-compose.yaml and mount it under /etc/vpp/vpp.conf.\n      # Otherwise remove this mount.\n      - ./vpp-startup.conf:/etc/vpp/vpp.conf\n      # To start StoneWork with some initial configuration, create day0-config.yaml under the config\n      # sub-directory, placed next to this docker-compose.yaml and mount it under /etc/stonework/config\n      # Otherwise remove this mount.\n      - ./config:/etc/stonework/config\n\n  # Multiple CNFs may share the same Linux network namespace. This is in some case needed\n  # if CNFs are to work together (e.g. BGP peering established over OSPF-learned routes).\n  # The common network namespace is represented by a separate container (similar to the\n  # sandbox container of a K8s Pod).\n  router-ns:\n    container_name: router-ns\n    image: \"busybox:1.29.3\"\n    command: tail -f /dev/null\n\n  # CNF running alongside StoneWork (i.e. using the VPP of StoneWork as data-plane).\n  # Name the container such that it is clear what services CNF provides (e.g. \"cnf-dhcp\").\n  \u003ccnf-name\u003e:\n    container_name: \u003ccnf-name\u003e\n    image: \"\u003ccnf-image-name\u003e\"\n    depends_on:\n      - stonework\n    # CNFs typically require privileges to perform administrative network operations.\n    privileged: true\n    # \u003ccnf-name\u003e-license.env is file that is obtained when the license of CNF is purchased.\n    # Put \u003ccnf-name\u003e-license.env into the same directory as docker-compose.yaml.\n    # It contains single line:\n    # LICENSE=\u003csigned license content\u003e\n    env_file:\n      - \u003ccnf-name\u003e-license.env\n    volumes:\n      # /run/stonework must be shared between StoneWork and every CNF.\n      - runtime_data:/run/stonework\n    environment:\n      INITIAL_LOGLVL: \"debug\"\n      # MICROSERVICE_LABEL is effectively used to mark the container with CNF name.\n      # StoneWork is then able to identify the CNF container among all containers.\n      MICROSERVICE_LABEL: \"\u003ccnf-name\u003e\"\n      ETCD_CONFIG: \"\"\n      # If CNF runs alongside StoneWork (and not standalone), env. variable \"CNF_MODE\"\n      # must be defined with value \"STONEWORK_MODULE\".\n      CNF_MODE: \"STONEWORK_MODULE\"\n    # Multiple CNFs may share the same Linux network namespace.\n    # Use network_mode and point a group of CNFs to the same container (acting just like sandbox\n    # container of a K8s Pod).\n    network_mode: \"service:router-ns\"\n\n  # here list other CNFs...\n```\n\n## Development\n[![Go Reference](https://pkg.go.dev/badge/go.pantheon.tech/stonework.svg)](https://pkg.go.dev/go.pantheon.tech/stonework)\n\n- **Build**: Build instruction for StoneWork can be found [here][build].\n- **Architecture**: StoneWork architecture is described in detail [here][architecture].\n- **CNF Compatibility**: A guide on how to make CNF compatible with StoneWork can be found [here][cnf-how-to].\n- **GNS3 \u0026 StoneWork**: StoneWork GNS3 VM development documentation is [here][gns3-vm-docs].\n\n[architecture]: docs/ARCHITECTURE.md\n[build]: docs/BUILD.md\n[cnf-how-to]: docs/CNF_HOW_TO.md\n[config]: docs/config/STONEWORK-CONFIG.md\n[config-pdf]: docs/config/STONEWORK-CONFIG.pdf\n[config-jsonschema]: docs/config/STONEWORK-CONFIG.jsonschema\n[vscode-jsonschema]: https://dev.to/brpaz/how-to-create-your-own-auto-completion-for-json-and-yaml-files-on-vs-code-with-the-help-of-json-schema-k1i\n[compose]: https://docs.docker.com/compose/\n[install-docker]: https://docs.docker.com/engine/install/ubuntu/\n[install-compose]: https://docs.docker.com/compose/install/linux/\n[vpp]: https://wiki.fd.io/view/VPP\n[ligato-vpp-agent]: https://github.com/ligato/vpp-agent\n[cdnf-io]: https://cdnf.io/cnf_list/\n[examples]: examples/README.md\n[getting-started]: examples/getting-started/README.md\n[agentctl]: https://docs.ligato.io/en/latest/user-guide/agentctl/\n[vpp-pci]: https://wiki.fd.io/view/VPP/How_To_Connect_A_PCI_Interface_To_VPP\n[vfio]: https://www.kernel.org/doc/Documentation/vfio.txt\n[dpdk-linux-drivers]: https://doc.dpdk.org/guides/linux_gsg/linux_drivers.html\n[hugepages]: https://wiki.debian.org/Hugepages\n[vpp-hugepages]: https://s3-docs.fd.io/vpp/21.10.1/gettingstarted/users/configuring/hugepages.html\n[gns3-vm-docs]: docs/GNS3_APPLIANCES.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpantheontech%2Fstonework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpantheontech%2Fstonework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpantheontech%2Fstonework/lists"}