test

Guide du développeur de services de données Sun Cluster pour SE Solaris

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

Ce chapitre répertorie et présente brièvement les fonctions d'accès et les méthodes de rappel qui constituent l'interface APIGR (API de gestion des ressources). Toutefois, la référence faisant foi pour ces fonctions et méthodes se trouve dans les pages de manuel consacrées à l'interface APIGR.

Ce chapitre contient les rubriques suivantes :

Méthodes d'accès de l'interface APIGR

L'API fournit des fonctions d'accès aux propriétés des ressources, des groupes et des types de ressources, ainsi qu'à d'autres informations sur le cluster, sous la forme de commandes shell et de fonctions C, qui vous permettent de mettre en œuvre des programmes de contrôle en tant que scripts shell ou programmes C.

Commandes shell de l'interface APIGR

Les commandes shell s'utilisent dans les mises en œuvre par scripts shell des méthodes de rappel des types de ressource qui représentent des services contrôlés par le gestionnaire RGM du cluster. Elles permettent d'effectuer les tâches suivantes :

Remarque –

cette rubrique ne fournit que de brèves descriptions des commandes shell ; la référence faisant foi en matière de commandes shell se trouve dans les pages de manuel 1HA. Sauf indication contraire, chaque commande est associée à une page de manuel du même nom.

Commandes APIGR relatives aux ressources

Les commandes ci-dessous vous permettent d'accéder aux informations sur une ressource ou d'en définir les propriétés Status et Status_msg.

scha_resource_get

Donne accès aux informations sur une ressource ou un type de ressource contrôlé par le RGM. Cette commande renvoie les mêmes données que la fonction C scha_resource_get(). Pour obtenir plus d'informations, reportez-vous à la page de manuel scha_resource_get(1HA).

scha_resource_setstatus

Définit les propriétés Status et Status_msg d'une ressource contrôlée par le RGM. C'est la commande que le détecteur de la ressource utilise pour indiquer l'état de cette dernière. Elle remplit les mêmes fonctions que scha_resource_setstatus(). Pour plus d'informations sur cette commande, reportez-vous à la page de manuel scha_resource_setstatus(1HA).

Remarque –

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

Commande relative aux types de ressources

scha_resourcetype_get

Donne accès à des informations sur un type de ressource enregistré dans le RGM. Cette commande fournit la même fonctionnalité que la fonction C scha_resourcetype_get (). Elle est décrite plus en détail dans la page de manuel scha_resourcetype_get(1HA).

Commandes relatives aux groupes de ressources

Les commandes ci-dessous vous donnent accès aux informations sur un groupe de ressources ou vous permettent de redémarrer un groupe de ressources.

scha_resourcegroup_get

Présente des informations sur un groupe de ressources contrôlé par le RGM. Cette commande fournit la même fonctionnalité que la fonction C scha_resourcetype_get (). Pour plus d'informations sur cette commande, reportez-vous à la page de manuel scha_resourcegroup_get(1HA).

scha_control

Demande le redémarrage d'un groupe de ressources contrôlé par le RGM ou son déplacement vers un autre nœud. Cette commande est équivalente à la fonction C scha_control(). Elle est décrite plus en détail dans la page de manuel scha_control(1HA).

Commande du cluster

scha_cluster_get

Fournit des informations sur un cluster : nom du cluster, noms des noeuds, ID, états et groupes de ressources. Cette commande renvoie les mêmes données que la fonction C scha_cluster_get(). Elle est décrite plus en détail dans la page de manuel scha_cluster_get(1HA).

Fonctions C

Les fonctions C sont utilisées pour mettre en œuvre, à l'aide de programmes en langage C, les méthodes de rappel des types de ressources qui représentent les services contrôlés par le RGM du cluster. Elles permettent d'effectuer les tâches suivantes :

Remarque –

cette rubrique ne fournit que de brèves descriptions des fonctions C ; la référence faisant foi en matière de fonctions C se trouve dans les pages de manuel 3HA. Sauf indication contraire, chaque fonction est associée à une page de manuel du même nom. Pour obtenir plus d'informations sur les arguments de sortie et les codes de retour des fonctions C, reportez-vous à la page de manuel scha_calls(3HA).

