Annonce du Clever Cloud Rust SDK

Bonjour 🖖, amis humains et robots ! Notre équipe d’ingénieurs est fière d’annoncer un tout nouveau kit de développement logiciel (sdk) Rust, également connu sous le nom de “clevercloud-sdk” sur crates.io.

Certains d’entre vous ont peut-être remarqué qu’il y a de nouveaux dépots sur notre organisation GitHub. Ces dépots sont nommés “clevercloud-sdk-rust” et “oauth10a-rust“. Leur objectif est de fournir un moyen pratique d’interagir avec l’API de Clever Cloud avec des fonctionnalités intéressantes que nous allons vous faire découvrir dans ce blogpost!

Conçu pour être asynchrone

Le kit de développement logiciel et le client oauth 1.0a sont principalement construits sur la base de deux crates bien connus de la communauté. Il s’agit de hyper, et du runtime asynchrone qui le propulse, nommé tokio.

L’idée principale derrière l’utilisation de la crate hyper et par extension du runtime asynchrone tokio est de tirer parti de l’écosystème actuel qui gravite autour de ces crates et des efforts pour intégrer une nouvelle API du kernel appelée io_uring. Une fois que cette nouvelle API kernel sera intégrée dans le runtime tokio, cela conduira à une amélioration significative de la performance, selon le billet de blog de l’annonce de tokio. Nous attendons avec impatience cette amélioration qui nous permettra d’itérer plus rapidement ! 🚀

L’observabilité au cœur de l’outil

Ces crates sont développées avec l’idée d’être entièrement observables. Cela a été réalisé par d’autres crates bien connus comme log et tracing, ou en utilisant des initiatives communautaires comme le crate prometheus. Les intégrations de ces crates font partie du système de flags de fonctionnalités de compilateur fourni par le dépot cargo.

Façade de logs standard

Tout d’abord, vous devez savoir que la façade de logs standard est activée par défaut. Elle fournira des informations utiles sur les comportements internes des crates ci-dessus, en utilisant le logger standard s’il est défini. Elle vous aidera à comprendre comment les appels à l’API de Clever Cloud sont réalisés avec quelques informations de débogage, si vous en avez besoin.

clevercloud-sdk = { version = "^0.10.0", default-features = false }

Si vous voulez le désactiver, vous devez désactiver les ensembles par défaut de fonctionnalités activées. Cela peut être réalisé en utilisant la syntaxe suivante pour le crate clevercloud-sdk dans votre fichier Cargo.toml.

Orienté métriques

Nous pensons que les métriques sont importantes. Elles aident à comprendre les systèmes en mettant en corrélation des choses qui ne semblent pas être liées au départ.

C’est pourquoi nous avons lancé Clever Cloud Metrics assez rapidement, il y a quelques années. Nous l’avons récemment enrichi de nouvelles fonctionnalités en offrant plus de moyens d’interroger Clever Cloud Metrics, grâce à Erlenmeyer qui est un proxy de langage d’interrogation de séries temporelles. Vous trouverez plus de détails sur la façon dont vous pouvez l’utiliser dans cet article de blog.

Enfin, nous avons annoncé le produit Tardis qui vous permet de nous envoyer vos métriques et nous nous occupons du reste comme nous le faisons toujours et, plus récemment, nous avons intégré des tableaux de bord Grafana pré-construits pour vous aider à visualiser l’état de vos applications et add-ons, vous pouvez en savoir plus ici.

Revenons à nos crates. Vous pouvez activer la collecte de métriques à l’aide du crate prometheus, en activant les flags de métriques au niveau du crate dans votre fichier Cargo.toml. Cela peut être réalisé en utilisant la syntaxe suivante.

clevercloud-sdk = { version = “^0.10.0”, features = [“metrics”] }

Une fois cette fonctionnalité activée, il n’y a plus grand-chose à faire. Vous devrez exposer les métriques via un serveur HTTP ou les envoyer en utilisant la passerelle push de prometheus. Cette partie est décrite dans la documentation du crate prometheus ou dans ces exemples.

Capacités de traces

Le dernier pilier de l’observabilité, mais non le moindre, sont les traces. Selon l’initiative et la documentation d’OpenTelemetry, les traces sont définies comme suit :

Les traces suivent la progression d’une demande unique, appelée trace, telle qu’elle est traitée par les services qui composent une application. La demande peut être initiée par un utilisateur ou une application. Les traces distribués sont une forme de trace qui traverse les frontières du processus, du réseau et de la sécurité. Chaque unité de travail dans une trace est appelée un span ; une trace est un arbre de spans. Les spans sont des objets qui représentent le travail effectué par les services ou les composants individuels impliqués dans une requête au fur et à mesure qu’elle circule dans un système. Un span contient un contexte de span, qui est un ensemble d’identifiants uniques au monde représentant la demande unique dont chaque span fait partie. Un span fournit des mesures de Demande, Erreur et Durée (RED) qui peuvent être utilisées pour déboguer les problèmes de disponibilité et de performance…

Documentation sur OpenTelemetry

