Create an instance pool
Create a pool from a launch template and a desired count. The desired_count instances are spawned synchronously; a background reconciler then converges member_count toward desired_count as it’s changed. min_count/max_count default to desired_count.
The top-level tags label the pool itself; template.tags are stamped
on every instance it launches.
Authorizations
BASALTIC-HMAC-SHA256 request signing for service-account (access-key) auth.
An AWS-SigV4-style scheme: an HMAC-SHA256 over a canonical request, keyed by a
signing key derived from your secret access key. The basaltic CLI does this
for you; the steps below are for a non-CLI client.
Headers you send
Authorization(this scheme) — format below.X-Date: request time in UTC, compact ISO-8601 basic:YYYYMMDDTHHMMSSZ(e.g.20240115T103000Z). Must be within 5 minutes of server time.X-Nonce: random per-request value (e.g. 16+ bytes of hex). Required — it is what makes each signature unique so the server can reject replays.X-Datealone is not enough (one-second resolution;UNSIGNED-PAYLOADnever enters the canonical request).X-Content-Sha256(optional): lowercase-hex SHA-256 of the request body, to bind the exact bytes to the signature — the server re-hashes and rejects a mismatch. Omit it, and put the literalUNSIGNED-PAYLOADin the body-hash slot, for an empty body or a streaming upload that shouldn't be buffered.
Authorization header format
<date>:YYYYMMDD(the day part of X-Date).<region>: target region code (e.g.sa-saopaulo-1), orglobalfor the region-agnostic (IAM) endpoints.<service>:basaltic.SignedHeaders: the covered header names, lowercased and sorted, joined by;— at minimumhost;x-date;x-nonce(all three required).Signature: lowercase hex from step 4.- Note the
,(comma + space) between the three Authorization parameters.
Step 1 — canonical request
Join these six lines with \n (LF):
canonical-path: the URL-escaped request path (e.g./v1/compute/instances).canonical-query: each query key and value URL-encoded, sorted by key then value, joined by&; empty string when there is no query.canonical-headers: for each signed header,name:value(name lowercased, value trimmed), sorted by name, each followed by a trailing\n.signed-headers: the same names, lowercased, sorted, joined by;.body-hash: lowercase-hex SHA-256 of the body, or the literalUNSIGNED-PAYLOAD.
Step 2 — string to sign
Join with \n:
The second line is the credential date at midnight — NOT the X-Date value — and the third is the credential scope without the access-key id.
Step 3 — derive the signing key (HMAC chain over your secret)
Step 4 — signature
Example (POST with a JSON body)
Request validity
- Valid for 5 minutes from the X-Date timestamp.
- The signature must cover at least
host,x-date, andx-nonce. - Mutating requests (POST/PUT/PATCH/DELETE) that present a signed nonce are
anti-replay guarded for the drift window; omitting
X-Nonceis rejected.
Rate limits
There is no global request budget: a limit applies only where an operation
documents a 429 response, and each such endpoint counts its own fixed
window. Everything else is bounded by quota, not by request rate.
Per-endpoint request limits
A few endpoints are limited in front of the handler, counted per caller —
the authenticated principal when the request carries credentials, the
client IP otherwise. On this API surface that is the public region
catalogue, GET /v1/regions: it guards no secret, and the budget is there
because the catalogue is unauthenticated and database-backed.
An operation that is limited says so by documenting a 429. These
responses — 429 and 2xx — carry the budget, so a client can pace
itself instead of discovering the ceiling by hitting it:
X-RateLimit-Limit— requests allowed per window on this endpoint. Authoritative: read it rather than hard-coding a number.X-RateLimit-Remaining— requests left in the window (0 on a 429).X-RateLimit-Reset— seconds until the window resets. A duration, not a timestamp, so it needs no clock agreement.Retry-After— on a 429 only; seconds to wait. Never zero.
Over the limit the response is 429 with error code RATE_LIMITED. Honor
Retry-After — retrying sooner is refused and extends the window, since
the refused attempt is itself counted.
Service-level limits
Some resources meter the work itself rather than the request, and are
documented on the operation. They return 429 with their own error code
and no rate-limit headers, because the budget is not a per-endpoint window:
sending email is capped per (account, identity) per second
(EMAIL_RATE_LIMIT), and charge attempts are capped per invoice
(INVOICE_PAYMENT_ATTEMPTS_EXHAUSTED).
Headers
Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token.
255Body
Two shapes are accepted for the launch config. template is the current one — the same fields instance create takes. The flat fields beside it are the shape pools shipped with; they still work, and the response renders both, so nothing written against either has to move.
They are alternatives, not layers: sending template together with any flat launch field is refused with a 400 rather than resolved by a precedence rule you would have to know to predict what your replicas boot as.
The pool's own fields — name, description, tags, sizing — stay at the top level in both shapes, because they describe the pool rather than the instances in it. A flavor and a primary subnet are required either way: as template.flavor_id + template.networks[0].subnet_id, or as the flat flavor_id + subnet_id.
"web-asg"
Labels on the pool resource, for IAM conditions (basalt:RequestTag/<key> here, basalt:ResourceTag/<key> on later operations) and cost attribution. They are not propagated to the instances the pool launches; template.tags is that set.
A pool field, so it may be sent with either launch-config shape — unlike the deprecated flat fields below, it does not conflict with template. Replica tags are only reachable through template.tags.
The pool's launch config, in the shape a standalone instance create takes: same field names, same types, same meanings, so a client that can build an instance can build a pool of them without a second, narrower contract to learn.
It belongs to the pool. There is no separate launch-template resource to create, version or share between pools.
Networking is one ordered networks list, index 0 being the primary NIC, replacing the flat subnet_id + extra_nics split. ip_address and mac are part of that shared NIC shape but are refused here: every replica launches from this one template, so a fixed address would have the second replica ask for one the first already holds.
Superseded by template.flavor_id.
Superseded by template.image_id.
Superseded by template.networks[0].subnet_id.
Superseded by template.networks[0].security_group_ids.
Superseded by template.key_names.
Superseded by template.user_data.
Superseded by template.metadata.
Superseded by template.iam_role_id.
Superseded by template.boot_volume_size_gb.
1 <= x <= 16384Superseded by template.boot_volume_type.
ssd, nvme Superseded by template.networks[1:].
Superseded by template.data_volumes.
Superseded by template.assign_public_ip.
0 <= x <= 1002
0 <= x <= 1001
1 <= x <= 1003
Response
Pool created; initial instances spawned.
A launch template plus a desired count. Creating a pool spawns desired_count instances; a reconciler converges member_count toward desired_count as it changes. member_count is how many members the pool holds; live_count is how many of them are running.
A pool carries two tag sets and they answer different questions. tags labels the pool resource — that is what an IAM condition reads as basalt:ResourceTag/<key> and what a cost report groups by, and it reaches no instance. template.tags is the set stamped on every replica the pool launches.