Fonctions relatives aux ressources

Les fonctions ci-dessous renvoient des informations sur une ressource gérée par le gestionnaire RGM ou présentent son état selon son détecteur.

scha_resource_open(), scha_resource_get () et scha_resource_close()

Ces fonctions fournissent des informations sur une ressource gérée par le RGM. scha_resource_open() initialise l'accès à la ressource et renvoie un identificateur destiné à la fonction scha_resource_get(), qui accède aux informations sur la ressource. scha_resource_close() annule la validité de l'identificateur et libère la mémoire affectée aux valeurs de retour de scha_resource_get ().

Une ressource peut être modifiée (à la suite d'une reconfiguration du cluster ou d'une action administrative) après le renvoi de son identificateur par la fonction scha_resource_open(). Dans ce cas, scha_resource_get() risque d'obtenir des informations inexactes. Si un cluster a été reconfiguré ou qu'une action administrative a été effectuée sur une ressource, le RGM renvoie le code d'erreur scha_err_seqid à scha_resource_get() pour indiquer que les informations sur la ressource ont peut-être changé. Ce message ne constitue pas une erreur fatale : il ne bloque pas la fonction. Vous pouvez ignorer le message et accepter les informations renvoyées. Vous pouvez également fermer l'identificateur actuel et ouvrir un nouvel identificateur pour accéder aux informations sur la ressource.

Ces trois fonctions sont décrites dans une même page de manuel, accessible à l'aide de la fonction scha_resource_open(3HA), scha_resource_get(3HA) ou scha_resource_close(3HA).

scha_resource_setstatus()

Définit les propriétés Status et Status_msg d'une ressource contrôlée par le 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 propre aux détecteurs de ressources, tout programme peut l'appeler.

Fonctions relatives au type de ressources

Les fonctions suivantes fournissent des informations sur un type de ressources enregistré dans le gestionnaire RGM.

scha_resourcetype_open(), scha_resourcetype_get () et scha_resourcetype_close()

La fonction scha_resourcetype_open() initialise l'accès à une ressource et renvoie un identificateur destiné à la fonction scha_resourcetype_get(), qui accède aux informations sur le type de ressources. scha_resourcetype_close() annule la validité de l'identificateur et libère la mémoire affectée aux valeurs de retour de scha_resourcetype_get ().

Un type de ressource peut être modifié (à la suite d'une reconfiguration du cluster ou d'une action administrative) après le renvoi de son identificateur par la fonction scha_resourcetype_open(). Dans ce cas, scha_resourcetype_get() risque d'obtenir des informations inexactes. Si un cluster a été reconfiguré ou qu'une action administrative a été effectuée sur un type de ressource, le RGM renvoie le code d'erreur scha_err_seqid à scha_resourcetype_get() pour indiquer que les informations sur le type de ressource ont peut-être changé. Ce message ne constitue pas une erreur fatale : il ne bloque pas la fonction. Vous pouvez ignorer le message et accepter les informations renvoyées. Vous pouvez également fermer l'identificateur actuel et en ouvrir un autre pour accéder aux informations sur le type de ressource.

Ces trois fonctions sont décrites dans une même page de manuel, accessible à l'aide de la fonction scha_resourcetype_open(3HA), scha_resourcetype_get(3HA) ou scha_resourcetype_close(3HA).

Fonctions relatives au groupe de ressources

Les fonctions suivantes vous donnent accès aux informations sur un groupe de ressources ou vous permettent de redémarrer un groupe de ressources.

scha_resourcegroup_open(), scha_resourcegroup_get () et scha_resourcegroup_close()

Ces fonctions présentent des informations sur un groupe de ressources contrôlé par le RGM. La fonction scha_resourcegroup_open() initialise l'accès au groupe de ressources et renvoie un identificateur destiné à la fonction scha_resourcegroup_get (), qui accède aux informations sur le groupe de ressources. scha_resourcegroup_close() annule la validité de l'identificateur et libère la mémoire affectée aux valeurs de retour de scha_resourcegroup_get().

