cautionary_note.md

ISUCON13 当日マニュアル

スケジュール

• 10:00 競技開始
• 17:00 リーダーボードの更新停止
• 18:00 競技終了
• 19:30 結果発表(予定)

アプリケーション ISUPipe について

ISUPipe の仕様についてはISUPipe アプリケーションマニュアルを参照してください。

ISUCON13 ポータルサイト（ポータル）

ISUCON13 の競技では下記のウェブサイトを利用します。事前に登録した情報を用いてログインしてください。 なお、このページは競技開始時刻までアクセスすることはできません。

https://portal.isucon.net/contest/

ポータルでは、負荷走行（ベンチマーク）の実行/結果確認、質問/サポート依頼の送信、リーダーボードの確認ができます。

リーダーボードの更新について

ポータル上のリーダーボードは、競技終了 1 時間前に他チームの情報が更新されなくなり、自チームの情報のみ更新されます。

Discord の利用について

ISUCON13 サポート Discord サーバーは競技中ならびにその前後の時間はすべてのチャンネルが発言不可となります。 競技時間中はポータルを通して質問/サポート依頼を送信することができますので、そちらを利用してください。

ただし、参加者（以下選手）は競技時間中も Discord の確認が可能な状態、通知が受け取れる状態を維持してください。 これは主催者が選手とリアルタイムでのチャットが必要だと判断した場合、主催者が Discord 上でプライベートチャンネルを作成しメンションの上、呼びかけを行う場合があるためです。呼びかけに応じない場合、競技に支障をきたす可能性があるため、必ず応答可能な状態を維持してください。

また、主催者からのアナウンス等も Discord で実施されます。

質問について

選手は主催者へ質問を送信することができます。質問は競技内容・マニュアル・レギュレーション等に対する疑問点の確認や、サーバー障害などのトラブル報告・サポート依頼に利用することができますが、これに限りません。

主催者は質問された内容が競技の一環である場合は、回答できない旨を返答することがあります。

競技時間中の質問について、主催者からの回答は全選手へ公開、あるいは個別に回答されます。全選手へ公開される場合、質問内容の原文、あるいは主催者による内容の要約が公開されます。未回答の質問・未公開の回答については質問した選手およびそのチームメンバー、主催者のみが確認できます。質問への回答・更新はポータル上にて選手およびそのチームへ通知されます。

主催者は競技時間中の質問への回答を、原則として全選手へ公開します。ただし、重複する質問や、選手およびチーム個別の問題に対する対応の場合、この限りではありません。

サポート対象外の事項

主催者が事前に Discord サーバー等で告知していた通り、下記はサポート対象外となります。

競技環境確認を事前に行っていないチームからの競技環境に関する質問/サポート依頼

• AWS クーポンに関する質問/サポート依頼
• スポンサー各社が提供しているサービスについての質問/サポート依頼

競技環境構築と接続

競技に参加するにあたり、各チームが用意した AWS アカウントで競技環境を下記の手順に従って構築してください。

1. テンプレートのダウンロード

まず、環境構築には AWS CloudFormation を利用するため、チームはポータル上から AWS CloudFormation のテンプレートをダウンロードします。 テンプレートはチームごとに固有のものとなっているため共有厳禁です。

https://portal.isucon.net/contest/

このテンプレートでは以下のリソースを作成します。

• EC2 インスタンス （c5.large）x 3
• EBS（gp3 40GB）x 3
• EIP x 3
• VPC x 1
• VPC サブネット x 1
• VPC ルートテーブル x 1
• インターネットゲートウェイ x 1
• セキュリティグループ x 1
• Availability Zone 情報取得に利用する Lambda 関数 x 1
• IAM ロール x 2
• EC2 インスタンスプロファイル x 1

テンプレートから作成される IAM ロールは、EC2 インスタンスおよび Lambda 関数で上記リソースの情報取得を行うために利用します。 許可されているアクションは AWS の仕様上、アカウントに存在する他のリソースの情報も閲覧できる設定になっていますが、主催者は不要な情報の取得は行いません。

2. スタックの作成

