{"id":13603322,"url":"https://github.com/robur-coop/albatross","last_synced_at":"2025-05-16T05:13:21.161Z","repository":{"id":39706095,"uuid":"96707511","full_name":"robur-coop/albatross","owner":"robur-coop","description":"Albatross: orchestrate and manage MirageOS unikernels with Solo5","archived":false,"fork":false,"pushed_at":"2025-04-11T20:31:33.000Z","size":1119,"stargazers_count":151,"open_issues_count":13,"forks_count":17,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-12T05:58:23.914Z","etag":null,"topics":["deployment","mirageos","ocaml","orchestration","provisioning","security","unikernel","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robur-coop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2017-07-09T19:49:03.000Z","updated_at":"2025-04-09T04:09:46.000Z","dependencies_parsed_at":"2024-05-08T11:30:14.374Z","dependency_job_id":"838a69e8-b178-454d-8d9c-8708681d83fb","html_url":"https://github.com/robur-coop/albatross","commit_stats":null,"previous_names":["robur-coop/albatross","roburio/albatross"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Falbatross","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Falbatross/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Falbatross/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Falbatross/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robur-coop","download_url":"https://codeload.github.com/robur-coop/albatross/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254470970,"owners_count":22076587,"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":["deployment","mirageos","ocaml","orchestration","provisioning","security","unikernel","virtual-machine"],"created_at":"2024-08-01T19:00:18.076Z","updated_at":"2025-05-16T05:13:21.083Z","avatar_url":"https://github.com/robur-coop.png","language":"OCaml","funding_links":[],"categories":["Tools"],"sub_categories":["Unikernel-like"],"readme":"# Albatross: orchestrate and manage MirageOS unikernels with Solo5\n\nThe goal of albatross is robust deployment of [MirageOS](https://mirage.io)\nunikernels using [Solo5](https://github.com/solo5/solo5). Resources managed\nby albatross are network interfaces of kind `tap`, which are connected to\nalready existing bridges, block devices, memory, and CPU. Each unikernel is\npinned (`cpuset` / `taskset`) to a specific core.\n\nAlbatross allows remote management. To deploy or destroy a unikernel, no shell\naccess is necessary. The remote channel is a mutually authenticated (with X.509\ncertificates) TLS connection. Console output of the unikernels is stored in\nmemory in a ring buffer, and accessible remotely. Monitoring data (CPU and\nmemory usage) of the unikernels can be collected as well, and pushed into an\nInflux time series database.\n\nAlbatross consists of multiple processes, each running with the least\nprivileges. Albatross can be run next to other orchestration systems; it does\nnot assume to be the single instance on a dom0 which creates and destroys\nvirtual machines. Resource policies can be dynamically configured for each\nadministrative domain (similar to DNS, a hierarchical naming scheme), and are\nchecked statically (to decrease while going down the tree)\nand dynamically when a new unikernel is to be deployed.\n\nWhen a unikernel is deployed, albatross tries its best to keep it\nrunning, even when the physical hardware reboots, or albatross is restarted.\nWhen the unikernel exits, depending on configuration and its exit code, it is\nre-started. The current set of running unikernels is persisted on disk, though\nthere is no dependency or order for restarting them.\n\nThe scope of albatross is to provide a minimal orchestration system that avoids\nthe need for shell access on the dom0. This leads to mostly immutable - or only\nmutable via albatross - infrastructure. Further dissemination of albatross into\nvirtual machines, and a communication interface for deploying and destroying\nunikernels, is being researched on.\n\n## Components\n\nAlbatross consists of a set of binaries. Several daemons, which communicate in a\nrequest-response style over Unix domain sockets, are run in the host system:\n- `albatrossd`: privileged to create and destroy unikernels\n- `albatross-console`: reads the console output of unikernels\n- `albatross-stats`: statistics gathering (rusage, ifstat, BHyve debug counters)\n- `albatross-tls-endpoint`: remote deployment via TLS (and possibly inetd)\n- `albatross-influx`: statistic reporting from `albatross-stats` to influx\n\nThe main daemon is the privileged `albatrossd`, which supervises unikernels. It opens\na listening Unix domain socket, reads the persisted unikernel configuration,\nstarts these unikernels, and awaits commands. Access can be regulated by Unix\nfile permissions -- only those users who can write to that socket can send\ncommands.\n\n`Albatross-console` does not keep any persistent state, but a ring buffer of console\noutput from each unikernel. These messages can be retrieved by a client as a\nstream of messages (history, and whenever a new line is output, it is sent to\nthe interested client). Each unikernel output can only be read by a single\nclient, to avoid amplification of traffic if lots of clients are connected.\n`Albatrossd` sends a message to `albatross-console` whenever a new unikernel is started,\nupon reception `albatross-console` opens and reads the fifo which the unikernel will\nwrite their standard output to.\n\n`Albatross-stats` periodically gathers statistics (memory, CPU, network, hypervisor)\nfrom all running unikernels.\n\n`Albatross-tls-endpoint` listens on a TCP port, or uses systemd socket activation, or\nvia inetd (remember to add `--syslog` when using `--inetd` to log via syslog),\nand proxies requests from remote clients to the respective daemons described\nabove. It enforces client authentication, and uses the common names of the client\ncertificate chain as the administrative domain. The policies are embedded in CA\ncertificates, and the command is embedded in the leaf certificate.\n\nThe `albatross-client` is provided for both local and remote management. It executes the provided command, and can also prepare certificate signing requests (`--csr`) to send the certificate at a later point.\nIt also includes functionality for generating an initial CA (and server certificate), and signing certificate signing requests.\n\n## Albatross over TLS\n\nAlbatross uses PKI to authenticate both client and server. Requests are signed\nby a certificate authority (CA) that is trusted by the server. CA can delegate\nresources using policies, which happens by creating an intermediate CA.\nRevokation is not implemented, as delegation happens without the server knowing\nabout it.\n\n\nThis example shows how one can delegate part of the resources to a user. There\nare 4 entities:\n- **server**: runs the albatross TLS endpoint\n- **CA**: root certificate authority\n- **intermediate CA**: user certificate authority\n- **client**: requests initiator\n\n_Note_: there are 4 entities but depending on the security model some can exist\non the same machine. For example, when **client** and **intermediate CA** can be\ncombined, requests are automatically signed using `albatross-client --destination` (see step 8).\n\n## Setup\n\nThis step-by-step guide shows how files are generated and to which entity they\nbelong. Filename is in **bold** when it's created by the current step.\n\n1. Generate the root CA certificate and server keypair\n\n```\nalbatross-client generate ca db\n```\n\n\n| description           | | server         |  CA            | intermediate CA | client |\n| --------------------- |-| -------------- | -------------- | --------------- | ------ |\n| _private key_         | | **server.key** | **ca.key**     |                 |        |\n| _public certificate_  | | **server.pem** | **cacert.pem** |                 |        |\n\n2. **server:** start the endpoint using the server keypair and the root CA certificate\n\n```\nalbatross-tls-endpoint cacert.pem server.pem server.key\n```\n\n3. **intermediate CA:** we want to delegate part of the resources to a given\nuser. The user generates a signing request to allow a memory of 1024MB to run\n16 unikernels on CPU IDs 0 and 1.\n\n```\nalbatross-client add-policy user 16 --mem 1024 --cpu 0 --cpu 1 --csr\n```\n\n| description                   | | server     |  CA        | intermediate CA | client |\n| ----------------------------- |-| ---------- | ---------- | --------------- | ------ |\n| _private key_                 | | server.key | ca.key     | **user.key**    |        |\n| _public certificate_          | | server.pem | cacert.pem |                 |        |\n| _certificate signing request_ | |            |            | **user.req**    |        |\n\n4. **CA:** CA signs the user's request, which generates an intermediate CA\ncertificate containing the restriction policies (limited memory, cpu), which in\nturn will be used to sign user requests.\n\n```\nalbatross-client sign cacert.pem db ca.key user.req\n```\n\n| description                   | | server     |  CA        | intermediate CA | client |\n| ----------------------------- |-| ---------- | ---------- | --------------- | ------ |\n| _private key_                 | | server.key | ca.key     | user.key        |        |\n| _public certificate_          | | server.pem | cacert.pem | **user.pem**    |        |\n| _certificate signing request_ | |            |            | user.req        |        |\n\n5. **client:** the client wants to create an unikernel, it has to wrap the request in a\ncertificate signing request which will be submitted to the intermediate CA. Note: you can [download hello-key.hvt](https://builds.robur.coop/job/hello/build/latest/f/bin/hello-key.hvt).\n\n```\nalbatross-client create hello hello-key.hvt --csr [--arg='--hello=albatross-hi'] [--cpu=1]\n```\n\n| description                   | | server     |  CA        | intermediate CA | client        |\n| ----------------------------- |-| ---------- | ---------- | --------------- | ------------- |\n| _private key_                 | | server.key | ca.key     | user.key        | **hello.key** |\n| _public certificate_          | | server.pem | cacert.pem | user.pem        |               |\n| _certificate signing request_ | |            |            | user.req        | **hello.req** |\n\n6. **intermediate CA:** the intermediate CA signs the request\n\n```\nalbatross-client sign user.pem db user.key hello.req\n```\n\n| description                   | | server     |  CA        | intermediate CA | client        |\n| ----------------------------- |-| ---------- | ---------- | --------------- | ------------- |\n| _private key_                 | | server.key | ca.key     | user.key        | hello.key     |\n| _public certificate_          | | server.pem | cacert.pem | user.pem        | **hello.pem** |\n| _certificate signing request_ | |            |            | user.req        | hello.req     |\n\n7. **client:** client sends the signed request to the server,\n`albatross-client sign` appended the intermediate CA certificate to `hello.pem`\nto form the full chain.\n\n```\nalbatross-client certificate cacert.pem hello.pem hello.key --destination \u003cREMOTE_IP:PORT\u003e`\n```\n\n8. Steps 5, 6, and 7 can be done in a single command - if there's no requirement\nto retain the signing request and certificate, and the user keys are on the\nlocal machine.\n\n```\nalbatross-client create hello hello-key.hvt --ca=user.pem --ca-key=user.key --server-ca=cacert.pem --destination \u003cREMOTE_IP:PORT\u003e [--arg='--hello=albatross-hi'] [--cpu=1]\n```\n\n## Installation\n\nBinary packages are available for Debian, Ubuntu and FreeBSD. [How to install](https://robur.coop/Projects/Reproducible_builds).\n\nFor other operating systems / distributions, run `opam install albatross`.\n\nAlso read [the blog article](https://hannes.robur.coop/Posts/Albatross)\nfor the motivation behind albatross and an overview of its functionality.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobur-coop%2Falbatross","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobur-coop%2Falbatross","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobur-coop%2Falbatross/lists"}