SphinxのSCVersioningでバージョンを切り替えられるマニュアルをつくる

SIOS Coati開発チームの清水です。

今回はSphinxについてです。

Sphinxとは「Pythonでかかれたドキュメント作成ツール」で、PythonやAWS CLIのリファレンスもこのSphinxで作成されているので、みたことがある方は多いかもしれません。

ちなみにSIOS CoatiのマニュアルもSphinxで作成されており、過去にブログでも紹介しました。

SIOS Coatiのオンラインマニュアルの作成方法(前編)


Sphinxでアプリケーションのマニュアルを作成したとき、多くの場合はブラウザ上でも見れるようにオンラインマニュアルの形式で公開すると思います。

そのとき、過去のバージョンのマニュアルをどのように公開するかは、結構悩むポイントだと思います。よくあるパターンとしては、ユーザーがいくつかのバージョンの中から選べるようにすることです。

この機能を用意するには、URLを分割したり、ヘッダー/フッターにスイッチを用意したり、バージョンを自動で追跡させたりと、独自で実装するのは割と大変です。Sphinxを利用しているのであれば、Sphinxの機能を活用していきたいところです。

バージョンを選択できるようにするには、readthedocs のようなホスティングサービスを使うのもひとつの手ですが、今回はホスティングサービスなしでもビルドできる SCVersioning を紹介します。

SCVersioning

https://robpol86.github.io/sphinxcontrib-versioning/index.html

SCVersioningは、複数のバージョンを同時にビルドしてくれて、ページ内にしっかりバージョンを切り替えるためのリンクも用意してくれます。
なお注意点として、マニュアルがgitでバージョン管理されている必要があります。その点だけ、ご注意ください。

インストール

公式に記載の通り pip install  するだけです。

pip install sphinxcontrib-versioning

ここで注意があります。この記事公開時点で、SCVersioningは最新バージョンのSphinxに追従できていないようです。

https://github.com/Robpol86/sphinxcontrib-versioning/issues/42

そのため、公式のものを利用する場合は、Sphinxのバージョンをさげて使用してください。

pip install sphinx==1.5.6

なお Pull-Request に、最新のSphinxに追従したものがあるみたいなので、それを使うのも良いかと思います。(動作は未確認です)

https://github.com/Robpol86/sphinxcontrib-versioning/pull/46

使い方

まず ビルドしたいプロジェクト の Makefile がある場所に移動して、次のコマンドを入力してください。

sphinx-versioning build . _build/html

このコマンドを入力することで、カレントディレクトリをビルドして、ファイルを _build/htmlディレクトリに出力します。
なお、デフォルトだと「masterブランチ」をメインページとなり、すべてのブランチ・タグが生成の対象となります。

基本的に作業は以上になります。とても簡単です。あとは 生成されたファイル(_build/html )を自由に移動すれば完了となります。

ビルドオプション

ビルドオプションをつけないと、すべてブランチ・タグでページを生成します。

そのときは  -W "作成対象とするタグ(正規表現)"  のように指定して、生成対象を決めることができます。

その他、詳細は以下のページに記載されている通りに指定してあげると OK です。

https://robpol86.github.io/sphinxcontrib-versioning/v2.2.1/settings.html

よく使いそうなものをピックアップすると、

-w : 生成対象とするブランチを正規表現で制御

-W : 生成対象とするタグを正規表現で制御

-r : メインページとなるブランチ(タグ)を変更

あたりでしょうか。

基本的には、生成対象以外はデフォルトでも十分使用できるかと思います。

まとめ

今回は Sphinx で作成したマニュアルを、バージョンごとに選択できるようにする SCVersioning を紹介しました。

個人的に SCVersioning の開発リポジトリが最近更新されていないところが気になりますが、とても便利です。

ちょっとしたマニュアルを作った際は、ぜひ使用してみてください。

LinuxからWindowsのコマンドをリモート実行するPythonモジュールpywinrm

SIOS Coati 開発チーム、沼野井です。正月に軍艦島に行って来ました。

前日の天気予報が雪で最悪ゥ―とか思っていたのですが、当日は幸いにも雪も雨も降らず、風もほぼ無風だったので、無事上陸を果たせました。

廃墟マニアならずとも見ごたえのある所でした。皆様もぜひどうぞ!

 

さて本日は、そんな軍艦島とは全く関係のないpywinrm のお話です。

Windowsマシンからリモートで接続されている別のWindowsマシンのコマンドやpowershellコマンドレットを実行するプロトコル(と実装)にWinRMがあります。
Linuxでも、WinRMのクライアントを導入すれば、このプロトコルを利用してWindowsを操作することが可能です。Pythonでそれを実行可能にするのが、pywinrmモジュールです。
今回はこのpywinrm導入の方法と実行の簡単な例を紹介したいと思います。

事前準備

