Cloud Genomics v1alpha2 の移行ガイド

v1alpha2 API はサポート終了となり、2018 年の後半には使用できなくなります。このガイドでは、v1alpha2 パイプライン定義を v2alpha1 API に移行する方法を説明します。v2alpha API では大幅なパフォーマンス改善が行われていますが、このガイドでは v1alpha2 リクエストを変換するために最小限必要な手順のみを取り上げます。

このガイドに加え、v1alpha2 リクエストを自動的に移行するオープンソースのツールも利用できます。このツールは標準入力から v1alpha2 リクエストを読み取って、以下に説明する変換を適用した後、v2alpha1 リクエストを標準出力に書き込みます。

v2alpha1 での主な違い

v2alpha1 API には次の重要な違いがあり、これらの違いを理解することが重要です。

  1. 1 つのパイプライン リクエストで複数のコンテナを実行できます。それらのコンテナでは、同じ 1 つのイメージを使用しても複数のイメージを使用しても構いません。各コンテナの実行は Action メッセージで定義されます。

  2. ローカライズおよびローカライズ解除(それぞれ、VM へのファイルのコピー、VM からのファイルのコピー)は API の組み込み機能ではなくなっています。代わりに、ローカライズとローカライズ解除を行うアクションをパイプラインに追加する必要があります。

  3. Cloud Storage へのロギングは API の組み込み機能ではなくなっていますが、パイプラインの実行中に v1alpha2 API よりも多くの情報が提供されます。追加のログが必要な場合は、VM からログをコピーするアクションをパイプラインに追加する必要があります。

  4. パイプライン定義と入力 / 出力パラメータが分離されなくなったため、リクエストが大幅に単純化されています。

  5. データやサービスへのアクセスに使用されるサービス アカウントで、以下のスコープが自動的に有効になることはありません。したがって、パイプラインでこれらのスコープが必要な場合は、手動で有効にする必要があります。

    • https://www.googleapis.com/auth/compute
    • https://www.googleapis.com/auth/devstorage.full_control
    • https://www.googleapis.com/auth/logging.write
    • https://www.googleapis.com/auth/monitoring.write

リクエストの移行

v1alpha2 リクエストを新しい API に移行するプロセスは、主に、ユーザー指定の単一の Docker コマンドを、ローカライズ、ローカライズ解除、ロギングを行う一連のアクションでラップするという作業からなります。このプロセスについて、以降のセクションで詳しく説明します。

リソース

v1alpha2 API では、EphemeralPipelinePipelineArgs の 2 つの部分でリソースを指定します。これら 2 つの仕様を 1 つにマージしてから v2alpha1 の Resources オブジェクトに変換する必要があります。最も簡単な方法は、一時的パイプライン内に指定された値を、パイプライン引数で指定した値によってオーバーライドすることです。

リソースをマージすると、ほとんどのフィールドは Resources オブジェクト内の対応するフィールドに直接対応するようになります。

1 つの重要な例外は、マシンタイプ文字列です。この文字列は、v1alpha2 リクエスト内の minimumCpuCores フィールドと minimumRamGb フィールドに基づいて生成する必要があります。

マシンタイプ名には標準の名前(たとえば、n1-standard-1)またはカスタム名(たとえば、custom-1-4096)を使用できます。指定されたカスタムタイプが低コストの標準タイプに直接対応する場合、Compute Engine では自動的に標準タイプを使用します。

既存の値をマシンタイプに移行するのに最も簡単な方法は、指定されている最小の CPU コア数と RAM を使用してカスタム マシンタイプ(custom-N-M)を生成することです。ここで、N はコア数、M は RAM のメガバイト数です。この方法を使うと、通常は低コストのマシンが割り当てられます。ただし、パイプラインでリクエストする CPU と RAM の最小値が十分でないと、パイプラインが失敗することがあります。

例: CPU と RAM の最小値をカスタム マシンタイプにマッピングする

v1alpha2v2alpha1

{
  'ephemeralPipeline': {
    'resources': {
      'minimumCpuCores': 1,
      'minimumRamGb': 4
    }
  },
  'pipelineArgs': {
    'resources': {
      'minimumRamGb': 8,
      'preemptible': true
    }
  }
}

{
  'pipeline': {
    'resources': {
      'virtualMachine': {
        'machineType': 'custom-1-8192',
        'preemptible': true
      }
    }
  }
}

ローカライズ

v1alpha2 API と同じ方法でローカライズを行うには、inputParameters フィールド内の各エントリを変換する必要があります。v1alpha2 リクエスト内の inputParameters および pipelineArgs セクションは 1 つにマージする必要があることにご注意ください。

