Skip to navigation

Examples

The IBEE examples repository is a set of short programs that each do one task with IBEE: usually create a resource, read it, and delete it. Every product has the same task three ways, a main.py (Python SDK), an index.ts (TypeScript SDK) and a cli.sh (CLI), so you can copy the version that matches your tools.

When to use the examples

You want to…Start with
See a whole task working end to end, then copy itThe examples (this page)
Understand one request, its fields and its errorsThe endpoint’s page in the API reference
Learn how tokens, errors, paging and asynchronous work behaveAPI overview
Manage infrastructure as filesThe Terraform examples

How it works

  1. Each folder is one product, with a README that lists the token scopes and the environment variables it reads.
  2. Every example reads your token and workspace from IBEE_TOKEN and IBEE_WORKSPACE_ID.
  3. getting-started creates nothing: it checks your token and prints the site, plan and image IDs that the other examples need.
  4. The other examples create what they need and delete it at the end. VM examples check each operation every few seconds until it has finished (get_compute_operation in the SDKs, ibee ops get in the CLI versions).
  5. The examples use the 0.7.0 SDKs and CLI and Terraform provider 0.8.0, the versions the SDK, CLI and Terraform pages describe. requirements.txt, package.json and each main.tf pin them.

Before you begin

  • Git, Python 3.10 or later, and Node.js 18 or later (for the TypeScript examples). jq for the cli.sh and api.sh scripts.
  • An API token with the scopes the example’s README lists, for example vm.read for getting-started and vm.read plus vm.write for cloud-vms. See Authentication.
  • Your workspace ID. See Find your workspace ID.
  • Credit in your account. Most examples create billable resources (VMs, for example, with HOURLY billing) for a few minutes. If an example stops halfway, delete what it created in the portal.

Run your first example

1

Clone the repository and install the clients

git clone https://github.com/devs-ibee/examples.git
cd examples
pip install -r requirements.txt # ibee, ibee-cli and boto3
npm install # ibee-sdk, tsx and TypeScript
2

Set your token and workspace

export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx"
export IBEE_WORKSPACE_ID="907479"

Set IBEE_ENV=dev as well only if you use a development token (ibee_dev_key_…).

3

Run getting-started

python3 getting-started/main.py

It prints the sites, plans and images you can use. Nothing is created. npx tsx getting-started/index.ts, bash getting-started/cli.sh and bash getting-started/api.sh (plain curl) do the same.

4

Save the IDs the other examples need

Copy a site_id, a plan_id from that site and a template_id:

export IBEE_SITE_ID="SITE_ID" IBEE_PLAN_ID="PLAN_ID" IBEE_TEMPLATE_ID="TEMPLATE_ID"
5

Run a product example

python3 cloud-vms/main.py

This creates a cloud VM, waits for it, reads it and deletes it. npx tsx cloud-vms/index.ts and bash cloud-vms/cli.sh do the same.

Compute

Storage

Networking and security

Terraform

Interfaces

InterfaceInstallVersion the examples useReference
Python SDKpip install ibee0.7.xSDKs
TypeScript SDKnpm install ibee-sdk0.7.xSDKs
CLIpip install ibee-cli0.7.xCLI
HTTPcurl and jq—API overview
Terraformdevs-ibee/ibee from the Terraform Registry0.8.x (~> 0.8.0 in each main.tf)Terraform

Virtual IPs, Bare Metal Servers, SSH keys, ISOs and Email Service are managed in the portal and have no public API yet, so they have no examples.

Troubleshooting

You seeWhat it meansWhat to do
KeyError: 'IBEE_SITE_ID' or an empty --site-idThe example needs IDs from getting-startedRun getting-started and export IBEE_SITE_ID, IBEE_PLAN_ID and IBEE_TEMPLATE_ID.
401 invalid_api_keyThe token is wrong, cut short, or for the other environmentExport the whole token; set IBEE_ENV=dev only for a development token.
403 insufficient_scopeThe token lacks a scope the example’s README listsCreate a token with those permissions.
402 billing_deniedBilling refused the createAdd credit; see Billing refusals.
An example stopped before deleting what it createdAn error or Ctrl+C interrupted itDelete the leftover resource in the portal, or with the CLI (ibee vms delete VM_ID --public-ip-action release --yes).
npx tsx asks to install tsxnpm install wasn’t run in the repository folderRun npm install in examples/ first.

Open an issue for questions or requests.