ランブックス

ランブックは、特定のシステムの起動、停止、デバッグ、トラブルシューティングなど、特定のプロセスを実行する方法を説明する文書化された手順のコレクションです。

Jupyter Notebooksと Rubixライブラリを使用することで、ユーザーは自分自身の実行可能なランブックを書き始めることができます。

歴史的に、ランブックは条件やシステムに応じて、デシジョンツリーや詳細なステップバイステップのガイドの形をとってきました。

最新の実装では、”実行可能なランブック “というコンセプトが導入され、明確に定義されたプロセスと共に、オペレーターは与えられた環境に対して、事前に書かれたコードブロックやデータベースクエリを実行することができます。

実行可能なランブック

GitLab 11.4で導入されました。

GitLab Kubernetesインテグレーションで提供されるJupyterHubアプリにNurtchのRubixライブラリが同梱され、DevOpsランブックを簡単に作成できるようになりました。一般的なオペレーションを紹介するサンプルランブックが提供されています。Rubixを使えばKubernetesやAWSの一般的なワークフローを簡単に作成できますが、Rubixを使わずに手動で作成することもできます。

GitLabでこれを実現する方法の概要については、このビデオをご覧ください！

要件

実行可能なランブックを作成するには、以下のものが必要です：

Kubernetes- 残りのアプリケーションをデプロイするには、Kubernetesクラスターが必要です。最も簡単な方法は、GitLabエージェントを使用してクラスターに接続することです。
Ingress- Ingressはロードバランシング、SSLターミネーション、名前ベースのバーチャルホスティングを提供できます。アプリケーションのウェブプロキシとして機能します。
JupyterHub-JupyterHubはチーム全体でノートブックを管理するためのマルチユーザーサービスです。Jupyterノートブックは、データ分析、可視化、機械学習に使用されるWebベースのインタラクティブなプログラミング環境を提供します。

Nurtch

NurtchはRubixライブラリを開発している会社です。Rubix はオープンソースの Python ライブラリで、Jupyter Notebooks 内で一般的な DevOps タスクを簡単に実行できます。CloudwatchメトリクスのプロットやECS/Kubernetesアプリのロールなどのタスクは、数行のコードに簡略化されます。詳しくはNurtchドキュメントをご覧ください。

GitLabで実行可能なランブックの設定

このステップバイステップガイドに従って、GitLabで実行可能なランブックを設定します。上記で説明したコンポーネントと事前にロードされたデモランブックを使用します。

JupyterHub用のOAuthアプリケーションを作成します。

JupyterHubをHelmでインストールする場合は、以下の値を使用します：

#-----------------------------------------------------------------------------
# The gitlab and ingress sections must be customized!
#-----------------------------------------------------------------------------
   
gitlab:
   clientId: <Your OAuth Application ID>
   clientSecret: <Your OAuth Application Secret>
   callbackUrl: http://<Jupyter Hostname>/hub/oauth_callback,
   # Limit access to members of specific projects or groups:
   # allowedGitlabGroups: [ "my-group-1", "my-group-2" ]
   # allowedProjectIds: [ 12345, 6789 ]
   
# ingress is required for OAuth to work
ingress:
   enabled: true
   host: <JupyterHostname>
   # tls:
   #    - hosts:
   #       - <JupyterHostanme>
   #         secretName: jupyter-cert
   # annotations:
   #    kubernetes.io/ingress.class: "nginx"
   #    kubernetes.io/tls-acme: "true"
   
#-----------------------------------------------------------------------------
# NO MODIFICATIONS REQUIRED BEYOND THIS POINT
#-----------------------------------------------------------------------------
   