例: 単純な入力パラメータ

次の例は、単純な入力パラメータを変換する方法を示しています(コピーされるファイルはありません)。この場合、値をパイプラインの environment マップに追加して、コンテナに対して環境変数として公開されるようにするだけです。

v1alpha2v2alpha1

{
  'ephemeralPipeline': {
    'inputParameters': [
      {
        'name': 'SHARDS',
        'defaultValue': '1'
      },
    ],
  },
  'pipelineArgs': {
    'SHARDS': '2',
  }
}

{
  'pipeline': {
    'environment': {
      'SHARDS': '2'
    }
  }
}

例: 入力ファイルをコピーする

次の例は、localCopy を使用する入力パラメータを示しています。この場合、一意のローカル ファイル名を生成して該当する環境変数に割り当て、gsutil コマンドを呼び出してファイルを VM にコピーするアクションを追加する必要があります。

接続された data ディスクは、ファイルをコピーするアクションだけでなく、そのファイルを使用すると予想されるすべてのアクションにもマウントされる必要があることにご注意ください。

v1alpha2v2alpha1

{
  'ephemeralPipeline': {
    'inputParameters': [
      {
        'name': 'INPUT1',
        'defaultValue': 'gs://DIRECTORY/FILE'
        'localCopy': {
          'path': 'test',
          'disk': 'data'
        }
      }
   ],
   'resources': {
     'disks': [
       {
         'name': 'data',
         'mountPoint': '/data'
       }
     ]
   }
 }
}

{
  'pipeline': {
     'environment': {
       'INPUT1': '/data/input1'
     },
    'actions': [
      {
        'imageUri': 'google/cloud-sdk',
        'commands': [
          'sh', '-c', 'gsutil cp gs:/DIRECTORY/FILE $INPUT1'
        ]
        'mounts': [
          {
            'disk': 'data',
            'path': '/data'
          }
        ]
      }
    ]
    'resources': {
      'virtualMachine': {
        'disks': [
           {
             'name': 'data'
           }
        ]
      }
    }
  }
}

ユーザー コマンドの実行

必要なローカライズ アクションを追加した後は、ユーザー指定の v1alpha2 エグゼキュータから単一のアクションを生成します。それには、DockerExecutor パラメータをアクションに変換する必要があります。

v1alpha2 API ではコマンドを実行する方法として bash を使用していました。v2alpha1 ではその必要はありませんが、予期しない結果にならないよう、パイプラインを移行する際には同じ方法を使用することをおすすめします。特に、環境関数を展開させるためには bash を使用する必要があります。

例: シェルを使用してユーザー指定のコマンドを実行する

v1alpha2v2alpha1

{
  'ephemeralPipeline': {
    'executor': {
      'imageName': 'ubuntu',
      'cmd': 'echo hello world'
    }
  }
}

{
  'pipeline': {
    'actions': [
      {
        'imageUri': 'ubuntu',
        'commands': [
          'bash', '-c', 'echo hello world'
        ]
      }
    ]
  }
}

ローカライズ解除

ユーザー コマンドを実行するアクションを追加した後は、すべての outputParameters に、さらにアクションを追加する必要があります。これらのアクションによって、VM のデータを Cloud Storage にコピーします。

追加するアクションには ALWAYS_RUN フラグを指定して、ユーザー コマンドが失敗しても実行されるようにします。通常、アクションが失敗すると、そのパイプラインは実行を停止します。部分的な出力ファイルでも役立つ場合があるため、ローカライズ解除アクションは必ず実行されるようにしてください。使用可能なフラグの完全なリストについては、Action リファレンス ドキュメントをご覧ください。

例: 出力ファイルをコピーする

v1alpha2v2alpha1

{
  'ephemeralPipeline': {
    'outputParameters': [
      {
        'name': 'OUTPUT1',
        'defaultValue': 'gs://DIRECTORY/FILE'
        'localCopy': {
          'path': 'test',
          'disk': 'data'
        }
      }
   ],
   'resources': {
     'disks': [
       {
         'name': 'data',
         'mountPoint': '/data'
       }
     ]
   }
 }
}

{
  'pipeline': {
     'environment': {
       'INPUT1': '/data/input1'
     },
    'actions': [
      {
        'imageUri': 'google/cloud-sdk',
        'commands': [
          'sh', '-c', 'gsutil cp $OUTPUT1 gs://DIRECTORY/FILE'
        ]
        'flags': [
          'ALWAYS_RUN'
        ],
        'mounts': [
          {
            'disk': 'data',
            'path': '/data'
          }
        ]
      }
    ]
    'resources': {
      'virtualMachine': {
        'disks': [
           {
             'name': 'data'
           }
        ]
      }
    }
  }
}

