Oracle Cloud Infrastructureドキュメント

コマンド仕様

コマンド仕様には、デプロイメント中に実行されるシェル・コマンドおよび設定が含まれます。コマンド仕様は、YAMLで記述されます。ファイルの内容をインラインで指定するか、仕様をアーティファクト・レジストリ・リポジトリに格納できます。

Oracleによって事前インストールされていないバイナリ・ファイルを実行するには、それをルート・フォルダに直接ダウンロードするか、ワークスペース・フォルダにダウンロードしてから、実行する前にルート・フォルダに移動する必要があります。

コマンド仕様は、次のセクションで構成されています:

  • 環境変数の設定。
  • 入力アーティファクト。
  • 順番に実行するステップ。

コマンド仕様の構文

version: 0.1
component: command
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
 
inputArtifacts:
  - name: artifact-name
    type: GENERIC_ARTIFACT
    artifactId: "artifact-ocid"
    registryId: OCID of the Artifact Registry
    path: path of the artifact in the Registry
    version: version of the artifact
    location: target-location
  - name: artifact-name
    type: URL
    url: downloadable link
    location: target-location
 
steps:
  - type: Command
    name: step-name
    shell: shellType
    timeoutInSeconds: 650
    failImmediatelyOnError: true
    command: command
    onFailure:
      - type: Command
        command: |
          command
          command
        timeoutInSeconds: 400
 
  - type: Command
    name: step-name
    command: |
      command
      command
      command
    onFailure:
      - type: Command
        command: |
          command
        timeoutInSeconds: 400

コマンド仕様のパラメータ

次に、コマンド仕様のパラメータとその詳細を示します:

パラメータ 説明
version 必須。コマンド仕様のバージョンを示します。バージョンが存在しないか無効であると、「シェル」ステージは失敗します。

サポートされる値は0.1です。
component 必須。DevOpsの特定のコンポーネントを示します。値が存在しないか無効であると、ステージは失敗します。

サポートされる値はcommandです。
timeoutInSeconds オプション。コマンド仕様ファイル全体のタイムアウトを指定します。各ステップには、オプションで独自のタイムアウト値を指定することもできます。

値を指定しない場合、デフォルト値の8時間が使用されます。許可される最大値は8時間です。
shell オプション。コマンド仕様のグローバル・レベルで使用するシェルを指定します。値は、オプションでステップ・レベルでオーバーライドできます。

許可される値は/bin/shおよびbashです。指定しない場合、デフォルト値のbashが使用されます。
failImmediatelyOnError オプション。ステップ内のいずれかのコマンドがゼロ以外の終了値で失敗した場合にデプロイメントを続行する必要があるかどうかを指定します。指定しない場合、デフォルト値はfalseで、ステップは続行されます。使用可能な値はtrueおよびfalseです。OCIでは、この属性の値をtrueに設定することをお薦めします。
env

オプション。カスタム変数を定義できます。3つのタイプの変数がサポートされます:

  • env/variables: オプション。キーは文字列で、POSIX環境変数に準拠している必要があります。値には任意の文字列を指定できます。この変数のスコープは、コマンド仕様ファイルの実行です。変数の値の変更は、後続のステップで認識されます。これらの変数は、コマンド仕様ファイル内のすべてのステップの環境変数として使用できます。

    変数の値に改行(\n)またはキャリッジ・リターン(\r)文字が含まれている場合は、後続のステップでスペースに置き換えられます。

  • env/vaultVariables: オプション。キーは文字列で、POSIX環境変数に準拠している必要があります。この値は、ボールトからのシークレットのOCIDである必要があります。ボールトとパイプラインは、同じテナンシである必要があります。テナンシには、デプロイメント・パイプライン・リソースがシークレットにアクセスすることを許可する適切なポリシーが必要です。

    この変数のスコープは、コマンド仕様ファイルの実行であり、ファイル内のすべてのステップで使用できます。これらの変数の値は、ボールトから取得され、コマンド仕様ファイル内のすべてのステップの環境変数として使用できます。

  • env/exportedVariables: オプション。変数のリストはここで宣言できます。変数名は文字列で、POSIX環境変数に準拠している必要があります。この値は、コマンド仕様ファイル内のいずれかのステップで割り当てることができます。この変数のスコープは、デプロイメント・パイプラインです。エクスポートされた変数は、同じパイプラインの「シェル」ステージでのみ使用できます。
inputArtifacts

オプション。現在の「シェル」ステージの実行に必要な入力アーティファクトのリストを定義するために使用されます。

アーティファクト・レジストリからの汎用アーティファクトをサポートします。

