=====================
AAClusterの作成/削除
=====================

.. Contents:: 目次
    :local:
    :depth: 2

AAPF WebUIからAAClusterを作成/削除する
======================================

ウェブブラウザ上でAAClusterの作成や削除を行うには、AAPF WebUIを利用します。
AAPF WebUIを利用するにはブラウザを起動し、AAPF WebUIのURLにアクセスしてください。
アクセスするとログイン画面が表示されますので、ユーザー名とパスワードを入力し、ログインしてください。

ログインすると、AAPF WebUIのTopページが表示されます。Topページには作成済みのAAClusterの一覧が表示され、
この画面からAAClusterの作成や削除が行えます。

.. note::

    AAPF WebUIには、サポートされたブラウザでアクセスしてください。
    サポートブラウザは、Google ChromeとFirefoxです。
    サポートブラウザの詳細については、 :ref:`こちら <supported_browser>` を参照してください。

Topページの詳しい説明は :doc:`aapf_webui` を参照してください。

AAClusterを作成する
-------------------

#. Topページ右上の :guilabel:`[Create AACluster]` ボタンを押下します。
#. AACluster作成画面の :guilabel:`[Input Cluster Name]` フォームにクラスタ名を入力し、Jupyter Notebookのコンテナイメージ、性能タイプを選択します。
   性能タイプの詳細は :ref:`available-resource` を参照してください。
#. :guilabel:`[Create AACluster]` ボタンを押下します。

    下図のように、:guilabel:`[Status]` が :guilabel:`[created]` となり、
    隣接するアイコンが緑色になれば作成完了です。

.. image:: ./_static/created_cluster.png

.. note::

    | GPUを利用する場合は、コンテナイメージ、性能タイプで下記を指定する必要があります。

    * コンテナイメージ : GPU利用に必要なライブラリが搭載されたコンテナイメージ
    * 性能タイプ : GPUが1以上に設定されている性能タイプ

    | 該当するコンテナイメージ、性能タイプがリストに存在しない場合は、 :ref:`note_about_using_gpu` を参照し、分析PF管理者に連絡してください。

.. _access_jupyter_notebook:

Jupyter Notebookへ接続する
--------------------------

作成したAAClusterのJupyter Notebookに接続するには、以下の様にしてください。

#. Jupyter Tokenを取得します。

   Jupyter Notebookにログインするために、Jupyter Token（Jupyter Notebookにログインする際に入力する認証トークンで、
   AAClusterごとに異なる）を取得します。
   作成したAAClusterの :guilabel:`[Access Jupyter Notebook]` ボタンを押下し、
   表示されるJupyter Tokenを記録してください。

   .. image:: ./_static/show_jupyter_token.png

#. Jupyter Notebookにログインします。

   #. 先の手順で表示されたポップアップ画面の :guilabel:`[Open Jupyter Notebook]` ボタンを押下し
      Jupyter Notebookへ接続します。
   #. :guilabel:`[Password or token]` フォームに先の手順で取得したJupyter Tokenを入力し、 
      ログインします。

Jupyter Notebookの基本的な使い方については、
`Notebook Basics <https://nbviewer.jupyter.org/github/jupyter/notebook/blob/5.4.1/docs/source/examples/Notebook/Notebook%20Basics.ipynb>`_
を参照してください。
より詳しい使い方は、 `Jupyter Notebook Documentation <https://jupyter-notebook.readthedocs.io/en/5.4.1/>`_ を参照してください。


AAClusterを削除する
-------------------

#. Topページに表示されているAAClusterの一覧を確認し、削除したいAAClusterが表示されている列にある :guilabel:`[Delete]` （ゴミ箱のアイコン） ボタンを押下します。
#. AACluster削除確認ダイアログの :guilabel:`[Delete AACluster]` ボタンを押下します。一覧から削除しようとしたAAClusterが消えれば削除完了です。

AAPF WebAPIを利用してAAClusterを作成/削除する
=============================================

AAPF WebAPIを利用すると、Terminalやスクリプト等からAAClusterの作成や削除を行う事ができます。
ここでは、HTTPクライアントとして ``cURL`` を使用した場合の例を交えて説明します。

AAPF WebAPIの詳細については  *AAPF WebAPI Reference* を参照してください。

AAPF API Tokenを取得する
------------------------

AAPF WebAPIを利用するには、あらかじめAAPF WebAPI用の認証トークンを取得する必要があります。
ここでは、認証トークンとしてAAPF API Tokenを取得する手順を説明します。

