MARA：身近なワークステーションで稼働開始

Jason Schmidt

私たちがNGINX Modern Apps Reference Architecture（MARA）プロジェクトに着手した際、IaaSプロバイダーとしてAWSを選びました。すでにこのプラットフォームに精通しており、部門予算で費用を賄えたためです。もちろん、誰もが同じ経験や予算を持っているわけではありません。そのため、K3s、Canonical MicroK8s、minikubeなどのKubernetesディストリビューションを使用して、ラボ環境やワークステーション上でMARAをローカルに実行するための選択肢を求める声が多く寄せられています。

皆さまのご要望を受け、MARAをMicroK8sでテストし、ご自身でデプロイするための手順を本日公開できることをうれしく思います。

テストにMicroK8sを選んだ理由は、メモリ使用量が少なく導入しやすい構成で、MARAに必要なDNS、ストレージ、外向き通信の機能を提供できるためです。MicroK8sを使用すれば、テストシナリオを容易に繰り返し検証し、妥当なレベルのパフォーマンスを実現するデプロイに必要な最小要件を特定できます。

この取り組みにより、他のKubernetesディストリビューションのテストも進めやすくなると期待しています。各ディストリビューションの現在の状況については、F5の「GitHubリポジトリ」をご覧ください。リストへの追加を希望するディストリビューションがある場合は、ぜひフォークしてテストを行い、プルリクエストを作成してください。

リソース制約への対処

MARAをローカルで実行する際の最大の制約は、メモリとCPUです。予備テストでは、メモリ枯渇に関する問題の大半がElasticsearchに起因していることが判明しました。メモリが極端に少ない（16 GB未満）構成では、Kibanaはほとんど使用できません。この問題に対処するため、MARAの設定ファイルには、通常の完全なElasticsearchデプロイメントに備わっている冗長性保護を無効にする設定を用意しています。これにより障害モードは増えますが、リソースに制約のある環境では必要なトレードオフです。

CPUの制約は、サンプルの「Bank of Sirius」アプリケーションにかかる負荷の大きさに直接関係します。MARAデプロイメントには、Bank of Siriusに負荷を生成するための「Locust」が含まれており、ユーザー数と新規ユーザーの生成率はユーザーが設定できます。

Bank of Siriusの負荷を増やすと、システムの他の部分にも影響することに注意してください。ユーザー数またはスポーンレートが高すぎると、MARAのパフォーマンスが低下し、コンポーネントがクラッシュまたは停止する可能性が高くなります。この動作が発生する値は利用可能なCPUによって異なりますが、少なくとも要件に記載された容量を備えたデプロイメントであれば、最大64ユーザー、同時に16ユーザーのスポーンレートによって生じる負荷を処理できると見込まれます。

MicroK8sへのMARAのデプロイ

以上の背景を踏まえ、MicroK8s上にMARAを構築する準備が整いました。

要件

• rootアクセスが可能な、Ubuntu 20.04（Focal）以降を実行するシステム（ベアメタルLinuxサーバー、仮想環境、またはクラウド）。最小要件は次のとおりです。
  • 20 GBのディスク容量
  • 16 GBメモリ
  • 4 CPU相当
• ローカルシステム上のPython 3仮想環境（MARAに必要なすべてのライブラリとバイナリを含む）。Python 3がまだインストールされていない場合は、次のコマンドを実行します：

$  sudo apt update$  sudo apt install -y python3-venv

• NGINX Ingress Controllerのエグレスに割り当てるため、MicroK8sに統合されたMetalLBロードバランサー用に、少なくとも1つの未使用IPv4アドレスが必要です。localhost経由でBank of Siriusアプリケーションにアクセスする場合は、利用可能なプライベートアドレス（RFC 1918準拠）であれば使用できます。たとえば、ネットワークが192.168.100.0/24の場合、10.10.10.10などのアドレスを使用できます。
• Pulumiアカウントとアクセストークン。まだお持ちでない場合は、ステップ1（MARAのデプロイ）で作成します。Pulumiでは、状態ファイルをS3互換オブジェクトストアまたはローカルファイルシステムに保存できますが、本稿執筆時点ではMARAはこれをサポートしていません。この制限は、MARAまたはPulumiの今後のリリースで解消される予定です。

MicroK8sのインストールと設定

