Scaleway credentials and profile loading
README.md

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:

  1. the environment variables SCW_ACCESS_KEY, SCW_SECRET_KEY, SCW_DEFAULT_ORGANIZATION_ID, SCW_DEFAULT_PROJECT_ID, SCW_DEFAULT_REGION and SCW_DEFAULT_ZONE;
  2. the named profile in $SCW_CONFIG_PATH, or ~/.config/scw/config.yaml by default, chosen by ?name, $SCW_PROFILE or the file's active_profile;
  3. 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.