1. AWS マネジメントコンソールの CloudFormation を開き、ページ右上に表示されているリージョン名がアジアパシフィック（東京）（ap-northeast-1）になっていることを確認します。
2. 「スタックの作成」をクリックします。 既存のスタックがある場合は「スタックの作成」から「新しいリソースを使用（標準）」を選択します。
3. 「スタックの作成」ページから「テンプレートの準備完了」、「テンプレートファイルのアップロード」を選択し、上記でダウンロードしたテンプレートのアップロードを行い「次へ」をクリックします。
4. 「ステップ 2 スタックの詳細を指定」では任意のスタック名を設定し、「次へ」をクリックします。
5. 「ステップ 3 スタックオプションの設定」では変更を行わず「次へ」をクリックします。
6. 「ステップ 4 レビュー」において、ページ最下部「スタックの作成」ボタンの上に表示されている「AWS CloudFormation によって IAM リソースが作成される場合があることを承認します」にチェックを入れた上で、「スタックの作成」をクリックします。
7. 作成したスタックの状態が CREATE_COMPLETE（作成完了）になるまで待機します。

マネジメントコンソールが「日本語」の場合手順です。他の言語で同様の手順に従ってください。

3. サーバーへの SSH 接続

スタックの作成完了後、数分程度で SSH 接続できるようになります。サーバーには選手が GitHub に登録している SSH 鍵を利用して、ユーザ名 isucon で SSH 接続ができます。

また、AWSマネージメントコンソールからセッションマネージャーによる接続も可能です。セッションマネージャーで接続した場合は ssm-user というユーザーになるため、sudo su - isucon で isucon ユーザーに切り替えてください。

サーバーの IP アドレスはポータルか、AWS マネジメントコンソールの EC2 インスタンスページから確認できます。

サーバーへ接続後、下記のコマンドを実行することで正しく起動しているか検証が行えます。

$ sudo /opt/isucon-env-checker/envcheck

サーバー起動後にポータルのサーバーリストに表示されない場合は、サーバーに　SSH(またはセッションマネージャ)ログインし、上記 envcheck コマンドを実行し、詳細を確認してください。

アプリケーションの動作確認

ISUPipe には、サーバーのWeb ブラウザから HTTPS でアクセスできます。

動作確認のためのhostsファイル設定

ISUPipe はホスト名に依存した挙動があるため、ブラウザにサーバーのIPアドレスを直打ちする形での閲覧はできません。以下の手順でhostsファイルを編集し、動作確認のためのホスト名が競技サーバーのIPアドレスにつながるようにします。

Mac や Linux であれば /etc/hosts に、 Windows であれば C:\Windows\System32\drivers\etc\hosts に以下の行を追記します。{サーバー IP アドレス} はサーバーの IP アドレスに読み替えてください。

{サーバー IP アドレス} pipe.u.isucon.dev
{サーバー IP アドレス} test001.u.isucon.dev

そのほかアプリケーションの確認のためにサブドメインを追加することがあります。

{サーバー IP アドレス} サブドメイン.u.isucon.dev

上記変更の反映にはブラウザの再起動が必要な場合があります。

ISUPipe へのログイン

ISUPipe へのログインは以下のアカウント情報を用いることができます。

ユーザ名	パスワード
test001	test

ブラウザでの表示上の注意

初期実装ではブラウザからのアクセスにより、サーバの負荷が高くなることが考えられます。

負荷走行への影響を避けるため、ベンチマーカーの実行中はブラウザでの表示は行わないのが推奨されます。

ベンチマーカーの実行

負荷走行はポータル上からリクエストします。

ポータル にアクセスし、「Job Enqueue Form」から「名前解決を行う」対象のサーバーを選択、「Enqueue」をクリックすることで負荷走行のリクエストが行われ、順次開始されます。

なお、負荷走行が待機中（WAITING）もしくは実行中（RUNNING）の間は追加でリクエストを行うことはできません。

ベンチマーカーが不正に終了した場合、結果がすぐに表示されない場合があります。6分以上その状態が続く場合は自動で ABORT 状態となり、次の負荷走行のリクエストを行うことができます。

競技環境について

環境情報の確認と送信

サーバー起動（再起動を含む）時に競技環境が主催者の指定した環境で構築されているかを確認し、サーバー IP アドレスを含む環境情報をポータルに送信する処理が実行されます。