今回ご紹介する例ではWindowsマシンへのアクセスにBasic認証を利用します。この場合、操作する対象のWindows上で以下の設定が必要です。

  • WinRMの通信ポートでの通信をできるようにしておく
    WinRMが使用するデフォルトのポート番号は5985です。
  • PowerShellリモーティングが有効になっている
    ご参考
  • Basic認証を許可する
    以下のコマンドです(要管理者権限)。
  • ネットワークがHomeまたはPrivateになっている
    [コントロールパネル]-[ファイアウォール]-[プライベートネットワーク] から設定できます(windows 10の場合)

 pywinrmの導入

Linux側へのpywinrm導入の手順です。
pipでepelリポジトリからインストールすることができますので、入っていない場合には先にそれらをインストールしてください。

 実行方法

pywinrmを使用した、Windowsリモートアクセスの方法です。

  1. セッションを張る
  2. コマンドを実行する
    1 で張ったセッションを利用します。
    PowerShellコマンドレットの場合は、run_ps()メソッドで実行します。

    Windowsコマンドの場合は、run_cmd()メソッドです。

実行例

WindowsコマンドとPowerShellコマンドレットで、現在日時を取得するサンプルです。

 

Basic認証以外を利用する場合

KerberosまたはCredSSLが使用できまするようです。(試してないです。すみません。)
その場合、別途モジュールの導入が必要です。
README を参照してください。

 


LinuxからWindowsを操作するケースは、様々な端末の操作自動化をLinuxにまとめてしまいたいというシチュエーションなどであるかも知れませんが、そのようなときにぜひご活用ください。

AMI登録解除時、スナップショットを自動で削除するように設定してみました!

こんにちは、SIOS Coati開発担当の黒田です。

EC2のAMIは、EC2のバックアップ用途等で利用することが多いと思いますが、
不要になったAMIを削除する際は、「AMIの登録解除」と「スナップショットの削除」の
両方を実行しなければなりません。

その為、不要になったAMIを削除する作業は、地味に面倒な作業であります。
また、不要になったAMIを削除する際に、AMIと関連しているスナップショットの削除を
忘れてしまって不要なスナップショットが残り無駄なコストがかかってしまったり、
誤って必要なスナップショットを削除してしまうかもしれません。

なので今回は、AWS Lambda と Amazon CloudWatch Events を利用して、AMI登録解除時、
関連するスナップショットを自動で削除する設定方法を紹介したいと思います。

1. ポリシー作成とロール作成

AWS Lambda で使用するポリシーとロールを作成します。

AWSへログイン後、AWSマネージドコンソールからIAMへ移行してください。

ポリシー作成

IAM画面からポリシーの「ポリシーの作成」を選択します。

ビジュアルエディターから以下のポリシーを選択し、ポリシーを作成してください。

  • DescribeSnapshots
  • DeleteSnapshot

ロール作成

IAM画面からポリシーの「ポリシーの作成」を選択します。

「信頼されたエンティティの種類を選択の」AWSサービスの中から「Lambda」を選択し、

「次のステップ:アクセス権限」を選択してください。

以下のポリシーを選択してください。

  • AmazonEC2DeleteSnapshots(今回作成したポリシー)
  • AWSLambdaBasicExecutionRole

「ロール作成」を選択しロールを作成します。

2. AWS Lambda 関数の作成

AMIと関連するスナップショットを削除するAWS Lambda関数を作成します。

AWSマネージドコンソールからAWS Lambdaへ移行し、「関数の作成」を選択してください。

「一から作成」を選択し、以下の情報を入力してください。

  • 名前: delete_snapshot_after_ami_deregister_image
  • ランタイム: Python 3.6
  • 既存のロール: delete_snapshot_after_ami_deregister_image(今回作成したロールです。)
  • コード: 以下のサンプルコードを参照してください。
  • タイムアウト: 30秒(環境により変更してください。)

 

サンプルコード

 

「関数の作成」を選択し、内容を確認して関数を作成してください。

3. Amazon CloudWatch Events設定

AMIの登録解除を契機にAWS Lambda関数を実行するように設定します。

AWSマネージドコンソールからAWS CloudWatchのルールへ移行し、「ルールの作成」を選択してください。

イベントソースの「イベントパターン」を選択し、以下の情報を選択と入力してください。

  • サービス名: EC2
  • イベントタイプ: AWS API Call via CloudTrail
  • 特定のオペレーション : DeregisterImage

ターゲットの「Lambda 関数」を選択し、以下の情報を選択してください。

  • delete_snapshot_after_ami_deregister_image(今回作成したLambda関数を選択)

「設定の詳細」を選択し、内容を確認して設定を完了してください。

4. 動作の確認

AMIの登録を解除したときにAMIと関連するスナップショットが
自動で削除されることを確認してください。

5. まとめ

