{"id":19048968,"url":"https://github.com/aemengo/bosh-runc-cpi-release","last_synced_at":"2025-08-27T02:09:52.166Z","repository":{"id":148266613,"uuid":"144289573","full_name":"aemengo/bosh-runc-cpi-release","owner":"aemengo","description":"BOSH release for the bosh-runc-cpi","archived":false,"fork":false,"pushed_at":"2019-01-29T20:07:00.000Z","size":6843,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-22T00:16:17.971Z","etag":null,"topics":["bosh","bosh-release","cpi","runc"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/aemengo.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":"2018-08-10T13:28:20.000Z","updated_at":"2021-05-26T17:37:45.000Z","dependencies_parsed_at":"2023-05-25T20:45:46.831Z","dependency_job_id":null,"html_url":"https://github.com/aemengo/bosh-runc-cpi-release","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/aemengo/bosh-runc-cpi-release","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aemengo%2Fbosh-runc-cpi-release","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aemengo%2Fbosh-runc-cpi-release/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aemengo%2Fbosh-runc-cpi-release/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aemengo%2Fbosh-runc-cpi-release/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aemengo","download_url":"https://codeload.github.com/aemengo/bosh-runc-cpi-release/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aemengo%2Fbosh-runc-cpi-release/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272279645,"owners_count":24905947,"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","status":"online","status_checked_at":"2025-08-27T02:00:09.397Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bosh","bosh-release","cpi","runc"],"created_at":"2024-11-08T23:09:18.557Z","updated_at":"2025-08-27T02:09:52.144Z","avatar_url":"https://github.com/aemengo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bosh-runc-cpi-release\n\nThe bosh-runc-cpi-release houses a set of tooling intended for the BOSH ecosystem that *orchestrates the creation of containers*, as opposed to VMs. It was inspired by and can most directly be compared to the [warden-cpi-release](https://github.com/cppforlife/bosh-warden-cpi-release). The primary use case is for virtual machine environments where the provisioning of [Garden](https://github.com/cloudfoundry/garden-runc-release) proves prohibitive. It was what powers [blt](https://github.com/aemengo/blt) and [cfdev](https://github.com/cloudfoundry-incubator/cfdev).\n\n![runc-cpi-env](images/runc-cpi-env.png)\n\n## Architecture\n\nMuch like the warden-cpi interacts with a garden server, the **runc-cpi** interacts with a **runc-cpi-daemon** counterpart. The cpi itself is a standalone binary that is invoked in the BOSH lifecycle with arguments via stdin. Consequently, the normal workflow is that the daemon is *first* set up listening on a particular `tcp` or `unix` address, *and then* the cpi must be configured with the aforementioned address.\n\n## Daemon\n\n### Prerequisites\n\n- [Golang](https://golang.org): 1.10+\n- [RunC](https://github.com/opencontainers/runc): v1.0.0-rc5+\n- Tar\n\n### Building\n\nWith this repository cloned and all the submodules initialized. Simply compile with Go tooling. Cross-compiling is completely supported:\n\n```bash\n$ cd bosh-runc-cpi-release\n$ export GOPATH=$PWD\n$ export GOARCH=amd64\n$ export GOOS=linux\n$ go build \\\n    github.com/aemengo/bosh-runc-cpi/cmd/cpid \n```\n\n### Running\n\nHaving the daemon server running is straightfoward. Simply execute the binary built from the previous step with a configuration yaml file and a long running process will be invoked.\n\nTar and RunC must be on the `$PATH`. Only linux environments are supported. `sudo` privileges are also required.\n\n```bash\n# Make sure that tar is on the $PATH\n# Make sure that runc is on the $PATH\n\n$ sudo ./cpid ./config.yml\nInitializing bosh-runc-cpid...\n```\n\n**Note:** In order to support a wide array of use cases, containers created by the bosh-runc-daemon are *privileged*. Running on your host machine is extremely discouraged and at your own risk!  \n\n### config.yml\n\nAs of right now, the `./config.yml` file only supports these properties. Here's an example configuration file:\n\n```bash\n$ cat config.yml\n---\nwork_dir: \"/var/lib/cpid\"\nnetwork_type: \"tcp\"\naddress: \"0.0.0.0:9999\"\ncidr: \"10.0.0.0/16\"\n```\n- `work_dir:` The location where all bosh state (stemcells, disks, containers) will be kept. If the directory does not exist, it will be created. A directory with high disk space and that can sustain heavy writes is preferred.\n- `network_type:` Either `unix` or `tcp`. The protocol type that the daemon will listen as. Since this server must be accessed by both the [director](https://bosh.io/docs/bosh-components/#director) and your bootstrap environment, `tcp` is more flexible and thus supported. `unix` support might be removed in the future.\n- `address:` The listen address for the server. With `tcp` it is the form of `\u003cIP\u003e:\u003cPORT\u003e` and with `unix` it is the location of the unix socket. Parent directories will be created if they do not exist. `unix` support might be removed in the future.\n- `cidr:` The CIDR block to be used for containers IPs. A network bridge and gateway will automatically be created from this value. The gateway IP will automatically be assigned at x.x.x.1/xx. \n\n## CPI\n\n### Prerequisites\n\n- [Golang](https://golang.org): 1.10+\n- [BOSH CLI](https://bosh.io/docs/cli-v2/)\n\nThe master branch of this repository keeps an up-to-date reference to a pre-built CPI ready for use with [bosh-deployment](https://github.com/cloudfoundry/bosh-deployment/tree/v1.1.0). To utilize in a the BOSH fashion, simply use the `-o` option to the ops-file at [./operations/runc-cpi.yml](./operations/runc-cpi.yml) and pass in the necessary variables. For example:\n\n```bash\n$ cd bosh-runc-cpi-release\n$ bosh create-env ../bosh-deployment/bosh.yml \\\n    -o ./operations/runc-cpi.yml \\\n    --state ./state.json \\\n    --vars-store ./creds.yml \\\n    -v director_name=director \\\n    -v external_cpid_ip=127.0.0.1 \\\n    -v internal_cpid_ip=192.168.65.3 \\\n    -v internal_nameserver=192.168.65.1 \\\n    -v internal_ip=10.0.0.4 \\\n    -v internal_gw=10.0.0.1 \\\n    -v internal_cidr=10.0.0.0/16\n```\n\n### variables\n- `director_name:` Name for your bosh director\n- `external_cpid_ip:` Network address of the runc-daemon server used **at bootstrap**. The port of `9999` and network_type of `tcp` is assumed but these can be changed in the ops-file.\n- `internal_cpid_ip:` Network address of the runc-daemon server used **by the director** container. The port of `9999` and network_type of `tcp` is assumed but these can be changed in the ops-file.\n- `internal_nameserver:` This is the nameserver address that will be configured with every container. When running inside of VM, you may opt to choose the nameserver of the VM itself, otherwise `8.8.8.8` is perfectly valid.\n- `internal_ip:` The IP that the bosh director container will be assigned. Your value must fall within the `cidr` that was configured with runc-daemon.\n- `internal_gw:` The gateway that will be used by containers in a bridge network. You must specify the `x.x.x.1` value of the `cidr` that was configured with runc-daemon, since the runc-daemon server has *pre-configured* a gateway at that IP.\n- `internal_cidr:` The IP range that container will be assigned. You must specify the value for `cidr` that was configured with your runc-daemon.\n\nYou may opt to use the cloud-config.yml found in this repository at [./operations/cloud-config.yml](./operations/cloud-config.yml) for reference, choosing to adjust the network IPs for your specific configuration.\n\n**Note:** As of right now, only bosh-deployment [v1.1.0](https://github.com/cloudfoundry/bosh-deployment/tree/v1.1.0) is supported.\n\n### Building\n\nWith this repository cloned and all the submodules initialized. Simply compile with Go tooling. Cross-compiling is completely supported.\n\n```bash\n$ cd bosh-runc-cpi-release\n$ export GOPATH=$PWD\n$ export GOARCH=amd64\n$ GOOS=linux go build \\\n    -o ./runc-cpi-linux \\\n    github.com/aemengo/bosh-runc-cpi/cmd/cpi\n$ GOOS=darwin go build \\\n    -o ./runc-cpi-darwin \\\n    github.com/aemengo/bosh-runc-cpi/cmd/cpi    \n```\n\nTo go further and create a BOSH release:\n\n```bash\n$ bosh add-blob ./runc-cpi-darwin runc-cpi-darwin\n$ bosh add-blob ./runc-cpi-linux runc-cpi-linux\n$ bosh create-release --name=bosh-runc-cpi --version=\u003cversion\u003e --tarball=\u003ctarball-path\u003e.tgz\n```\n\nThen to test your developement bosh-release, you may edit the ops-file at [./operations/runc-cpi.yml](./operations/runc-cpi.yml). You must replace all references of `/releases/-` and `release:` to point to your location and name of your new release, respectively.\n\nFinally you can follow the instructions [here](#CPI) to see it in action.\n\n## License\n\n[Apache 2.0](LICENSE).\n\nCopyright (c) 2018 Anthony Emengo","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faemengo%2Fbosh-runc-cpi-release","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faemengo%2Fbosh-runc-cpi-release","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faemengo%2Fbosh-runc-cpi-release/lists"}