ポータルは送信された環境情報を元に、ポータル上に表示されるサーバー IP アドレス等のサーバー情報を更新します。なお、これはサーバー単位で更新されます。

この処理はサーバー起動時以外に、以下のコマンドで選手自らが行えます。

$ sudo /opt/isucon-env-checker/envcheck boot

サーバ環境に確認が必要な事項があれば、登録はされません。

競技環境の再構築方法

選手自らが設定変更等により競技環境を破壊するなどして、初期状態に戻す必要がある場合は上記「競技環境構築と接続」を参考に選手自らが AWS CloudFormation で新たに競技環境の構築を行うことになります。再構築以前の競技環境上で変更を加えたソースコードや設定ファイル等の移行が必要な場合は、各チームの責任で行ってください。

なお、サーバーの起動・停止・再起動は AWS マネジメントコンソールや API から選手が行っても構いません。

後述する「複数スタック」の問題を回避するため、再構築作業完了後は以前の AWS CloudFormation スタックを削除することをおすすめします。

サーバリストへの登録について

サーバリストはチームあたり最大3台までの登録となります。以前のサーバーが一覧に残っていると再構築後のサーバは登録されません。

再構築を行う際は、作業開始前にサーバーリストから削除してください。

もし再構築を先に行なってサーバーが追加されない場合は、サーバーリストから使用しないサーバーを削除し、全ての新しいサーバーを再起動を行なってください。サーバー情報の更新はサーバーが起動（再起動を含む）された際に行われます。

複数スタックについて

ポータルからダウンロードしたテンプレートを利用して AWS CloudFormation スタックを複数作成しても構いません。ただし、以下の点に留意してください。

まず、「環境情報の確認と送信」で言及した通り、サーバー情報の更新はサーバー単位、かつサーバーが起動（再起動を含む）するたびに実施されます。 そのため、複数のスタックで作成されたサーバーが同時に存在している時、選手の操作によっては、ポータル上のサーバー情報が複数のスタックに跨ってしまう場合（混在）があります。

競技時間中は混在した状態になってしまっても問題ありませんが、競技終了時点でポータル上のサーバー情報が混在していた場合は失格となります。

主催者はポータルに登録された環境以外のサポートや、混在した状態でのサポートは行いません。

なお、混在しているかの判断はポータルとスタックのリソースに表示されている IP アドレスを元に行ってください。

競技環境の変更について

選手が競技を進めるにあたって新たなポート解放が必要な場合、セキュリティグループの変更は行なっても構いません。

ただし、SSH(TCP/22)、HTTPS(TCP/443) および DNS(UDP/53) については競技に影響があり変更しないでください。

上記セキュリティグループの変更により、ベンチマークが実行できない場合は失格となります。

重要事項

• 競技終了後は主催者からアナウンスがあるまで競技環境のシャットダウンや停止などは行わず、3 台とも起動した状態を維持してください。
  • 競技時間中の再起動や一時的な停止に関しては問題ありません。
• 競技に利用できる計算機資源は主催者が公開した CloudFormation テンプレートの内容に沿って起動された EC2 インスタンスのみです。
  • 例えば、テンプレートで作成されたリソースを、その内容に沿わなくなる変更（例： インスタンスタイプの変更）を行った状態で、競技に利用すると失格となります。
  • 競技終了時点で 環境情報の確認 に失敗する状態の場合、失格となります。
  • 競技終了時点でポータル上のサーバー情報に複数環境（スタック）が混在した状態の場合、失格となります。
  • レギュレーションに記載した通り、モニタリングやテスト、開発において外部の資源を用いても構いませんが（例： メトリクス計測サービス）、スコアを向上させるいかなる効果を持つものであってはいけません。これは前述している複数環境の利用も含みます。
• 競技終了後は、主催者が追試を行います。Discord サーバー および https://isucon.net にて主催者がアナウンスをするまで、競技環境の操作はしないでください。
  • 競技終了後、別途アナウンスがあるまでの作業や操作（削除を含む）は失格となります。なお、アナウンスは結果発表後の予定です。
  • 競技環境の削除は、各チームで行う必要があります。削除を行わなかったために発生した不利益について、主催者は一切の責任を負いません。削除を行ってよいタイミングについても、結果発表後にアナウンスの予定です。

