{"id":13646344,"url":"https://github.com/firecracker-microvm/firecracker-go-sdk","last_synced_at":"2025-05-14T11:08:54.865Z","repository":{"id":38011709,"uuid":"156933116","full_name":"firecracker-microvm/firecracker-go-sdk","owner":"firecracker-microvm","description":"An SDK in Go for the Firecracker microVM API","archived":false,"fork":false,"pushed_at":"2025-05-05T15:52:30.000Z","size":1434,"stargazers_count":532,"open_issues_count":41,"forks_count":131,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-05-05T16:35:42.580Z","etag":null,"topics":["firecracker","firecracker-api","firecracker-vm","golang-library","sdk","virtual-machine"],"latest_commit_sha":null,"homepage":"","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/firecracker-microvm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-11-10T00:32:41.000Z","updated_at":"2025-05-05T15:49:47.000Z","dependencies_parsed_at":"2023-12-17T22:41:43.892Z","dependency_job_id":"43b2caa8-6b69-4268-89ad-c3040658754f","html_url":"https://github.com/firecracker-microvm/firecracker-go-sdk","commit_stats":{"total_commits":457,"total_committers":50,"mean_commits":9.14,"dds":0.7833698030634573,"last_synced_commit":"a29fc8f9cc0f93207f0c47c51e145ec41fae015f"},"previous_names":["firecracker-microvm/go-firecracker"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firecracker-microvm%2Ffirecracker-go-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firecracker-microvm%2Ffirecracker-go-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firecracker-microvm%2Ffirecracker-go-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firecracker-microvm%2Ffirecracker-go-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firecracker-microvm","download_url":"https://codeload.github.com/firecracker-microvm/firecracker-go-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129484,"owners_count":22019628,"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":["firecracker","firecracker-api","firecracker-vm","golang-library","sdk","virtual-machine"],"created_at":"2024-08-02T01:02:53.360Z","updated_at":"2025-05-14T11:08:54.826Z","avatar_url":"https://github.com/firecracker-microvm.png","language":"Go","funding_links":[],"categories":["Go","SDK","Foundational sandbox primitives and low-level tooling"],"sub_categories":["Security","Linux"],"readme":"A basic Go interface to the Firecracker API\n====\n\n[![Build status](https://badge.buildkite.com/de08ca676829bedbf6de040c2c2ba1a5d2892e220997c2abdd.svg?branch=main)](https://buildkite.com/firecracker-microvm/firecracker-go-sdk)\n[![GoDoc](https://godoc.org/github.com/firecracker-microvm/firecracker-go-sdk?status.svg)](https://godoc.org/github.com/firecracker-microvm/firecracker-go-sdk)\n\nThis package is a Go library to interact with the Firecracker API. It\nis designed as an abstraction of the OpenAPI-generated client that\nallows for convenient manipulation of Firecracker VM from Go programs.\n\nThere are some Firecracker features that are not yet supported by the\nSDK.  These are tracked as GitHub issues with the\n[firecracker-feature](https://github.com/firecracker-microvm/firecracker-go-sdk/issues?q=is%3Aissue+is%3Aopen+label%3Afirecracker-feature)\nlabel . Contributions to address missing features are welcomed.\n\nDeveloping\n---\n\nPlease see [HACKING](HACKING.md)\n\nBuilding\n---\n\nThis library requires Go 1.23 or later and Go modules to build.  A Makefile is provided\nfor convenience, but is not required.  When using the Makefile, you can pass\nadditional flags to the Go compiler via the `EXTRAGOARGS` make variable.\n\nTools\n---\n\nThere's a [firectl](https://github.com/firecracker-microvm/firectl/)\ntool that provides a simple command-line interface to launching a\nfirecracker VM. It also serves as an example client of this SDK.\n\nNetwork configuration\n---\n\nFirecracker, by design, only supports Linux tap devices. The SDK\nprovides facilities to:\n* Attach a pre-created tap device, optionally with static IP configuration, to\n  the VM. This is referred to as a \"static network interface\".\n* Create a tap device via [CNI](https://github.com/containernetworking/cni) plugins, \n  which will then be attached to the VM automatically by the SDK. This is referred \n  to as a \"CNI-configured network interface\"\n  \n### CNI\nIf a VM is configured with a CNI-configured network interface, by default CNI configuration\nfiles will be sought from `/etc/cni/conf.d` and CNI plugins will be sought under\n`/opt/cni/bin` (both of these values can be overridden via API fields). CNI network lists\nmust be specified in a configuration file at this time.\n\nIt's currently highly recommended to use CNI configuration that includes\n[tc-redirect-tap](https://github.com/awslabs/tc-redirect-tap) as a chained plugin.\nThis will allow you to adapt pre-existing CNI plugins/configuration to a tap device\nusable by a Firecracker VM.\n\n#### Example\n\nWith the following file at `/etc/cni/conf.d/fcnet.conflist`:\n```\n{\n  \"name\": \"fcnet\",\n  \"cniVersion\": \"0.3.1\",\n  \"plugins\": [\n    {\n      \"type\": \"ptp\",\n      \"ipMasq\": true,\n      \"ipam\": {\n        \"type\": \"host-local\",\n        \"subnet\": \"192.168.127.0/24\",\n        \"resolvConf\": \"/etc/resolv.conf\"\n      }\n    },\n    {\n      \"type\": \"firewall\"\n    },\n    {\n      \"type\": \"tc-redirect-tap\"\n    }\n  ]\n}\n```\n\nand the \n[`ptp`](https://github.com/containernetworking/plugins/tree/master/plugins/main/ptp), \n[`host-local`](https://github.com/containernetworking/plugins/tree/master/plugins/ipam/host-local),\n[`firewall`](https://github.com/containernetworking/plugins/tree/master/plugins/meta/firewall),\nand `tc-redirect-tap` CNI plugin binaries installed under `/opt/cni/bin`, you can specify,\nin the Go SDK API, a `Machine` with the following `NetworkInterface`:\n```go\n{\n  NetworkInterfaces: []firecracker.NetworkInterface{{\n    CNIConfiguration: \u0026firecracker.CNIConfiguration{\n      NetworkName: \"fcnet\",\n      IfName: \"veth0\",\n    },\n  }}\n}\n```\n\nNote that `NetworkName` in the `CNIConfiguration` of the API matches the `name` field \nspecified inside the `/etc/cni/conf.d/fcnet.conflist` file.\n\nWith the above configuration, when the Firecracker VM is started the SDK will invoke\nCNI and place the final VM inside the resultant network namespace. The end result being:\n* Outside the network namespace, a single veth endpoint created by the `ptp` plugin will\n  exist with a static IP from the `host-local` plugin (i.e. `192.168.127.1`)\n  * Users can obtain the IP address and other static network configuration generated for\n    their machine via CNI by inspecting the network interface's `StaticConfiguration`\n    field, which will be automatically filled out after the machine has been started.\n  * The IP address, for example, can be obtained at\n    `NetworkInterfaces[0].StaticConfiguration.IPConfiguration.IPAddr` after a call to the\n    machine object's `Start` method succeeds.\n* Inside the VM's network namespace:\n    * The other side of the veth device will exist with name `veth0`, as specified by the\n      `IfName` parameter above, and a different IP (i.e. `192.168.127.2`)\n    * The tap device created by `tc-redirect-tap`, which will not have an IP but will have\n      all of its traffic mirrored with the `veth0` device\n* Inside the actual Firecracker VM guest:\n    * A network interface with the same IP as that of `veth0` (i.e. `192.168.127.2`)\n    * Traffic sent on this device will be mirrored with the external `veth0` device,\n      so from a practical perspective the VM's internal network interface will externally\n      appear the same as `veth0`\n    * The internal name of the interface is determined by the Guest OS, not the Firecracker\n      Go SDK.\n\nNote that the `ptp` and `host-local` plugins are not required, they are just used in this\nexample. The `tc-redirect-tap` plugin can be chained after any CNI plugin that creates a\nnetwork interface. It will setup the tap device to be mirrored with the `IfName` device\ncreated by any previous plugin. Any IP configuration on that `IfName` device will be\napplied statically to the VM's internal network interface on boot.\n\nAlso note that use of CNI-configured network interfaces will require the SDK to be running with at least\n`CAP_SYS_ADMIN` and `CAP_NET_ADMIN` Linux capabilities (in order to have the \nability to create and configure network namespaces).\n\n### Network Setup Limitations\nThese limitations are a result of the current implementation and may be lifted in the future:\n* For a given VM, if a CNI-configured network interface is specified or a static interface\n  that includes IP configuration is specified, the VM can only have a single\n  network interface, not multiple.\n  * Users can specify multiple static interfaces as long as none of them \n    include IP configuration.\n* DNS nameserver settings will only be effective if the VM's rootfs makes\n  `/etc/resolv.conf` be a symlink to `/proc/net/pnp`.\n* Only up to 2 DNS nameservers can be configured within the VM internally.\n  * If a static network interface specifies more than 2, an error will be \n    returned.\n  * If a CNI-configured network interface receives more than 2 nameservers from the CNI \n    invocation result, the nameservers after the second will be ignored without \n    error (in order to be compatible with pre-existing CNI plugins/configuration).\n\nQuestions?\n---\n\nPlease use\n[GitHub issues](https://github.com/firecracker-microvm/firecracker-go-sdk/issues)\nto report problems, discuss roadmap items, or make feature requests.\n\nIf you've discovered an issue that may have security implications to\nusers or developers of this software, please do not report it using\nGitHub issues, but instead follow\n[Firecracker's security reporting guidelines](https://github.com/firecracker-microvm/firecracker/blob/main/SECURITY.md).\n\nOther discussion: For general discussion, please join us in the\n`#general` channel on the [Firecracker Slack](https://join.slack.com/t/firecracker-microvm/shared_invite/zt-1zlb87h4z-NED1rBhVqOQ1ygBgT76wlg).\n\nLicense\n====\n\nThis library is licensed under the Apache 2.0 License. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirecracker-microvm%2Ffirecracker-go-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirecracker-microvm%2Ffirecracker-go-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirecracker-microvm%2Ffirecracker-go-sdk/lists"}