今回の設定で、AMIの登録解除時に自動でスナップショットを削除するので、
もういちいち個別でスナップショットを削除する必要がありません。

地味な自動化ではありますが、AMIを多く利用している方にとっては、
格段に運用が楽になると思います。

 

参考にさせてもらったページ

AMI削除時にスナップショットも自動で削除するCloudWatch Events

 

Kotlin REPLからAWS SDK for Javaを使う

SIOS Coati開発チームの清水です。

今回は、個人的でオススメしている Kotlin の紹介です。ちなみに製品内でKotlinは使われておりません。。。

Kotlin とは

Kotlinは、IDEのIntelliJやPyCharmなどを開発しているJetBrains社によって開発されたプログラミング言語です。

Kotlinで書かれたプログラムはJava仮想マシン上で動作するため、主にJavaとつながりが強い言語です。そのため、Scalaと共に語られることが多いです。現在はAndroidの公式サポート言語であるため、最近盛り上がっている言語のひとつです。

そんなKotlinですが、利用事例はいまのところ圧倒的にAndroidが多めです。ですが、Android専用というわけではないので、Javaのアプリケーション開発でも使うことができます。

Kotlin REPL

そんなKotlinですが、スクリプト言語だと大体おなじみの対話型で実行できるREPLが用意されています。
(最近になってJavaにも入った!)REPLの使い方として、数行で完結する処理をさくっと書いて実行したいときにとても便利です。

今回折角なので、Linuxコンソール上のKotlinでも同じことをできないか試してみました。最終的にAWSリソースをライブラリでさくっと操作できるようにするのを目標とします。

課題

いざ、Kotlin REPLでAWS APIにアクセスしようと思ったとき問題になるのはライブラリです。

Kotlinは、Javaのライブラリをそのまま利用できるため、AWS SDK for Javaを使うことになります。ただ、Kotlin REPLには、Pythonのpipのようなライブラリを手軽に管理する方法がありません。そのため、通常のアプリケーション同様にGradle・Mavenなどを使って、ライブラリの依存関係などを解決する必要がありそうです。

解決策

今回は「最小限のGradleを定義しておいてライブラリをjarに固める → Kotlin REPLのクラスパスに指定」する方法にしてみました。

今回はJava・Gradle・Kotlinを使用するので SDKMAN を事前にインストールしておきます。そのうえで、次のコマンドでインストールします。

次に作業用ディレクトリを用意し、Gradleをinitコマンドで設定します。ちなみにディレクトリ名はなんでもOKです。

最後に build.gradle を書き換えます。ここに、Kotlinの初期設定と依存ライブラリを指定します。
下側にある dependencies { compile “com.amazonaws:aws-java-sdk:1.11.+” } の中に、使用したいライブラリを追加していきます。ちなみにここで指定するライブラリの情報は、MVNREPOSITORYですぐに見つかります。

あとは実行するだけです

実際に、REPLからライブラリをimportできるか確認します。下はS3のバケット名一覧を取得するサンプルコードです。

unresolved referenceエラーが表示されなければ OK です。ちなみにスクリプトファイルも同じように起動できます。

まとめ

Kotlinはとても書きやすいです。ただREPLだと、いまのところ補完がきかないため、importがわりと大変です。

是非、この機会にKotlinをお試しください!

Developers Summit 2018に出展します!

皆様、こんにちは、SIOS Coatiのマーケティング担当をしております吉岡です。

2018年2月15日(木)、16日(金)の二日間にわたり、Developers Summit 2018に出展いたします。

技術者のコミュニティから生まれたこのイベントをSIOS Coatiは応援します!

今年のテーマは

「変わるもの×変わらないもの」

 

技術の進化が目まぐるしい中で、エンジニアを取り巻く環境及びエンジニアに求められる役割が変化しようとしている中で、変わるものと変わらないものがあると。このような時代にどうエンジニアが立ち向かっていくかを一緒に考えるということがテーマとなっています。

 

確かにAI, Machine Learning, IoTなど新しい技術領域が増えてきて、かつすごいスピードで実用化に向かっています。エンジニアは我々の業界だけかと思っていましたが、すでに業種を超えてエンジニアは増えている。

またエンドユーザ側においてもエンジニアを育成して、自前でクラウド移行を進めている企業もどんどん増えています。

マーケティングの人間から見てもそうなのですから、実情はもっと変化しているのでしょう。

 

話は戻りますが、このイベントではAmazon EC2上で稼働するアプリケーションを自動復旧するクラウドサービスSIOS Coatiをご紹介します。ぜひ、お立ち寄りください。

概要

Developers Summit 2018

日時:2018年2月15日(木)、16日(金) 10:00~ 18:45(16日は18:25まで)
会場:ホテル雅叙園東京
(〒153-0064 東京都目黒区下目黒1-8-1)

本イベントの詳細、お申込みはこちらのサイトをご覧ください。