変更してはいけない点

下記は追試や環境確認に利用するため、変更した場合は失格となります。

• envcheck.serviceに関わるファイル
  • /etc/systemd/system/envcheck.service
  • /etc/systemd/system/multi-user.target.wants/envcheck.service
  • /opt/isucon-env-checker 内のファイル、バイナリファイル
• aws-env-isucon-subdomain-address.service に関わるファイル
  • /etc/systemd/system/aws-env-isucon-subdomain-address.service
  • /etc/systemd/system/multi-user.target.wants/aws-env-isucon-subdomain-address.service
  • /opt/aws-env-isucon-subdomain-address.sh
• isuadmin ユーザに関わるファイルおよびログイン情報
• その他、主催者による追試を妨げる変更（例： サーバー上の isucon 以外のユーザに関する、ユーザ削除や既存の公開鍵の削除、サーバーの再起動の妨害）

コンテンツ配信サービスについて

映像とサムネイル画像の配信は主催者が提供するコンテンツ配信サービス media.xiii.isucon.dev から行われます。

media.xiii.isucon.dev に障害等が発生した場合、ブラウザ上での映像配信・サムネイル表示がおかしくなりますが、ベンチマーカーの動作や採点には一切影響ありません。

参考実装

下記の言語での実装が提供されています。

• Go
• Node.js
• Perl
• PHP
• Python
• Ruby
• Rust

参考実装の切り替え方法

初期状態では Go による実装が起動しています。

各言語実装は systemd で実行、管理されています。 参考実装を Go から他の言語に切り替えるには以下手順を実行します。

1. isupipe-go.service を停止、無効化します

$ sudo systemctl stop isupipe-go.service
$ sudo systemctl disable isupipe-go.service

以下のコマンドで stop と disable を両方行うことができます

$ sudo systemctl disable --now isupipe-go.service

1. isupipe-{各言語}.service を起動、有効化します

{各言語} のところには perlやrubyがはいります。

$ sudo systemctl start isupipe-{各言語}.service
$ sudo systemctl enable isupipe-{各言語}.service

以下のコマンドで start と enable を両方行うことができます

$ sudo systemctl enable --now isupipe-{各言語}.service

PHPへの切り替え

ただし、PHP を使う場合のみ、systemd の設定変更の他に、次のように nginx の設定ファイルの変更が必要です。

$ sudo ln -s /etc/nginx/sites-available/isupipe-php.conf /etc/nginx/sites-enabled/
$ sudo systemctl restart nginx.service

一部言語の初期実装での負荷走行後の負荷について

一部言語では負荷走行終了後も処理が走り続け、ベンチマーカーからのリクエストは止まっているにもかかわらず、負荷が下がらないことがあります。

時間経過により解消しますが、作業上の障害となる場合は、アプリケーションの再起動などを行なってください。

DNSサーバーについて

参考実装では、PowerDNS がDNSサーバーとして動作しています。

ポータルから負荷走行を実行した場合、指定したサーバー(IPアドレス)のDNSサーバー(53/UDP)に名前解決を行い、得られたIPアドレスに対してHTTPSでアクセスを行います。DNSサーバーが動作していない場合や、ポータルに登録されたサーバー3台のIPアドレス以外が名前解決の結果として得られた場合、ベンチマーカーが走行せず、エラーとなります。

DNSサーバーの動作確認とトラブルシューティング

名前解決の確認は dig コマンドを利用することで行えます。

対象サーバーに入り

$ dig pipe.u.isucon.dev @127.0.0.1

もしくはその他の環境から

$ dig pipe.u.isucon.dev @{サーバのグローバルIP}

と実行することで、名前解決結果を確認できます。

負荷走行が不正に終了し、名前解決が正しく行われない場合、DNSサーバーのゾーン情報の初期化を行なってください。

$ pdnsutil delete-zone u.isucon.dev
$ sudo rm -f /opt/aws-env-isucon-subdomain-address.sh.lock
$ sudo reboot # 再起動します