Si vous souhaitez vous intéresser de plus près aux traces, même si elles ne sont pas en Rust, vous pouvez consulter l’organisation OpenTelemetry GitHub. Il y a beaucoup de bibliothèques, de SDKs et de documentation pour vous aider à construire votre solution de traces ou à l’intégrer à une solution déjà existante. En outre, si vous utilisez le langage rust et peut-être le runtime tokio, vous pouvez consulter les articles de blog qui expliquent comment les traces fonctionnent dans le runtime asynchrone ci-dessus et comment les visualiser à l’aide de la console ou en utilisant le connecteur OpenTelemetry qui permet d’envoyer des traces à plus de puits, la liste est disponible sur le dépot rust GitHub d’OpenTelemetry.

Alors comment activer concrètement la fonctionnalité de traces à l’aide de clevercloud-sdk ? Comme mentionné ci-dessus, toutes les fonctionnalités sont pilotées par un flag de fonctionnalité, donc pour obtenir des capacités de traces, vous devez activer le flag de trace.

clevercloud-sdk = { version = “^0.10.0”, features = [“trace”] }

Une fois que l’indicateur de fonctionnalité a été activé, vous devrez collecter et envoyer des traces en utilisant le connecteur et les sinks ci-dessus.

À quoi ça ressemble ?

Prenons un exemple concret pour illustrer ce à quoi ressemble le clevercloud-sdk. Mais avant de passer en revue l’utilisation de clevercloud-sdk, je vais vous présenter les dépendances et les exigences dont vous aurez besoin. La première chose à faire est de déclarer les crates dans le fichier Cargo.toml.

[dependencies] tokio = { version = “^1.17.0”, features = [“full”] } clevercloud-sdk = { version = “^0.10.0”, features = [“metrics”, “tokio”, “trace”, “jsonschemas”] }

Nous sommes maintenant capables d’écrire un logiciel à l’aide de clevercloud-sdk. Voici un exemple de la façon d’utiliser le SDK :

...
use clevercloud_sdk::{
    oauth10a::{
        proxy::{self, ProxyConnectorBuilder},
        Credentials,
    },
    v2::myself,
    Client,
};
...

// See the full code at:
// - https://github.com/CleverCloud/clevercloud-sdk-rust/blob/main/examples/cleverctl
// - https://github.com/CleverCloud/clevercloud-sdk-rust/blob/main/examples/cleverctl/src/cmd/myself.rs
pub async fn get(config: Arc<Configuration>, output: &Output) -> Result<(), Error> {
    let credentials: Credentials = config.credentials.to_owned().into();
    let connector = ProxyConnectorBuilder::try_from_env().map_err(Error::ProxyConnector)?;
    let client = Client::builder()
        .with_credentials(credentials)
        .build(connector);

    let user = myself::get(&client).await.map_err(Error::Get)?;

    println!(
        "{}",
        output
            .format(&user)
            .map_err(|err| Error::FormatOutput(Box::new(err)))?
    );

    Ok(())
}

Un autre exemple du sdk qui interagit avec les add-ons :

… use clevercloud_sdk::{ oauth10a::{ proxy::{self, ProxyConnectorBuilder}, Credentials, }, v2::addon, Client, }; … // See the full code at: // – https://github.com/CleverCloud/clevercloud-sdk-rust/blob/main/examples/cleverctl // – https://github.com/CleverCloud/clevercloud-sdk-rust/blob/main/examples/cleverctl/src/cmd/addon/mod.rs pub async fn list( config: Arc, output: &Output, organisation_id: &str, ) -> Result<(), Error> { let credentials: Credentials = config.credentials.to_owned().into(); let connector = ProxyConnectorBuilder::try_from_env().map_err(Error::ProxyConnector)?; let client = Client::builder() .with_credentials(credentials) .build(connector); let addons = addon::list(&client, organisation_id) .await .map_err(|err| Error::List(organisation_id.to_owned(), err))?; println!( “{}”, output .format(&addons) .map_err(|err| Error::FormatOutput(Box::new(err)))? ); Ok(()) }

Vous pouvez trouver le code source complet de l’exemple d’interface de ligne de commande dans le dépot clevercloud-sdk dans le dépot d’exemples ou vous pouvez suivre ce lien.

Quelles sont les prochaines étapes ?

Jetons un coup d’œil aux fonctionnalités à venir qui seront intégrées dans ces crates.

Biscuit et token porteur oauth2

Chez Clever Cloud, nous travaillons sur un nouveau token d’authentification et d’autorisation appelé Biscuit. Plus de détails à ce sujet dans le billet de blog d’introduction.

Ce nouveau token d’authentification et d’autorisation fonctionnera avec la norme OAuth 2.0. L’une des tâches du SDK et du client est de faciliter la transition de OAuth 1.0a à OAuth 2.0 en utilisant Biscuit.

Nouvelles fonctionnalités !

Le kit de développement logiciel va se développer pour prendre en charge l’ensemble de l’API. La prochaine fonctionnalité est l’intégration du bus d’événements afin de s’abonner aux événements qui se produisent sur la plateforme de Clever Cloud. Vous serez par exemple en mesure de recevoir des notifications sur le déploiement d’une application, etc.

En outre, ces caisses sont utilisées pour construire un autre logiciel que vous avez découvert dans un autre article du blog. Il présente un opérateur Kubernetes que vous pouvez utiliser sur OpenShift, qui expose les add-ons de Clever Cloud comme des custom ressources.