Un groupe de ressources peut être modifié (à la suite d'une reconfiguration du cluster ou d'une action administrative) après le renvoi de son identificateur par la fonction scha_resourcegroup_open(). Dans ce cas, scha_resourcegroup_get() risque d'obtenir des informations inexactes. Si un cluster a été reconfiguré ou qu'une action administrative a été effectuée sur un groupe de ressources, le RGM renvoie le code d'erreur scha_err_seqid à scha_resourcegroup_get() pour indiquer que les informations sur le groupe de ressources ont peut-être changé. Ce message ne constitue pas une erreur fatale : il ne bloque pas la fonction. Vous pouvez ignorer le message et accepter les informations renvoyées. Vous pouvez également fermer l'identificateur actuel et en ouvrir un autre pour accéder aux informations sur le groupe de ressources.

Ces trois fonctions sont décrites dans une même page de manuel, accessible à l'aide de la fonction scha_resourcegroup_open(3HA), scha_resourcegroup_get(3HA) ou scha_resourcegroup_close(3HA).

scha_control()

Demande le redémarrage d'un groupe de ressources contrôlé par le RGM ou son déplacement vers un autre nœud. Cette fonction est décrite plus en détail dans la page de manuel scha_control(3HA).

Fonctions du cluster

Les fonctions ci-dessous fournissent des informations sur un cluster.

scha_cluster_open(), scha_cluster_get () et scha_cluster_close()

Ces fonctions fournissent des informations sur un cluster : nom du cluster, noms des noeuds, ID, états et groupes de ressources.

Un cluster peut être modifié (lors d'une reconfiguration ou d'une action administrative) après le renvoi de son identificateur par la fonction scha_cluster_open(). Dans ce cas, scha_cluster_get() risque d'obtenir des informations erronées. Si un cluster a été reconfiguré ou a subi une action administrative, le RGM renvoie le code d'erreur scha_err_seqid à scha_cluster_get()pour indiquer que les informations sur le cluster ont peut-être changé. Ce message ne constitue pas une erreur fatale : il ne bloque pas la fonction. Vous pouvez ignorer le message et accepter les informations renvoyées. Vous pouvez également fermer l'identificateur actuel et en ouvrir un autre pour accéder aux informations sur le cluster.

Ces trois fonctions sont décrites dans une même page de manuel, accessible à l'aide de la fonction scha_cluster_open(3HA), scha_cluster_get(3HA) ou scha_cluster_close(3HA).

scha_cluster_getlogfacility()

Renvoie le numéro de l'utilitaire de journalisation système utilisé comme journal du cluster. Cette fonction utilise la valeur renvoyée, avec la fonction syslog() de Solaris, pour enregistrer les événements et les messages de statut dans le journal du cluster. Elle est décrite plus en détail dans la page de manuel scha_cluster_getlogfacility(3HA).

scha_cluster_getnodename()

Renvoie le nom du noeud du cluster sur lequel est appelée la fonction. Cette fonction est décrite plus en détail dans la page de manuel scha_cluster_getnodename(3HA).

Fonction de l'utilitaire

Cette fonction convertit les codes d'erreur en messages d'erreur équivalents.

scha_strerror()

Convertit un code d'erreur renvoyé par l'une des fonctions scha_ en un message d'erreur. Vous pouvez associer cette fonction à la commande logger afin d'enregistrer les messages dans le journal système de Solaris (syslog). Cette fonction est décrite plus en détail dans la page de manuel scha_strerror(3HA).

Méthodes de rappel de l'interface APIGR

