test

Sun Cluster 3.1 10/03: Guía del desarrollador de los servicios de datos

Capítulo 4 Referencia de la API de gestión de recursos

Este capítulo proporciona una referencia a las funciones de acceso y los métodos de rellamada que forman la API de gestión de recursos (RMAPI). Enumera y describe brevemente cada función y método. Sin embargo, la referencia definitiva para estas funciones y métodos son las páginas de comando man de RMAPI.

La información de este capítulo incluye:

Métodos de acceso a RMAPI

La API proporciona funciones para acceder a las propiedades tanto de los recursos como del grupo y tipo de recursos, además de otra información del clúster. Estas funciones se suministran en forma de comandos del shell y funciones de C, lo que permite que los suministradores de tipos de recursos implementen programas de control en forma de secuencias del shell o programas de C.

Comandos del shell de RMAPI

Los comandos del shell se usan en las implementaciones de las secuencias del shell de los métodos de rellamada para los tipos de recursos que representan los servicios controlados por RGM del clúster. Puede utilizar estos comandos para:

Nota –

Esta sección proporciona descripciones breves de los comandos del shell; las páginas de comando man individuales de la sección 1HA sirven de referencia definitiva para los comandos del shell. Cada comando dispone de una página de comando man del mismo nombre salvo que se indique lo contrario.

Comandos de los recursos de RMAPI

Estos comandos permiten acceder a información sobre un recurso o establecer las propiedades Status y Status_msg de un recurso.

scha_resource_get

Accede a información sobre un recurso o tipo de recurso controlado por RGM. Proporciona la misma información que la función scha_resource_get().

scha_resource_setstatus

Establece las propiedades Status y Status_msg de un recurso controlado por RGM. El supervisor del recurso lo utiliza para indicar el estado del recurso, según lo percibe. Realiza la misma tarea que la función de C scha_resource_setstatus().

Nota –

scha_resource_setstatus() es especialmente útil para un supervisor de recursos, cualquier programa puede invocarlo.

Comando del tipo de recurso

Este comando accede a información sobre un tipo de recurso registrado con RGM.

scha_resourcetype_get

Realiza la misma tarea que la función de C scha_resource_setstatus().

Comandos del grupo de recursos

Estos comandos permiten acceder a información acerca de un grupo de recursos o reiniciarlo.

scha_resourcegroup_get

Accede a información sobre un grupo de recursos controlado por RGM. Realiza la misma tarea que la función de C scha_resourcetype_get().

scha_control

Solicita el reinicio de un grupo de recursos controlado por RGM o su reubicación en un nodo diferente. Realiza la misma tarea que la función de C scha_control().

Comando del clúster

Este comando permite acceder a información acerca de un clúster, como nombres de nodo, ID, estados, el nombre de clúster, grupos de recursos, etc.

scha_cluster_get

Este comando proporciona la misma información que la función de C scha_cluster_get().

Funciones de C

Las funciones de C se deben usar en las implementaciones del programa de C de los métodos de rellamada para los tipos de recursos que representan servicios controlados por RGM del clúster. Puede utilizar estas funciones para:

Nota –

Esta sección proporciona descripciones breves de las funciones de C; las páginas de comando man individuales de (3HA) sirven de referencia definitiva para las funciones de C. Cada función tiene una página de comando man del mismo nombre, salvo que se indique lo contrario. Consulte la página de comando man de scha_calls(3HA) para obtener información sobre los argumentos de salida y códigos de retorno de las funciones de C.

Funciones de los recursos

Estas funciones permiten acceder a información sobre un recurso gestionado por RGM o indicar el estado del recurso, como lo percibe el supervisor.

scha_resource_open(), scha_resource_get() y scha_resource_close()

Estas funciones, juntas, permiten acceder a información sobre un recurso gestionado por RGM. La función scha_resource_open() inicializa el acceso a un recurso y devuelve un manejador para scha_resource_get(), que accede a la información del recurso. La función scha_resource_close() anula el manejador y libera la memoria asignada para los valores de retorno de scha_resource_get().

Un recurso puede cambiar, mediante una reconfiguración del clúster o una acción administrativa, después de que scha_resource_open() devuelva el manejador del recurso, en cuyo caso la información que obtiene scha_resource_get() a través del manejador puede no ser precisa. En el caso de una reconfiguración del clúster o una acción administrativa en un recurso, RGM devuelve el código de error scha_err_seqid a scha_resource_get() para indicar que la información del recurso puede haber cambiado. Se trata de un mensaje de error de tipo no fatal; la función devuelve información de forma satisfactoria. En consecuencia, puede ignorar el mensaje y aceptar la información que ha devuelto o cerrar el manejador actual y abrir uno nuevo para acceder a la información del recurso.