パラメータは次のとおりです:

  • inputArtifacts/*/url: オプション。入力アーティファクトの外部のダウンロード可能HTTP URLを指定する必要があります。URLはパブリックに使用可能である必要があります。現在、認証/認可はサポートされていません。
  • inputArtifacts/*/name: 必須。この名前は、コマンド実行でアーティファクトを参照するために使用されます。
  • inputArtifacts/*/location: 必須。入力アーティファクトをダウンロードする必要があるローカル・ファイル・システムの宛先パス。パスは次のいずれかの方法で指定できます:
    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • プロジェクト・ホームからの相対パス、pom.xml

    いずれかの値を使用すると、入力アーティファクトがファイル名pom.xmlでプライマリ・ソース・ホーム・ディレクトリにダウンロードされます。

    locationでは、exportedVariablesまたはパイプライン変数はサポートされていません。

  • inputArtifacts/*/type: 必須。ダウンロードする必要がある入力アーティファクトのタイプ。許可される値はURLおよびGENERIC_ARTIFACTです。
  • inputArtifacts/*/artifactld: 必須。アーティファクトのOCID。OCIDを指定した場合、デプロイメント・パイプラインはregistryId、パスおよびバージョンを無視します。
  • inputArtifacts/*/registryld: 必須。アーティファクト・レジストリのOCID。
  • inputArtifacts/*/path: 必須。アーティファクトの宛先パス。
  • inputArtifacts/*/version: 必須。アーティファクトのバージョン。

ノート: GENERIC_ARTIFACTタイプの入力アーティファクトの場合、必須パラメータとしてアーティファクトのOCID、またはレジストリID、パスおよびアーティファクト・バージョンの組合せを指定できます。
steps

必須。このセクションでは、実行する必要があるステップのリストを定義します。

  • steps/*/type: 必須。ステップのタイプを指定します。Commandの値がサポートされます
  • steps/*/name: オプション。ステップのわかりやすい名前。

ステップのタイプ

コマンド

属性名 説明
command 単一行と複数行の両方のコマンドがサポートされます。1つのステップで指定されているすべてのコマンドは、同じシェル・セッションで実行されます。steps/*/shellの値に基づいて、コマンドはshellまたはbashのいずれかになります。

フェイル・ファストは有効になっていません。ステップの成功については、ステップの最終コマンドの出力が考慮されます。最終コマンドの終了コードが0の場合、ステップは成功とみなされます。
timeoutInSeconds (オプション) ステップのタイムアウトを指定します。指定しない場合、値はグローバルtimeoutInSecondsパラメータから継承されます。許可される最大値は8時間です。
shell (オプション) 現在のステップのシェル・タイプを指定します。指定しない場合、値はグローバルshellパラメータから継承されます。許可される値は/bin/shおよびshellです。
onFailure (オプション) 「シェル」ステージを正常に終了するために失敗時に実行する必要があるステップのリスト。対応するステップが失敗し、実行後にコマンド仕様が終了した場合に実行します。

失敗の処理は、「シェル」ステージのステータスに影響しません。いずれかのステップが失敗した場合、「シェル」ステージのステータスはfailedのままになりますが、onFailureブロックを使用して処理されます。
failImmediatelyOnError (オプション) ステップ内のいずれかのコマンドがゼロ以外の終了値で失敗した場合にデプロイメントを続行する必要があるかどうかを指定します。指定しない場合、デフォルト値はfalseで、ステップは続行されます。使用可能な値はtrueおよびfalseです。OCIでは、この属性の値をtrueに設定することをお薦めします。

stepsで定義されているfailImmediatelyOnError属性値は、stepsの外部で定義されている同じ属性値よりも優先されます。

事前定義済システム変数

DevOpsには、デフォルト値を持つ事前定義済システム変数のセットがあり、コマンド仕様で使用できます。

変数 説明
OCI_DEPLOYMENT_ID 現在のデプロイメントのOCID。
OCI_PIPELINE_ID 現在のデプロイメント・パイプラインのOCID。
OCI_RESOURCE_PRINCIPAL_RPST リソース・プリンシパル・トークン。
OCI_RESOURCE_PRINCIPAL_VERSION リソース・プリンシパル・バージョン。
OCI_CLI_AUTH リソース・プリンシパルを使用するように事前構成されたOCI CLI AUTH。
OCI_RESOURCE_PRINCIPAL_REGION リソース・プリンシパル・リージョン。
OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM リソース・プリンシパルの秘密キー・パス。

コマンド仕様の例

例: OKEネームスペースを作成します。

version: 0.1
component: command
timeoutInSeconds: 6000
shell: bash

steps:
  - type: Command
    timeoutInSeconds: 600
    name: "Setup kube config and get nodes"
    command: |
      oci ce cluster create-kubeconfig --cluster-id ${clusterid} --file $HOME/.kube/config --region us-ashburn-1 --token-version 2.0.0  --kube-endpoint ${endpoint}
      kubectl get nodes
    onFailure:
      - type: Command
        command: |
          echo "Failed to set up kube config and get nodes"
        timeoutInSeconds: 60