test

Guide des développeurs pour les services de données Sun Cluster 3.1 10/03

Chapitre 4 Référence concernant l'API de gestion des ressources

Ce chapitre fournit une référence concernant les fonctions d'accès et les méthodes de rappel constituant l'API de gestion des ressources (API GR). Il énumère et décrit brièvement chaque fonction et méthode. Toutefois, la référence faisant foi pour ces fonctions et méthodes se trouve dans les pages de manuel consacrées à l'API GR.

Les informations fournies par ce chapitre sont les suivantes :

Méthodes d'accès à l'API GR

L'API propose des fonctions permettant d'accéder aux propriétés de la ressource, du type de ressource et du groupe de ressources, ainsi qu'à d'autres informations du cluster. Ces fonctions sont fournies sous la forme de commandes shell et de fonctions C, ce qui permet aux fournisseurs de types de ressource de mettre en oeuvre des programmes de contrôle sous la forme de scripts Shell ou de programmes C.

Commandes shell API GR

Les commandes Shell doivent être utilisées dans les mises en oeuvre du script Shell des méthodes de rappel pour les types de ressource représentant des services contrôlés par le RGM du cluster. Vous pouvez utiliser ces commandes pour :

Remarque :

bien que cette rubrique fournisse de brèves descriptions des commandes shell, les différentes pages du manuel, dans la rubrique 1HA, constituent la référence faisant foi pour les commandes shell. Sauf mention contraire, chaque commande correspond à une page de manuel portant le même nom.

Commandes de la ressource API GR

Ces commandes vous permettent d'accéder aux informations relatives à une ressource ou de définir les propriétés Statut et msg_statut de celle-ci.

scha_resource_get

Accède aux informations relatives à une ressource ou à un type de ressource sous le contrôle du RGM. Elle fournit les mêmes informations que la fonction scha_resource_get ().

scha_resource_setstatus

Définit les propriétés Statut et msg_statut d'une ressource sous le contrôle du RGM. Elle est utilisée par le détecteur de la ressource afin d'indiquer l'état de celle-ci tel qu'il le perçoit. Elle propose la même fonctionnalité que la fonction C scha_resource_setstatus().

Remarque :

bien que scha_resource_setstatus() soit d'un intérêt particulier pour les détecteurs de ressources, tout programme peut l'appeler.

Commande du type de ressource

Cette commande accède à des informations sur un type de ressource enregistré auprès du RGM.

scha_resourcetype_get

Cette commande fournit la même fonctionnalité que la fonction C scha_resourcetype_get ().

Commandes du groupe de ressources

Ces commandes vous permettent d'accéder à des informations sur un groupe de ressources ou de redémarrer celui-ci.

scha_resourcegroup_get

Accède aux informations relatives au groupe de ressources sous le contrôle du RGM. Cette commande fournit la même fonctionnalité que la fonction C scha_resourcetype_get ().

scha_control

Demande le redémarrage d'un groupe de ressources sous le contrôle du RGM ou son déplacement vers un autre noeud. Elle propose la même fonctionnalité que la fonction C scha_control().

Commande du cluster

Cette commande accède aux informations relatives à un cluster, telles que les noms des noeuds, les ID, les états, le nom du cluster, les groupes de ressources, etc.

scha_cluster_get

Cette commande fournit les mêmes informations que la fonction C scha_cluster_get ().

Fonctions C

Les fonctions C doivent être utilisées dans les mises en oeuvre du programme C des méthodes de rappel pour les types de ressource représentant des services contrôlés par le RGM du cluster. Ces fonctions vous permettent d'effectuer les opérations suivantes :

Remarque :

bien que cette rubrique fournisse de brèves descriptions des fonctions C, les différentes pages du manuel (3HA) constituent la référence faisant foi pour les fonctions C. Sauf mention contraire, chaque fonction correspond à une page de manuel portant le même nom. Reportez-vous à la page scha_calls( 3HA) du manuel pour obtenir des informations sur les arguments de sortie et les codes de retour des fonctions C.

Fonctions des ressources

Ces fonctions accèdent aux informations relatives à une ressource gérée par le RGM ou indiquent l'état de celle-ci tel qu'il est perçu par le détecteur.

scha_resource_open(), scha_resource_get () et scha_resource_close()