Una sola página de comando man describe estas tres funciones; es accesible a través de cualquiera de las tres funciones, scha_resource_open(3HA), scha_resource_get(3HA) o scha_resource_close(3HA).

scha_resource_setstatus()

Establece las propiedades Status y Status_msg de un recurso controlado por RGM. El supervisor del recurso utiliza esta función para indicar el estado del recurso.

Nota –

scha_resource_setstatus() es especialmente útil para un supervisor de recursos, cualquier programa puede invocarlo.

Funciones del tipo de recurso

Estas funciones, juntas, permite acceder a información sobre un tipo de recurso registrado con RGM.

scha_resourcetype_open(), scha_resourcetype_get(), scha_resourcetype_close()

La función scha_resourcetype_open() inicializa el acceso a un recurso y devuelve un manejador para scha_resourcetype_get() que accede a la información de tipo de recurso. La función scha_resourcetype_close() invalida el manejador y libera la memoria asignada para los valores de retorno de scha_resourcetype_get().

Un tipo de recurso puede cambiar, mediante una reconfiguración de clúster o un acción administrativa, después de que scha_resourcetype_open() devuelva el manejador del tipo de recurso, en cuyo caso la información que obtiene scha_resourcetype_get() a través del manejador puede no ser precisa. En el caso de una reconfiguración del clúster o una acción administrativa en un tipo de recurso, RGM devuelve el código de error scha_err_seqid a scha_resourcetype_get() para indicar que la información acerca del tipo de recurso puede haber cambiado. Se trata de un mensaje de error de tipo no fatal; la función devuelve información de forma satisfactoria. En consecuencia, puede ignorar el mensaje y aceptar la información que ha devuelto o cerrar el manejador actual y abrir uno nuevo para acceder a la información del tipo de recurso.

Una sola página de comando man describe estas tres funciones; es accesible a través de cualquiera de las tres funciones individuales, scha_resourcetype_open(3HA), scha_resourcetype_get(3HA) o scha_resourcetype_close(3HA).

Funciones del grupo de recursos

Estas funciones permiten acceder a información acerca del grupo de recursos o reiniciarlo.

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

Estas funciones, juntas, permiten acceder a información sobre un grupo de recursos gestionado por RGM. La función scha_resourcegroup_open() inicializa el acceso a un grupo de recursos y devuelve un manejador para scha_resourcegroup_get(), que accede a la información del grupo de recursos. La función scha_resourcegroup_close() invalida el manejador y libera la memoria asignada para los valores de retorno de scha_resourcegroup_get().

Un grupo de recursos puede cambiar, mediante una reconfiguración del clúster o una acción administrativa, después de que scha_resourcegroup_open() devuelva el manejador del grupo de recursos, en cuyo caso la información que obtiene scha_resourcegroup_get() a través del manejador puede no ser precisa. En el caso de una reconfiguración del clúster o una acción administrativa en un grupo de recursos, RGM devuelve el código de error scha_err_seqid a scha_resourcegroup_get() para indicar que la información acerca del grupo de recursos puede haber cambiado. Se trata de un mensaje de error de tipo no fatal; la función devuelve información de forma satisfactoria. En consecuencia, puede ignorar el mensaje y aceptar la información que ha devuelto o cerrar el manejador actual y abrir uno nuevo para acceder a la información del grupo de recursos.

scha_control(3HA)

Solicita el reinicio de un grupo de recursos controlado por RGM o su reubicación en un nodo diferente.

Funciones del clúster

Estas funciones permiten acceder a información sobre un clúster o la devuelven.

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

Estas funciones, juntas, permiten acceder a información sobre un clúster, como los nombres de nodos, ID, estados, nombre del clúster, grupos de recursos, etc.

Un clúster puede cambiar, mediante una reconfiguración o una acción administrativa, después de que scha_cluster_open() devuelva el manejador del clúster, en cuyo caso la información que obtiene scha_cluster_get() a través del manejador puede no ser precisa. En el caso de una reconfiguración del clúster o una acción administrativa, RGM devuelve el código de error scha_err_seqid a scha_cluster_get() para indicar que la información del clúster puede haber cambiado. Se trata de un mensaje de error de tipo no fatal; la función devuelve información de forma satisfactoria. En consecuencia, puede ignorar el mensaje y aceptar la información que ha devuelto o cerrar el manejador actual y abrir uno nuevo para acceder a la información del clúster.

scha_cluster_getlogfacility(3HA)

Devuelve el número del recurso de registro del sistema que se está usando como registro del clúster. Utiliza el valor devuelto con la función syslog() de Solaris para registrar mensajes de estado y eventos en el registro del clúster.

