※ リポジトリは、https://github.com/linux-ha-japan/doc-ja に移行しました。
日本語翻訳ドキュメント用リポジトリ
| Revisión | 22db173ef5f31262a4538608851b5e7a582edc95 (tree) |
|---|---|
| Tiempo | 2012-02-27 20:20:51 |
| Autor | Keisuke MORI <kskmori@inte...> |
| Commiter | Keisuke MORI |
ra-dev-guide: Initial translation. Based revision: ra-dev-guide-1.0.0
http://hg.linux-ha.org/doc/file/aba98765a68a/dev-guides/ra-dev-guide.txt
| @@ -0,0 +1,1234 @@ | ||
| 1 | += OCFリソースエージェント開発者ガイド | |
| 2 | + | |
| 3 | +== はじめに | |
| 4 | + | |
| 5 | +本書は、OCF（Open Cluster Framework）準拠のクラスタリソースエージェントに関して作業をしているすべての開発者、メンテナンス担当者および寄稿者に対するガイドおよびリファレンスとして機能します。本書は、リソースエージェントの構造や一般的機能を説明し、リソースエージェントAPIを説明し、リソースエージェント著者に効果的なヒントやヘルプを提供します。 | |
| 6 | + | |
| 7 | +=== リソースエージェントとは何？ | |
| 8 | + | |
| 9 | +リソースエージェントは、クライアントリソースを管理する実行ファイルです。クラスタリソースに関しては、「クラスタが管理するものはすべてリソースである」という以外、正式な記述はありません。 | |
| 10 | + | |
| 11 | +クラスタリソースは、IPアドレス、ファイルシステム、データベースサービスおよび仮想マシン全体など多種多様なものとなっています。 | |
| 12 | + | |
| 13 | +=== 誰がまたは何がリソースエージェントを使うのか？ | |
| 14 | + | |
| 15 | +OCF（Open Cluster Framework）に準拠したクラスタ管理アプリケーションなら、いずれのアプリケーションも、本書で説明されているリソースエージェントを使いリソースを管理することができます。本書の執筆時、Linuxプラットフォーム用に2つのOCF準拠クラスタ管理アプリケーションがあります。 | |
| 16 | + | |
| 17 | +* _Pacemaker_ ：CorosyncおよびHeartbeatクラスタメッセージングフレームワークの両方をサポートするクラスタマネージャ。Pacemakerは、Linux-HAプロジェクトから進化し独立しています。 | |
| 18 | +* _RGmanager_ ：Red Hat Cluster Suiteでバンドルされているクラスタマネージャ。これは、Corosyncクラスタメッセージングフレームワークだけをサポートします。 | |
| 19 | + | |
| 20 | +=== リソースエージェントはどの言語で記述されているのか？ | |
| 21 | + | |
| 22 | +OCF準拠リソースエージェントは _どのような_ プログラミング言語ででも実装可能です。APIは言語を問いません。しかし、ほとんどのリソースエージェントはshellスクリプトとして実装されています。本ガイドは、主にshell言語で記述されたサンプルコードを使います。 | |
| 23 | + | |
| 24 | +== API定義 | |
| 25 | + | |
| 26 | +=== [[_environment_variables]]環境変数 | |
| 27 | + | |
| 28 | +リソースエージェントは、環境変数を通じて、それが管理するリソースのすべての設定情報を受け取ります。これらの環境変数の名前は、常に、 +OCF_RESKEY_+ という接頭語が付いたリソースパラメータの名前となります。たとえば、リソースが、 +192.168.1.1+ に設定されている +ip+ パラメータを持っている場合、リソースエージェントは、その値を保持する +OCF_RESKEY_ip+ 環境変数にアクセスできます。ユーザによって設定される必要のないリソースパラメータに対しては、つまり、リソースエージェントメタデータでのそのパラメータ定義は +required="true"+ を指定しませんが、リソースエージェントは以下を行う必要があります。 | |
| 29 | + | |
| 30 | +* 適切なデフォルトを提供する。これは、メタデータで宣言される必要があります。慣例により、リソースエージェントは、このデフォルトを保持する +OCF_RESKEY_<parametername>_default+ と名付けられた変数を使います。 | |
| 31 | +* あるいは、空値に対して正しく対処する。 | |
| 32 | + | |
| 33 | +さらに、クラスタマネージャは、 _meta_ リソースパラメータもサポートします。これらは、リソース設定には直接適用されませんが、クラスタリソースマネージャが _どのように_ リソースを管理するかが指定されます。たとえば、Pacemakerクラスタマネージャは、リソースが起動されるべきか停止されるべきかを指定するために、 +target-role+ metaパラメータを使います。 | |
| 34 | + | |
| 35 | +metaパラメータは +OCF_RESKEY_CRM_meta_+ 名前空間でリソースエージェントに渡されます。（この場合、ハイフンはアンダースコアに変換されます）。したがって、 +target-role+ 属性は +OCF_RESKEY_CRM_meta_target_role+ と名付けられた環境変数にマッピングされます。 | |
| 36 | + | |
| 37 | +=== アクション | |
| 38 | + | |
| 39 | +いずれのリソースエージェントも1つのコマンドライン引数をサポートしなければなりません。これは、リソースエージェントが実行しようとしているアクションを指定します。以下のアクションはいずれのリソースエージェントによってサポートされなければなりません。 | |
| 40 | + | |
| 41 | +* +start+ -- リソースを起動します。 | |
| 42 | +* +stop+ -- リソースを停止します。 | |
| 43 | +* +monitor+ -- リソースの状態を問合せします。 | |
| 44 | +* +meta-data+ -- リソースエージェントメタデータをダンプします。 | |
| 45 | +さらに、リソースエージェントは、以下のアクションをオプションとしてサポートします。 | |
| 46 | +* +promote+ -- リソースを +Master+ 役割に変更します（Master/Slaveリソースのみ）。 | |
| 47 | +* +demote+ -- リソースを +Slave+ 役割に変更します（Master/Slaveリソースのみ）。 | |
| 48 | +* +migrate_to+ および +migrate_from+ -- リソースのライブマイグレーションを実施します。 | |
| 49 | +* +validate-all+ --リソースの設定を検証します。 | |
| 50 | +* +usage+ or +help+ -- リソースエージェントがコマンドラインから起動される場合に、クライアントメッセージの代わり使用メッセージを表示します。 | |
| 51 | +* +status+ -- +monitor+ に対する歴史的（旧）同義語。 | |
| 52 | + | |
| 53 | +=== タイムアウト | |
| 54 | + | |
| 55 | +アクションのタイムアウトは、リソースエージェントの範囲外で実施されます。リソースエージェントアクションがどれぐらいの時間実行されているかを監視し、その終了時間にアクションが終了しない場合には、そのアクションを停止するのはクラスタマネージャの責任です。したがって、リソースエージェント自身は、タイムアウトをチェックする必要はありません。しかし、リソースエージェントは、適切なタイムアウト値（正しく設定されれば、クラスタマネージャによって正しく実行される）をユーザに_忠告_することができます。リソースエージェントが、その提案されたタイムアウトをどのように忠告するかについては<<_metadata,以下のセクション>>を参照してください。 | |
| 56 | + | |
| 57 | +=== [[_metadata]]メタデータ | |
| 58 | + | |
| 59 | +それぞれのリソースエージェントは、一連のXML メタデータで自分自身の目的とサポートされているパラメータを記述しなければなりません。このメタデータは、オンラインヘルプに対して、クラスタ管理アプリケーションによって使われ、リソースエージェントのmanページもそれから生成されます。以下は、架空のリソースエージェントからの一連の仮想メタデータです。 | |
| 60 | + | |
| 61 | +[source,xml] | |
| 62 | +-------------------------------------------------------------------------- | |
| 63 | +<?xml version="1.0"?> | |
| 64 | +<!DOCTYPE resource-agent SYSTEM "ra-api-1.dtd"> | |
| 65 | +<resource-agent name="foobar" version="0.1"> | |
| 66 | + <version>0.1</version> | |
| 67 | + <longdesc lang="en"> | |
| 68 | +This is a fictitious example resource agent written for the | |
| 69 | +OCF Resource Agent Developers Guide. | |
| 70 | + </longdesc> | |
| 71 | + <shortdesc lang="en">Example resource agent | |
| 72 | + for budding OCF RA developers</shortdesc> | |
| 73 | + <parameters> | |
| 74 | + <parameter name="eggs" unique="0" required="1"> | |
| 75 | + <longdesc lang="en"> | |
| 76 | + Number of eggs, an example numeric parameter | |
| 77 | + </longdesc> | |
| 78 | + <shortdesc lang="en">Number of eggs</shortdesc> | |
| 79 | + <content type="integer"/> | |
| 80 | + </parameter> | |
| 81 | + <parameter name="superfrobnicate" unique="0" required="0"> | |
| 82 | + <longdesc lang="en"> | |
| 83 | + Enable superfrobnication, an example boolean parameter | |
| 84 | + </longdesc> | |
| 85 | + <shortdesc lang="en">Enable superfrobnication</shortdesc> | |
| 86 | + <content type="boolean" default="false"/> | |
| 87 | + </parameter> | |
| 88 | + <parameter name="datadir" unique="0" required="1"> | |
| 89 | + <longdesc lang="en"> | |
| 90 | + Data directory, an example string parameter | |
| 91 | + </longdesc> | |
| 92 | + <shortdesc lang="en">Data directory</shortdesc> | |
| 93 | + <content type="string"/> | |
| 94 | + </parameter> | |
| 95 | + </parameters> | |
| 96 | + <actions> | |
| 97 | + <action name="start" timeout="20" /> | |
| 98 | + <action name="stop" timeout="20" /> | |
| 99 | + <action name="monitor" timeout="20" | |
| 100 | + interval="10" depth="0" /> | |
| 101 | + <action name="reload" timeout="20" /> | |
| 102 | + <action name="migrate_to" timeout="20" /> | |
| 103 | + <action name="migrate_from" timeout="20" /> | |
| 104 | + <action name="meta-data" timeout="5" /> | |
| 105 | + <action name="validate-all" timeout="20" /> | |
| 106 | + </actions> | |
| 107 | +</resource-agent> | |
| 108 | +-------------------------------------------------------------------------- | |
| 109 | + | |
| 110 | ++resource-agent+ 要素はリソースエージェント毎に1つだけ設定される必要があり、リソースエージェントの +name+ と +version+ を定義します。 | |
| 111 | + | |
| 112 | ++resource-agent+ の +longdesc+ と +shortdesc+ 要素は、リソースエージェントの機能のlong説明とshort説明を設定します。 +shortdesc+ は、リソースエージェントが何をするかの説明（1行）で、通常、簡単なリストで使われます。それに対して +longdesc+ は、リソースエージェントを出来るだけ詳細に説明します。 | |
| 113 | + | |
| 114 | ++parameters+ 要素はリソースエージェントのパラメータを説明し、リソースエージェントがサポートするそれぞれのパラメータに対し て +parameter+ 要素をいくつも持ちます。 | |
| 115 | + | |
| 116 | +それぞれの +parameter+ は、全体的に +resource-agent+ のように、 +shortdesc+ と +longdesc+ と共に設定され、また、パラメータの期待される内容を記述す る +content+ 要素と共に設定されます。 | |
| 117 | + | |
| 118 | ++content+ 要素では、4種類の属性が設定されます。 | |
| 119 | + | |
| 120 | +* +type+ はパラメータタイプ（ +string+ , +integer+ , +boolean+ ）を設定します。デフォルト： +string+ | |
| 121 | + | |
| 122 | +* +required+ はパラメータ設定が必須（ +required="true"+ ）であるかオプション( +required="false"+ )であるかを設定します。 | |
| 123 | + | |
| 124 | +* オプションパラメータに関しては、default属性を通じて適切なデフォルトを提供してください。 | |
| 125 | + | |
| 126 | +* 最後に、 +unique+ 属性（許容値： +true+ 、 +false+ ）は、この特定のリソースタイプのこのパラメータに対してその特定値がクラスタ全体で一意となる必要があることを示します。たとえば、特に多く使われるフローティングIPアドレスは +unique+ として宣言され、1つのIPアドレスは、クラスタを通じて1回しか使用できません。 | |
| 127 | + | |
| 128 | ++actions+ リストは、リソースエージェントが「サポートされている」と宣伝するアクションを定義します。 | |
| 129 | + | |
| 130 | +それぞれの +action+ は、自分自身の +timeout+ 値をリストします。これは、アクションに対してどのような_最小_タイムアウトが設定されるべきかというユーザに対するヒントとなります。これは、特定のリソース（例：IPアドレスやファイルシステム）はすばやく起動／停止できたり、他のリソース（例：データベース）は数分かかったりするのに対応するためです。 | |
| 131 | + | |
| 132 | +さらに、繰り返しアクション（例： +monitor+ ）は、最低推奨 +interval+ も指定する必要があります。 +interval+ は、同じアクションが2回続けて起動される場合の間隔を指定します。 +timeout+ のように、この値はデフォルト設定できません。これは、どのような最低アクション間隔を設定すればいいかというユーザへのヒントにすぎません。 | |
| 133 | + | |
| 134 | +== [[_return_codes]]戻り値 | |
| 135 | + | |
| 136 | +アクションが起動されたら、リソースエージェントは、定義された戻り値で終了しなければなりません。戻り値は、起動されたアクションの結果を呼出側に通知します。戻り値は以下の項で詳細が説明されています。 | |
| 137 | + | |
| 138 | +=== +OCF_SUCCESS+ (0) | |
| 139 | + | |
| 140 | +アクションは正しく終了しています。これは、正しく終了したアクション（ +start+ , +stop+ , +promote+ , +demote+ , +migrate_from+ , +migrate_to+ , +meta_data+ , +help+ および +usage+ ）に対する戻り値となります。しかし、 +monitor+ （ +status+ ：旧エイリアス）に関しては、変更された規定が適用されます。 | |
| 141 | + | |
| 142 | +* primitive (stateless)リソースに関しては、 +monitor+ からの +OCF_SUCCESS+ は、リソースが実行されていることを意味します。実行されておらず正しく停止されたリソースは、 +OCF_NOT_RUNNING+ を返す必要があります。 | |
| 143 | + | |
| 144 | +* master/slave (stateful)リソースに関しては、 +monitor+ からの +OCF_SUCCESS+ は、リソースが _Slaveモードで_ 実行されていることを意味します。Masterモード実行されているリソースは +OCF_RUNNING_MASTER+ を返す必要があり、正しく停止されたリソースは +OCF_NOT_RUNNING+ を返す必要があります。 | |
| 145 | + | |
| 146 | +=== +OCF_ERR_GENERIC+ (1) | |
| 147 | + | |
| 148 | +アクションは汎用エラーを返しています。以下に定義された具体的なエラーコードが、いずれも問題を記述していない場合にのみ、リソースエージェントこの終了コードでアクションを終了する必要があります。 | |
| 149 | + | |
| 150 | +クラスタリソースマネージャは、この終了コードを_ソフト_エラーとして解釈します。これは、具体的に設定されていない限り、リソースマネージャは、同じノードのリソースを再起動することによってインプレース の+OCF_ERR_GENERIC+ で失敗したリソースをリカバリしようとします。 | |
| 151 | + | |
| 152 | +=== +OCF_ERR_ARGS+ (2) | |
| 153 | + | |
| 154 | +リソースエージェントは正しくない引数で起動されました。これは、「あってはならない」エラーに対する安全策で、リソースエージェントは、たとえば、正しくない数のコマンドライン引数で起動されたような場合にのみに返すべきです。 | |
| 155 | + | |
| 156 | +NOTE: リソースエージェントは、サポートしていないアクションを実行するよう指示された場合、このエラーを返すべきではありません。その代わり、そのような状況では、OCF_ERR_UNIMPLEMENTEDを返すべきです。 | |
| 157 | + | |
| 158 | +=== +OCF_ERR_UNIMPLEMENTED+ (3) | |
| 159 | + | |
| 160 | +リソースエージェントは、エージェントが設定していないアクションを実行するよう指示されました。 | |
| 161 | + | |
| 162 | +すべてのリソースエージェントが必須となっているわけではありません。リソースエージェントはそれらを設定しているかしていな い+promote+ , +demote+ , +migrate_to+ , +migrate_from+ および +notify+ はすべてオプショナルのアクションです。non-statefulリソースエージェントが、たとえば、まちがってmaster/slaveリソースに設定された場合、リソースエージェントは、 +promote+ | |
| 163 | +および +demote+ アクションで、 +OCF_ERR_UNIMPLEMENTED+ を返してこの設定エラーについてユーザに警告するべきです。 | |
| 164 | + | |
| 165 | +=== +OCF_ERR_PERM+ (4) | |
| 166 | + | |
| 167 | +アクションは、不十分なアクセス権限により失敗しました。これは、エージェントが特定のファイルを開くことができなかったり、特定のソケットでlistenできなかったり、ディレクトリに書き込みができなかったりしたことによるものです。 | |
| 168 | + | |
| 169 | +クライアントリソースマネージャは、この終了コードを _ハード_エラーとして解釈します。この場合、具体的に設定されていないかぎり、リソースマネージャは、異なるノード（アクセス権限に関する問題がない）でリソースを再起動することにより、このエラーで故障したリソースをリカバリしようとします。 | |
| 170 | + | |
| 171 | + | |
| 172 | +=== +OCF_ERR_INSTALLED+ (5) | |
| 173 | + | |
| 174 | +アクションは、それが実行されたノードに必要コンポーネントがなかったために失敗しました。これは、必要バイナリが実行可能ではなかった、あるいは、重要な設定ファイルが「読めない」ことによるものです。 | |
| 175 | + | |
| 176 | +クラスタマネージャは、この終了コードを _ハード_ エラーとして解釈します。 | |
| 177 | + | |
| 178 | +この場合、具体的に設定されていないかぎり、リソースマネージャは、異なるノード（必要ファイルやバイナリがある）でリソースを再起動することにより、このエラーで故障したリソースをリカバリしようとします。 | |
| 179 | + | |
| 180 | +=== +OCF_ERR_CONFIGURED+ (6) | |
| 181 | + | |
| 182 | +アクションは、ユーザがリソースを正しく設定しなかったために失敗しました。たとえば、ユーザが、整数パラメータに英数字文字列を設定したような場合です。 | |
| 183 | + | |
| 184 | +クラスタリソースマネージャは、この終了コードを _致命的_ エラーとして解釈します。これはクラスタ全体の設定エラーであるため、インプレースのノードではもちろんのこと、異なるノードでそのようなリソースをリカバリするのは意味がありません。リソースがこのエラーで故障すると、クラスタマネージャは、リソースを停止しようとし、管理者の介入を待ちます。 | |
| 185 | + | |
| 186 | +=== +OCF_NOT_RUNNING+ (7) | |
| 187 | + | |
| 188 | +リソースは実行されていないことが判明しました。これは、 +monitor+ アクションのみによって返される終了コードです。 | |
| 189 | + | |
| 190 | +NOTE: これはリソースが _正しく_ 終了されているか、そもそも起動されていなかったことを意味します。 | |
| 191 | + | |
| 192 | +リソースがエラー状態のせいで実行されていない場合、 +monitor+ アクションは、代わりに +OCF_ERR_+ 終了コードの一つか、 +OCF_FAILED_MASTER+ を返すべきです。 | |
| 193 | + | |
| 194 | +=== +OCF_RUNNING_MASTER+ (8) | |
| 195 | + | |
| 196 | +リソースは、 +Master+ roleで実行されていると判明しました。これはstateful (Master/Slave)リソースにのみ適用され、そして、それらの +monitor+ アクションにのみ適用されます。 | |
| 197 | + | |
| 198 | +NOTE: "slaveモードでの実行"に対しては特定の終了コードはありません。これは、通常に実行されているprimitiveリソースと、slaveとして実行されているstatefulリソースの間の区別がないからです。 +Slave+ roleで通常に実行されているstatefulリソース の+monitor+ アクションは +OCF_SUCCESS+ を返します。 | |
| 199 | + | |
| 200 | +=== +OCF_FAILED_MASTER+ (9) | |
| 201 | + | |
| 202 | +リソースは +Master+ roleで故障していると判明しました。これはstateful (Master/Slave)リソースにのみ適用され、そして、それらの +monitor+ アクションにのみ適用されます。 | |
| 203 | + | |
| 204 | +クラスタリソースマネージャは、この終了コードを_ソフト_ エラーとして解釈します。この場合、リソースマネージャは、具体的に設定されていないかぎり、インプレースの +$OCF_FAILED_MASTER+ で故障したリソースをリカバリしようとします。これは、通常、同じノードのリソースを格下げしたり、停止したり、起動したり、そして、プロモートしたりして行います。 | |
| 205 | + | |
| 206 | +== リソースエージェントの構造 | |
| 207 | + | |
| 208 | +典型的（shellベース）のリソースエージェントは、本項でリストされた順序で標準の構成要素を持っています。それらの構成要素は、 +foobar+ と名付けられた仮想リソースエージェントを例として使い、リソースエージェントの期待される動作を、それがサポートする各種のアクションに関して記述します。 | |
| 209 | + | |
| 210 | +=== リソースエージェントインタプリタ | |
| 211 | + | |
| 212 | +スクリプトとして実装されたリソースは、標準の"shebang" (+#!+)ヘッダ構文を使い、そのインタプリタを指定しなければなりません。 | |
| 213 | + | |
| 214 | +-------------------------------------------------------------------------- | |
| 215 | +#!/bin/sh | |
| 216 | +-------------------------------------------------------------------------- | |
| 217 | + | |
| 218 | +リソースエージェントがshellで記述されている場合、必須ではありませんが汎用shellインタプリタを指定してください。 +/bin/sh+ 互換として宣言されたリソースエージェントは、特定のshellにネイティブな構文（例 ：+bash+ にネイティブな +${!variable}+ 構文）を使用できません。必要に応じて、 +checkbashisms+ などのsanitizationユーティリティを使い、そのようなリソースエージェントを実行してください。 | |
| 219 | + | |
| 220 | +それまでは +sh+ 互換であったリソースエージェントが +bash+ 、 +ksh+ あるいは他の非汎用shellにのみにしか互換性がないようにするパッチはリグレッションであると考えます。しかし、新しいリソースエージェントが、 +/bin/bash+ といった特定のshellをインタプリタとして明示的に定義することはまったく問題ありません。 | |
| 221 | + | |
| 222 | +=== 著者およびライセンス情報 | |
| 223 | + | |
| 224 | +リソースエージェントは、リソースエージェントの著者や著作権保持者、そして、リソースエージェントに適用されるライセンスを記載したコメントを記述する必要があります。 | |
| 225 | + | |
| 226 | +[source,bash] | |
| 227 | +-------------------------------------------------------------------------- | |
| 228 | +# | |
| 229 | +# Resource Agent for managing foobar resources. | |
| 230 | +# | |
| 231 | +# License: GNU General Public License (GPL) | |
| 232 | +# (c) 2008-2010 John Doe, Jane Roe, | |
| 233 | +# and Linux-HA contributors | |
| 234 | +-------------------------------------------------------------------------- | |
| 235 | + | |
| 236 | +リソースエージェントが、複数のバージョンに対するライセンスを参照する場合、それはその時点のバージョンが対象であると前提します。 | |
| 237 | + | |
| 238 | +=== [[_initialization]]初期化 | |
| 239 | + | |
| 240 | +どのようなshellリソースエージェントも、 +.ocf-shellfuncs+ 関数ライブラリをソースとしなければなりません。これは、以下の構文を使って、 +$OCF_FUNCTIONS_DIR+ で行うことができます。 +$OCF_FUNCTIONS_DIR+ は、テスト目的およびドキュメンテーションの生成に対して、コマンドラインから上書きされます。 | |
| 241 | + | |
| 242 | +[source,bash] | |
| 243 | +-------------------------------------------------------------------------- | |
| 244 | +# Initialization: | |
| 245 | +: ${OCF_FUNCTIONS_DIR=${OCF_ROOT}/resource.d/heartbeat} | |
| 246 | +. ${OCF_FUNCTIONS_DIR}/.ocf-shellfuncs | |
| 247 | +-------------------------------------------------------------------------- | |
| 248 | + | |
| 249 | +リソースエージェントパラメータのデフォルトは、 +_default+ 接尾語で変数を初期化することにより設定されるべきです。 | |
| 250 | + | |
| 251 | +[source,bash] | |
| 252 | +-------------------------------------------------------------------------- | |
| 253 | +# Defaults | |
| 254 | +OCF_RESKEY_superfrobnicate_default=0 | |
| 255 | + | |
| 256 | +: ${OCF_RESKEY_superfrobnicate=${OCF_RESKEY_superfrobnicate_default}} | |
| 257 | +-------------------------------------------------------------------------- | |
| 258 | + | |
| 259 | +NOTE: リソースエージェントは、メタデータで +required+ と指定されていないパラメータに対してデフォルトを設定しなければなりません。 | |
| 260 | + | |
| 261 | +=== リソースエージェントアクションを実装する関数 | |
| 262 | + | |
| 263 | +以下に、リソースエージェントのアクション（宣伝された）を実装する関数が説明されています。個々のアクションは<<_resource_agent_actions,リソースエージェントアクション>>で詳細が説明されています。 | |
| 264 | + | |
| 265 | +=== 実行ブロック | |
| 266 | +これは、リソースエージェントの一部で、リソースエージェントが起動された場合に実際に実行される部分です。これは、大体において標準的な構造となっています。 | |
| 267 | + | |
| 268 | +[source,bash] | |
| 269 | +-------------------------------------------------------------------------- | |
| 270 | +# Make sure meta-data and usage always succeed | |
| 271 | +case $__OCF_ACTION in | |
| 272 | +meta-data) foobar_meta_data | |
| 273 | + exit $OCF_SUCCESS | |
| 274 | + ;; | |
| 275 | +usage|help) foobar_usage | |
| 276 | + exit $OCF_SUCCESS | |
| 277 | + ;; | |
| 278 | +esac | |
| 279 | + | |
| 280 | +# Anything other than meta-data and usage must pass validation | |
| 281 | +foobar_validate || exit $? | |
| 282 | + | |
| 283 | +# Translate each action into the appropriate function call | |
| 284 | +case $__OCF_ACTION in | |
| 285 | +start) foobar_start;; | |
| 286 | +stop) foobar_stop;; | |
| 287 | +status|monitor) foobar_monitor;; | |
| 288 | +promote) foobar_promote;; | |
| 289 | +demote) foobar_demote;; | |
| 290 | +reload) ocf_log info "Reloading..." | |
| 291 | + foobar_start | |
| 292 | + ;; | |
| 293 | +validate-all) ;; | |
| 294 | +*) foobar_usage | |
| 295 | + exit $OCF_ERR_UNIMPLEMENTED | |
| 296 | + ;; | |
| 297 | +esac | |
| 298 | +rc=$? | |
| 299 | + | |
| 300 | +# The resource agent may optionally log a debug message | |
| 301 | +ocf_log debug "${OCF_RESOURCE_INSTANCE} $__OCF_ACTION returned $rc" | |
| 302 | +exit $rc | |
| 303 | +-------------------------------------------------------------------------- | |
| 304 | + | |
| 305 | +== [[_resource_agent_actions]]リソースエージェントアクション | |
| 306 | + | |
| 307 | +それぞれのアクションは、通常、リソースエージェントの別々の関数やメソッドで実装されています。規定では、これらは、通常、 +<agent>_<action>+ というように名前が付けられています。したがって、 +foobar+ に +start+ アクションを実装する関数は、 +foobar_start()+ というような名前が付けられます。 | |
| 308 | + | |
| 309 | +原則として、 リソースエージェントが致命的なエラーに遭遇した場合、ただちに終了し、例外を出力したり、そうでなければ停止することが許可されています。この例としては設定問題、バイナリのないこと、アクセス権限に関する問題などがあります。また、これらのエラーはコールスタックに渡す必要はありません。 | |
| 310 | + | |
| 311 | +この場合、ユーザの設定に基づいて適切なリカバリアクションを起動するのはクラスタマネージャの責任です。リソースエージェントは、その設定に対しては何も推定するべきではありません。 | |
| 312 | + | |
| 313 | +=== +start+ アクション | |
| 314 | + | |
| 315 | +リソースエージェントは、 +start+ アクションで起動されると、リソースを起動しなければなりません（すでに実行されていない場合）。このことは、エージェントは、リソースの設定を検証し、その状態を問合せし、もしそのリソースが実行されていない場合にのみ、そのリソースを起動する必要があります。これを行う一般的な方法は、以下の例で示されているように、 +validate_all+ および +monitor+ 関数を最初に起動することになるでしょう。 | |
| 316 | + | |
| 317 | +[source,bash] | |
| 318 | +-------------------------------------------------------------------------- | |
| 319 | +foobar_start() { | |
| 320 | + # exit immediately if configuration is not valid | |
| 321 | + foobar_validate_all || exit $? | |
| 322 | + | |
| 323 | + # if resource is already running, bail out early | |
| 324 | + if foobar_monitor; then | |
| 325 | + ocf_log info "Resource is already running" | |
| 326 | + return $OCF_SUCCESS | |
| 327 | + fi | |
| 328 | + | |
| 329 | + # actually start up the resource here (make sure to immediately | |
| 330 | + # exit with an $OCF_ERR_ error code if anything goes seriously | |
| 331 | + # wrong) | |
| 332 | + ... | |
| 333 | + | |
| 334 | + # After the resource has been started, check whether it started up | |
| 335 | + # correctly. If the resource starts asynchronously, the agent may | |
| 336 | + # spin on the monitor function here -- if the resource does not | |
| 337 | + # start up within the defined timeout, the cluster manager will | |
| 338 | + # consider the start action failed | |
| 339 | + while ! foobar_monitor; do | |
| 340 | + ocf_log debug "Resource has not started yet, waiting" | |
| 341 | + sleep 1 | |
| 342 | + done | |
| 343 | + | |
| 344 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 345 | + return $OCF_SUCCESS | |
| 346 | +} | |
| 347 | +-------------------------------------------------------------------------- | |
| 348 | + | |
| 349 | +=== +stop+ アクション | |
| 350 | + | |
| 351 | +リソースエージェントは、 +stop+ アクションで起動された場合、リソース（実行されている場合）を停止しなければなりません。このことは、エージェントはリソースの設定を検証し、その状態を問合せし、そして、それがその時点で実行されている場合にのみ、そのリソースを停止しなければならないことを意味します。これを行う一般的な方法は、以下の例で示されているように、 +validate_all+ およ び +monitor+ 関数を最初に起動することです。ここで覚えておかなければならないのは、 +stop+ は強制的なオペレーションであるということです。リソースエージェントは、その権限の範囲内でリソース（ノードをリブートしたり停止したりできない）を停止する必要があります。以下の例を見てください。 | |
| 352 | + | |
| 353 | +[source,bash] | |
| 354 | +-------------------------------------------------------------------------- | |
| 355 | +foobar_stop() { | |
| 356 | + local rc | |
| 357 | + | |
| 358 | + # exit immediately if configuration is not valid | |
| 359 | + foobar_validate_all || exit $? | |
| 360 | + | |
| 361 | + foobar_monitor | |
| 362 | + rc=$? | |
| 363 | + case "$rc" in) | |
| 364 | + "$OCF_SUCCESS") | |
| 365 | + # Currently running. Normal, expected behavior. | |
| 366 | + ocf_log debug "Resource is currently running" | |
| 367 | + ;; | |
| 368 | + "$OCF_RUNNING_MASTER") | |
| 369 | + # Running as a Master. Need to demote before stopping. | |
| 370 | + ocf_log info "Resource is currently running as Master" | |
| 371 | + foobar_demote || \ | |
| 372 | + ocf_log warn "Demote failed, trying to stop anyway" | |
| 373 | + ;; | |
| 374 | + "$OCF_NOT_RUNNING") | |
| 375 | + # Currently not running. Nothing to do. | |
| 376 | + ocf_log info "Resource is already stopped" | |
| 377 | + return $OCF_SUCCESS | |
| 378 | + ;; | |
| 379 | + esac | |
| 380 | + | |
| 381 | + # actually shut down the resource here (make sure to immediately | |
| 382 | + # exit with an $OCF_ERR_ error code if anything goes seriously | |
| 383 | + # wrong) | |
| 384 | + ... | |
| 385 | + | |
| 386 | + # After the resource has been stopped, check whether it shut down | |
| 387 | + # correctly. If the resource stops asynchronously, the agent may | |
| 388 | + # spin on the monitor function here -- if the resource does not | |
| 389 | + # shut down within the defined timeout, the cluster manager will | |
| 390 | + # consider the stop action failed | |
| 391 | + while foobar_monitor; do | |
| 392 | + ocf_log debug "Resource has not stopped yet, waiting" | |
| 393 | + sleep 1 | |
| 394 | + done | |
| 395 | + | |
| 396 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 397 | + return $OCF_SUCCESS | |
| 398 | + | |
| 399 | +} | |
| 400 | +-------------------------------------------------------------------------- | |
| 401 | + | |
| 402 | +NOTE: 正しいstopオペレーションに対して期待される終了コードは +$OCF_SUCCESS+ です（ +$OCF_NOT_RUNNING+ ではありません）。 | |
| 403 | + | |
| 404 | +IMPORTANT: 失敗したstopオペレーションは危険な状況を生み出す可能性があります。つまり、クラスタマネージャは、ノードを隔離（fencing）することにより問題を解決しようとし、stopオペレーションが失敗したノードをクラスタから強制的に排除します。しかし、最終的にはこの方法はデータを保護しますが、アプリケーションやそれらのユーザに混乱を引き起こします。したがって、リソースエージェントは、適切なリソース停止手段がすべて実行し尽した場合にのみ、エラーで終了する必要があります。 | |
| 405 | + | |
| 406 | +=== [[_literal_monitor_literal_action]]+monitor+ アクション | |
| 407 | + | |
| 408 | ++monitor+ アクションは、リソースのその時点の状態を問合せし、3種類の状態をそれぞれ識別しなければなりません。 | |
| 409 | + | |
| 410 | +* リソースがその時点で実行されています（ +$OCF_SUCCESS+ を返します） | |
| 411 | +* リソースは正しく停止されています（ +$OCF_NOT_RUNNING+ を返します） | |
| 412 | +* リソースはエラーに遭遇したため失敗したと認識されます（エラーを示す適切な +$OCF_ERR_+ コードを返します。） | |
| 413 | + | |
| 414 | +[source,bash] | |
| 415 | +-------------------------------------------------------------------------- | |
| 416 | +foobar_monitor() { | |
| 417 | + local rc | |
| 418 | + | |
| 419 | + # exit immediately if configuration is not valid | |
| 420 | + foobar_validate_all || exit $? | |
| 421 | + | |
| 422 | + ocf_run frobnicate --test | |
| 423 | + | |
| 424 | + # This example assumes the following exit code convention | |
| 425 | + # for frobnicate: | |
| 426 | + # 0: running, and fully caught up with master | |
| 427 | + # 1: gracefully stopped | |
| 428 | + # any other: error | |
| 429 | + case "$?" in | |
| 430 | + 0) | |
| 431 | + rc=$OCF_SUCCESS | |
| 432 | + ocf_log debug "Resource is running" | |
| 433 | + ;; | |
| 434 | + 1) | |
| 435 | + rc=$OCF_NOT_RUNNING | |
| 436 | + ocf_log debug "Resource is not running" | |
| 437 | + ;; | |
| 438 | + *) | |
| 439 | + ocf_log err "Resource has failed" | |
| 440 | + exit $OCF_ERR_GENERIC | |
| 441 | + esac | |
| 442 | + | |
| 443 | + return $rc | |
| 444 | +} | |
| 445 | +-------------------------------------------------------------------------- | |
| 446 | + | |
| 447 | +Stateful (master/slave)リソースエージェントは、より高度な監視機構を使い、 +Master+ roleを引き受けるのにどのインスタンスが最適であるかを識別するヒントをクラスタマネージャに提供することができます。 | |
| 448 | +詳細は<<_specifying_a_master_preference,masterプリファレンスを指定する>>で説明されています。 | |
| 449 | + | |
| 450 | +NOTE: クラスタマネージャは、 _probe_ に対して +monitor+ アクションを起動し、リソースがその時点で実行されているかどうかをテストします。通常、monitorオペレーションは、probeおよび「実際の」monitorアクションの間、まったく同じように機能します。しかし、特定のリソースが、probesに対して特別な処理を行う場合、その目的のために +ocf_is_probe+ 簡易関数がOCF shell関数ライブラリで提供されています。 | |
| 451 | + | |
| 452 | +=== +validate-all+ アクション | |
| 453 | + | |
| 454 | ++validate-all+ アクションは、正しいリソースエージェント設定と作業環境をテストします。 +validate-all+ は、以下のいずれかの戻り値になければなりません。 | |
| 455 | + | |
| 456 | +* +$OCF_SUCCESS+ -- すべてが正しく機能しており、設定も正しく使用可能となっています。 | |
| 457 | +* +$OCF_ERR_CONFIGURED+ -- ユーザはリソースを正しく設定していません。 | |
| 458 | +* +$OCF_ERR_INSTALLED+ -- リソースは正しく設定されているように思われますが、 +validate-all+ が実行されているノードには重要な部分（コンポーネント）がありません。 | |
| 459 | +* +$OCF_ERR_PERM+ -- リソースは正しく設定されており、必要部分（コンポーネント）もすべてありますが、アクセス権限に関するエラー（例：必要ファイルが作成できない）により問題が生じています。 | |
| 460 | + | |
| 461 | ++validate-all+ は、通常、関数で定義されています。この関数は、対応するアクションが明示的に起動される場合にしか呼び出されませんが、sanityチェックのように、他のほとんどの関数からも呼び出し可能となっています。したがって、リソースエージェントの著者は、関数が +start+ , +stop+ ,および +monitor+ オペレーション中に起動され、また、probes中にも起動されることを考慮しなければなりません。 | |
| 462 | + | |
| 463 | +Probesは、検証にあらたな問題を提議します。probe中（クラスタマネージャが、probe実行ノードでリソースが _起動されていない _と予測する場合）、いくつかの必要部分（コンポーネント）は、影響を受けるノードでは使用不可能となると_予測される_かもしれません。たとえば、これには、probe中の読み込みには提供されないストレージデバイスの共有データが含まれます。したがって +validate-all+ 関数は、 +ocf_is_probe+ 簡易関数を使って、probesを特別に取り扱う必要があります。 | |
| 464 | + | |
| 465 | +[source,bash] | |
| 466 | +-------------------------------------------------------------------------- | |
| 467 | +foobar_validate_all() { | |
| 468 | + # Test for configuration errors first | |
| 469 | + if ! ocf_is_decimal $OCF_RESKEY_eggs; then | |
| 470 | + ocf_log err "eggs is not numeric!" | |
| 471 | + exit $OCF_ERR_CONFIGURED | |
| 472 | + fi | |
| 473 | + | |
| 474 | + # Test for required binaries | |
| 475 | + check_binary frobnicate | |
| 476 | + | |
| 477 | + # Check for data directory (this may be on shared storage, so | |
| 478 | + # disable this test during probes) | |
| 479 | + if ! ocf_is_probe; then | |
| 480 | + if ! [ -d $OCF_RESKEY_datadir ]; then | |
| 481 | + ocf_log err "$OCF_RESKEY_datadir does not exist or is not a directory!" | |
| 482 | + exit $OCF_ERR_INSTALLED | |
| 483 | + fi | |
| 484 | + fi | |
| 485 | + | |
| 486 | + return $OCF_SUCCESS | |
| 487 | +} | |
| 488 | +-------------------------------------------------------------------------- | |
| 489 | + | |
| 490 | +=== +meta-data+ アクション | |
| 491 | ++meta-data+ アクションは、リソースエージェントメタデータを標準出力にダンプします。出力は、<<_metadata,メタデータ>>で指定されているようにメタデータフォーマットに準拠する必要があります。 | |
| 492 | + | |
| 493 | +[source,bash] | |
| 494 | +-------------------------------------------------------------------------- | |
| 495 | +foobar_meta_data { | |
| 496 | + cat <<EOF | |
| 497 | +<?xml version="1.0"?> | |
| 498 | +<!DOCTYPE resource-agent SYSTEM "ra-api-1.dtd"> | |
| 499 | +<resource-agent name="foobar" version="0.1"> | |
| 500 | + <version>0.1</version> | |
| 501 | + <longdesc lang="en"> | |
| 502 | +... | |
| 503 | +EOF | |
| 504 | +} | |
| 505 | +-------------------------------------------------------------------------- | |
| 506 | + | |
| 507 | +=== +promote+ アクション | |
| 508 | + | |
| 509 | ++promote+ アクションはオプショナルとなっています。これは、 _stateful_ リソースエージェントによってのみサポートされなければなりません。このことは、エージェントは +Master+ と +Slave+ という2つの個別の役割（role）を識別しなければならないことを意味します。 +Slave+ は、statelessリソースエージェントでの +Started+ 状態と機能的には同じです。したがって、通常（stateless）のリソースエージェントは、 +start+ および +stop+ のみを実装しなければなりませんが、statefulリソースエージェントは、 +Started+ ( +Slave+ ）および +Master+ の役割（role）の間での遷移を可能にするため、 +promote+ アクションもサポートしなければなりません。 | |
| 510 | + | |
| 511 | +[source,bash] | |
| 512 | +-------------------------------------------------------------------------- | |
| 513 | +foobar_promote() { | |
| 514 | + local rc | |
| 515 | + | |
| 516 | + # exit immediately if configuration is not valid | |
| 517 | + foobar_validate_all || exit $? | |
| 518 | + | |
| 519 | + # test the resource's current state | |
| 520 | + foobar_monitor | |
| 521 | + rc=$? | |
| 522 | + case "$rc" in) | |
| 523 | + "$OCF_SUCCESS") | |
| 524 | + # Running as slave. Normal, expected behavior. | |
| 525 | + ocf_log debug "Resource is currently running as Slave" | |
| 526 | + ;; | |
| 527 | + "$OCF_RUNNING_MASTER") | |
| 528 | + # Already a master. Unexpected, but not a problem. | |
| 529 | + ocf_log info "Resource is already running as Master" | |
| 530 | + return $OCF_SUCCESS | |
| 531 | + ;; | |
| 532 | + "$OCF_NOT_RUNNING") | |
| 533 | + # Currently not running. Need to start before promoting. | |
| 534 | + ocf_log info "Resource is currently not running" | |
| 535 | + foobar_start | |
| 536 | + ;; | |
| 537 | + *) | |
| 538 | + # Failed resource. Let the cluster manager recover. | |
| 539 | + ocf_log err "Unexpected error, cannot promote" | |
| 540 | + exit $rc | |
| 541 | + ;; | |
| 542 | + esac | |
| 543 | + | |
| 544 | + # actually promote the resource here (make sure to immediately | |
| 545 | + # exit with an $OCF_ERR_ error code if anything goes seriously | |
| 546 | + # wrong) | |
| 547 | + ocf_run frobnicate --master-mode || exit $OCF_ERR_GENERIC | |
| 548 | + | |
| 549 | + # After the resource has been promoted, check whether the | |
| 550 | + # promotion worked. If the resource promotion is asynchronous, the | |
| 551 | + # agent may spin on the monitor function here -- if the resource | |
| 552 | + # does not assume the Master role within the defined timeout, the | |
| 553 | + # cluster manager will consider the promote action failed. | |
| 554 | + while true; do | |
| 555 | + foobar_monitor | |
| 556 | + if [ $? -eq $OCF_RUNNING_MASTER ]; then | |
| 557 | + ocf_log debug "Resource promoted" | |
| 558 | + break | |
| 559 | + else | |
| 560 | + ocf_log debug "Resource still awaiting promotion" | |
| 561 | + sleep 1 | |
| 562 | + fi | |
| 563 | + done | |
| 564 | + | |
| 565 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 566 | + return $OCF_SUCCESS | |
| 567 | +} | |
| 568 | +-------------------------------------------------------------------------- | |
| 569 | + | |
| 570 | +=== +demote+ アクション | |
| 571 | + | |
| 572 | ++demote+ アクションはオプショナルです。これは、 _stateful_ リソースエージェントによってのみサポートされる必要があります。このことは、エージェントは +Master+ と +Slave+ という2つの個別の役割（role）を識別しなければならないことを意味します。 +Slave+ は、statelessリソースエージェントでの +Started+ 状態と機能的には同じです。したがって、通常（stateless）のリソースエージェントは、 +start+ および +stop+ のみを実装しなければなりませんが、statefulリソースエージェントは、 +Master+ および +Started+ ( +Slave+ )の役割（role）の間での遷移を可能にするため、 +demote+ アクションもサポートしなければなりません。 | |
| 573 | + | |
| 574 | +[source,bash] | |
| 575 | +-------------------------------------------------------------------------- | |
| 576 | +foobar_demote() { | |
| 577 | + local rc | |
| 578 | + | |
| 579 | + # exit immediately if configuration is not valid | |
| 580 | + foobar_validate_all || exit $? | |
| 581 | + | |
| 582 | + # test the resource's current state | |
| 583 | + foobar_monitor | |
| 584 | + rc=$? | |
| 585 | + case "$rc" in) | |
| 586 | + "$OCF_RUNNING_MASTER") | |
| 587 | + # Running as master. Normal, expected behavior. | |
| 588 | + ocf_log debug "Resource is currently running as Master" | |
| 589 | + ;; | |
| 590 | + "$OCF_SUCCESS") | |
| 591 | + # Alread running as slave. Nothing to do. | |
| 592 | + ocf_log debug "Resource is currently running as Slave" | |
| 593 | + return $OCF_SUCCESS | |
| 594 | + ;; | |
| 595 | + "$OCF_NOT_RUNNING") | |
| 596 | + # Currently not running. Getting a demote action | |
| 597 | + # in this state is unexpected. Exit with an error | |
| 598 | + # and let the cluster manager recover. | |
| 599 | + ocf_log err "Resource is currently not running" | |
| 600 | + exit $OCF_ERR_GENERIC | |
| 601 | + ;; | |
| 602 | + *) | |
| 603 | + # Failed resource. Let the cluster manager recover. | |
| 604 | + ocf_log err "Unexpected error, cannot demote" | |
| 605 | + exit $rc | |
| 606 | + ;; | |
| 607 | + esac | |
| 608 | + | |
| 609 | + # actually demote the resource here (make sure to immediately | |
| 610 | + # exit with an $OCF_ERR_ error code if anything goes seriously | |
| 611 | + # wrong) | |
| 612 | + ocf_run frobnicate --unset-master-mode || exit $OCF_ERR_GENERIC | |
| 613 | + | |
| 614 | + # After the resource has been demoted, check whether the | |
| 615 | + # demotion worked. If the resource demotion is asynchronous, the | |
| 616 | + # agent may spin on the monitor function here -- if the resource | |
| 617 | + # does not assume the Slave role within the defined timeout, the | |
| 618 | + # cluster manager will consider the demote action failed. | |
| 619 | + while true; do | |
| 620 | + foobar_monitor | |
| 621 | + if [ $? -eq $OCF_RUNNING_MASTER ]; then | |
| 622 | + ocf_log debug "Resource still awaiting promotion" | |
| 623 | + sleep 1 | |
| 624 | + else | |
| 625 | + ocf_log debug "Resource demoted" | |
| 626 | + break | |
| 627 | + fi | |
| 628 | + done | |
| 629 | + | |
| 630 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 631 | + return $OCF_SUCCESS | |
| 632 | +} | |
| 633 | +-------------------------------------------------------------------------- | |
| 634 | + | |
| 635 | +=== +migrate_to+ アクション | |
| 636 | + | |
| 637 | ++migrate_to+ アクションは、2つの目的に対応しています。 | |
| 638 | + | |
| 639 | +* リソースに対してネイティブの _push_ タイプのマイグレーションを起動します。つまり、これは、リソースがその時点で実行されているノードから、特定のノード _に_ 移動するよう指示します。リソースエージェントは、 +$OCF_RESKEY_CRM_meta_migrate_target+ 環境変数を通じて、その宛先を知っています。 | |
| 640 | + | |
| 641 | +* _freeze/thaw_ ( _suspend/resume_ としても知られている)タイプのマイグレーションでリソースをフリーズします。通常、このモードでは、リソースはその時点でのその宛先ノードについての情報を必要としていません。 | |
| 642 | + | |
| 643 | +以下の例は、pushタイプのマイグレーションを示しています。 | |
| 644 | + | |
| 645 | +[source,bash] | |
| 646 | +-------------------------------------------------------------------------- | |
| 647 | +foobar_migrate_to() { | |
| 648 | + # exit immediately if configuration is not valid | |
| 649 | + foobar_validate_all || exit $? | |
| 650 | + | |
| 651 | + # if resource is not running, bail out early | |
| 652 | + if ! foobar_monitor; then | |
| 653 | + ocf_log err "Resource is not running" | |
| 654 | + exit $OCF_ERR_GENERIC | |
| 655 | + fi | |
| 656 | + | |
| 657 | + # actually start up the resource here (make sure to immediately | |
| 658 | + # exit with an $OCF_ERR_ error code if anything goes seriously | |
| 659 | + # wrong) | |
| 660 | + ocf_run frobnicate --migrate \ | |
| 661 | + --dest=$OCF_RESKEY_CRM_meta_migrate_target \ | |
| 662 | + || exit OCF_ERR_GENERIC | |
| 663 | + ... | |
| 664 | + | |
| 665 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 666 | + return $OCF_SUCCESS | |
| 667 | +} | |
| 668 | +-------------------------------------------------------------------------- | |
| 669 | + | |
| 670 | +対称的に、freeze/thawタイプのマイグレーションは以下のようなfreezeオペレーションを実装します。 | |
| 671 | + | |
| 672 | +[source,bash] | |
| 673 | +-------------------------------------------------------------------------- | |
| 674 | +foobar_migrate_to() { | |
| 675 | + # exit immediately if configuration is not valid | |
| 676 | + foobar_validate_all || exit $? | |
| 677 | + | |
| 678 | + # if resource is not running, bail out early | |
| 679 | + if ! foobar_monitor; then | |
| 680 | + ocf_log err "Resource is not running" | |
| 681 | + exit $OCF_ERR_GENERIC | |
| 682 | + fi | |
| 683 | + | |
| 684 | + # actually start up the resource here (make sure to immediately | |
| 685 | + # exit with an $OCF_ERR_ error code if anything goes seriously | |
| 686 | + # wrong) | |
| 687 | + ocf_run frobnicate --freeze || exit OCF_ERR_GENERIC | |
| 688 | + ... | |
| 689 | + | |
| 690 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 691 | + return $OCF_SUCCESS | |
| 692 | +} | |
| 693 | +-------------------------------------------------------------------------- | |
| 694 | + | |
| 695 | + | |
| 696 | +=== +migrate_from+ アクション | |
| 697 | + | |
| 698 | ++migrate_from+ アクションは以下の2つの目的の1つに対応します。 | |
| 699 | + | |
| 700 | +* リソースに対してネイティブの_push_ タイプマイグレーションを完了する。つまり、マイグレーションが正しく終了したかどうかをチェックし、リソースがローカルノードで実行されているかどうかをチェックします。リソースエージェントは、 +$OCF_RESKEY_CRM_meta_migrate_source+ 環境変数を通じて、そのマイグレーションソースを知っています。 | |
| 701 | +* _freeze/thaw_ ( _suspend/resume_ としても知られている)タイプマイグレーションでリソースを解凍する。このモードでは、通常、リソースはその時点でのそのソースノードについての情報を必要としていません。 | |
| 702 | + | |
| 703 | +以下の例は、pushタイプのマイグレーションを示しています。 | |
| 704 | + | |
| 705 | +[source,bash] | |
| 706 | +-------------------------------------------------------------------------- | |
| 707 | +foobar_migrate_from() { | |
| 708 | + # exit immediately if configuration is not valid | |
| 709 | + foobar_validate_all || exit $? | |
| 710 | + | |
| 711 | + # After the resource has been migrated, check whether it resumed | |
| 712 | + # correctly. If the resource starts asynchronously, the agent may | |
| 713 | + # spin on the monitor function here -- if the resource does not | |
| 714 | + # run within the defined timeout, the cluster manager will | |
| 715 | + # consider the migrate_from action failed | |
| 716 | + while ! foobar_monitor; do | |
| 717 | + ocf_log debug "Resource has not yet migrated, waiting" | |
| 718 | + sleep 1 | |
| 719 | + done | |
| 720 | + | |
| 721 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 722 | + return $OCF_SUCCESS | |
| 723 | +} | |
| 724 | +-------------------------------------------------------------------------- | |
| 725 | + | |
| 726 | +対称的に、freeze/thawタイプのマイグレーションは以下のようなthawオペレーションを実装します。 | |
| 727 | + | |
| 728 | +[source,bash] | |
| 729 | +-------------------------------------------------------------------------- | |
| 730 | +foobar_migrate_from() { | |
| 731 | + # exit immediately if configuration is not valid | |
| 732 | + foobar_validate_all || exit $? | |
| 733 | + | |
| 734 | + # actually start up the resource here (make sure to immediately | |
| 735 | + # exit with an $OCF_ERR_ error code if anything goes seriously | |
| 736 | + # wrong) | |
| 737 | + ocf_run frobnicate --thaw || exit OCF_ERR_GENERIC | |
| 738 | + | |
| 739 | + # After the resource has been migrated, check whether it resumed | |
| 740 | + # correctly. If the resource starts asynchronously, the agent may | |
| 741 | + # spin on the monitor function here -- if the resource does not | |
| 742 | + # run within the defined timeout, the cluster manager will | |
| 743 | + # consider the migrate_from action failed | |
| 744 | + while ! foobar_monitor; do | |
| 745 | + ocf_log debug "Resource has not yet migrated, waiting" | |
| 746 | + sleep 1 | |
| 747 | + done | |
| 748 | + | |
| 749 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 750 | + return $OCF_SUCCESS | |
| 751 | +} | |
| 752 | +-------------------------------------------------------------------------- | |
| 753 | + | |
| 754 | +=== [[_literal_notify_literal_action]]+notify+ アクション | |
| 755 | + | |
| 756 | +通知により、clone（そして、cloneの拡張であるmaster/slaveリソース）のインスタンスは、それらの状態についてお互いに通知します。通知を有効にすると、cloneインスタスのアクションで +pre+ と +post+ が通知されます。そして、クラスタマネージャは、 _すべての_ cloneインスタンスで +notify+ オペレーションを起動します。 +notify+ オペレーションに関しては、追加の環境変数が、リソースエージェント（実行中）に渡されます。 | |
| 757 | + | |
| 758 | +* +$OCF_RESKEY_CRM_meta_notify_type+ --通知タイプ ( +pre+ または +post+ ) | |
| 759 | + | |
| 760 | +* +$OCF_RESKEY_CRM_meta_notify_operation+ -- 通知が説明するオペレーション（アクション） ( +start+ , +stop+ , +promote+ , +demote+ | |
| 761 | +など) | |
| 762 | + | |
| 763 | +* +$OCF_RESKEY_CRM_meta_notify_start_uname+ -- リソースが起動されているノードの名前（ +start+ 通知のみ） | |
| 764 | + | |
| 765 | +* +$OCF_RESKEY_CRM_meta_notify_stop_uname+ -- リソースが停止されているノードの名前( +stop+ 通知のみ) | |
| 766 | + | |
| 767 | +* +$OCF_RESKEY_CRM_meta_notify_master_uname+ -- リソースがその時点で _Masterモード_ にある_ノードの名前 | |
| 768 | + | |
| 769 | +* +$OCF_RESKEY_CRM_meta_notify_promote_uname+ -- リソースがその時点でMaster roleにプロモートされているノードの名前 ( +promote+ 通知のみ) | |
| 770 | + | |
| 771 | +* +$OCF_RESKEY_CRM_meta_notify_demote_uname+ -- ソースがその時点でSlave roleに格下げされているノードの名前 ( +demote+ 通知のみ) | |
| 772 | + | |
| 773 | +通知は、"pull"スキームを使っているmaster/slaveリソースに特に便利です。この場合、masterはプロバイダであり、slaveはサブスクライバとなります。masterは、プロモートが発生した時にのみ明らかであり、slaveは、正しいプロバイダに彼ら自身を加入するよう設定するために "pre-promote" 通知を使うことができます。同じように、サブスクライバも、プロバイダから脱会したいかもそれません。その場合、それに対して "post-demote" 通知を使うことができます。このコンセプトについては以下の例を参照してください。 | |
| 774 | + | |
| 775 | +[source,bash] | |
| 776 | +-------------------------------------------------------------------------- | |
| 777 | +foobar_notify() { | |
| 778 | + local type_op | |
| 779 | + type_op="${OCF_RESKEY_CRM_meta_notify_type}-${OCF_RESKEY_CRM_meta_notify_operation}" | |
| 780 | + | |
| 781 | + ocf_log debug "Received $type_op notification." | |
| 782 | + case "$type_op" in | |
| 783 | + 'pre-promote') | |
| 784 | + ocf_run frobnicate --slave-mode \ | |
| 785 | + --master=$OCF_RESKEY_CRM_meta_notify_promote_uname \ | |
| 786 | + || exit $OCF_ERR_GENERIC | |
| 787 | + ;; | |
| 788 | + 'post-demote') | |
| 789 | + ocf_run frobnicate --unset-slave-mode || exit $OCF_ERR_GENERIC | |
| 790 | + ;; | |
| 791 | + esac | |
| 792 | + | |
| 793 | + return $OCF_SUCCESS | |
| 794 | +} | |
| 795 | +-------------------------------------------------------------------------- | |
| 796 | + | |
| 797 | +NOTE: master/slaveリソースエージェントは、 _multi-master_ 設定をサポートできます。この場合、常に、複数のmasterが存在します。その場合、 +$OCF_RESKEY_CRM_meta_notify_*_uname+ 変数は、それぞれhostnameのリスト（空白文字で区切られた）を持ちます（例で示されているような1つだけのホスト名でなく）。そのような状況の下で、リソースエージェントは、このリストで正しく繰り返される必要があります。 | |
| 798 | + | |
| 799 | +== スクリプト変数 | |
| 800 | +本項は、リソースエージェントに提供される変数（便利さをもたらす）について説明します。エージェントが実行されている間使用できる他の変数については、 | |
| 801 | +<<_environment_variables,環境変数>>と <<_return_codes,戻り値>>を参照してください。 | |
| 802 | + | |
| 803 | +=== +$OCF_ROOT+ | |
| 804 | + | |
| 805 | +OCFリソースエージェントのディレクトリ階層のルート。これは、リソースエージェントによって変更されてはいけません。これは、通常 、+/usr/lib/ocf+ となります。 | |
| 806 | + | |
| 807 | +=== +$OCF_FUNCTIONS_DIR+ | |
| 808 | + | |
| 809 | +リソースエージェントshell関数ライブラリ（ +.ocf-shellfuncs+ ）が常駐しているディレクトリ。これは、通常、 +$OCF_ROOT+ で定義されており、リソースエージェントによって変更されてはいけません。しかし、この変数は、新規または修正リソースエージェントをテストしている間、コマンドラインから上書きされる場合があります。 | |
| 810 | + | |
| 811 | +=== [[_literal_ocf_resource_instance_literal]]+$OCF_RESOURCE_INSTANCE+ | |
| 812 | + | |
| 813 | +リソースインスタンス名。primitive (non-clone, non-stateful) リソースに関しては、これは単なるリソース名となります。clonesおよびstatefulリソースに対してはこれはprimitive名と、その後にコロンとcloneインスタンス番号（例： +p_foobar:0+ ）が続きます。 | |
| 814 | + | |
| 815 | +=== +$__OCF_ACTION+ | |
| 816 | + | |
| 817 | +その時点で起動されているアクション。これは、クラスタが、リソースエージェントを起動する場合に指定する最初のコマンドライン引数です。 | |
| 818 | + | |
| 819 | +=== +$__SCRIPT_NAME+ | |
| 820 | + | |
| 821 | +リソースエージェントの名前。これは、リソースエージェントスクリプトのベース名です（先行するディレクトリ名が削除された）。 | |
| 822 | + | |
| 823 | +=== +$HA_RSCTMP+ | |
| 824 | + | |
| 825 | +リソースエージェントにより使用される一時ディレクトリです。システム起動シーケンス（LSB準拠Linuxディストリビューション）は、システム起動時、このディレクトリが空にされるようにします。それにより、このディレクトリは、ノードリブートの後、状態データを含まないようになります。 | |
| 826 | + | |
| 827 | +== 簡易関数 | |
| 828 | + | |
| 829 | +=== ロギング： +ocf_log+ | |
| 830 | + | |
| 831 | +リソースエージェントは、ロギングに対して +ocf_log+ 関数を使います。この簡易ロギングラッパーは以下のように起動されます。 | |
| 832 | + | |
| 833 | +[source,bash] | |
| 834 | +-------------------------------------------------------------------------- | |
| 835 | +ocf_log <severity> "Log message | |
| 836 | +-------------------------------------------------------------------------- | |
| 837 | + | |
| 838 | +これは、以下のseverityをサポートします。 | |
| 839 | + | |
| 840 | +* +debug+ -- デバッギングメッセージ用。ほとんどのロギング設定はデフォルトでこのレベルを抑制します。 | |
| 841 | +* +info+ -- エージェントの行動または状態に関する情報メッセージ。 | |
| 842 | +* +warn+ -- 警告用。これは、回復できないエラーを_生じない_予想外行動を反映するメッセージに対するものです。 | |
| 843 | +* +err+ --エラー用。原則的にこのロギングレベルは、適切なエラーコードでの +exit+ の直前でのみ使われるべきです。 | |
| 844 | +* +crit+ -- クリティカルエラー用。 +err+ でのこのロギングレベルは、リソースエージェントがエラーコードで終了する以外、使われるべきではありません。これはごくまれにしか使われません。 | |
| 845 | + | |
| 846 | +=== バイナリ用テスト： +have_binary+ および +check_binary+ | |
| 847 | + | |
| 848 | +リソースエージェントは、特定の実行可能ファイルの使用可能性をテストする必要があります。ここでは +have_binary+ 簡易関数が便利です。 | |
| 849 | + | |
| 850 | +[source,bash] | |
| 851 | +-------------------------------------------------------------------------- | |
| 852 | +if ! have_binary frobnicate; then | |
| 853 | + ocf_log warn "Missing frobnicate binary, frobnication disabled!" | |
| 854 | +fi | |
| 855 | +-------------------------------------------------------------------------- | |
| 856 | + | |
| 857 | +バイナリのないことがリソースに対して致命的エラーとなる場合 、+check_binary+ 関数が使われるべきです。 | |
| 858 | + | |
| 859 | +[source,bash] | |
| 860 | +-------------------------------------------------------------------------- | |
| 861 | +check_binary frobnicate | |
| 862 | +-------------------------------------------------------------------------- | |
| 863 | + | |
| 864 | ++check_binary+ を使うのは、指定されたバイナリの存在（そして実行可能性）と +$OCF_ERR_INSTALLED+ で終了する（見つからない場合または実行されない場合）をテストする省略メソッドです。 | |
| 865 | + | |
| 866 | +NOTE: テスト用のバイナリがフルパスとして指定されていない場合、 +have_binary+ および +check_binary+ は、両方とも +$PATH+ を使います。バイナリインストレーションパスワードは、ディストリビューションやユーザポリシーによって異なるため、フルパスはテストしないほうがいいでしょう。 | |
| 867 | + | |
| 868 | +=== コマンドを実行し、それらの出力を記録する： +ocf_run+ | |
| 869 | + | |
| 870 | +リソースエージェントがコマンドを実行し、その出力を記録する必要がある場合、リソースエージェントは、この例で起動されているように +ocf_run+ 簡易関数を使う必要があります。 | |
| 871 | + | |
| 872 | +[source,bash] | |
| 873 | +-------------------------------------------------------------------------- | |
| 874 | +ocf_run "frobnicate --spam=eggs" || exit $OCF_ERR_GENERIC | |
| 875 | +-------------------------------------------------------------------------- | |
| 876 | + | |
| 877 | +上記のコマンドを使い、リソースエージェントは、 +frobnicate --spam=eggs+ を起動し、その出力と終了コードを記録します。終了コードが非ゼロ（エラーを示す）の場合、 +ocf_run+ が +err+ ロギングseverityでコマンド出力をログし、そして、その後リソースエージェントは終了します。リソースエージェントが正しいコマンド実行と失敗したコマンド実行の両方の結果を記録したい場合 、 +ocf_run+ を +-v+ フラグで使用できます。以下の例では、 +ocf_run+ は、コマンド終了コードがゼロの場合（成功）、コマンドからの出力を +info+ severityでログし、コマンド終了コードがゼロ以外の場合、 +err+ で出力をログします。 | |
| 878 | + | |
| 879 | +[source,bash] | |
| 880 | +-------------------------------------------------------------------------- | |
| 881 | +ocf_run -v "frobnicate --spam=eggs" || exit $OCF_ERR_GENERIC | |
| 882 | +-------------------------------------------------------------------------- | |
| 883 | + | |
| 884 | +最後に、リソースエージェントが、ゼロ以外の終了コードのコマンドの出力を、severityが _other_ thanのエラーでログしたい場合は、 +-info+ または +-warn+ オプションを +ocf_run+ に付加して行うことができます。 | |
| 885 | + | |
| 886 | +[source,bash] | |
| 887 | +-------------------------------------------------------------------------- | |
| 888 | +ocf_run -warn "frobnicate --spam=eggs" | |
| 889 | +-------------------------------------------------------------------------- | |
| 890 | + | |
| 891 | +=== ロック： +ocf_take_lock+ および +ocf_release_lock_on_exit+ | |
| 892 | + | |
| 893 | +リソースに関しては、クラスタ設定において同じタイプの異なるリソースがある場合があります。それらは、並列でアクションを実行するべきではありません。同じマシンでアクションが同時実行されないようにするために、リソースエージェントは 、+ocf_take_lock+ および +ocf_release_lock_on_exit+ 簡易関数を使うことができます。 | |
| 894 | + | |
| 895 | +[source,bash] | |
| 896 | +-------------------------------------------------------------------------- | |
| 897 | +LOCKFILE=${HA_RSCTMP}/foobar | |
| 898 | +ocf_release_lock_on_exit $LOCKFILE | |
| 899 | + | |
| 900 | +foobar_start() { | |
| 901 | + ... | |
| 902 | + ocf_take_lock $LOCKFILE | |
| 903 | + ... | |
| 904 | +} | |
| 905 | +-------------------------------------------------------------------------- | |
| 906 | + | |
| 907 | ++ocf_take_lock+ は、指定された +$LOCKFILE+ を読み込もうとします。これが不可能な場合 、+ocf_take_lock+ は、0秒から1秒の間、ランダムな時間スリープし、その後、リトライします 。+ocf_release_lock_on_exit+ は、エージェントが終了する場合（なんらかの理由で）、lockfileをリリースします。 | |
| 908 | + | |
| 909 | +=== 数値に対してテストする： +ocf_is_decimal+ | |
| 910 | + | |
| 911 | +特にパラメータ検証において、指定された値が数値であるかどうかをテストすると効果的です。そのため に+ocf_is_decimal+ 関数があります。 | |
| 912 | + | |
| 913 | +-------------------------------------------------------------------------- | |
| 914 | +foobar_validate_all() { | |
| 915 | + if ! ocf_is_decimal $OCF_RESKEY_eggs; then | |
| 916 | + ocf_log err "eggs is not numeric!" | |
| 917 | + exit $OCF_ERR_CONFIGURED | |
| 918 | + fi | |
| 919 | + ... | |
| 920 | +} | |
| 921 | +-------------------------------------------------------------------------- | |
| 922 | + | |
| 923 | +=== ブール値に対してテストする： +ocf_is_true+ | |
| 924 | + | |
| 925 | +リソースエージェントがbooleanパラメータを定義する場合、そのパラメータに対する値は、 +0+/+1+ 、 +true+/+false+ あるいは +on+ / +off+ としてユーザにより指定されます。しかし、これは、リソースエージェントからの各種のすべての値をテストするには面倒であることから、エージェントは代わり に+ocf_is_true+ 簡易関数を使うべきです。 | |
| 926 | + | |
| 927 | +[source,bash] | |
| 928 | +-------------------------------------------------------------------------- | |
| 929 | +if ocf_is_true $OCF_RESKEY_superfrobnicate; then | |
| 930 | + ocf_run "frobnicate --super" | |
| 931 | +fi | |
| 932 | +-------------------------------------------------------------------------- | |
| 933 | + | |
| 934 | +NOTE: +ocf_is_true+ が、空の変数あるいは存在しない変数に対して使われると、その関数は、常に、 +1+ の終了コードを返します。これは +false+ と同じです。 | |
| 935 | + | |
| 936 | +=== 疑似リソース： +ha_pseudo_resource+ | |
| 937 | + | |
| 938 | +「疑似リソース」というのは、リソースエージェントが、実際には、startしたりstopしたりしない実行可能プロセスに類似したもので、単一のアクションを実行するだけのものであり、したがって、アクションが実行されたかどうかを追跡する何らかのフォームが必要となります。 +portblock+ リソースエージェントがこの例です。疑似リソースに対するリソースエージェントは +ha_pseudo_resource+ 簡易関数を使います。この簡易関数はリソースの状態を記録する _tracking files_ を使います。 +foobar+ が疑似リソースを管理するよう構築されている場合、その +start+ アクションは以下のようになります。 | |
| 939 | + | |
| 940 | +[source,bash] | |
| 941 | +-------------------------------------------------------------------------- | |
| 942 | +foobar_start() { | |
| 943 | + # exit immediately if configuration is not valid | |
| 944 | + foobar_validate_all || exit $? | |
| 945 | + | |
| 946 | + # if resource is already running, bail out early | |
| 947 | + if foobar_monitor; then | |
| 948 | + ocf_log info "Resource is already running" | |
| 949 | + return $OCF_SUCCESS | |
| 950 | + fi | |
| 951 | + | |
| 952 | + # start the pseudo resource | |
| 953 | + ha_pseudo_resource ${OCF_RESOURCE_INSTANCE} start | |
| 954 | + | |
| 955 | + # After the resource has been started, check whether it started up | |
| 956 | + # correctly. If the resource starts asynchronously, the agent may | |
| 957 | + # spin on the monitor function here -- if the resource does not | |
| 958 | + # start up within the defined timeout, the cluster manager will | |
| 959 | + # consider the start action failed | |
| 960 | + while ! foobar_monitor; do | |
| 961 | + ocf_log debug "Resource has not started yet, waiting" | |
| 962 | + sleep 1 | |
| 963 | + done | |
| 964 | + | |
| 965 | + # only return $OCF_SUCCESS if _everything_ succeeded as expected | |
| 966 | + return $OCF_SUCCESS | |
| 967 | +} | |
| 968 | +-------------------------------------------------------------------------- | |
| 969 | + | |
| 970 | +== 特記事項 | |
| 971 | + | |
| 972 | +=== ライセンス | |
| 973 | + | |
| 974 | +リソースエージェント寄稿者は、新規リソースエージェントには、GNU General Public License (GPL)（バージョン2以降）を使用してください。shell関数ライブラリは、これについては強制はしていませんが、GNU General Public License (GPL)（バージョン2以降）でライセンスされています（それによりnon-GPLエージェントにより使用されます）。リソースエージェントは、自分自身のライセンスをエージェントソースコードで明示的に_記述しなければなりません_。 | |
| 975 | + | |
| 976 | +=== ロケール設定 | |
| 977 | + | |
| 978 | +<<_initialization,初期化>>で説明されているよう に+.ocf-shellfuncs+ を読み込む場合、リソースエージェントの、+LANG+ および +LC_ALL+ は自動的に +C+ ロケールに設定されます。それにより、リソースエージェントは、常に、 +C+ ロケールで機能すると期待でき 、+LANG+ やいずれの +LC_+ 環境変数自体をリセットする必要がありません。 | |
| 979 | + | |
| 980 | + | |
| 981 | +=== 実行中プロセスに対してテストする | |
| 982 | + | |
| 983 | +特定のプロセス（既知のプロセスIDを持った）がその時点で実行されているかどうかをテストするのによく用いられる方法は、それに +0+ シグナルを送り、エラーをキャッチすることです。以下に類似した方法が示されています。 | |
| 984 | + | |
| 985 | +[source,bash] | |
| 986 | +-------------------------------------------------------------------------- | |
| 987 | +if kill -s 0 `cat $daemon_pid_file`; then | |
| 988 | + ocf_log debug "Process is currently running" | |
| 989 | +else | |
| 990 | + ocf_log warn "Process is dead, removing pid file" | |
| 991 | + rm -f $daemon_pid_file | |
| 992 | +if | |
| 993 | +-------------------------------------------------------------------------- | |
| 994 | + | |
| 995 | +この方法は大きな欠点があります。 +kill -s 0+ は、zombieプロセスに対しても正しく終了します。Zombieは、defunctプロセスとしても知られているもので、実行はされてはいませんが、プロセステーブルでエントリを保持しているプロセスです。したがって、それらは、すべての場合に対して、故障したリソースと見なされ、それらに対する +kill -s 0+ アプローチは、誤解を招きやすい成功結果を生じます。この場合、 +kill -s 0+ アプローチは、別のセーフガード（ただしLinuxでしか機能しません）を使うことができます。 | |
| 996 | + | |
| 997 | +[source,bash] | |
| 998 | +-------------------------------------------------------------------------- | |
| 999 | +pid=`cat $daemon_pid_file` | |
| 1000 | +if kill -s 0 $pid; then | |
| 1001 | + # Process exists in process table, check its status | |
| 1002 | + if grep -E "State:[[:space:]]+Z \(zombie\)" /proc/$pid/status; then | |
| 1003 | + ocf_log err "Process is defunct" | |
| 1004 | + # Bail out and let the cluster manager recover | |
| 1005 | + exit $OCF_ERR_GENERIC | |
| 1006 | + else | |
| 1007 | + ocf_log_debug "Process is currently running" | |
| 1008 | + fi | |
| 1009 | +else | |
| 1010 | + ocf_log warn "Process is dead, removing pid file" | |
| 1011 | + rm -f $daemon_pid_file | |
| 1012 | +if | |
| 1013 | +-------------------------------------------------------------------------- | |
| 1014 | + | |
| 1015 | +IMPORTANT: これらの例よりずっと高度はアプローチがあります。それは、daemonをクライアントプロセスに接続することにより、そのdaemonの _機能_ をテストすることです。これは、<<_literal_monitor_literal_action,+monitor+>>アクションの例で示されています。 | |
| 1016 | + | |
| 1017 | +=== [[_specifying_a_master_preference]]masterプリファレンスを指定する | |
| 1018 | + | |
| 1019 | +Stateful (master/slave)リソースはそれら自身の _master プリファレンス_ を設定する必要があります。それにより、それらはクラスタマネージャにヒントを提供できます。これは、 +Master+ roleへプロモートするためのベストインスタンスとなります。 | |
| 1020 | + | |
| 1021 | +IMPORTANT: 複数のインスタンスが同一の正のmasterプリファレンスを持つことができます。この場合、クラスタリソースマネージャは、プロモートするリソースエージェントを自動的に選択します。しかし、 _すべての_ インスタンスが（デフォルト）masterスコア（0）を持っている場合、クラスタマネージャは、どのインスタンスをもプロモートしません。 したがって、少なくとも1つのインスタンスが正のmasterスコアを持っていなければなりません。 | |
| 1022 | + | |
| 1023 | +これに対しては、 +crm_master+ が効果的です。 +crm_attribute+ の簡易ラッパーは、master-<<_literal_ocf_resource_instance_literal,$OCF_RESOURCE_INSTANCE>>と名前が付けられたノード属性を設定し（それが実行されているノードに対して）、指定された値をこの属性に設定します。そして、クラスタマネージャは、対応するインスタンスに対して、これをプロモートスコアに変換します。 | |
| 1024 | + | |
| 1025 | +Statefulリソースエージェントは、通常、 <<_literal_monitor_literal_action,+monitor+>>や<<_literal_notify_literal_action,+notify+>>アクション中に +crm_master+ を実行します。以下の例では、 +foobar+ リソースエージェントは、アプリケーションの状態をテストすることができます。これは、以下のいずれかに基づいた特定の終了コードを返すバイナリを実行することにより行われます。 | |
| 1026 | + | |
| 1027 | +* リソースがmaster roleかslave（masterに完全に追いついた；いずれにしても最新データを持っている）であるかどうか | |
| 1028 | +* リソースがslave role（しかし、なんらかの非同期複製がmasterより「遅れている」）であるかどうか | |
| 1029 | +* リソースが正しく停止されているかどうか | |
| 1030 | +* リソースが予期しないで故障したかどうか | |
| 1031 | + | |
| 1032 | + | |
| 1033 | +[source,bash] | |
| 1034 | +-------------------------------------------------------------------------- | |
| 1035 | +foobar_monitor() { | |
| 1036 | + local rc | |
| 1037 | + | |
| 1038 | + # exit immediately if configuration is not valid | |
| 1039 | + foobar_validate_all || exit $? | |
| 1040 | + | |
| 1041 | + ocf_run frobnicate --test | |
| 1042 | + | |
| 1043 | + # This example assumes the following exit code convention | |
| 1044 | + # for frobnicate: | |
| 1045 | + # 0: running, and fully caught up with master | |
| 1046 | + # 1: gracefully stopped | |
| 1047 | + # 2: running, but lagging behind master | |
| 1048 | + # any other: error | |
| 1049 | + case "$?" in | |
| 1050 | + 0) | |
| 1051 | + rc=$OCF_SUCCESS | |
| 1052 | + ocf_log debug "Resource is running" | |
| 1053 | + # Set a high master preference. The current master | |
| 1054 | + # will always get this, plus 1. Any current slaves | |
| 1055 | + # will get a high preference so that if the master | |
| 1056 | + # fails, they are next in line to take over. | |
| 1057 | + crm_master -l reboot -v 100 | |
| 1058 | + ;; | |
| 1059 | + 1) | |
| 1060 | + rc=$OCF_NOT_RUNNING | |
| 1061 | + ocf_log debug "Resource is not running" | |
| 1062 | + # Remove the master preference for this node | |
| 1063 | + crm_master -l reboot -D | |
| 1064 | + ;; | |
| 1065 | + 2) | |
| 1066 | + rc=$OCF_SUCCESS | |
| 1067 | + ocf_log debug "Resource is lagging behind master" | |
| 1068 | + # Set a low master preference: if the master fails | |
| 1069 | + # right now, and there is another slave that does | |
| 1070 | + # not lag behind the master, its higher master | |
| 1071 | + # preference will win and that slave will become | |
| 1072 | + # the new master | |
| 1073 | + crm_master -l reboot -v 5 | |
| 1074 | + ;; | |
| 1075 | + *) | |
| 1076 | + ocf_log err "Resource has failed" | |
| 1077 | + exit $OCF_ERR_GENERIC | |
| 1078 | + esac | |
| 1079 | + | |
| 1080 | + return $rc | |
| 1081 | +} | |
| 1082 | +-------------------------------------------------------------------------- | |
| 1083 | + | |
| 1084 | + | |
| 1085 | +== リソースエージェントをテスト、インストール、そして、パッケージングする | |
| 1086 | + | |
| 1087 | +本項は、リソースエージェントがいったん設定された後、何をするかについて説明します。つまり、本項ではリソースをどのようにテストするか、どこにインストールするか、そして、どのようにしてアプリケーションパッケージやLinux-HAリソースエージェントリポジトリのいずれかにインクルードするかが説明されています。 | |
| 1088 | + | |
| 1089 | +=== リソースエージェントをテストする | |
| 1090 | + | |
| 1091 | +リソースエージェントリポジトリ（したがって、インストールされたいずれのリソースエージェントパッケージ）は、 +ocf-tester+ と名付けられたユーティリティを含んでいます。このshellスクリプトは、リソースエージェントの機能を効率的に簡単にテストできるようにします。通常、 +ocf-tester+ は、以下で示されているように +root+ として起動されます。 | |
| 1092 | + | |
| 1093 | +-------------------------------------------------------------------------- | |
| 1094 | +ocf-tester -n <name> [-o <param>=<value> ... ] <resource agent> | |
| 1095 | +-------------------------------------------------------------------------- | |
| 1096 | + | |
| 1097 | +* +<name>+ は、任意のリソース名です。 | |
| 1098 | + | |
| 1099 | +* +<param>=<value>+ は、 +-o+ オプションで、テスト用に設定したいリソースパラメータに応じていくつでも設定できます。 | |
| 1100 | + | |
| 1101 | +* +<resource agent>+ がリソースエージェントへの完全パスです。 | |
| 1102 | + | |
| 1103 | ++ocf-tester+ は、起動されると、すべての必須アクションを実行し、<<_resource_agent_actions,リソースエージェントアクション>>で説明されているようにアクションを強制実行します。 | |
| 1104 | + | |
| 1105 | +また、これは、オプショナルのアクションもテストします。オプショナルアクションは、宣伝された時、期待通りに実行される必要がありますが、実装されていない場合には、 +ocf-tester+ がエラーを示さないようにします。 | |
| 1106 | + | |
| 1107 | +IMPORTANT: +ocf-tester+ はアクションの「ドライラン」を起動しませんし、いかなる種類のリソースダミーをも作成しません。そのかわり、これは、実際のリソースエージェントをそのまま実行します。この場合、それが、データベースのオープンやクローズ、ファイルシステムの実装、仮想マシンの起動や停止などを含んでいても、そのまま実行します。この場合、これは注意して使用しなければなりません。たとえば、以下のように、 +foobar+ リソースデータベースで +ocf-tester+ を実行することができます。 | |
| 1108 | + | |
| 1109 | +-------------------------------------------------------------------------- | |
| 1110 | +# ocf-tester -n foobartest \ | |
| 1111 | + -o superfrobnicate=true \ | |
| 1112 | + -o datadir=/tmp \ | |
| 1113 | + /home/johndoe/ra-dev/foobar | |
| 1114 | +Beginning tests for /home/johndoe/ra-dev/foobar... | |
| 1115 | +* Your agent does not support the notify action (optional) | |
| 1116 | +* Your agent does not support the reload action (optional) | |
| 1117 | +/home/johndoe/ra-dev/foobar passed all tests | |
| 1118 | +-------------------------------------------------------------------------- | |
| 1119 | + | |
| 1120 | + | |
| 1121 | +=== リソースエージェントをインストールする | |
| 1122 | + | |
| 1123 | +リソースエージェントを自分自身のプロジェクトに含めたい場合、正しい場所にそれをインストールしてください。リソースエージェントは、 +/usr/lib/ocf/resource.d/<provider>+ ディレクトリにインストールにインストールしてください。この場合、 +<provider>+ はプロジェクトの名前、または、リソースエージェントを識別したいなんらかの名前を入れてください。 | |
| 1124 | + | |
| 1125 | +たとえば、 +foobar+ リソースエージェントが、 +fortytwo+ という名前のプロジェクトの一部としてパッケージされている場合、そのリソースエージェントへの正しい完全パスは +/usr/lib/ocf/resource.d/fortytwo/foobar+ となります。この場合、リソースエージェントは、 +0755+ ( +-rwxr-xr-x+ )アクセス権限ビットでインストールしてください。 | |
| 1126 | + | |
| 1127 | +この方法でインストールを行うと、 OCF準拠クラスタリソースマネージャは、リソースエージェントを正しく識別し、パースし、実行できるようになります。たとえば、Pacemakerクラスタマネージャは、上記のインストレーションパスを +ocf:fortytwo:foobar+ リソースタイプ識別子にマッピングします。 | |
| 1128 | + | |
| 1129 | +=== リソースエージェントをパッケージする | |
| 1130 | + | |
| 1131 | +パッケージリソースがプロジェクトの一部としてパッケージする場合、本項で説明されている注意事項に従ってください。 | |
| 1132 | + | |
| 1133 | +NOTE: 代わりにリソースエージェントを Linux-HAリソースエージェントリポジトリに提出したい場合、その詳細については <<_submitting_resource_agents,リソースエージェントを提出する>>を参照してください。 | |
| 1134 | + | |
| 1135 | +==== [[_rpm_packaging]]RPMパッケージング | |
| 1136 | + | |
| 1137 | +OCFリソースエージェントは 、+<toppackage>-resource-agents+ という名前でRPMサブパッケージに入れてください。この場合、パッケージがそのプロバイダディレクトリを所有しており、上位 +resource-agents+ パッケージ（ディレクトリ階層を設定し簡易shell関数を提供する）に依存していることを確認してください。以下にRPM仕様スニペットが示されています。 | |
| 1138 | + | |
| 1139 | +-------------------------------------------------------------------------- | |
| 1140 | +%package resource-agents | |
| 1141 | +Summary: OCF resource agent for Foobar | |
| 1142 | +Group: System Environment/Base | |
| 1143 | +Requires: %{name} = %{version}-%{release}, resource-agents | |
| 1144 | + | |
| 1145 | +%description resource-agents | |
| 1146 | +This package contains the OCF-compliant resource agents for Foobar. | |
| 1147 | + | |
| 1148 | +%files resource-agents | |
| 1149 | +%defattr(755,root,root,-) | |
| 1150 | +%dir %{_prefix}/lib/ocf/resource.d/fortytwo | |
| 1151 | +%{_prefix}/lib/ocf/resource.d/fortytwo/foobar | |
| 1152 | +-------------------------------------------------------------------------- | |
| 1153 | + | |
| 1154 | +NOTE: RPM spec ファイルに +%package+ 宣言が記述されている場合、RPMは、それ を+Name+ , +Version+ , +License+ などのトップレベルフィールドを継承するサブパッケージであると認識します。そのようなサブパッケージは、それ自身の名前の前に、トップレベルパッケージの名前を自動的に付加します。したがって、上記のスニペットは +foobar-resource-agents+ (パッケージ +Name+ は +foobar+ であると前提されている)と名前が付けられたサブパッケージを作成します。 | |
| 1155 | + | |
| 1156 | +==== Debianパッケージング | |
| 1157 | + | |
| 1158 | +Debianパッケージに関しては、<<_rpm_packaging,RPMs>>と同じように、リソースエージェントを保持する別のパッケージを作成してください。この場合、これは +cluster-agents+ パッケージに依存します。 | |
| 1159 | + | |
| 1160 | +NOTE: 本項では +debhelper+ でパッケージングされていると前提します。以下に +debian/control+ スニペットの例が示されています。 | |
| 1161 | + | |
| 1162 | +-------------------------------------------------------------------------- | |
| 1163 | +Package: foobar-cluster-agents | |
| 1164 | +Priority: extra | |
| 1165 | +Architecture: all | |
| 1166 | +Depends: cluster-agents | |
| 1167 | +Description: OCF-compliant resource agents for Foobar | |
| 1168 | +-------------------------------------------------------------------------- | |
| 1169 | + | |
| 1170 | +ここでは、別の +.install+ ファイルも作成します。 +foobar+ リソースエージェントを +fortytwo+ のサブパッケージとしてインストールする例に従い 、+debian/fortytwo-cluster-agents.install+ ファイルは、以下の内容から構成されます。 | |
| 1171 | + | |
| 1172 | +-------------------------------------------------------------------------- | |
| 1173 | +usr/lib/ocf/resource.d/fortytwo/foobar | |
| 1174 | +-------------------------------------------------------------------------- | |
| 1175 | + | |
| 1176 | +=== [[_submitting_resource_agents]]リソースエージェントを提出する | |
| 1177 | + | |
| 1178 | +リソースエージェントをパッケージにバンドルしないけれども、それを、上位リソースエージェントリポジトリ（http://hg.linux-ha.org/agents[the Linux-HA Mercurial server]でホスティングされている）に提出したい場合、本項で説明されている手順に従ってください。 | |
| 1179 | + | |
| 1180 | +まず、以下のコマンドで、上位リポジトリのワーキングコピー（Mercurial _clone_） を作成してください。 | |
| 1181 | + | |
| 1182 | +-------------------------------------------------------------------------- | |
| 1183 | +hg clone http://hg.linux-ha.org/agents resource-agents | |
| 1184 | +-------------------------------------------------------------------------- | |
| 1185 | + | |
| 1186 | +新規Mercurialキューと、新規パッチセットを作成してください。 | |
| 1187 | + | |
| 1188 | +------------------------------------------------------------------------- | |
| 1189 | +cd resource-agents | |
| 1190 | +hg qinit | |
| 1191 | +hg qnew --edit foobar-ra | |
| 1192 | +-------------------------------------------------------------------------- | |
| 1193 | + | |
| 1194 | +パッチメッセージで、以下のような分かりやすい説明を記述してください。 | |
| 1195 | + | |
| 1196 | +-------------------------------------------------------------------------- | |
| 1197 | +High: foobar: new resource agent | |
| 1198 | + | |
| 1199 | +This new resource agent adds functionality to manage a foobar service. | |
| 1200 | +It supports being configured as a primitive or as a master/slave set, | |
| 1201 | +and also optionally supports superfrobnication. | |
| 1202 | +-------------------------------------------------------------------------- | |
| 1203 | + | |
| 1204 | +リソースエージェントを +heartbeat+ サブディレクトリにコピーしてください。 | |
| 1205 | + | |
| 1206 | +-------------------------------------------------------------------------- | |
| 1207 | +cd heartbeat | |
| 1208 | +cp /path/to/your/local/copy/of/foobar . | |
| 1209 | +chmod 0755 foobar | |
| 1210 | +hg add foobar | |
| 1211 | +cd .. | |
| 1212 | +-------------------------------------------------------------------------- | |
| 1213 | + | |
| 1214 | +次に、 +resource-agents/heartbeat+ で +Makefile.am+ ファイルを編集し、新規リソースエージェントを +ocf_SCRIPTS+ リストに追加してください。これにより、エージェントが正しくインストールされるようにします。最後に +resource-agents/doc+ でMakefile.amを開き 、+ocf_heartbeat_<name>.7+ を +man_MANS+ 変数に追加してください。これにより、リソースエージェントのマニュアルページが、そのメタデータから自動的に作成され、そのマニュアルページが正しい場所にインストールされます。 | |
| 1215 | + | |
| 1216 | +この作業が行われたら、パッチセットを更新することができます。 | |
| 1217 | + | |
| 1218 | +-------------------------------------------------------------------------- | |
| 1219 | +hg qrefresh | |
| 1220 | +-------------------------------------------------------------------------- | |
| 1221 | + | |
| 1222 | +これで、パッチセットはメーリングリストで参照が可能となります。 | |
| 1223 | + | |
| 1224 | +-------------------------------------------------------------------------- | |
| 1225 | +hg email --to=linux-ha-dev@lists.linux-ha.org foobar-ra | |
| 1226 | +-------------------------------------------------------------------------- | |
| 1227 | + | |
| 1228 | +新規リソースエージェントが、マージできるようになれば、上位開発者は、パッチを上位リポジトリにpushします。この時点で、上位からチェックアウトを更新し、元のパッチセットを削除できます。 | |
| 1229 | + | |
| 1230 | +-------------------------------------------------------------------------- | |
| 1231 | +hg qpop -a | |
| 1232 | +hg pull --update | |
| 1233 | +hg qdelete foobar-ra | |
| 1234 | +-------------------------------------------------------------------------- |
Fork
linux-ha-doc/dev-guides/ra-dev-guide.txt