- OCaml 99%
- Raku <1%
- Shell <1%
ocaml-scaleway #
A Scaleway API client for OCaml, split into a pure request builder and an Eio runtime.
Deploying to Scaleway from OCaml means calling the Instance, Block Storage,
Container Registry, Serverless Containers, IAM and Secret Manager APIs, and
re-running the same deploy
without creating a second server or a second security group each time. The
scaleway package builds every call as a value without doing any I/O, and
scaleway-eio performs those calls and adds the operations that take several:
walking every page, finding a resource by name, creating only if missing, and
waiting for a resource to settle.
The client covers the control plane only. Object Storage is the separate s3
package.
| Module | API | Resources |
|---|---|---|
Iam |
/iam/v1alpha1 |
applications, policies, API keys |
Secret_manager |
regional, /secret-manager |
secrets, versions |
Instance |
zonal, /instance |
servers, user data, flexible IPs, security groups, snapshots, images |
Block |
zonal, /block/v1 |
volumes, snapshots |
Elastic_metal |
zonal, /baremetal/v1 |
servers, installation, user data, OS list, partitioning schemas |
Registry |
regional, /registry/v1 |
namespaces |
Container |
regional, /containers/v1 |
Serverless Containers: namespaces, containers, domains |
Account |
/account/v3 |
projects |
Console |
zonal, WebSocket | serial console |
Installation #
Install with opam:
opam install scaleway
If opam cannot find the package, it may not yet be released in the public
opam-repository. Add the overlay repository, then install it:
opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
opam update
opam install scaleway
Usage #
A profile holds the credentials and default region and zone, resolved the way
the scw CLI resolves them:
match Scaleway_eio.Profile.load () with
| Ok p ->
Printf.printf "access-key: %s\nregion: %s\n" p.access_key
(Scaleway.Region.to_string p.default_region)
| Error e -> prerr_endline (Scaleway.Error.to_string e)
Zonal APIs are scoped to a Zone.t and regional ones to a Region.t. They are
distinct types because passing a region where a zone belongs is the commonest
Scaleway mistake, and the API answers it with an opaque 404:
# Scaleway.Zone.of_string "fr-par" |> Result.map_error Scaleway.Error.to_string
- : (Scaleway.Zone.t, string) result =
Error
"invalid Scaleway request: \"fr-par\" is a region, not a zone: append the zone index, as in \"fr-par-1\""
Requests are values #
Every operation in scaleway returns a Request.t, a call that is described
but not made: its method, path, query, body and the decoder for its response.
The URL and the body, which are otherwise only visible against the live
service, become values a test can assert on, and a plan-then-apply deploy can
show a change before making it.
# let profile =
Result.get_ok
(Scaleway.Profile.decode
"access_key: AK\nsecret_key: SK\ndefault_zone: fr-par-1\n" ())
in
let request =
Result.get_ok
(Scaleway.Instance.Server.attach_volume profile ~server_id:"abc"
~volume_id:"v1" ())
in
Fmt.str "%a" Scaleway.Request.pp request
- : string = "POST /instance/v1/zones/fr-par-1/servers/abc/attach-volume"
scaleway-eio performs these requests. On top of that, list walks every
page, find looks a resource up by name, ensure creates a resource unless
one of that name exists, and the wait_* functions poll until a resource has
settled. It retries the idempotent methods up to four times, honouring
Retry-After, and never retries a create: the API has no idempotency key, so
a repeated create would make a second server.
Deploying a server #
This creates a server, gives it cloud-init user data and a data volume, and
powers it on. cloud-init is the program most cloud Linux images run at first
boot: it reads the user data attached to the server, here a #cloud-config
YAML document, and applies it (installing packages, writing files, running
commands). A server is created stopped, so the last two steps are needed
before it runs:
let deploy ~env ~sw profile =
let ( let* ) = Result.bind in
let client = Scaleway_eio.Client.v ~env ~sw profile in
(* [ensure], not [add]: a deploy is re-run. *)
let* server =
Scaleway_eio.Instance.Server.ensure client
(Scaleway.Instance.Server.Create.v ~name:"deploy-1"
~commercial_type:"PRO2-XS"
~image:(Scaleway.Instance.Server.Label "ubuntu_noble") ())
in
let* () =
Scaleway_eio.Instance.Server.set_user_data client ~server_id:server.id
~key:"cloud-init" "#cloud-config\npackages: [docker.io]\n"
in
let* volume =
Scaleway_eio.Block.Volume.ensure client ~name:"deploy-data"
~size:107374182400L ()
in
let* _ = Scaleway_eio.Block.Volume.wait_available client volume.id in
let* server =
Scaleway_eio.Instance.Server.attach_volume client ~server_id:server.id
~volume_id:volume.id ()
in
let* () =
Scaleway_eio.Instance.Server.action client server.id
Scaleway.Instance.Server.Poweron
in
Scaleway_eio.Instance.Server.wait_state client server.id
Scaleway.Instance.Server.Running
Converging a security group #
ensure returns an existing resource untouched. Bringing it to the state you
asked for is a separate call, update for a resource's fields and set_rules
for a security group's rules:
let converge client group_id =
let open Scaleway.Instance.Security_group in
Scaleway_eio.Instance.Security_group.set_rules client ~group_id
[
Rule.v ~protocol:Rule.Tcp ~direction:Rule.Inbound ~action:Rule.Accept
~dest_port_from:443 ();
Rule.v ~protocol:Rule.Tcp ~direction:Rule.Inbound ~action:Rule.Accept
~dest_port_from:80 ();
]
set_rules replaces the whole ordered list in one call. Adding and deleting
rules one at a time leaves a window in which the group is either more open or
more closed than both the old and the new rule set, and on a group that denies
inbound traffic except on a few ports that window is a security problem.
Custom images #
A disk image in Object Storage becomes bootable in two steps: import it as a snapshot, then register an image from the snapshot. Scaleway imports QCOW2 only, so convert a raw image before uploading it.
let register client =
let ( let* ) = Result.bind in
let* snapshot =
Scaleway_eio.Instance.Snapshot.import client ~name:"uniboot"
~bucket:"images" ~key:"uniboot.qcow2" ~size:1073741824L ()
in
(* Rejected imports say why: Scaleway puts it in [error_reason], and the
waiter surfaces it instead of a bare state. *)
let* snapshot = Scaleway_eio.Instance.Snapshot.wait_available client snapshot.id in
let* image =
Scaleway_eio.Instance.Image.add client ~name:"uniboot"
~snapshot_id:snapshot.id ~arch:Scaleway.Instance.Image.Arm64 ()
in
Ok (Scaleway.Instance.Server.Id image.id)
The import size must be a multiple of 512 bytes, between 1 GiB and 1 TiB.
Scaleway.Instance.Snapshot.check_size refuses anything else before the
request is sent, where the API would answer with an opaque
invalid_arguments.
Configuration #
A field of the profile takes the first value found, in this order:
- the environment variables
SCW_ACCESS_KEY,SCW_SECRET_KEY,SCW_DEFAULT_ORGANIZATION_ID,SCW_DEFAULT_PROJECT_ID,SCW_DEFAULT_REGIONandSCW_DEFAULT_ZONE; - the named profile in
$SCW_CONFIG_PATH, or~/.config/scw/config.yamlby default, chosen by?name,$SCW_PROFILEor the file'sactive_profile; - the top-level defaults of the same file.
A missing configuration file is not an error, so the environment alone can carry a complete profile, as it does in CI.
Licence #
ISC. See LICENSE.md.