1. MicroK8sをインストールします：

$ sudo snap install microk8s --classicmicrok8s (1.23/stable) v1.23.3 from Canonical✓ installed

1. Set the necessary permissions for running microk8sコマンドを実行するために必要な権限を設定します。<username>には、システムでroot権限を持つアカウントを指定してください：

$ sudo usermod -a -G microk8s <username>$ sudo chown -f -R <username> ~/.kube
$ newgrp microk8s

1. 新しい権限を有効にするには、root権限を持つアカウントから一度ログアウトし、再度ログインします。
2. MicroK8sのアドオンであるDNS、storage、MetalLBを有効にします。プロンプトが表示されたら、次のいずれかを表すIPアドレス範囲をX.X.X.X‑X.X.X.Yの形式で指定します。

$ microk8s enable dns storage metallbEnabling DNS
Applying manifest
...
Restarting kubelet
DNS is enabled
Enabling default storage class
...
Storage will be available soon
Enabling MetalLB
Enter each IP address range delimited by comma (e.g. '10.64.140.43-10.64.140.49,192.168.0.105-192.168.0.111'): 192.168.100.100-192.168.100.110
Applying Metallb manifest
...
MetalLB is enabled

• 実際に使用するプライベートIPアドレスの範囲（例：192.168.100.100-192.168.100.110。以下ではこの値を使用します）
• 単一のプライベートIPアドレス（例：192.168.100.100-192.168.100.100）

1. MicroK8sが実行中であることを確認します：

$ microk8s statusmicrok8s is running
high-availability: no
  datastore master nodes: 127.0.0.1:19001
  datastore standby nodes: none
addons:
  enabled:
    dns           # CoreDNS
    ha-cluster    # Configure high availability on the current node
    metallb       # Loadbalancer for your Kubernetes cluster
    storage       # Storage class; allocates storage from host directory
...

1. MicroK8sの設定を、ほとんどのユーティリティが参照する次のファイル（~/.kube/config）に読み込み、ディレクトリとファイルに推奨される権限を設定します：

$ microk8s config > ~/.kube/config$ sudo chmod 0644 ~/.kube/config

MARAリポジトリをクローンしてMicroK8sクラスターをセットアップする

1. MARAリポジトリをクローンし、Bank of Siriusサブモジュールを初期化します：

$ git clone https://github.com/nginxinc/kic-reference-architectures.git$ cd kic-reference-architectures/
$ git submodule update --init --recursive --remote

1. クローンしたMARAリポジトリのルートディレクトリ（前の手順で移動したディレクトリ）で、MicroK8sクラスター用のPython仮想環境をセットアップします：

$ ./bin/setup_venv.sh

1. このコマンドを実行すると、長いトレースが生成されます。エラーが発生した場合は、MARAのGitHubリポジトリにある「既知の問題／注意事項」セクションで解決策をご確認ください。
2. Python仮想環境を有効化します。このコマンドにより、仮想環境を使用するようにPATHおよびその他の環境変数が設定されます。

$ source ./pulumi/python/venv/bin/activate

1. MARAのデプロイ用にMicroK8sクラスターが正しく構成されていることを確認します。

$ ./bin/testcap.sh
This script will perform testing on the current kubernetes installation using the currently active kubernetes configuration and context.
Any failures should be investigated, as they will indicate that the installation does not meet the minimum set of capabilities required to run MARA.

...
==============================================================
| All tests passed! This system meets the basic requirements |
| to deploy MARA.                                            |
==============================================================

MARAをデプロイ

このセクションでMARAのデプロイに使用するstart.shスクリプトは、デプロイを成功させるために追加の操作が必要となるオプションにも対応しています。ここでは簡略化のため、以下の基本的なデプロイを前提とします。

• サポートされている他のデプロイオプションではなく、kubeconfigファイルを使用します。他のオプションの詳細については、GitHubリポジトリの「スタートガイド」を参照してください。
• MARAでテスト済みの最新バージョンのNGINX Open Sourceを使用します（必ずしもリリースされた最新バージョンとは限りません）。
• NGINX Open SourceベースのNGINX Ingress Controllerを使用します。NGINX PlusベースのNGINX Ingress Controllerを使用する場合は、KubernetesクラスターでF5 DockerレジストリのNGINX Plusベースのイメージを使用する必要があります。詳細については、以下の注意事項（ステップ3）の最初の項目を参照してください。
• 単一の標準Kubernetesコンテキストを使用します。Step 3の2つ目の「注意事項」を参照してください。