Les méthodes de rappel sont les éléments essentiels que l'API fournit pour la mise en œuvre d'un type de ressource. Elles permettent au RGM de gérer les ressources du cluster en cas de modification des membres du cluster (par exemple, initialisation ou arrêt brutal d'un nœud).

Remarque –

pour exécuter les méthodes de rappel, le RGM utilise des droits de superutilisateur ou de rôle équivalent, car le programme client contrôle les services à haute disponibilité du système du cluster. Installez et gérez ces méthodes avec des membres et des autorisations de fichiers restrictifs. Vous devez notamment leur attribuer un propriétaire privilégié (par exemple, bin ou root) et les rendre inaccessibles en écriture.

Cette rubrique décrit les arguments et les codes de sortie des méthodes de rappel. Elle décrit les méthodes de rappel des catégories suivantes :

Remarque –

cette rubrique décrit brièvement les méthodes de rappel ; elle indique leur point d'exécution et leur effet escompté. Cependant, la référence faisant foi en matière de méthodes de rappel est la page de manuel rt_callbacks(1HA).

Arguments destinés aux méthodes de rappel

Pour exécuter les méthodes de rappel, le RGM utilise la syntaxe de commande suivante : 

method -R resource-name -T type-name -G group-name

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 sous la forme des valeurs marquées suivantes :

Ayez recours aux arguments disposant de fonctions d'accès pour récupérer des informations sur la ressource.

L'appel de la méthode Validate utilise des arguments supplémentaires, notamment les valeurs des propriétés de la ressource et le groupe sur lequel la méthode est appelée.

Pour obtenir plus d'informations, reportez-vous à la page de manuel scha_calls(3HA).

Codes de sortie des méthodes de rappel

Toutes les méthodes de rappel utilisent les mêmes codes de sortie. Ces codes définissent l'effet de l'appel de la méthode sur l'état de la ressource. Ils sont décrits plus en détail dans la page de manuel scha_calls(3HA). Les codes de sortie se classent en deux catégories principales :

Le RGM gère également les arrêts anormaux lors de l'exécution des méthodes de rappel, notamment les dépassements des délais d'attente et les core dumps.

Les mises en œuvre de méthodes doivent consigner les informations sur les échecs en utilisant la fonction syslog() sur chaque nœud. En effet, les sorties écrites dans stdout ou stderr ne sont parfois pas communiquées à l'utilisateur, même si elles sont affichées sur la console du nœud local.

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

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

Start

La méthode Start, exécutée par le gestionnaire RGM sur un nœud de cluster lorsque le groupe qui contient une ressource donnée est connecté à ce nœud, active cette ressource sur ce nœud.

La méthode Start ne doit être arrêtée que lorsque la ressource qu'elle active a démarré et est disponible sur le nœud 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é. En outre, son délai d'attente doit être suffisamment long, car certaines ressources (par exemple, les démons de bases de données) mettent un certain temps à démarrer.

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

Le délai d'attente de la méthode Start d'une ressource est déterminé par la propriété Start_timeout du fichier RTR.

Stop

La méthode Stop est la méthode obligatoire que le RGM exécute sur un nœud de cluster lorsque le groupe qui contient une ressource donnée est déconnecté de ce nœud. Cette méthode désactive la ressource si elle est active.

Elle ne doit être fermée que lorsque la méthode qu'elle contrôle a été totalement désactivée et a fermé tous ses descripteurs de fichiers. Si elle était fermée trop tôt, le RGM supposerait à tort que la ressource a été désactivée (même si cette ressource était encore active) et des données risqueraient d'être corrompues. Pour prévenir toute corruption de données, la meilleure méthode consiste à mettre fin à tous les processus exécutés sur le nœud local associé à la ressource.

Avant sa fermeture, la méthode Arrêt doit interroger la ressource afin de déterminer si elle est arrêtée. En outre, son délai d'attente doit être suffisamment long, car certaines ressources (par exemple, les démons de bases de données) mettent un certain temps à démarrer.

La manière dont le gestionnaire RGM réagit à l'échec de la méthode Stop dépend du paramétrage de la propriété Failover_mode. Pour plus d'informations, voir Propriétés des ressources.

Le délai d'attente de la méthode Stop associée à une ressource est défini par la propriété Stop_timeout du fichier RTR.

Init

Init est une méthode facultative que le gestionnaire RGM exécute ponctuellement sur une ressource afin de l'initialiser, lorsque cette ressource devient gérée, c'est-à-dire lorsque cette ressource est créée (si son groupe est déjà géré) ou que son groupe passe de l'état non géré à l'état géré. Elle est appelée sur les nœuds identifiés par la propriété de ressource Init_nodes.

Fini

Fini est une méthode facultative que le RGM appelle, à des fins de nettoyage, lorsqu'une ressource devient non gérée, c'est-à-dire lorsque le groupe qui contient la ressource passe à l'état non géré ou que la ressource elle-même est supprimée (si elle appartient à un groupe de ressources géré). Elle est appelée sur des nœuds identifiés par la propriété de ressource Init_nodes.

Boot

Le RGM exécute cette méthode facultative, similaire à Init, pour initialiser une ressource sur des nœuds qui rejoignent le cluster alors que le groupe auquel appartient cette ressource est déjà géré par le RGM. Les nœuds sur lesquels est exécutée cette méthode sont identifiés par la propriété de ressource Init_nodes . La méthode Boot est appelée lorsque l'un des nœuds concernés démarre ou redémarre, donc se connecte ou se reconnecte au cluster.

Remarque –

l'échec des fonctions Init, Fini ou Boot entraîne la création d'un message d'erreur par la fonction syslog() ; il n'a aucun autre effet sur 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. Pour les réaliser, les mises en œuvre des types de ressources utilisent les méthodes de rappel Validate et Update.

Validate

Le RGM appelle la méthode facultative Validate lorsqu'une ressource est créée ou qu'une action administrative met à jour les propriétés de la ressource ou de son groupe. La méthode est appelée sur l'ensemble de nœuds de clusters identifiés par la propriété Init_nodes du type de la ressource. La méthode Validate est appelée avant la création ou la mise à jour effective. Par conséquent, un code de sortie d'échec de la méthode sur un nœud, quel qu'il soit, entraîne l'annulation de la création ou de la mise à jour.

Validate n'est appelée que lorsque l'administrateur d'un cluster modifie les propriétés d'une ressource ou d'un groupe de ressources et non lorsque le RGM définit des propriétés, ni lorsqu'un détecteur règle les propriétés de ressource Status et Status_msg.

Update

Le RGM exécute la méthode facultative Update pour signaler à une ressource en cours d'exécution que ses propriétés ont été modifiées, après l'exécution réussie d'une action administrative de paramétrage des 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. Elle peut utiliser les fonctions d'accès de l'interface API pour lire les valeurs de propriété susceptibles d'affecter une ressource active et régler les ressources en cours d'exécution en conséquence.

Remarque –

en cas d'échec de la méthode Update, la fonction syslog() émet un message d'erreur ; cependant, cet échec n'a aucun autre effet sur la gestion de la ressource par le RGM.

Méthodes de rappel relatives au réseau

Pour certains services qui utilisent des ressources d'adresse réseau, les étapes de démarrage et d'arrêt devront être exécutées dans un ordre précis, dépendant de la configuration. Les méthodes de rappel facultatives Prenet_start et Postnet_stop permettent à la mise en œuvre d'un type de ressource d'effectuer des actions de démarrage et d'arrêt spéciales avant et après la configuration ou l'annulation de la configuration d'une adresse réseau liée.

Prenet_start

Cette méthode facultative permet d'effectuer des actions de démarrage spéciales avant la configuration des adresses réseau d'un même groupe de ressources.

Postnet_stop

Cette méthode facultative permet d'effectuer des actions d'arrêt spéciales après le retrait des adresses réseau d'un groupe.

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

Une mise en œuvre de type de ressources peut comporter un programme destiné à contrôler les performances d'une ressource, à écrire un rapport sur son statut ou à intervenir en cas de défaillance d'une ressource. Les méthodes Monitor_start, Monitor_stop et Monitor_check permettent d'implémenter un détecteur de ressource dans une mise en œuvre de type de ressources.

Monitor_start

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

Monitor_stop

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

Monitor_check

Cette méthode facultative est appelée pour évaluer la fiabilité d'un nœud avant qu'un groupe de ressources ne soit réaffecté à ce nœud. Lorsque vous la mettez en œuvre, vous devez veiller à ce qu'elle n'entre en conflit avec aucune autre méthode exécutée au même moment.