hub:
   extraEnv:
      JUPYTER_ENABLE_LAB: 1
   extraConfig: |
      c.KubeSpawner.cmd = ['jupyter-labhub']
      c.GitLabOAuthenticator.scope = ['api read_repository write_repository']
   
      async def add_auth_env(spawner):
         '''
         We set user's id, login and access token on single user image to
         enable repository integration for JupyterHub.
         See: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47138#note_154294790
         '''
         auth_state = await spawner.user.get_auth_state()
   
         if not auth_state:
            spawner.log.warning("No auth state for %s", spawner.user)
            return
   
         spawner.environment['GITLAB_ACCESS_TOKEN'] = auth_state['access_token']
         spawner.environment['GITLAB_USER_LOGIN'] = auth_state['gitlab_user']['username']
         spawner.environment['GITLAB_USER_ID'] = str(auth_state['gitlab_user']['id'])
         spawner.environment['GITLAB_USER_EMAIL'] = auth_state['gitlab_user']['email']
         spawner.environment['GITLAB_USER_NAME'] = auth_state['gitlab_user']['name']
   
      c.KubeSpawner.pre_spawn_hook = add_auth_env
   
auth:
   type: gitlab
   state:
      enabled: true
   
singleuser:
   defaultUrl: "/lab"
   image:
      name: registry.gitlab.com/gitlab-org/jupyterhub-user-image
      tag: latest
   lifecycleHooks:
      postStart:
         exec:
         command:
            - "sh"
            - "-c"
            - >
               git clone https://gitlab.com/gitlab-org/nurtch-demo.git DevOps-Runbook-Demo || true;
               echo "https://oauth2:${GITLAB_ACCESS_TOKEN}@${GITLAB_HOST}" > ~/.git-credentials;
               git config --global credential.helper store;
               git config --global user.email "${GITLAB_USER_EMAIL}";
               git config --global user.name "${GITLAB_USER_NAME}";
               jupyter serverextension enable --py jupyterlab_git
   
proxy:
   service:
      type: ClusterIP

JupyterHubのインストールが完了したら、ブラウザでJupyter Hostnameを開きます。Sign in with GitLabボタンを選択してJupyterHubにサインインし、サーバを起動します。GitLabインスタンスのどのユーザーに対してもOAuth2による認証が有効になっています。このボタンはGitLabのページにリダイレクトし、JupyterHubがあなたのGitLabアカウントを使用するための承認を要求します。
Authorizeを選択すると、GitLabからJupyterHubアプリケーションにリダイレクトされます。
Start My Serverを選択すると、数秒でサーバーが起動します。
ランブックから GitLab プロジェクトへのアクセスを設定するには、デモランブックのSetupセクションにGitLab アクセストークンとプロジェクト ID を入力します：
1. 左側のパネルにあるDevOps-Runbook-Demoフォルダを選択します。
2. Nurtch-DevOps-Demo.ipynb ランブックを選択します。
  Jupyterはランブックの内容を画面の右側に表示します。Setupセクションには、PRIVATE_TOKEN とPROJECT_IDが表示されます。以下のように、シングルクォーテーションを維持したまま、これらの値を入力します：
```
PRIVATE_TOKEN = '<your_access_token>'
PROJECT_ID = '1234567'
```
3. このセクションの最終行のVARIABLE_NAME を、アクセストークンに使用する変数名に合わせて更新します。この例では、変数名はPRIVATE_TOKEN です。
```
VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value
```
ランブックのオペレーションを設定するには、変数を作成して設定します。この例では、サンプル・ランブックのRun SQL queries in Notebookセクションを使用して、PostgreSQLデータベースにクエリを実行します。以下のコードブロックの最初の4行は、このクエリが機能するために必要な変数を定義しています：
```
%env DB_USER={project.variables.get('DB_USER').value}
%env DB_PASSWORD={project.variables.get('DB_PASSWORD').value}
%env DB_ENDPOINT={project.variables.get('DB_ENDPOINT').value}
%env DB_NAME={project.variables.get('DB_NAME').value}
```
1. プロジェクトに変数を作成するには、[Settings] > [CI/CD] > [Variables] に移動します。
2. 変数の保存を選択します。
3. Jupyterで、Run SQL queries in Notebook見出しを選択し、Runを選択します。結果は以下のようにインラインで表示されます：