MicroK8sクラスターにMARAをデプロイします：

1. Run the start.shスクリプトを実行します。Pulumiを使用するようにワークステーションをまだ設定していない場合は、Pulumiへのログイン（必要に応じてアカウントを作成）を求められた後、Pulumiアカウントに関連付けられたAPIトークンの入力を求められます。

$ ./bin/start.shAdding to [/home/ubuntu/kic-reference-architectures/bin/venv/bin] to PATH
Manage your Pulumi stacks by logging in.
Run `pulumi login --help` for alternative login options.
Enter your access token from https://app.pulumi.com/account/tokens
    or hit <ENTER> to log in using your browser            : <token>

Please read the documentation for more details.

1. デプロイタイプを選択し、プロンプトで「k」と入力して、kubeconfigファイルを使用してデプロイをビルドします。「make」とDockerがインストールされていないという警告は無視してください。代わりに、レジストリにあるNGINX Ingress Controllerイメージが使用されます。

Type a for AWS, k for kubeconfig? k
Calling kubeconfig startup script
make is not installed - it must be installed if you intend to build NGINX Kubernetes Ingress Controller from source.
docker is not installed - it must be installed if you intend to build NGINX Kubernetes Ingress Controller from source.

1. プロンプトで、作成するPulumiスタックの名前（ここでは「mara」）を指定します。この名前は、Pulumiアカウント内で一意である必要があります。

Enter the name of the Pulumi stack to use in all projects: maraSubmodule source found
Configuring all Pulumi projects to use the stack: mara
Created stack 'mara'

NOTICE! Currently the deployment via kubeconfig only supports pulling images from the registry! A JWT is required in order to access the NGINX Plus repository. This should be placed in a file in the extras directory in the root, in a file named jwt.token

See https://docs.nginx.com/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret/ for more details and examples.

No JWT found; writing placeholder manifest

NOTICE! When using a kubeconfig file you need to ensure that your environment is configured to connect to Kubernetes properly. If you have multiple kubernetes contexts (or custom contexts) you may need to remove them and replace them with a simple ~/.kube/config file. This will be addressed in a future release.

1. プロンプトが表示されたら、kubeconfigファイルのフルパスとクラスター名を指定します。この例では、それぞれ「/home/<username>/.kube/config」と「microk8s-cluster」です。

Provide an absolute path to your kubeconfig filevalue: /home/<username>/.kube/config
Provide your clustername
value: microk8s-cluster
Attempting to connect to kubernetes cluster

1. 次のプロンプトで、クラスターの完全修飾ドメイン名（FQDN）を指定します。スクリプトは、NGINX Ingress Controllerの構成と自己署名証明書の作成という2つの目的でFQDNを使用します（後者の目的があるため、IPアドレスは指定できません）。mara.example.comの代わりに別のFQDNを指定する場合は、以降の手順でも同じFQDNを使用してください。

Create a fqdn for your deploymentvalue: mara.example.com

1. Grafanaの管理者パスワードを指定します。

Create a password for the grafana admin user; this password will be used to access the Grafana dashboardThis should be an alphanumeric string without any shell special characters; it is presented in plain text due to current limitations with Pulumi secrets. You will need this password to access the Grafana dashboard.
value: <password>

インストールプロセスのトレースが表示され、各ステップについて次の情報を確認できます。

• 各ステップで実行される主なアクションを示すバナー（たとえば、LogstoreはElasticsearchのデプロイ開始を示します）
• Pulumiが実行するタスクの一覧
• Pulumiの各タスクのリアルタイムステータスインジケーター
• PulumiとMARAによって生成される診断情報（定義されたホスト名やIPアドレスなど）
• 影響を受けるリソースの数
• 経過時間

最後のステップ（Bank of Sirius用）が完了すると、トレースには、MetalLBによってNGINX Ingress Controllerに割り当てられたIPアドレス（ここでは「192.168.100.100」）と、デプロイ用に選択したFQDN（ここでは「mara.example.com」）が、デプロイに関するその他の情報とともに表示されます。

