Macstadium Orka

An unofficial and low-effort Go library that wraps around Macstadium's Orka API.

Usage

The best way to learn how to use this library is probably by reading through CLIs in the 'examples' folder.

These example CLIs implement a subset of Macstadium's API quick start guide: they let you create a token for a user, deploy a VM, then purge the VM, and revoke the token.

To run these examples, start by building the binaries:

./scripts/build_examples.sh

Next, create a user and password via the Orka CLI if you haven't already. Create a file named my-user-config.json that contains the following:

{
   "server_url": "http://10.221.188.100",
   "email": "USER_EMAIL_HERE",
   "password": "USER_PASSWORD_HERE"
}

Generate a token for this user by running:

./build/orka-token-create --user-config-path ./my-user-config.json

Copy the printed bearer token into a new JSON file named my-api-config.json that contains the following:

{
   "server_url": "http://10.221.188.100",
   "bearer_token": "YOUR_BEARER_TOKEN"
}

View the available images, then create, deploy, and list your VMs:

Next, create, deploy, and list your VMs:

./build/orka-image-list --api-config-path ./my-api-config.json

# Pick image from above list
BASE_IMAGE="90GCatalinaSSH.img"  

VM_NAME="my-test-vm"

./build/orka-vm-create --api-config-path ./my-api-config.json \
    --base-image="$BASE_IMAGE" \
    --vm-name="$VM_NAME" \
    --cpu-core=6 \
    --vcpu-count=6

# Confirm we can see the newly created VM config
./build/orka-vm-list --api-config-path ./my-api-config.json

./build/orka-vm-deploy --api-config-path ./my-api-config.json \
    --vm-name="$VM_NAME" \
    --enable-vnc=true

Finally, purge your VM and (optionally) revoke your token:

./build/orka-vm-purge --api-config-path ./my-api-config.json \
    --vm-name="$VM_NAME"

./build/orka-token-revoke --api-config-path ./my-api-config.json

Using the library

This library was generated by exporting the Postman collection for v2.1.0 of Macstadium's Orka API, converting it into OpenAPI 3.0 using postman2openapi, then generating a Go client using oapi-codegen.

The generated code can be found in ./pkg/orka/*.gen.go. The package also contains some hand-written code for creating and using an Orka client in ./pkg/orka/core.go.

The generated methods are based on the name of the entry given in the API reference, as opposed to the route.

For example, take the Deploy VM Configuration: /resources/vm/deploy entry.

The name of the entry is "Deploy VM Configuration", so the oapi-codegen will generate the following methods:

# Returns a bare HTTP response without parsing and deserializing it.
client.DeployVmConfiguration(...)

# Returns the parsed and deserialized HTTP response.
client.DeployVmConfigurationWithResponse(...)

# Like DeployVmConfiguration, but lets you set a custom HTTP request body.
client.DeployVmConfigurationWithBody(...)

# Like DeployVmConfigurationWithResponse, but lets you set a custom HTTP request body.
client.DeployVmConfigurationWithBodyWithResponse(...)

In most cases, you will want to use the *WithResponse variant and occasionally the *WithBodyWithResponse variant.

Remember to also handle the case where the response has a non-2xx status code. Just checking the err returned by these methods is unfortunately not sufficient.

Instructions for regenerating

To regenerate the Go code, run the following steps:

1. Visit https://orkadocs.macstadium.com/docs/api-quick-start

2. Make a note of the current API version (upper-left dropdown)

3. Click the "API Reference" button.

4. Click the "Run in Postman" button in the upper-right.

5. Export the Orka API Postman collection.

6. Convert the collection to an OpenAPI 3.0 spec using this tool: https://github.com/kevinswiber/postman2openapi

7. Generate the go types and clients by running:

   go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@v1.9.0
   ./scripts/openapi_spec_to_go.sh

"Roadmap"

This project is low-effort and implements just the bare minimum set of functionality I need to unblock some infra I'm building on top of Orka. In particular, I'm completely punting on the following problems for the time being:

1. There are no tests.
2. The autogenerated API is a bit janky and would benefit from either a cleaner codegen or a handwritten (and streamlined) wrapper library.

My hope is that Macstadium will one day implement a higher-quality SDK that solves the above problems for me.