orbit

Ephemeral sandboxes as an OpenStack service. A client asks for "a machine with these resources"; the service hands it over isolated and reachable over SSH, and when the client is done it makes it disappear entirely. Each sandbox is an orb.

---

The problem

Whoever runs untrusted or destructive work, such as builds, tests or an agent editing a repository, needs a whole machine, not a folder. That machine must be isolated, sized to the work and, when the work ends, it must disappear without leaving anything behind: not the machine, not the key, not the firewall, not the address.

Done by hand, with a handful of openstack commands, each of these points breaks: the available sizes are those in the catalog, a machine may find no room after everything else has been created, a creation that fails halfway leaves scattered pieces, a forgotten deletion leaves an address taken. orbit treats the sandbox as a single object, the orb, which is born whole and dies whole.

What it does

• Accepts the requested size (processors, memory, disk) orb by orb, without catalogs of fixed sizes.
• Reserves the capacity before building: if there is no room it says so right away, instead of failing halfway.
• Creates the orb in the project of whoever asks for it: it appears among their resources and consumes their quota.
• Installs the public key supplied by the client and returns address, user and the machine's host keys for SSH access, so the client verifies whom it connects to.
• Admits SSH only from the network the client names in each request: one address or a small network, within an optional cap set by the operator.
• Restricts outbound connections to the operator's allowed destinations and egress proxy (network policy).
• Deletes the orb's resources through one repeatable operation: capacity, flavor, machine and surrounding resources.
• Tells the truth about the status: every read looks at the real resources, so a machine deleted by hand does not leave behind an orb that lies.

What it does not do

It does not enter the orb: it does not run commands, does not copy files, does not know what runs inside. It hands over an address and steps aside. It does not decide when an orb must end: whoever asked for it decides. It persists no tokens or delegations. It does not prepare images, does not act as a proxy, does not manage more than one machine per orb.

---

Lifecycle of an orb

sequenceDiagram
    autonumber
    actor C as Client
    participant A as orbit
    participant B as Blazar
    participant H as Heat

    C->>A: POST /v1/orbs with size, public key and SSH source network
    A->>B: reserve this capacity in a long-lived lease
    B-->>A: reservation and private flavor
    A-->>C: 202 Accepted, orb in RESERVING

    Note over A,B: wait: the reservation<br/>must become active
    A->>H: create the stack with the reservation's flavor

    C->>A: GET /v1/orbs/{id}
    A->>H: stack status and address
    A-->>C: ACTIVE, SSH address, user and host keys

    C->>A: DELETE /v1/orbs/{id}
    A->>H: delete the stack
    A->>B: delete the lease
    Note over B: destroys the machine,<br/>then the flavor
    A-->>C: 202 Accepted, orb in DELETING

Loading

---

Interface

Clients use the REST API, /v1/orbs. Agents can follow the orbit skill for the create, work and cleanup procedure. People watch the orbs in Horizon, in the read-only Project → Orbit → Orbs panel.

---

Installation

1. Clone DevStack:

   $ git clone https://opendev.org/openstack/devstack
   $ cd devstack

2. Write local.conf, enabling orbit after the Heat and Blazar plugins it depends on:

   $ cat > local.conf <<'EOF'
   [[local|localrc]]
   ADMIN_PASSWORD=secret
   DATABASE_PASSWORD=$ADMIN_PASSWORD
   RABBIT_PASSWORD=$ADMIN_PASSWORD
   SERVICE_PASSWORD=$ADMIN_PASSWORD
   enable_plugin heat   https://opendev.org/openstack/heat
   enable_plugin blazar https://opendev.org/openstack/blazar
   enable_plugin orbit  https://github.com/taekwondodev/orbit
   # Optional: enable the host's egress proxy.
   # Set ORBIT_EGRESS_PROXY_DOMAINS to the hostnames your work needs.
   ORBIT_EGRESS_PROXY=True
   EOF

3. Install:

   $ ./stack.sh

4. If the agent runs on another machine, make the orbs reachable from there by running tools/reach-orbs.sh <host> on it: its header says when to run it again.

5. Give the agent the orbit skill and the credentials of a project, for example those source openrc demo demo sets for demo.

6. Watch the agent's orbs in Horizon: at http://<host>/dashboard, log in as demo with the ADMIN_PASSWORD, pick the demo project in the project menu at the top, and open Project → Orbit → Orbs. DevStack gives demo no default project, so Horizon may open invisible_to_admin instead, where the list is empty.

What each plugin does and what the installation requires: docs/architecture.md.

Tests

The unit tests need no OpenStack. tox.ini defines the test environments and dependencies; the delivery policy selects the checks required for each kind of change.

---

Documents

Document	Content
GLOSSARY	glossary of the domain and of the OpenStack terms used
Architecture	ownership boundaries, composition of an orb, full sequence, installation requirements
API contract	HTTP resources, statuses, errors
orbit skill	how an agent creates, uses and deletes an orb
Stored state	the service's table and reconciliation
Orb template	Heat description of an orb's resources
Decisions	the shape choices, with rejected alternatives and sources