Ensemble, ces fonctions accèdent à des informations sur une ressource gérée par le RGM. La fonction scha_resource_open() initialise l'accès à une ressource et renvoie un identificateur pour scha_resource_get (), lequel accède aux informations de la ressource. La fonction scha_resource_close () invalide l'identificateur et libère la mémoire allouée aux valeurs de retour scha_resource_get().

Une ressource peut changer, à la suite d'une reconfiguration du cluster ou d'une action de l'administrateur, après que la fonction scha_resource_open() a renvoyé l'identificateur de la ressource, auquel cas les informations obtenues par scha_resource_get() par le biais de celui-ci risquent d'être erronées. Dans le cas d'une reconfiguration du cluster ou d'une action de l'administrateur sur une ressource, le RGM renvoie le code d'erreur scha_err_seqid à scha_resource_get() pour indiquer qu'il est possible que les informations concernant la ressource aient changé. Il s'agit d'un message d'erreur non fatale. La fonction renvoie une réussite. Vous pouvez choisir d'ignorer le message et d'accepter l'information renvoyée ou de fermer l'identificateur actuel et d'en ouvrir un nouveau pour accéder aux informations relatives à la ressource.

Ces trois fonctions sont décrites par une même page du manuel. Vous pouvez accéder à cette page par le biais des fonctions scha_resource_open(3HA), scha_resource_get(3HA) ou scha_resource_close(3HA).

scha_resource_setstatus()

Définit les propriétés Statut et msg_statut d'une ressource sous le contrôle du RGM. Le détecteur de la ressource utilise cette fonction pour indiquer l'état de celle-ci.

Remarque :

bien que scha_resource_setstatus() soit d'un intérêt particulier pour les détecteurs de ressources, tout programme peut l'appeler.

Fonctions du type de ressource

Ensemble, ces fonctions accèdent aux informations sur le type de ressource enregistré avec le RGM.

scha_resourcetype_open(), scha_resourcetype_get(), scha_resourcetype_close()

La fonction scha_resourcetype_open() initialise l'accès à une ressource et renvoie un identificateur pour scha_resourcetype_get (), lequel accède aux informations du type de ressource. La fonction scha_resourcetype_close () invalide l'identificateur et libère la mémoire allouée aux valeurs de retour scha_resourcetype_get().

Un type de ressource peut changer, à la suite d'une reconfiguration du cluster ou d'une action de l'administrateur, après que la fonction scha_resourcetype_open() a renvoyé l'identificateur du type de ressource, auquel cas les informations obtenues par scha_resourcetype_get() par le biais de celui-ci risquent d'être erronées. Dans le cas d'une reconfiguration du cluster ou d'une action de l'administrateur sur un type de ressource, le RGM renvoie le code d'erreur scha_err_seqid à scha_resourcetype_get() pour indiquer qu'il est possible que les informations concernant le type de ressource aient changé. Il s'agit d'un message d'erreur non fatale. La fonction renvoie une réussite. Vous pouvez choisir d'ignorer le message et d'accepter l'information renvoyée ou de fermer l'identificateur actuel et d'en ouvrir un nouveau pour accéder aux informations relatives au type de ressource.

Ces trois fonctions sont décrites par une même page du manuel. Vous pouvez accéder à cette page du manuel par le biais de chacune des fonctions scha_resourcetype_open(3HA), scha_resourcetype_get(3HA) ou scha_resourcetype_close(3HA).

Fonctions du groupe de ressources

Ces fonctions vous permettent d'accéder aux informations relatives au groupe de ressources ou de redémarrer celui-ci.

scha_resourcegroup_open(3HA), scha_resourcegroup_get(3HA) et scha_resourcegroup_close(3HA)

Ensemble, ces fonctions accèdent à des informations sur un groupe de ressources géré par le RGM. La fonction scha_resourcegroup_open() initialise l'accès à un groupe de ressources et renvoie un identificateur pour scha_resourcegroup_get (), lequel accède aux informations du groupe de ressources. La fonction scha_resourcegroup_close () invalide l'identificateur et libère la mémoire allouée aux valeurs de retour scha_resourcegroup_get().

