Rundeck のプラグインは、Rundeck core で利用されるいくつかのサービスのための新しいプロバイダです。 Plugins for Rundeck contain new Providers for some of the Services used by the Rundeck core.
Rundeck にはビルトインのプロバイダがありますが、自分で開発したり、サードパーティ製のプラグインも使ってみましょう。
プリインストールされている script-plugin と stub-plugin については プリインストールプラグイン を参照してください。
プラグインのインストールはシンプルです:
plugin.jar
や some-plugin.zip
のようなプラグインファイルを Rundeck サーバの libext ディレクトリに配置して下さい:
cp some-plugin.zip $RDECK_BASE/libext
これでプラグインが有効化されました。内部で定義されている provider をノードやプロジェクトで利用できるようになっています。
Rundeck サーバをリスタートする必要はありません。
$RDECK_BASE/libext
から目的のファイルを削除すればアンインストールできます。
アップデートの時には古いファイルを新しいファイルで上書きしてください。
プラグインは 1 つ以上のサービスプロバイダを実装したファイル群です。プラグインファイルそれぞれに、異なるタイプのサービス用プロバイダを複数含めることができますが、何らかの形で関連しているプロバイダのみをまとめるのが一般的です。
Rundeck にはいくつかの "built-in" プロバイダと、"included" プラグインファイルが含まれています。
このドキュメントでは、"プラグイン" と "プロバイダ" をほぼ同義に扱います。実際のプロバイダ実装ファイルを参照するときには "プラグインファイル" と言います。
Rundeck Providers and Plugin Files
Rundeck は様々なサービスで動作させるためにいくつかの異なるプラグインタイプをサポートしています。
ノード上でのコマンド実行や、ノードへのファイルコピーの方法について定義するプラグインです。
より詳細な情報については:
リソースモデル情報を指定した種類のソース(たとえば URL、ファイル、ディレクトリ内のファイル群)から取得するメカニズムを定義するプラグインです。
より詳細な情報については:
このタイプのプラグインには異なるドキュメントフォーマットのリソースモデル情報に対するパーサとジェネレータを定義します。さらにこれらは Rundeck システムにおける他の部分と同じくリソースモデルソースプラグインから利用されます。
より詳細な情報については:
Rundeck のコアは、複数ノードに対して様々なワークフロー・ジョブ・コマンドを実行する機能を持ったいくつかの異なる "サービス" を利用します。
各サービスは各 "プロバイダ" を利用しています。各プロバイダはそれぞれを識別するためのユニークな "プロバイダ名" を持っており、ほとんどのサービスはどれを使うか指定しなくてもいいようフォルトのプロバイダを持っています。
Rundeck Services and Providers
サービスはどのように・どこで使われるかによって異なるサービスに分類されます。
サービスカテゴリ:
Node Executor サービス - これらのサービスの各プロバイダはある一つのノード定義の条件下で処理を行います。そしてノードの範囲も設定可能です:
プロジェクトサービス
グローバルサービス(フレームワークレベル)
これらのプラグインのプロバイダがどのように動作するかの詳細については以下で説明しています。
なお、Rundeck のプラグインは 1 つ以上のプロバイダを持つことができます。
Node Executor と File Copier という 2 つのノードサービスは共に似たような設定がされています。これは特定のノードに対して行われるよう設定されているか、またはあるプロジェクトまたはシステム用のデフォルトプロバイダとして設定されています。
複数プロバイダが定義される場合には以下のようにほとんどの定義で各プロバイダに優先順位を付けます:
あるノードに対してプロバイダを有効にするには、そのノードの定義にあるアトリビュートを追加します。
Node Executor プロバイダアトリビュート:
node-executor
ローカルではないノードに対してプロバイダ名を指定します。
local-node-executor
ローカル(Rundeck サーバー)ノードに対してプロバイダ名を指定します。
ファイルコピープロバイダアトリビュート:
file-copier
ローカルではないノードに対してプロバイダ名を指定します。
local-file-copier
ローカル(Rundeck サーバー)ノードに対してプロバイダ名を指定します。
サンプルのノードに対して、stub
という Node Executor プロバイダと File Copier プロバイダを YAML フォーマットで指定した例になります:
remotehost:
hostname: remotehost
node-executor: stub
file-copier: stub
Node Executor
プロジェクトまたはフレームワーク(または両方)のスコープにてノード郡を利用するためにデフォルトで接続されるプロバイダを定義できます。そのために、project.properties
または framework.properties
ファイルに、次のいずれかのプロパティを設定します。
service.NodeExecutor.default.provider
リモートノードに対してデフォルトの Node Executor プロバイダを指定します。
service.NodeExecutor.default.local.provider
ローカルノードに対してデフォルトの Node Executor プロバイダを指定します。
File Copier
service.FileCopier.default.provider
リモートノードに対してデフォルトの File Copier プロバイダを指定します。
service.FileCopier.default.local.provider
ローカルノードに対してデフォルトの File Copier プロバイダを指定します。
サンプルの project.properties
に stub
というデフォルトのローカルプロバイダを設定する例になります:
service.NodeExecutor.default.local.provider=stub
service.FileCopier.default.local.provider=stub
リソースモデルソースプロバイダはあるひとつのプロジェクト内の project.properties
ファイルに対して設定することができます。
そのプロジェクトに対して複数のリソースモデルソースの定義もできます。また必要に応じて指定した指定するプロバイダを混ぜたり組み合わせたり出来ます。
あるプロジェクトで複数のソースプロバイダを定義しているときは、全てのソースのマージがノードセットの結果になり、それらは定義にされた順に並べられます。これは 2 つまたは複数のソースが同じ名前でノードを定義しているとき、一番下にある定義がリストに用いられるということを意味します。
プロバイダが読み込まれノードがマージされたときの順番は:
project.resources.file
: デフォルト設定のファイルモデルソースproject.resources.url
: デフォルト設定の URL モデルソース(オプション)resources.source.N
: 1 から始まる順番の設定以下の方法で各プロジェクトの project.properties
ファイルにてリソースモデルソースの設定ができます:
project.resources.file
を定義する - このファイルパスはあるファイルソースパスとして用いられ、autogenration と includeServerNode はともに true になっています。project.resources.url
を定義する - この URL は URL ソース url として用いられ、キャッシュは ON になっています。このようにより多くのソースのリストから定義することも可能です:
インデックスは 1
から始まり、ナンバー N
のソースについて以下のようなプロパティを定義します:
resources.source.N.type=<provider-name>
resources.source.N.config.<property>=<value>
resources.source.N.config.<property2>=<value2>
...
<provider-name>
に有効なリソースモデルプロバイダ名を指定します。各リソースモデルプロバイダごとに、ソースについてのプロパティ設定が行えます。
デフォルトのファイルプロバイダとその他 2 つのプロバイダの project.properties
設定の例:
project.resources.file=/home/rundeck/projects/example/etc/resources.xml
resources.source.1.type=url
resources.source.1.url=http://server/nodes.yaml
resources.source.2.type=directory
resources.source.2.directory=/home/rundeck/projects/example/resources
リソースフォーマットジェネレータとパーサはリソースノードの定義セットにパースされるまたは、そこからジェネレートされるファイルフォーマットについてのサポートを定義します。
これらはリソースモデルソースといった Rundeck の他のパーツから使われます。
これらのプロバイダを使うのに一切設定は必要ありません。しかし各ジェネレータとパーサといった特定のプロバイダに関してはプロバイダを利用可能な状態にするためにプロバイダ名を知らせる必要があります。パーサまたはジェネレータを使いたいときその特定のプロバイダ名は "フォーマット名"として使われます。
例えば、あるファイルリソースモデルソース(ファイルリソースモデルソース設定を参照してください)に利用される特定のリソースフォーマットパーサを利用可能な状態にするために、そのプロバイダ名を指定します:
resources.source.1.format=myformat
これで "myformat" プロバイダを使うという指定になります。
別のケースでは、実際のプロバイダ名は知られていないかもしれません(例えば、リモート URL からコンテンツを読み込む場合)。各ジェネレータとパーサはある MIME タイプとサポートされているファイルエクステンションのリストを定義していなければいけません。これらはどのパーサ/ジェネレータを使うか決める際に利用されます。
Rundeck がノード上でコマンドアイテムを実行します。そのコマンドはジョブ内のあるワークフローの一部かもしれません、また複数ノードに対して何度も実行されるコマンドかもしれません。
今のところワークフローにて指定できるコマンドアイテムは 3 "種類" あります:
Rundeck はこれらのコマンドタイプを実行するプロセスの一部として Node Executor サービスと File Copier サービスを使います。
"exec" コマンドを実行する一連の処理は以下のようになります:
NodeExecutor#executeCommand
メソッドを呼びます"script" コマンドを実行する一連の処理は以下のようになります:
FileCopier#copy*
メソッドを呼び出しますNodeExecutor
メソッドを呼び出しますNodeExecutor#executeCommand
メソッドを実行しますRundeck がデフォルトサービスを提供するためのわずかなビルトインプロバイダを使います。
Node Executor プロバイダ:
local
ローカルでのコマンド実行。
jsch-ssh
SSH 経由のコマンドのリモート実行。ノードのアトリビュート "hostname" と "username" を必要とします。
File Copier プロバイダ:
local
あるスクリプト用に一時的なローカルファイルを作ります
jsch-scp
SCP 経由のリモートへのコマンドのコピー。ノードのアトリビュート "hostname" と "username" を必要とします。
SSH Node Executor と File Copier は Rundeck にデフォルトで付属しています。
それらを使うための典型的なノード設定はシンプルです。
hostname
アトリビュートをセットします。デフォルトポート 22 番以外を使っている場合は "hostname:port" というフォーマットも可能です。username
アトリビュートにセットします。これでノード上でリモートコマンドを実行したり、スクリプトを実行できるようになります。
設定のオプションについては以下を参照してください。
Sudo パスワード認証
SSH プロバイダは、補助的に Sudo パスワード認証もサポートしています。これは "sudo" コマンドがパスワード認証を必要としたときに、あるユーザーがパスワードをターミナルのパスワードプロンプトに入力するといった認証をシミュレートするものです。
一般的な SSH 設定の記述に加えて、いくつか SCP 用に追加設定があります。
あるリモートノード上であるスクリプトが実行されたとき、まず SCP 経由でスクリプトファイルをコピーし、それから実行します。SSH コネクションプロパティに加えて SCP 用に以下のようなノードアトリビュートを設定できます。
file-copy-destination-dir
: 実行前にそのスクリプトファイルをコピーする先となるリモートノード上のディレクトリ。デフォルトの値は Windowns ノードだと C:/WINDOWS/TEMP
、それ以外は /tmp
となります。osFamily
: windows ノード用には "windows" と指定します。SSH 認証は パスワードまたは公開鍵/秘密鍵認証の 2 つの方法で行われます。
デフォルトでは、公開鍵/秘密鍵認証方式が使われますが、フレームワークスコープ、プロジェクト、ノードによって変更できます。
どちらのメカニズムが使われるかは ssh-authentication
プロパティによって決められます。このプロパティはどちらか 2 つの値を持ちます:
password
privateKey
(デフォルト)ある特定のノードに接続した時、正しい認証メカニズムが選ばれるようこのシーケンスが使われます。
ssh-authentication
アトリビュートにターゲットノードにだけを適用します。project.properties
内の project.ssh-authentication
プロパティ。 project.properties
デフォルトでプロジェクト配下の全ノードに適用します。framework.properties
内の framework.ssh-authentication
プロパティ。デフォルトで全てのプロジェクトのノードに適用します。これらの値が一切セットされてない場合はデフォルトで公開鍵/秘密鍵認証方式が使われます。
SSH 経由で接続するための username は、ノードアトリビュート username
から取得します:
username="user1"
動的にこの値を変化させたい場合はプロパティ参照を組み込むこともできます。例えば、現在の Rundeck 利用者またはジョブのオプション値として username を取得して参照するといったことです:
${job.username}
- Rundeck でジョブを実行している username を使います${option.someUsername}
- "someUsername" というジョブオプションの値を使いますもしノードアトリビュート username
がセットされていない場合はプロジェクトまたはフレームワーク設定で使われてる静的な値を使います。あるノードへの接続時の username は下記の順番で値を探しにいきます:
username
。実行時の値やオプションを参照出来る場合は利用しますproject.properties
ファイル内の project.ssh.user
プロパティframework.properties
ファイル内の framework.ssh.user
プロパティデフォルトの認証メカニズムは公開鍵/秘密鍵認証です。
ビルトイン SSH コネクターにより秘密鍵を数種類の方法でできます。ノード毎、プロジェクト毎、Rundeck インスタンスごとにその方法を変えられます。
リモートノードに接続する時に、Rundeck は秘密鍵ファイルの場所を示したあるプロパティ/アトリビュート を探します。その際、以下の順番で最初にヒットするまで探します:
ssh-keypath
アトリビュート 。ターゲットノードにだけ適用します。project.properties
内の project.ssh-keypath
プロパティ。 デフォルトでプロジェクト配下の全ノードに適用します。framework.properties
内の framework.ssh-keypath
プロパティ. デフォルトで全プロジェクトに適用します。framework.properties
内の framework.ssh.keypath
プロパティ。デフォルトで全プロジェクトに適用します。(1.3 より前の Rundeck にも互換性があります)(デフォルトの値は、~/.ssh/id_rsa
)暗号化したパスフレーズを使う秘密鍵の場合は、ノードで実行する際にパスフレーズを入力させるためにプロンプトをすする "Secure Option" が利用できます。下記の項目を参照してください。
パスフレーズを使った秘密鍵認証は以下のように動作します:
さらに秘密鍵パスフレーズ認証にはいくつかの必要事項と制限があります:
パスフレーズは GUI ・CUI どちらからも入力できます。CUI または API 経由でジョブを実行したい場合はジョブの引数としてパスフレーズを入力します。
SSH 秘密鍵認証を利用可能にするために、まず ssh-authentication
の値が SSH 認証タイプの設定にて説明されているとおりに設定されてるか確かめてください。次に、SSH 秘密鍵の設定にて説明されているとおりに秘密鍵ファイルのパスが設定されているか確かめてください。
今度はジョブの設定を行います。オプションの定義 secureInput
に true
をセットします。このオプション名(ここでいう secureInput
)は自由に決めて構いませんが、ノードの設定でデフォルト値として使われている sshKeyPassphrase
を使うのが一番簡単です。
もしオプション名が sshKeyPassphrase
で無い場合は、以下のアトリビュートがセットされているか確かめてください:
ssh-key-passphrase-option
= "option.NAME
" NAME
部分にジョブのセキュアオプションの名前が入ります。ノードとジョブオプションの設定の例です:
<node name="egon" description="egon" osFamily="unix"
username="rundeck"
hostname="egon"
ssh-keypath="/path/to/privatekey_rsa"
ssh-authentication="privateKey"
ssh-password-option="option.sshKeyPassphrase" />
ジョブ:
<joblist>
<job>
...
<context>
<project>project</project>
<options>
<option required='true' name='sshKeyPassphrase' secure='true'
description="Passphrase for SSH Private Key"/>
</options>
</context>
...
</job>
</joblist>
パスワード認証は以下のように動作します:
パスワードは GUI・CUI どちらからも入力できます。CUI または API 経由でジョブを実行したい場合はジョブの引数としてパスワードを入力します。
パスワード認証を利用可能にするために、まず ssh-authentication
の値を SSH 認証タイプの設定にて説明されているとおりに設定されているか確かめてください。
次にジョブの設定をします。オプションの定義 secureInput
に true
をセットします。このオプション名(ここでいう secureInput
)は自由に決めて構いませんが、ノードの設定でデフォルト値として使われている
SSH 秘密鍵認証を利用可能にするために、まず ssh-authentication
の値が SSH 認証タイプの設定にて説明されているとおりに設定されてるか確かめてください。次に、SSH 秘密鍵の設定にて説明されているとおりに秘密鍵ファイルのパスが設定されているか確かめてください。
今度はジョブの設定を行います。オプションの定義 secureInput
に true
をセットします。このオプション名(ここでいう secureInput
)は自由に決めて構いませんが、ノードの設定でデフォルト値として使われている sshKeyPassphrase
を使うのが一番簡単です。
もしオプション名が sshKeyPassword
で無い場合は、以下のアトリビュートが各ノードにセットされているか確かめてください:
ssh-password-option
= "option.NAME
" : NAME
部分にジョブのセキュアオプションの名前が入ります。ノードとジョブオプションの設定の例です:
<node name="egon" description="egon" osFamily="unix"
username="rundeck"
hostname="egon"
ssh-authentication="password"
ssh-password-option="option.sshPassword1" />
ジョブ:
<joblist>
<job>
...
<context>
<project>project</project>
<options>
<option required='true' name='sshPassword1' secure='true' />
</options>
</context>
...
</job>
</joblist>
SSH プロバイダは 2 つ目の Sudo パスワード認証を設定できるメカニズムをサポートしています。あなたの環境におけるセキュリティ要件で一般的な "rundeck" アカウントではなくそれぞれのユーザアカウントを使って SSH 接続させ、"sudo" レベルのコマンドを実行時にパスワードを要求するような場合に便利です。
このメカニズムは以下のように動作します:
SSH パスワード認証に同じように、Sudo パスワード認証にも必要事項があります:
さらに Sudo パスワード認証にはいくつかの必要事項と制限があります:
パスワードは GUI ・CUI どちらからも入力できます。CUI または API 経由でジョブを実行したい場合はジョブの引数としてパスワードを入力します。
SSH パスワード認証を利用可能にするために、まず ssh-authentication
の値が SSH 認証タイプの設定にて説明されているとおりに設定されてるか確かめてください。
今度はジョブの設定を行います。オプションの定義 secureInput
に true
をセットします。このオプション名(ここでいう secureInput
)は自由に決めて構いませんが、ノードの設定でデフォルト値として使われている sshKeyPassword
を使うのが一番簡単です。
ノードやプロジェクト、Rundeck システム単位にこれらのプロパティの設定を行う事で Sudo パスワード認証が動作するようになります。project.properties の中の project.NAME
や framework.properties の中の framework.NAME
というアトリビュート名をノードにセットします。
sudo-command-enabled
- "true" をセットし、Sudo パスワード認証を利用可能にします。sudo-command-pattern
- Sudo 認証が必要なコマンドを見つけるための正規表現をセットします。デフォルトパターンは ^sudo$
です。sudo-password-option
- どのセキュアオプション値(パスワードとして利用される)かを定義するオプションリファレンス ("option.NAME") をセットしますsudo-prompt-pattern
- Sudo 認証の際のプロンプトを見つけるための正規表現をセットします。デフォルトパターンは ^\[sudo\] password for .+: .*
です。sudo-failure-pattern
- 認証失敗時の出力を見つけるための正規表現をセットします。デフォルトパターンは ^.*try again.*
です。sudo-prompt-max-lines
- 期待されるパスワードプロンプトは最大何行まで読む込むかをセットします。(デフォルトは 12
です)sudo-prompt-max-timeout
- 期待されるパスワードプロンプトが表示されるまで何ミリ秒待つかをセットします。(デフォルト 5000
です)sudo-response-max-lines
- 認証失敗時の出力を探す際何行読み込むかをセットします。(デフォルト 2
です)sudo-response-max-timeout
- maximum milliseconds to wait for response when detecting the failure response. (default 5000
)sudo-response-max-timeout
- 認証失敗時の出力が表示されるまで何ミリ秒待つかをセットします。(デフォルト false
です)sudo-success-on-prompt-threshold
- true/false. If true, succeed (without writing password), if the input max lines are reached without detecting password prompt. (default: true
).sudo-success-on-prompt-threshold
- true/false. true にすると、もしパスワードプロンプトを見つけられずに最大読み込み行数に達した場合に(パスワードを入力せずに)認証成功です。(デフォルトは true
です)????sudo-fail-on-prompt-timeout
- true/false. true にすると、パスワードプロンプトが表示される前にタイムアウトした場合はジョブの実行を失敗とします。(デフォルトは true
です)sudo-fail-on-response-timeout
- true/false. If true, fail on timeout looking for failure message. (default: false
)sudo-fail-on-response-timeout
- true/false. true にすると、認証失敗の出力を探し見つからないままタイムアウトした場合ジョブの実行は失敗となります。(デフォルトは false
です)???ノート: unix で "sudo" が必要なコマンドのデフォルト値は既に設定されていますが、もしインタラクションをカスタマイズする必要がある場合は上書きできます。
今度はジョブの設定を行います。オプションの定義 secureInput
に true
をセットします。このオプション名(ここでいう secureInput
)は自由に決めて構いませんが、ノードの設定でデフォルト値として使われている sudoPassword
を使うのが一番簡単です。
もしオプション名が sudoPassword
で無い場合は、以下のアトリビュートがセットされているか確かめてください:
sudo-password-option
= "option.NAME
" : NAME
部分にジョブのセキュアオプションの名前が入ります。ノードとジョブオプションの設定の例です:
<node name="egon" description="egon" osFamily="unix"
username="rundeck"
hostname="egon"
sudo-command-enabled="true"
sudo-password-option="option.sudoPassword2" />
ジョブ:
<joblist>
<job>
<sequence keepgoing='false' strategy='node-first'>
<command>
<exec>sudo apachectl restart</exec>
</command>
</sequence>
<context>
<project>project</project>
<options>
<option required='true' name='sudoPassword2' secure='true' description="Sudo authentication password"/>
</options>
</context>
...
</job>
</joblist>
ノードに対してさらに高度な sudo パスワード認証設定ができます。例えば "sudo -u user1 sudo -u user2 command" といったような "sudo" コマンドを連鎖的に実行する必要性があり、両方の "sudo" に対してパスワードを入力する必要性がある場合です。あなたの node/project/framework に合わせた 2 つ目のプロパティセットを設定できます。
プロパティの設定方法は、1 つ目の sudo パスワード認証と同じです。 2 つ目 sudo パスワード認証の設定にて説明されています。しかし以下のように、"sudo-" の代わりに "sudo2-" というプリフィックスを使います:
sudo2-command-enabled="true"
sudo2-command-pattern="^sudo .+? sudo .*$"
こうすることにより実行しようとしているコマンドが設定されたパターンにマッチするときは 2 つ目の sudo パスワードプロンプトを表示するよう仕向けます。
"sudo2-password-option" の値が設定されていないときは、デフォルトの値 option.sudo2Password
が利用されます。
"sudo2-command-pattern" について一つ注意点があります:
sudo 認証メカニズムはどちらの設定が呼ばれたのかを確認するために 2 つの正規表現を使います。
1 つ目の sudo 認証かを判別するために、実行されているコマンドの最初の部分と "sudo-command-pattern" の値とマッチングします。このパターンのデフォルト値は ^sudo$
です。
そのため "sudo -u user1 some command" のようなコマンドは正しくマッチします。(例えば、"su" をサポートするよう)正規表現を編集できます。しかしマッチング対象とされるのは常にコマンドの最初の部分であることに注意してください。
"sudo2-command-enabled" が "true" に設定されているとき "sudo2-command-pattern" の値もマッチングします。正しくマッチした場合はもう 1 つの sudo 認証が利用されます。しかし、どちらの sudo 認証を使うべきか決められるよう、コマンド文字列全体 を正規表現とのマッチング対象とします。デフォルトの正規表現は ^sudo .+? sudo .*$
です。必要に応じて正規表現はカスタマイズできます。
Rundeck は以下に示すビルトインプロバイダをコアに持っています:
file
サポートされているリソースフォーマットのファイルを使うプロバイダ。
url
サポートされているリソースフォーマットのリソースを URL から GET して取得するプロバイダ。
directory
あるディレクトリ内のサポートされているファイルを全て読み込むプロバイダ。ファイルプロバイダのエクステンションであり、内部では file
プロバイダを使っています。
script
あるスクリプトによりパースされた出力をサポートされているフォーマットとして使うプロバイダ。
これらのプロバイダの設定を行うには, リソースモデルソースの設定を参照してください。そして以下の項目で出てくるプロパティを使ってください。
file
リソースモデルソースプロバイダはサポートされているリソースモデルドキュメントフォーマットのファイルを読み込みます。
名前 | 値 | 説明 |
---|---|---|
file |
ファイルパス | ディスク上のファイルパス |
format |
フォーマット名 | 明示的にフォーマットを宣言することができます。利用できるフォーマットは file エクステンションのものに限ります。 |
requireFileExists |
true/false | 値が true かつファイルが存在しないとき、ノードの読み込みは失敗となります。(デフォルト: false ) |
includeServerNode |
true/false | 値が true ならば Rundeck サーバーのノードを自動的に含めます(デフォルト: false ) |
generateFileAutomatically |
true/false | 値が true ならば ファイルが存在しないとき、ファイルを自動で作成します。(デフォルト: false) |
format
の値はリソースモデルドキュメントフォーマットにてサポートされているものでなければなりません。ビルトインフォーマットは resourcexml
または resourceyaml
の 2 つです。
例:
resources.source.1.type=file
resources.source.1.file=/home/rundeck/projects/example/etc/resources2.xml
resources.source.1.format=resourcexml
resources.source.1.requireFileExists=true
resources.source.1.includeServerNode=true
resources.source.1.generateFileAutomatically=true
url
リソースモデルソースプロバイダは HTTP GET リクエストでノードの定義を取得します。
設定プロパティ:
Name | Value | Notes |
---|---|---|
url |
URL | http: または https: または file: プロトコルの正しい URL を記述します。 |
cache |
true/false | 値が true ならばサーバーからの ETag/Last-Modified 情報を用い、変更があったときのみ新しいコンテンツをダウンロードします。false の場合は常にダウンロードしてきます。(デフォルト: true) |
timeout |
秒 | リクエストをタイムアウトによる失敗とするまでの秒を指定します。0 とするとタイムアウトは無しとなります。(デフォルト: 30) |
table: リソースモデルソースプロバイダ url
用の設定プロパティ。
リソースモデルドキュメントフォーマット は リモートサーバに送信される MIME タイプを決定するのに利用されます。ビルトインフォーマットは "*/xml" と "*/yaml" と "*/x-yaml" を受け付けます. リソースフォーマットプラグイン を参照してください。
例:
resources.source.1.type=url
resources.source.1.url=file:/home/rundeck/projects/example/etc/resources2.xml
resources.source.1.cache=true
resources.source.1.timeout=0
derectory
リソースモデルソースプロバイダはあるディレクトリにあるすべてのファイルの一覧を表示します。そしてすべてのデフォルト設定オプションを用いてファイルリソースモデルとしてサポートされたファイルエクステンションを持つ各ファイル読み込みます。
Name | Value | Notes |
---|---|---|
directory |
ディレクトリパス | ディレクトリ内のサポートされているファイルエクステンションを持つ全てのファイルが読み込まれます。 |
table: directory
リソースモデルソースプロバイダ用の設定プロパティ
Example:
resources.source.2.type=directory
resources.source.2.directory=/home/rundeck/projects/example/resources
script
リソースモデルソースプロバイダはあるスクリプトファイルを実行します。そしてサポートされている Resource Model Document Formatsの一つとしてその実行結果を読み込みます。
Name | Value | Notes |
---|---|---|
file |
スクリプトファイルパス | interpreter が必要とする場合、スクリプトファイルが実行可能であるべきです |
interpreter |
コマンドまたはインタプリタ | 例. "bash -c" |
args |
渡したい追加の引数 | 引数は実行されるコマンドライン文字列の後ろに追加されます。 |
format |
フォーマット名 | 利用するフォーマットを明記します |
スクリプトはこのように実行されます:
[interpreter] file [args]
STDOUT 上のすべての出力はパースのためにリソースフォーマットパーサに渡されます。利用可能なフォーマットが指定されている必要があります。
例:
resources.source.2.type=script
resources.source.2.file=/home/rundeck/projects/example/etc/generate.sh
resources.source.2.interpreter=bash -c
resources.source.2.args=-project example
resources.source.2.format=resourceyaml
リソースフォーマットサービス(ジェネレータとパーサ)は一般的に同じフォーマット名に対して用いられるマッチするペアとなっています。
Rundeck はこれらのビルトインプロバイダを含んでいます:
resourcexml
リソース XML ドキュメントフォーマットをサポートしています: resource-v13(5) XML.
サポートされている MIME タイプ:
サポートされているファイルエクステンション:
resourceyaml
リソース YAML ドキュメントフォーマットをサポートしています: resource-v13(5) YAML
サポートされている MIME types:
サポートされているファイルエクステンション:
Rundeck には便利な 2 つのプリインストールプラグインが入っており、プラグイン開発およびプラグインの使い方の例としても役立ちます。
The scirpt-plugin
は以下のプロバイダを含んでいます:
script-exec
プロバイダscript-copy
プロバイダ(これらを利用可能にするために Using Providers を参照してくだい)
このプラグインはあるコマンドやローカルまたはリモートのスクリプトのファイルコピーとして実行させたい外部スクリプトやコマンドの指定を可能にします。
この script プラグインによりビルトインの SSH ベースのリモート実行メカニズムや SCP ベースのファイルコピーメカニズムを置き換える事により、外部のどんなメカニズムでも利用可能になります。
ノート: この plugin は スクリプトプラグインの開発 に似た機能を提供します。あなたが書いたスクリプトをテストするためにこのプラグインを使いたい、また後々スクリプトをスタンドアロンプラグインとしてパッケージングしたいと思うかもしれまぜん。
このプラグインの設定を行うには、実行したいコマンドラインの文字列を指定する必要があります。オプションでそのコマンドラインを実行する作業ディレクトリとコマンドを発行させるシェルを指定する事もできます。
プラグインの設定は特定の設定値を用い、全プロジェクトに(フレームワークワイド)、1 つのプロジェクトに(プロジェクトワイド)または特定のノードに対して設定できます。
フレームワーク全体とプロジェクトごとの設定として framework.properties または project.properties ファイルにそれぞれの設定を行います:
plugin.script-exec.default.command
特定ノードに対して設定する場合は script-exec
という名前のアトリビュートをノードのリソース定義に追加します。
script-exec
プロパティの詳細は script-exec コマンドの定義を参照してください。
フレームワークワイド、プロジェクトワイドにて framework.properties または project.properties ファイルのいずれかの設定を行います:
plugin.script-exec.default.dir
特定ノードに対して設定する場合は script-exec-dir
という名前のアトリビュートをノードのリソース定義に追加します。
script-exec-dir
フレームワーク全体とプロジェクトごとの設定として framework.properties または project.properties ファイルにそれぞれの設定を行います:
plugin.script-exec.default.shell
特定ノードに対して設定する場合は script-exec-shell
というアトリビュートをノードのリソース定義に追加します。
script-exec-shell
このプロパティやアトリビュートの値は外部システムプロセス内で実行したい正確なコマンドライン文字列であるはずです。
${node.name
または ${job.name}
のように記述することで、Rundeck の一般的なコマンド実行として データコンテキストプロパティ を利用できます。
さらに、このプラグインは新しいデータコンテキストプロパティを提供します:
exec.command
ワークフロー / ユーザーが指定されている実行したいコマンド
exec.dir
プロパティファイルまたはノード定義に設定されている場合の作業ディレクトリのパス
例:
ビルトイン SSH コマンドが存在する所で、それ他いくつかの外部のリモート接続コマンド ("/bin/execremote") を実行したい場合、以下のアトリビュートを指定できます:
mynode:
node-executor: script-exec
script-exec: /bin/execremote -host ${node.hostname} -user ${node.username} -- ${exec.command}
そのコマンドが特別なハンドリング(クオートや他の値の展開方法)を必要とする場合、シェルを使いたいと思うかもしれない。このケースではシェルを使うという指定ができます。
mynode:
node-executor: script-exec
script-exec-shell: bash -c
script-exec: ssh -o "some quoted option" ${node.username}@${node.hostname} ${exec.command}
実行時、指定されたプロパティは実行するコマンド文字列や特定ノード用の値が展開されます。
または $RDECK_BASE/projects/NAME/etc/project.properties
に置かれた project.properties ファイル内にて、全てのノードに対してデフォルト設定を行うことも可能です。
script-exec.default.command= /bin/execremote -host ${node.hostname} \
-user ${node.username} -- ${exec.command}
同様に $RDECK_BASE/etc/framework.properties
ファイルにて全プロジェクトに対しての設定ができます。
script plugin を使ったコマンドの実行では以下のマナーが守られていることが期待されます:
ノート: STDOUT と STDERR からの全出力は Rundeck のジョブ実行の一部としてキャプチャされます
script-copy の設定を行うには、実行したいコマンドラインの文字列を指定する必要があります。オプションでそのコマンドラインを実行する作業ディレクトリとコマンドを発行させるシェルを指定する事もできます。
プラグインの設定は特定の設定値を用い、全プロジェクトに(フレームワークワイド)、1 つのプロジェクトに(プロジェクトワイド)または特定のノードに対して設定できます。
ターゲットノード上のどこにファイルを置きたいかのファイルパスを設定する必要があります。これには 2 種類の方法があります。
プラグインの設定は特定の設定値を用い、全プロジェクトに(フレームワークワイド)、1 つのプロジェクトに(プロジェクトワイド)または特定のノードに対して設定できます。
フレームワーク全体とプロジェクトごとの設定として framework.properties または project.properties ファイルにそれぞれの設定を行います:
plugin.script-copy.default.command
特定ノードに対して設定する場合はこれらのアトリビュートをノードのリソース定義に追加します。
script-copy
プロパティの詳細は script-copy コマンドの定義を参照してください。
フレームワーク全体とプロジェクトごとの設定として framework.properties または project.properties ファイルにそれぞれの設定を行います:
plugin.script-copy.default.dir
特定ノードに対して設定する場合は script-copy-dir
アトリビュートをノードのリソース定義に追加します。
script-copy-dir
フレームワーク全体とプロジェクトごとの設定として framework.properties または project.properties ファイルにそれぞれの設定を行います:
plugin.script-copy.default.shell
特定ノードに対して設定する場合は script-copy-shell
アトリビュートをノードのリソース定義に追加します。
script-copy-shell
フレームワーク全体とプロジェクトごとの設定として framework.properties または project.properties ファイルにそれぞれの設定を行います:
plugin.script-copy.default.remote-filepath
特定ノードに対して設定する場合は script-copy-remote-filepath
アトリビュートをノードのリソース定義に追加します。
script-copy-remote-filepath
プロパティの詳細は script-copy ファイルパスの定義 を参照してください。
このプロパティもしくは属性の値は、外部システムのプロセスで実行するコマンドライン文字列でなければなりません。
通常の Rundeck のコマンド実行で利用できる ${node.name}
や ${job.name}
などのような データコンテキストプロパティ を利用できます。
加えて、このプラグインは新たなデータコンテキストプロパティを提供します:
file-copy.file
リモートノードにコピーするローカルファイルのパス
file-copy.filename
パス情報を含まないファイル名
例:
標準の SCP コマンドの代わりに外部リモート接続コマンド ("/bin/copyremote") を利用したいとき、ノードごとに以下の属性を指定できます。
mynode:
file-copier: script-copy
script-copy: /bin/copyremote -host ${node.hostname} -user ${node.username} -- ${file-copy.file} ${node.destdir}
実行時、このプロパティは指定したノード用の値に展開され、実行用のコマンド文字列になります。
もしくは、全てのノードに適用されるデフォルト値を $RDECK_BASE/projects/NAME/etc/project.properties
にある project.properties ファイル内に定義することおmできます。
script-copy.default.command= /bin/copyremote -host ${node.hostname} -user ${node.username} -- ${file-copy.file} ${node.destdir}
同様に全てのプロジェクトに適用するために $RDECK_BASE/etc/framework.properties
ファイルを利用できます。 projects.
このプロパティもしくは属性の値は、対象のノード上にあるファイルのフルパスでなければなりません。 スクリプトがコピーしたファイルを後から実行できるので、それを FileCopier サービスに伝えるためのものです。
これは 2つ の方法で実現できます。ここに記載するように設定プロパティとするか、以下に記載する script-copy コマンドの要件 のようにスクリプトからの出力を通じるかです。
通常の Rundeck のコマンド実行で利用できる ${node.name}
や ${job.name}
などのような データコンテキストプロパティ を利用できます。
くわえて、プラグインは新たなデータコンテキストプロパティを提供します:
file-copy.file
リモートノードにコピーされる必要のあるローカルファイルパス
file-copy.filename
パス情報を含まないファイル名
例:
上記から "/bin/copyremote" を例にします。リモートノードのどこにファイルをコピーするかきめるため、script-copy-remote-filepath
を設定する必要があります。この例では ${file-copy.file}
を ${node.destdir}
にコピーします。ノード上のこの属性にディレクトリパスを設定したと仮定します。
script-copy-remote-filepath
にファイルがコピーされた後のリモートノード上の場所を設定する必要があります。 ファイル名は ${file-copy.filename}
が利用可能なので、${node.destdir}/${file-copy.filename}
とセットします:
mynode:
file-copier: script-copy
script-copy: /bin/copyremote -host ${node.hostname} -user ${node.username} -- ${file-copy.file} ${node.destdir}
script-copy-remote-filepath: ${node.destdir}/${file-copy.filename}
実行時、このプロパティは指定したノード用の値に展開され、実行用のコマンド文字列になります。
もしくは、全てのノードに適用されるデフォルト値を $RDECK_BASE/projects/NAME/etc/project.properties
にある project.properties ファイル内に定義することおmできます。
script-copy.default.remote-filepath= ${node.destdir}/${file-copy.filename}
同様に全てのプロジェクトに適用するために $RDECK_BASE/etc/framework.properties
ファイルを利用できます。
script-copy によって実行されるコマンドは以下のマナーに沿うことを求められます。
利用パターンの参考になるスクリプトの例をいくつか載せます。
script-exec:
ノード定義:
mynode:
node-executor: script-exec
プロジェクト設定ファイル project.properties
:
plugin.script-exec.default.command: /tmp/myexec.sh ${node.hostname} ${node.username} -- ${exec.command}
/tmp/myexec.sh
の内容:
#!/bin/bash
# args are [hostname] [username] -- [command to exec...]
host=$1
shift
user=$1
shift
command="$*"
REMOTECMD=ssh
exec $REMOTECMD $user@$host $command
script-copy:
ノード定義:
mynode:
file-copier: script-copy
destdir: /some/node/dir
framework.properties
内のシステムワイド設定:
plugin.script-copy.default.command: /tmp/mycopy.sh ${node.hostname} ${node.username} ${node.destdir} ${file-copy.file}
/tmp/mycopy.sh
の内容:
#!/bin/bash
# args are [hostname] [username] [destdir] [filepath]
host=$1
shift
user=$1
shift
dir=$1
shift
file=$1
name=`basename $file`
# copy to node
CPCMD=scp
exec $CPCMD $file $user@$host:$dir/$name > /dev/null || exit $?
echo "$dir/$name"
ssh リプレースシステム:
この例ではシステムの "ssh" と "scp" コマンドをノード実行とファイルのコピーに使っています。 また、外部スクリプトファイルは使用しません:
Node-only configuration:
mynode:
hostname: mynode
username: user1
node-executor: script-exec
script-exec: ssh -o "StrictHostKeyChecking no" ${node.username}@${node.hostname} ${exec.command}
script-exec-shell: bash -c
file-copier: script-copy
destdir: /tmp
script-copy-shell: bash -c
script-copy: scp ${file-copy.file} ${node.username}@${node.hostname}:${node.destdir}
script-copy-remote-filepath: ${node.destdir}/${file-copy.filename}
デフォルト値は全て以下のような project.properties ファイル内のものがセットされます:
# set default node executor
service.NodeExecutor.default.provider=script-exec
# set script-exec defaults
plugin.script-exec.default.command=ssh -o "StrictHostKeyChecking no" ${node.username}@${node.hostname} ${exec.command}
plugin.script-exec.default.shell=bash -c
#set default file copier
service.FileCopier.default.provider=script-copy
#set script-copy defaults
plugin.script-copy.default.command=scp ${file-copy.file} ${node.username}@${node.hostname}:${node.destdir}
plugin.script-copy.default.shell: bash -c
plugin.script-copy.default.remote-filepath: ${node.destdir}/${file-copy.filename}
このケースではノード定義は単純です:
mynode:
hostname: mynode
username: user1
destdir: /tmp
スタブプラグイン
は以下のプロパイダを含んでいます:
スタブ
スタブ
(これらを有効にするには プロパイダの利用 を参考にして下さい)
このプラグインはリモートファイルのコピーやコマンド実行を実際に行うわけではありません。 コマンドが実行されたかのように単純なエコーを返したり、ファイルがコピーされたように振る舞います。
これは新しいノードやジョブ、ワークフローシーケンスを実際の実行環境に影響を与えずにテストしたい時に利用することを想定しています。
また、以下のノード属性を設定して障害シナリオをテストすることもできます。
stub-exec-success
="true/false"false にセットした場合、スタブコマンドの実行は失敗としてシミュレートされます
stub-result-code
実行結果の戻り値をシミュレートします
たとえば、単に project.properties
ノード executor プロバイダを stub
に設定するだけでプロジェクトのワークフローやジョブを一通りテストしたり無効化することができます。
プラグインはスクリプトを使ってカンタンに開発できます。Java も利用可能です。
詳細については デベロッパーガイド - プラグイン開発 を参照して下さい。