再起動後、サーバーのグローバルIPが確認され、ゾーン情報が再作成されます。

PowerDNSの設定

参考実装では PowerDNS は MySQL をバックエンドデータベースとして動作しています。

テーブルの定義はサーバー上の /usr/share/doc/pdns-backend-mysql/schema.mysql.sql を参考に構成されています。

名前解決の仕様

名前解決は UDP/53 を通して行われます。TCPへのフォールバックはサポートしていません。

Aレコードの問い合わせに対して、Aレコードのみを返すようにしてください。CNAMEの再帰問い合わせは行いません。

DNSラウンドロビンについて、複数のAレコードが返された場合、最初のIPアドレスを採用します。IPアドレスに対して接続できなかった場合に次のサーバーを参照する動作は致しません。

名前解決で得られたIPアドレスが、ポータルに登録されているサーバーのIPアドレス以外の場合、ベンチマーカーはエラーとして認識します。

ベンチマーカーの名前解決のタイムアウトは2秒で設定されています。タイムアウトやDNSサーバーに接続失敗した際のリトライは最大5回まで行います。ただし、負荷走行中はリトライを行いません。

また、TTLを設定することでベンチマーカーは指定された秒数またはベンチマーカー終了のどちらか短い時間まで、結果のIPアドレスをキャッシュします。

DNS 水責め攻撃について

負荷走行中、DNSサーバに対していわゆる「DNS水責め攻撃」が行われます。

DNS水責め攻撃はランダムなサブドメインを生成し、大量のアクセスを行うことでDNSサーバの応答に影響を与えることを目的とする攻撃手法です。

ベンチマーカーはDNS水責め攻撃およびスクレイピングを行い、名前解決ができると HTTPS によりアクセスを試みる動作を行います。失敗(NXDOMAINや応答なし)では来ません。

MySQL データベースについて

初期実装ではデータベースとして MySQL を利用しています。

MySQL へのログイン方法

参考実装のMySQLに管理者権限で接続するには以下のようにします。

$ sudo mysql {データベース名}

データベースのデータ、DNSゾーン情報の初期化

参考実装では、初期化処理（POST /api/initialize）においてデータベースのデータおよびDNSゾーン情報をベンチマーカーが想定している状態に戻します。 以下のコマンドでもデータベースのデータを初期化できます。

$ ~/webapp/sql/init.sh

DNSゾーン情報のみを初期化する場合、以下のコマンドを実行します

$ ~/webapp/pdns/init_zone.sh

初期化処理は用意された環境内で、ベンチマーカーが要求する範囲の整合性を担保します。 サーバーサイドで処理の変更・データ構造の変更などを行う場合、この処理が行っている内容を漏れなく提供してください。

初期実装のデータベースについて

参考実装では2つのデータベースがあります。

• isupipe アプリケーションが利用するデータベース
• isudns PowerDNSのゾーン情報を格納するデータベース

isupipe データベースのスキーマについて

isupipe データベースのスキーマは初期実装に含まれています

• webapp/sql/initdb.d/00_create_database.sql データベースおよびユーザの作成
• webapp/sql/initdb.d/10_schema.sql isupipe データベースのスキーマ

isupipe データベースを初期化するにはデータベースを DROP DATABASE isupipe および CREATE DATABASE isupipe で再作成し、

$ cat webapp/sql/initdb.d/10_schema.sql | sudo mysql isupipe

としたのち、データの初期化を行なってください。

TLS証明書について

サーバーには *.u.isucon.dev および u.isucon.dev のTLS証明書が設定されています。

このホスト名で HTTPS 接続を行うとTLS証明書の検証エラーは発生しません。ベンチマーカーはこれを期待します。

負荷走行について

ベンチマーカーによる負荷走行は以下のように実施されます。

• 初期化処理の実行 POST /api/initialize（42秒でタイムアウト）
• アプリケーション整合性チェック（数秒～数十秒）
• 負荷テスト（60 秒）
• 最終チェック（数秒～数十秒）

初期化処理もしくはアプリケーション整合性チェックに失敗すると、負荷走行は即時失敗（fail）になります。