Un groupe de ressources peut changer, à la suite d'une reconfiguration du cluster ou d'une action de l'administrateur, après que la fonction scha_resourcegroup_open() a renvoyé l'identificateur du groupe de ressources, auquel cas les informations obtenues par scha_resourcegroup_get() par le biais de celui-ci risquent d'être erronées. Dans le cas d'une reconfiguration du cluster ou d'une action de l'administrateur sur un groupe de ressources, le RGM renvoie le code d'erreur scha_err_seqid à scha_resourcegroup_get() pour indiquer qu'il est possible que les informations concernant le groupe de ressources aient changé. Il s'agit d'un message d'erreur non fatale. La fonction renvoie une réussite. Vous pouvez choisir d'ignorer le message et d'accepter l'information renvoyée ou de fermer l'identificateur actuel et d'en ouvrir un nouveau pour accéder aux informations relative au groupe de ressources.

scha_control( 3HA)

Demande le redémarrage d'un groupe de ressources sous le contrôle du RGM ou son déplacement vers un autre noeud.

Fonctions du cluster

Ces fonctions accèdent à des informations sur un cluster ou en renvoient.

scha_cluster_open(3HA), scha_cluster_get(3HA), scha_cluster_close(3HA)

Ensemble, ces fonctions accèdent à des informations relatives à un cluster, telles que les noms des noeuds, les ID, les états, le nom du cluster, les groupes de ressources, etc.

Un cluster peut changer, à la suite d'une reconfiguration du cluster ou d'une action de l'administrateur, après que la fonction scha_cluster_open() a renvoyé l'identificateur du cluster, auquel cas les informations obtenues par scha_cluster_get() par le biais de celui-ci risquent d'être erronées. Dans le cas d'une reconfiguration du cluster ou d'une action de l'administrateur sur une ressource, le RGM renvoie le code d'erreur scha_err_seqid à scha_cluster_get() pour indiquer qu'il est possible que les informations concernant le cluster aient changé. Il s'agit d'un message d'erreur non fatale. La fonction renvoie une réussite. Vous pouvez choisir d'ignorer le message et d'accepter l'information renvoyée ou de fermer l'identificateur actuel et d'en ouvrir un nouveau pour accéder aux informations relatives au cluster.

scha_cluster_getlogfacility(3HA)

Renvoie le numéro de la fonction syslog utilisée comme journal du cluster. Utilise la valeur renvoyée à l'aide de la fonction syslog() de Solaris pour enregistrer les événements et les messages d'état dans le journal du cluster.

scha_cluster_getnodename(3HA)

Renvoie le nom du noeud du cluster sur lequel est appelée la fonction.

Fonction de l'utilitaire

Cette fonction convertit un code d'erreur en message d'erreur.

scha_strerror( 3HA)

Traduit un code d'erreur, renvoyé par l'une des fonctions scha_, en message d'erreur. Utilisez cette fonction avec la commande logger pour consigner les messages dans le journal système (syslog).

Méthodes de rappel API GR

Les méthodes de rappel sont les éléments clés fournis par l'API pour la mise en oeuvre d'un type de ressource. Les méthodes de rappel permettent au RGM de contrôler les ressources du cluster en cas de modification des membres de celui-ci, par exemple en cas d'initialisation ou de blocage du noeud.

Remarque :

les méthodes de rappel sont exécutées par le RGM avec les autorisations racine étant donné que les programmes client contrôlent les services HA sur le système du cluster. Installez et gérez ces méthodes avec des membres et des autorisations de fichiers restrictifs. Plus spécifiquement, donnez-leur un propriétaire privilégié, par exemple bin ou root et rendez-les inaccessibles en écriture.

Cette rubrique décrit les arguments et codes de sortie des méthodes de rappel. Par ailleurs, elle énumère et décrit les méthodes de rappel des différentes catégories :

Remarque :

bien que cette rubrique fournisse de brèves descriptions des méthodes de rappel, comprenant le moment auquel la méthode est appelée et l'effet escompté sur la ressource, la page rt_callbacks( 1HA) du manuel constitue la référence faisant foi pour les méthodes de rappel.

Arguments de méthode

Le RGM exécute les méthodes de rappel de la manière suivante : 


méthode -R nom-ressource -T nom-type -G nom-groupe

La méthode est le nom du chemin d'accès enregistré comme Démarrage, Arrêt ou autre rappel. Les méthodes de rappel d'un type de ressource sont déclarées dans son fichier d'enregistrement.

Tous les arguments des méthodes de rappel sont transmis comme des valeurs marquées, avec - R indiquant le nom de l'instance de la ressource, -T indiquant le type de la ressource et -G indiquant le groupe dans lequel est configurée la ressource. Ayez recours aux arguments disposant de fonctions d'accès pour récupérer des informations sur la ressource.