scha_cluster_getnodename(3HA)

Devuelve el nombre del nodo del clúster en el que se invoca la función.

Función de utilidad

Esta función convierte un código de error en un mensaje de error.

scha_strerror(3HA)

Traduce un código de error, devuelto por una de las funciones scha_, al mensaje de error adecuado. Utilice esta función con logger para introducir los mensajes en el registro del sistema (syslog).

Métodos de rellamada de RMAPI

Los métodos de rellamada son los elementos clave que proporciona la API para implementar un tipo de recurso, ya que permiten que RGM controle los recursos del clúster en caso de un cambio en los miembros del clúster, como un arranque o una caída del nodo.

Nota –

RGM ejecuta los métodos de rellamada con permisos de root, porque los programas cliente controlan los servicios de alta disponibilidad (HA) del sistema del clúster. Instale y administre estos métodos con permisos y propiedad de archivos restrictivos. Específicamente, déles un propietario con privilegios, como bin o root, y no los haga grabables.

Esta sección describe los argumentos del método de rellamada y los códigos de salida y enumera y describe los métodos de rellamada de las siguientes categorías:

Nota –

Esta sección proporciona descripciones breves de los métodos de rellamada, incluidos el punto en el que se invoca el método y el efecto esperado en el recurso; la página de comando man rt_callbacks(1HA) es la referencia definitiva para los métodos de rellamada.

Argumentos del método

La sintaxis de los métodos de rellamada de RGM es: 


método -R nombre_recurso -T nombre_tipo -G nombre_grupo

El método es el nombre de ruta del programa que se registra como Start, Stop u otra rellamada. Los métodos de rellamada de un tipo de recurso se declaran en su archivo de registro.

Todos los argumentos del método de rellamada se pasan como valores con indicadores, donde -R indica el nombre de la instancia de recursos, -T indica el tipo del recurso y -G indica el grupo en el que se configura el recurso. Utilice los argumentos con funciones de acceso para recuperar información sobre el recurso.

El método Validate se invoca con argumentos adicionales (los valores de la propiedad del recurso y del grupo de recursos en el que se invoca).

Consulte scha_calls(3HA) para obtener más información.

Códigos de salida

Todos los métodos de rellamada tienen los mismos códigos de salida para especificar el efecto de la invocación del método en el estado del recurso. La página de comando man scha_calls(3HA) describe todos estos códigos de salida. Éstos son:

RGM también maneja los fallos anómalos en la ejecución del método de rellamada, como volcados de núcleo central y la finalización del tiempo de espera.

Las implementaciones del método deben emitir la información sobre fallos utilizando syslog en cada nodo. La salida que se graba en stdout o stderr no está garantizado que se entregue al usuario (aunque aparezca actualmente en la consola del nodo local).

Métodos de rellamada de control e inicialización

Los métodos primarios de rellamada de control e inicialización inician y detienen un recurso. Otros métodos ejecutan un código de inicialización y terminación en un recurso.

Start

Este método obligatorio se invoca en un nodo del clúster cuando el grupo de recursos que contiene el recurso se pone en línea en ese nodo. Este método activa el recurso en ese nodo.

Un método Start no debe salir hasta que el recurso que activa se haya iniciado y esté disponible en el nodo local. Por tanto, antes de salir, el método Start debe interrogar al recurso para determinar si ya se ha iniciado. Se debe establecer un valor de tiempo de espera suficientemente largo para este método. Por ejemplo, algunos recursos, como daemons de base de datos, tardan más tiempo en empezar, por lo que el valor del tiempo de espera de estos métodos debe ser mayor.

La forma en que RGM responde a un fallo del método Start depende de la configuración de la propiedad Failover_mode.

La propiedad START_TIMEOUT del archivo de registro del tipo de recurso establece el valor de tiempo de espera para un método Start de un recurso.

Stop

Este método obligatorio se invoca en un nodo del clúster cuando el grupo de recursos que contiene el recurso se pone fuera de línea en ese nodo. Este método desactiva el recurso si está activo.

Un método Stop no debe salir hasta que el recurso que controla haya detenido completamente toda su actividad en el nodo local y después de que haya cerrado todos los descriptores de archivos. En caso contrario, dado que RGM asume que el recurso se ha detenido, cuando en realidad sigue activo, se puede producir una corrupción de los datos. La forma más segura de evitar que los datos se corrompan es terminar todos los procesos en el nodo local relacionado con el recurso.

Antes de salir, el método Stop deberá interrogar al recurso para determinar si ya se ha detenido. Se debe establecer un valor de tiempo de espera suficientemente largo para este método. Por ejemplo, algunos recursos, como daemons de base de datos, tardan más tiempo en detenerse, por lo que el valor del tiempo de espera de estos métodos debe ser mayor.