負荷テスト終了時点で HTTP レスポンスの処理を打ち切ります。未完了のリクエストなどは強制的に切断されます。負荷テスト終了以降に強制的に切断されたリクエストはスコア、検証には影響しません

ベンチマーカーのタイムアウトについて

ベンチマーカーのタイムアウトはそれぞれ以下のように設定されています。

• 初期化処理の実行: 42秒
• アプリケーションの整合性チェック: 20秒
• 負荷テスト: 20秒
• 最終チェック: 10秒

負荷走行の打ち切り

負荷テスト実行中に停止することはありません。

反映までの猶予時間について

一部APIのデータはリクエストへの反映までに許容される猶予時間があります。

ISUPipe アプリケーションマニュアルを参照してください。

スコア計算

スコアは一回の負荷走行中にISUPipeの投げ銭(Tip)機能により、送金・寄付された金額(ISUCON)の合計となります。

スコアの合計額がサーバとベンチマーカーとで差分がある場合、ベンチマーカーで計測している値をスコアとします。

特別賞

競技中のスコアが、最初に 50,000 ISUCON(点)に到達した 1 チームを特別賞とします。

さくらインターネットの企業賞

さくらインターネットの企業賞の条件は、上位30チーム中で、最終負荷走行のDNSの「名前解決成功数」が最も多かったチーム となります。

最終スコア

競技中の最終計測を最終スコアとします。以下に述べる追試でfailになったチームを取り除いた最終スコアに基づいて順位を決定します。

追試

競技終了後、主催者は全サーバーの再起動後に負荷走行を実施し再現スコアを計測します。主催者による確認作業（追試）を行います。下記の点にあてはまる場合の最終スコアは fail とします。

全チームに対して行う追試項目

• 再起動後の負荷走行でfailした場合
• 再現スコアが最終スコアの75%以下の場合
• envcheckを利用したサーバ環境の確認

最終スコアで上位のチームに対して行う追試項目

• 負荷走行実行時にアプリケーションに書き込まれたデータが、サーバー再起動後に取得できない場合

POST /api/initialize での実装言語の出力

POST /api/initialize レスポンスにて、本競技で利用した言語を出力してください。参考実装はそのようになっています。この情報は集計し ISUCON 公式Blog での公表や、参考情報として利用させていただきます。

POST /api/initialize のレスポンスは以下のような JSON となります。

{
  "lang": "実装言語"
}

lang の値が実装に利用した言語となります。 lang が空の場合は初期化処理が失敗と見なされます。

禁止事項

以下の行為を特に禁止とします。

• 競技終了時間までに、競技の内容に関するあらゆる事項（問題内容・計測ツールの計測方法など）を公開・共有すること（内容を推察できる発言も含む）
  • 不特定多数への公開はもちろん、他チームの選手と連絡を取り、問題内容等を共有する事（結託行為）も禁止とする。
  • ただし主催者が Twitter, Web サイトにおいて公開している情報は除く。ポータルでログインを要するページ（選手が参加する Discord を含む）において記載されている内容は公開情報でない旨留意すること
• 競技時間中、チーム外の人物と ISUCON13 問題にまつわる事項のやりとり（ISUCON13 選手であるかどうかを問わない、SNS での発言も含む）
• 主催者の指示以外で利用が認められたサーバー以外の外部リソースを使用する行為（他のインスタンスに処理を委譲するなど) は禁止する。
  • モニタリングやテスト、開発などにおいては、PC や外部のサーバーを利用しても構わない。
  • AIによるコード分析、生成に必要なサービスは利用しても構わない
  • デプロイのために外部のコンテナレジストリ (Amazon ECRなど) を利用することも可能。ただし、競技終了まで他のチームに対して公開されないように注意すること
• 選手が主催者からその選手が属するチームへ提供されていないサーバーについて直接のアクセスを試みる行為や、外部への不正アクセスを試みる行為。具体的にはベンチマーカーへのログイン試行等。（なお、例示のため、これに限らない）
• 他チームと結託する行為（程度を問わず）
• 主催者が他チームへの妨害、競技への支障となるとみなす全ての行為
• 本マニュアルやレギュレーション、ポータルにおいて禁止とされた行為（禁止事項）への違反は、失格とします。