La méthode de Validation est appelée avec des arguments supplémentaires (les valeurs des propriétés de la ressource et du groupe de ressources ciblées par l'appel).

Reportez-vous à scha_calls(3HA) pour obtenir de plus amples informations.

Codes de sortie

Toutes les méthodes de rappel possèdent les mêmes codes de sortie définis pour spécifier l'effet de l'exécution de la méthode sur l'état de la ressource. La page scha_calls (3HA) du manuel décrit tous les codes de sortie. Les codes de sortie sont les suivants :

Le RGM gère également les échecs anormaux rencontrés lors de l'exécution de la méthode de rappel, tels que les dépassements de délai imparti et les core dumps.

Les mises en oeuvre de la méthode doivent sortir des informations d'échec à l'aide de syslog sur chaque noeud. L'envoi des sorties écrites sur stdout ou sur stderr à l'utilisateur n'est pas garanti, bien que celui-ci apparaisse sur la console du noeud local.

Méthodes de rappel de contrôle et d'initialisation

Les principales méthodes de rappel de contrôle et d'initialisation démarrent et arrêtent les ressources. Les autres méthodes exécutent un code d'initialisation et d'arrêt sur les ressources.

Démarrage

Cette méthode requise est exécutée sur un noeud du cluster lorsque le groupe contenant la ressource est mis en ligne sur ce noeud. Cette méthode active la ressource sur ce noeud.

Une méthode de Démarrage ne doit pas se fermer avant que la ressource qu'elle active ait été démarrée et soit disponible sur le noeud local. Par conséquent, avant sa fermeture, la méthode de Démarrage doit interroger la ressource afin de déterminer si elle a démarré. Par ailleurs, vous devez définir un délai imparti suffisamment long pour cette méthode. Par exemple, certaines ressources, telles que les démons de base de données, prennent plus de temps au démarrage et ont donc besoin d'une méthode prévoyant un délai plus long.

La manière dont le RGM réagit à l'échec de la méthode de Démarrage dépend du paramètre de la propriété Mode_basculement.

La propriété DÉLAI_DÉMARRAGE du fichier d'enregistrement du type de ressource définit la valeur du délai imparti pour une méthode de Démarrage de ressource.

Arrêt

Cette méthode requise est appelée sur un noeud du cluster lorsque le groupe contenant la ressource est mis hors ligne sur ce noeud. Cette méthode désactive la ressource si elle est active.

Une méthode d'Arrêt ne doit pas se fermer avant que la ressource qu'elle contrôle ait complètement arrêté toute activité sur le noeud local et ait fermé tous les descripteurs de fichier. Dans le cas contraire, comme le RGM suppose que la ressource est arrêtée alors qu'elle est toujours active, une corruption de données peut avoir lieu. La manière la plus sûre d'éviter une corruption de données consiste à mettre un terme à tous les processus sur le noeud local associé à la ressource.

Avant sa fermeture, la méthode d'Arrêt doit interroger la ressource afin de déterminer si elle est arrêtée. Par ailleurs, vous devez définir un délai imparti suffisamment long pour cette méthode. Par exemple, certaines ressources, telles que les démons de base de données, prennent plus de temps à l'arrêt et ont donc besoin d'une méthode prévoyant un délai plus long.

La manière dont le RGM réagit à l'échec de la méthode d'Arrêt dépend du paramètre de la propriété Mode_basculement (reportez-vous au Tableau A–2).

La propriété DÉLAI_ARRÊT du fichier d'enregistrement du type de ressource définit la valeur du délai imparti pour une méthode d'Arrêt de ressource.

Init

Cette méthode optionnelle est appelée pour effectuer une initialisation unique de la ressource lorsque celle-ci est gérée, soit quand le groupe de ressources auquel elle appartient passe d'un état non géré à un état géré soit lorsque la ressource est créée dans un groupe de ressources déjà géré. La méthode est appelée sur les noeuds déterminés par la propriété de ressource Noeuds_init.

Fini

Cette méthode facultative est appelée pour faire le ménage lorsque la ressource n'est plus gérée, soit quand le groupe auquel elle appartient n'est plus géré soit quand elle est supprimée d'un groupe de ressources géré. La méthode est appelée sur des noeuds déterminés par la propriété de ressource Noeuds_init.

Initialisation

Cette méthode facultative, analogue à Init, est appelée pour initialiser la ressource sur des noeuds rejoignant le cluster après que le groupe contenant la ressource a déjà été placé sous le contrôle du RGM. La méthode est appelée sur des noeuds déterminés par la propriété de ressource Noeuds_init. La méthode d'Initialisation est appelée lorsque le noeud adhère à un cluster à la suite d'une initialisation ou d'une réinitialisation.

Remarque :

un échec des méthodes Init, Fini ou Initialisation entraîne la génération, par la fonction syslog(), d'un message d'erreur, mais n'affecte en rien la gestion de la ressource par le RGM.

Méthodes d'assistance à l'administration

Les tâches d'administration concernant les ressources comprennent entre autres le paramétrage et la modification des propriétés de la ressource. Les méthodes de rappel Validation et Mise_à_jour permettent à la mise en oeuvre d'un type de ressource de passer par ces opérations d'administration.

Validation

Cette méthode facultative est appelée lorsqu'une ressource est créée et lorsque l'administrateur met à jour les propriétés de la ressource ou du groupe la contenant. Cette méthode est appelée sur le jeu de noeuds du cluster indiqué par la propriété Noeuds_init du type de ressource. Validation est appelée avant la création ou la mise à jour, et un code de sortie avec échec renvoyé par la méthode sur un noeud entraîne l'annulation de l'opération envisagée.

Validation n'est appelée que lorsque les propriétés de la ressource ou du groupe sont modifiées par une opération de l'administrateur, et non lorsque le RGM définit des propriétés, ou lorsqu'un détecteur définit les propriétés Statut et msg_statut de la ressource.

Mise_à_jour

Cette méthode facultative est appelée pour signaler à une ressource en cours d'exécution que les propriétés ont été modifiées. Mise_à_jour est appelée après la réussite d'une action de l'administrateur visant à définir les propriétés d'une ressource ou de son groupe. Cette méthode est appelée sur les noeuds lorsque la ressource est en ligne. La méthode utilise les fonctions d'accès de l'API pour lire les valeurs des propriétés susceptibles d'affecter une ressource active et régler la ressource en cours d'exécution en conséquence.

Un échec de la méthode Mise_à_jour pousse la fonction syslog() à générer un message d'erreur mais n'affecte en rien la gestion de la ressource par le RGM.

Méthodes de rappel relatives au Net

Il est possible que les services utilisant des ressources d'adresses réseau exigent que les étapes menant à un démarrage ou à un arrêt soient effectuées dans un certain ordre, en fonction de la configuration de l'adresse réseau. Les méthodes de rappel facultatives Démarrage_avant_réseau et Arrêt_après_réseau permettent à la mise en oeuvre d'un type de ressource d'effectuer des actions spéciales de démarrage et de fermeture avant et après la configuration ou la déconfiguration d'une adresse réseau liée.

Démarrage_avant_réseau

Cette méthode facultative est appelée pour entreprendre des actions de démarrage spéciales avant la configuration des adresses réseau du même groupe de ressources.

Arrêt_après_réseau

Cette méthode facultative est appelée pour effectuer des actions de fermeture spéciales une fois les adresses réseau du même groupe de ressources déconfigurées.

Méthodes de rappel de contrôle des détecteurs

La mise en oeuvre d'un type de ressource peut inclure, de manière facultative, un programme permettant de surveiller la performance d'une ressource, de faire rapport sur son état ou de réagir en cas d'échec. Les méthodes Démarrage_détecteur, Arrêt_détecteur et Contrôle_détecteur prennent en charge la mise en oeuvre d'un détecteur de ressources dans le type de ressource.

Démarrage_détecteur

Cette méthode facultative est appelée pour démarrer un détecteur destiné à la ressource lorsque celle-ci a démarré.

Arrêt_détecteur

Cette méthode facultative est appelée pour arrêter un détecteur destiné à la ressource avant l'arrêt de celle-ci.

Contrôle_détecteur

Cette méthode facultative est appelée pour évaluer la fiabilité d'un noeud avant le déplacement du groupe de ressources sur celui-ci. La méthode de Contrôle_détecteur doit être mise en oeuvre de manière à ne pas entrer en conflit avec d'autres méthodes exécutées simultanément.