ロギング

最後に、ローカライズ解除アクションの実行後、VM のログを Cloud Storage にコピーする必要があります。v1alpha2 API との完全な互換性を確保するためには、数分間隔でこのアクションがバックグラウンドで実行されなければなりません。ただし、ほとんどのユーザーがログを確認する必要があるのはパイプラインの完了後のみなので、単一のアクションを表示するだけで十分です。

ログは特殊な(常に読み取り専用でマウントされる)/google ディレクトリ内に保管されます。このディレクトリの詳しい説明については、Action リファレンス ドキュメントをご覧ください。

例: パイプラインの完了時にすべてのログを Cloud Storage にコピーする

この例では、ALWAYS_RUN としてマークされた最後のアクションとして、VM のログが 1 回コピーされます(ログはパイプラインが失敗した場合に特に有用となるため)。

v1alpha2v2alpha1

{
  'ephemeralPipeline': {
    'logging': {
      'gcsPath': 'gs://DIRECTORY/FILE'
    }
 }
}

{
  'pipeline': {
    'actions': [
      {
        'imageUri': 'google/cloud-sdk',
        'commands': [
          'sh', '-c', 'gsutil cp /google/logs/output gs://DIRECTORY/FILE'
        ],
        'flags': [
          'ALWAYS_RUN'
        ]
      }
    ]
  }
}

例: 定期的にログを Cloud Storage にコピーする

この例では、バックグラウンド アクションとしてログが毎分 VM からコピーされます(v2alpha1 API の新機能)。

v1alpha2v2alpha1

{
  'ephemeralPipeline': {
    'logging': {
      'gcsPath': 'gs://DIRECTORY/FILE'
    }
 }
}

{
  'pipeline': {
    'actions': [
      {
        'imageUri': 'google/cloud-sdk',
        'commands': [
          'sh', '-c', 'while true; sleep 1m; gsutil cp /google/logs/output gs://DIRECTORY/FILE; done'
        ],
        'flags': [
          'RUN_IN_BACKGROUND'
        ]
      }
    ]
  }
}

ステータス情報の読み取り

一般に、オペレーションのステータスは標準の Long Running Operations API と同様の方法で公開されます。実行中の各パイプラインには、そのパイプラインが完了したかどうかを示す done フィールドがあります。このフィールドにオペレーションが完了したことが示されると、error または response フィールドに値が取り込まれます。

イベント

v2alpha1 API は、機械が読み取り可能なイベント ストリームを公開します。イベントのセットは v1alpha2 API とは異なります。以下の表に、v1alpha2 のイベントの説明と v2alpha1 API で公開される情報との対応関係を示します(可能な場合)。

v1alpha2 v2alpha1
start 最初の PullStartedEvent
pulling-image 各プルの開始時に、PullStartedEvent が生成されます。各プルの停止時に、PullStoppedEvent が生成されます。
running-docker アクションごとに、コンテナの開始時には ContainerStartedEvent、コンテナの終了時には ContainerStoppedEvent が生成されます。
localizing-files
delocalizing-files
ローカライズは単にコンテナ呼び出しの 1 つにすぎないため、ContainerStartedEventContainerStoppedEvent はアクションごとのラベルと組み合わせて使用できます。
fail FailedEvent が生成されます。
ok 対応するイベントはありませんが、オペレーションの done フィールドが true に設定され、error フィールドが空となります。

コンテナへのアクセス

v2alpha1 API では、実行中のコンテナに SSH で直接接続できません。ただし、バックグラウンド アクションとして別の SSH サーバーを実行することによってコンテナにアクセスできます。このサーバーは他のコンテナと同じネットワーク上で動作し、それらと通信できます。別のサーバーを実行するには、他のアクションを実行する前にそのサーバーをバックグラウンド アクションとして(RUN_IN_BACKGROUND フラグを使用して)開始します。

例: バックグラウンド アクションとして SSH コンテナを開始する

v2alpha1

{
  'pipeline': {
    'actions': [
      {
        'imageUri': 'gcr.io/cloud-genomics-pipelines/tools',
        'entrypoint': 'ssh-server',
        'flags': [
          'RUN_IN_BACKGROUND'
        ],
        "portMappings": {
          "22": 22
        }
      }
    ]
  }
}
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...