The startup process has finished successfully
Next Steps:
1. Map the IP address (192.168.100.100) of your Ingress Controller with your FQDN (mara.example.com).
2. Use the ./bin/test-forward.sh program to establish tunnels you can use to connect to the management tools.
3. Use kubectl, k9s, or the Kubernetes dashboard to explore your deployment.

To review your configuration options, including the passwords defined, you can access the pulumi secrets via the following commands:

Main Configuration: pulumi config -C /jenkins/workspace/jaytest/bin/../pulumi/python/config

Bank of Sirius (Example Application) Configuration: pulumi config -C /jenkins/workspace/jaytest/bin/../pulumi/python/kubernetes/applications/sirius

K8 Loadbalancer IP: kubectl get services --namespace nginx-ingress

Please see the documentation in the github repository for more information

1. FQDNの名前解決に使用するツール（ローカルの「/etc/hosts」ファイルやDNSサーバーなど）で、前の手順で表示されたFQDNとIPアドレスのマッピングを作成します。
2. MARAデプロイへのリクエストが成功することを確認します。-kオプションを指定して、curlが自己署名証明書を受け入れるようにします。証明書の詳細情報を表示するには、-vオプションを追加します。

$ curl -k -I https://mara.example.comHTTP/1.1 200 OK
Server: nginx/1.21.5
Date: Day, DD Mon YYYY hh:mm:ss TZ
Content-Type: text/html; charset=utf-8
Content-Length: 7016
Connection: keep-alive

1. ブラウザでhttps://mara.example.comにアクセスし、Bank of SiriusのWebサイトを表示します。本稿執筆時点では、FirefoxやSafariを含む多くのブラウザで、サイトが自己署名証明書を使用していることを示す警告が表示されても、安全にそのまま進むことができます。最近のセキュリティ変更によりサイトへのアクセスがブロックされる可能性が高いため、Chromeは使用しないことを推奨します。
2. Run the test-forward.shスクリプトを実行してKubernetesのポートフォワーディングを設定すると、MARA管理スイートのツール（Elasticsearch、Grafana、Kibana、Locust、Prometheus）にアクセスできるようになります。このスクリプトは適切なサービス名を特定し、kubectlコマンドを実行してローカルポートに転送します。注：ポートフォワーディングを正しく機能させるには、このコマンドを実行するコマンドシェルと同じシステム上でブラウザーを実行する必要があります。異なるシステム上で実行している場合（仮想化環境を使用している場合など）、コマンドは成功したように見えても、実際にはポートフォワーディングが機能しません。詳しくは、GitHubリポジトリの「MARAの管理ツールへのアクセス」を参照してください。

$ ./bin/test-forward.shConnections Details
====================================
Kibana:        http://localhost:5601
Grafana:       http://localhost:3000
Locust:        http://localhost:8089
Prometheus:    http://localhost:9090
Elasticsearch: http://localhost:9200
====================================

Issue Ctrl-C to Exit

まとめ

以上です。この手順に従えば、約20分でお使いの環境にMARAをデプロイし、稼働させることができます。これで、Bank of Siriusアプリケーションを他のKubernetesアプリケーションと同様に操作できます。まずは、Locustでさまざまな負荷を生成しながら、組み込みのオブザーバビリティツールを使用して環境の動作をテストすることをお勧めします。

私たちは、できるだけ多くのKubernetesユーザーにとってMARAが最大限役立つものになることを目指しています。一部のコンポーネントについて、私たちの選択が適切でないと感じる場合は、独自のコンポーネントに置き換えてください。また、その内容を共有する場合は、プルリクエストを作成することをお勧めします。さらに、私たちが置いた前提に疑問がある場合も含め、リポジトリのIssuesページやDiscussionsページで、ご意見やご質問をお寄せください。

関連記事

この記事はシリーズの一部です。MARAに順次機能を追加する中で、その詳細をブログで公開しています。

• 新しいオープンソースのモダンアプリ向けリファレンスアーキテクチャ
• Modern Apps Reference ArchitectureへのOpenTelemetry統合 — 進捗レポート
• MARA：お近くのワークステーションで稼働開始（本記事）
• NGINX Modern Apps Reference Architectureバージョン1.0.0を発表

著者について

Jason Schmidt

Jason Schmidtのその他のブログ記事