#. AAPF WebUIにログインします。
#. Topページ右上にある「ユーザー名」が表示されている所をクリックし、メニューを開きます。
#. 表示されたメニューにある :guilabel:`[User Profile]` を押下します。
#. 表示されたAAPF API Tokenの一覧画面にある :guilabel:`[Create Token]` を押下します。
#. AAPF API Token作成ダイアログの :guilabel:`[Token Name]` フォームにAAPF API Tokenの名前を入力します。
#. AAPF API Token作成ダイアログの :guilabel:`[Input your login password to authenticate.]` フォームに「AAPF WebUIへのログイン時に使用したパスワード」を入力します。
#. AAPF API Token作成ダイアログの :guilabel:`[Create API Token]` を押下します。
#. AAPF API Token作成完了ダイアログに作成されたAAPF API Tokenが下図の赤枠内に表示されますので、コピーします。

    .. image:: ./_static/create_aapf_api_token_complete.png
        :scale: 70

    .. warning::

      AAPF API TokenはAAPF API Token作成完了ダイアログにしか表示されません。
      （AAPF API Tokenの一覧画面には作成時に入力した名前と作成日時が代わりに表示されます）
      また、このダイアログを閉じてしまうと、AAPF API Tokenを再度確認することはできません。
      AAPF API Tokenの内容を忘れてしまった場合は、AAPF API Tokenを作成しなおしてください。

コンテナイメージのリストを取得する
----------------------------------

AACluster作成時にパラメータとして利用するコンテナイメージを指定する必要があります。

実行例は以下の通りです。

.. note:: 実行結果は見やすいように整形しています。

::

    $ curl -X GET \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ' \
        "https://web.example.com/api/v1/images"
    {
        "images": [
            {
                "repositoryName": "aapf/aa_jupyter_notebook",
                "displayName": "Jupyter Notebook",
                "description": "Standard Jupyter Notebook image provided by AAPF."
            },
            {
                "repositoryName": "aagroup/aa_jupyter_pytorch",
                "displayName": "Jupyter Notebook with PyTorch",
                "description": "Jupyter Notebook image with torch and torchvision."
            },...
        ]
    }

``repositoryName`` フィールド中の文字列(上記の例の出力中の ``aapf/aa_jupyter_notebook`` や ``aagroup/aa_jupyter_pytorch``)を
AACluster作成時のパラメータに渡します。

.. note::

    | GPUを利用する場合は、GPU利用に必要なライブラリが搭載されたコンテナイメージを指定する必要があります。
    | 該当するコンテナイメージがリストに存在しない場合は、 :ref:`note_about_using_gpu` を参照し、分析PF管理者に連絡してください。

性能タイプのリストを取得する
----------------------------

AACluster作成時にパラメータとして利用する性能タイプを指定する必要があります。

実行例は以下の通りです。

.. note:: 実行結果は見やすいように整形しています。

::

    $ curl -X GET \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ' \
        "https://web.example.com/api/v1/perf-types"
    {
        "perfTypes": [
            {
                "name": "0010_micro",
                "displayName": "Micro (Fixed Performance)",
                "resources": {
                    "cpu": 0.25,
                    "memory": 512,
                    "nvidia.com/gpu": null
                }
            },
            {
                "name": "0020_small",
                "displayName": "Small (Fixed Performance)",
                "resources": {
                    "cpu": 1,
                    "memory": 2048,
                    "nvidia.com/gpu": null
                }
            },...
        ]
    }

``name`` フィールド中の文字列(上記の例の出力中の ``0010_micro`` や ``0020_small``)を
AACluster作成時のパラメータに渡します。

.. note::

    | GPUを利用する場合は、 ``resources`` 内の ``nvidia.com/gpu`` フィールドの値が1以上の性能タイプを指定する必要があります。
    | 該当する性能タイプがリストに存在しない場合は、 :ref:`note_about_using_gpu` を参照し、分析PF管理者に連絡してください。

AAClusterを作成する
-------------------

AAPF WebAPIを利用してAAClusterを作成するには、 ``<AAPF WebUIのURL>/api/v1/aaclusters/<AAClusterの名前>`` に ``PUT`` リクエストを送信します。

::

    $ curl --no-buffer -X PUT \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer <AAPF API Token>' \
        -d '{"jupyterNotebook": {"image": {"repositoryName": "<Repository Name>"}, "perfType": "<Performance Type>"}}' \
        "<AAPF WebUIのURL>/api/v1/aaclusters/<AAClusterの名前>"

実行例は以下の通りです。

::

    $ curl --no-buffer -X PUT \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ' \
        -d '{"jupyterNotebook": {"image": {"repositoryName": "aapf/aa_jupyter_notebook"}, "perfType": "0010_micro"}}' \
        "https://web.example.com/api/v1/aaclusters/sample"
    {"message": "Accepted creating AACluster named 'sample'."}