La forma en que RGM responde a un fallo del método Stop depende de la configuración de la propiedad Failover_mode (consulte la Tabla A–2).

La propiedad STOP_TIMEOUT del archivo de registro del tipo de recurso establece el valor del tiempo de espera para un método Stop del recurso.

Init

Este método opcional se invoca para realizar una inicialización del recurso una sola vez, cuando éste pase a ser gestionado, tanto cuando el grupo de recursos al que pertenece pasa de un estado no gestionado a un estado gestionado como cuando se crea en un grupo de recursos que ya está gestionado. El método lo invoca en los nodos determinados la propiedad de recurso Init_nodes.

Fini

Este método opcional se invoca para realizar una reorganización detrás del recurso, cuando éste deja de estar gestionado, tanto cuando el grupo de recursos al que pertenece pasa a un estado no gestionado como cuando el recurso se elimina de un grupo de recursos gestionado. El método lo invoca en los nodos determinados la propiedad de recurso Init_nodes.

Boot

Este método opcional, similar a Init, se invoca para inicializar el recurso en los nodos que se unen al clúster después de que el grupo de recursos al que pertenece dicho recurso se haya puesto bajo la gestión de RGM. El método lo invoca en los nodos determinados la propiedad de recurso Init_nodes. El método Boot se invoca cuando el nodo se une o se vuelve a unir al clúster, tras un arranque o un rearranque.

Nota –

Un fallo en los métodos Init, Fini o Boot hace que la función syslog() genere un mensaje de error, pero no afecta de ningún otro modo a la gestión del recurso por parte de RGM.

Métodos de soporte administrativo

Las acciones administrativas en los recursos incluyen la configuración y modificación de las propiedades de los recursos. Los métodos de rellamada Validate y Update permiten que una implementación de tipo de recurso enlace con estas acciones administrativas.

Validate

Este método opcional se invoca cuando se crea un recurso y cuando una acción administrativa actualiza las propiedades del recurso o el grupo de recursos que lo contiene. Esta invocación se realiza en el conjunto de nodos del clúster señalado por la propiedad Init_nodes del tipo de recurso antes de que se aplique la creación o actualización; un código de salida no satisfactorio desde el método en cualquier nodo hace que se cancele la creación o actualización.

Validate se invoca sólo cuando las propiedades del recurso o grupo de recursos se modifican con una acción administrativa, no cuando RGM establece las propiedades ni cuando un supervisor establece las propiedades del recurso Status y Status_msg.

Update

Este método opcional se invoca para notificar un recurso en ejecución cuyas propiedades se hayan cambiado después de que una acción de administración haya configurado satisfactoriamente las propiedades de un recurso o su grupo; se invoca en los nodos en los que el recurso está en línea. El método utiliza las funciones de acceso de API para leer los valores de propiedad que puedan afectar a un recurso activo y ajusta el recurso en ejecución según corresponda.

El fallo del método Update hace que la función syslog() genere un mensaje de error, pero no afecta de ningún otro modo a la gestión del recurso por parte del RGM.

Métodos de rellamada relacionados con la red

Los servicios que usan los recursos de dirección de red pueden requerir que los inicios y las paradas se realicen en un orden determinado, dependiendo de la configuración de la dirección de red. Los siguientes métodos de rellamada opcionales, Prenet_start y Postnet_stop, permiten que una implementación de un tipo de recurso realice acciones especiales de arranque y apagado, antes y después de que se configure o desconfigure una dirección de red relacionada.

Prenet_start

Este método opcional se invoca para que realice acciones de inicio especiales antes de que se configuren las direcciones de red del mismo grupo de recursos.

Postnet_stop

Este método opcional se invoca para que realice acciones de apagado especiales después de que se desconfiguren las direcciones de red del mismo grupo de recursos.

Métodos de rellamada del control del supervisor

Una implementación del tipo de recurso puede incluir, opcionalmente, un programa para supervisar el rendimiento de un recurso, informar de su estado o tomar medidas cuando se produce un fallo de un recurso. Los métodos Monitor_start, Monitor_stop y Monitor_check admiten la implementación de un supervisor de recursos en una implementación del tipo de recurso.

Monitor_start

Este método opcional se invoca para iniciar un supervisor para el recurso, una vez que se haya iniciado éste.

Monitor_stop

Este método opcional se invoca para detener un supervisor de un recurso antes de que éste se detenga.

Monitor_check

Este método opcional se invoca para evaluar la fiabilidad de un nodo antes de que se reubique un grupo de recursos en el nodo. El método Monitor_check se debe implementar de forma que no entre en conflicto con la ejecución simultánea de otro método.