AAClusterの作成は非同期に行われるため、上記リクエストが完了してもAAClusterの作成は完了していません。
AAClusterの作成が完了したかどうか確認するには、 ``<AAPF WebUIのURL>/api/v1/aaclusters/<AAClusterの名前>`` に
``GET`` リクエストを送信し、AAClusterの状態を取得します。

::

    $ curl --no-buffer -X GET \
        -H 'Authorization: Bearer <AAPF API Token>' \
        "<AAPF WebUIのURL>/api/v1/aaclusters/<AAClusterの名前>"

実行例は以下の通りです。AAClusterの状態取得結果はJSON形式で返されます。

.. note:: 実行結果は見やすいように整形しています。

::

    $ curl --no-buffer -X GET \
        -H 'Authorization: Bearer eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ' \
        "https://web.example.com/api/v1/aaclusters/sample"
    {
        "aacluster": {
            "name": "sample",
            "status": "created",
            "services": [
                {
                    "name": "jupyter-notebook",
                    "numberOfInstances": 1,
                    "instances": [
                        {
                            "index": 1,
                            "status": "ready",
                            "health": null,
                            "createdAt": "2017-08-01T01:55:59.474387+00:00",
                            "updatedAt": "2017-08-01T01:56:36.358779+00:00",
                            "url": "https://web.example.com/proxy/abcdefg123",
                            "urlPath": "/proxy/abcdefg123/jupyter",
                            "jupyterToken": "c6db3a7b715b04402b6a241faa6cf16274403bf50a7bbf91"
                        }
                    ],
                    "image": {
                        "repositoryName": "aapf/aa_jupyter_notebook",
                        "displayName": "Jupyter Notebook",
                        "description": "Standard Jupyter Notebook image provided by AAPF."
                    },
                    "perfType": {
                        "name": "0010_micro",
                        "displayName": "Micro (Fixed Performance)",
                        "resources": {
                            "cpu": 0.25,
                            "memory": 512,
                            "nvidia.com/gpu": null
                        }
                    },
                    "alerts": []
                },
                {
                    "name": "spark-master",
                    "numberOfInstances": 0,
                    "instances": [];
                    "image": {},
                    "perfType": {},
                    "alerts": []
                },
                {
                    "name": "spark-worker",
                    "numberOfInstances": 0,
                    "instances": [];
                    "image": {},
                    "perfType": {},
                    "alerts": []
                }
            ],
            "createdAt": "2017-08-01T01:57:02.401372+00:00"
        }
    }

JSON形式のデータに含まれている ``aacluster.status`` が AAClusterの ``Status`` です。
``aacluster.status`` が ``created`` になっていれば、AAClusterの作成が完了しています。

AAClusterを削除する
-------------------

AAPF WebAPIを利用してAAClusterを削除するには、 ``<AAPF WebUIのURL>/api/v1/aaclusters/<AAClusterの名前>`` に ``DELETE`` リクエストを送信します。

::

    $ curl --no-buffer -X DELETE \
        -H 'Authorization: Bearer <AAPF API Token>' \
        "<AAPF WebUIのURL>/api/v1/aaclusters/<AAClusterの名前>"

実行例は以下の通りです。

::

    $ curl --no-buffer -X DELETE \
        -H 'Authorization: Bearer eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ' \
        "https://web.example.com/api/v1/aaclusters/sample"
    {"message": "Accepted deleting AACluster named 'sample'."}

AAClusterの削除は非同期に行われるため、上記リクエストが完了してもAAClusterの削除は完了していません。
AAClusterの削除が完了したかどうか確認するには、 ``<AAPF WebUIのURL>/api/v1/aaclusters/<AAClusterの名前>`` に
``GET`` リクエストを送信し、AAClusterが存在するか確認します。

この例では、HTTPステータスコードを結果として取得しています。

::

    $ curl -w "%{http_code}" -o /dev/null --no-buffer -X GET \
        -H 'Authorization: Bearer <AAPF API Token>' \
        "<AAPF WebUIのURL>/api/v1/aaclusters/<AAClusterの名前>"

実行例は以下の通りです。以下の様に ``404`` と表示されるようになればAAClusterの削除は完了です。

::

    $ curl -w "%{http_code}" -o /dev/null --no-buffer -X GET \
        -H 'Authorization: Bearer eyJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNTEwMDQyNTA5LCJleHAiOjE1MTAwNDk3MDksInVzZXIiOnsidXNlcm5hbWUiOiJ1c2VyMSJ9fQ' \
        "https://web.example.com/api/v1/aaclusters/sample"
    404

付録
====

.. _note_about_using_gpu:

GPUの利用に関する注意事項
-------------------------
| GPUを利用したい場合は、分析PF管理者に連絡してください。
| 分析PF管理者が、AAPFデプロイ環境でGPUが利用可能かどうか確認し、GPUを利用可能なリソースクォータを設定します。
