Workload API > Update existing Workloads > チュートリアル：実行中のワークロードの背後にあるアーティファクトを置き換える

チュートリアル：実行中のワークロードの背後にあるアーティファクトを置き換える¶

このチュートリアルでは、ローリング置換の全プロセスについて説明します。エンドポイントのURL、ガバナンス、IDを維持したまま、実行中のワークロードのアーティファクトを新しいものと交換します。プラットフォームは候補のプロトンを立ち上げ、それがrunningに達するのを待ってから、古いプロトンを停止（ティアダウン）します。概念モデル（アーティファクトのステータスごとの置換ルール、候補のrunning述語、ステートマシン、およびIaCのトレードオフ）については、置き換えてロールアウトを参照してください。

前提条件¶

開始する前に以下が必要です。

前提条件	備考
実行中のワークロード	`$WORKLOAD_ID`は、`locked`（ロック済み）の`service`アーティファクトをバックエンドとするワークロードを参照します。
新しいロック済みアーティファクト	`$NEW_ARTIFACT_ID`は、ロールアウト先のロック済みの`service`アーティファクトです。
一致するアーティファクトステータス	両方のアーティファクトが`locked`（本番）であるか、両方が`draft`（開発）である必要があります。マトリックスと、異なるステータス間での置換が許可されていない理由については、置き換えてロールアウトを参照してください。
`curl`と`jq`を備えたターミナル	このチュートリアルでのHTTP呼び出しとJSONの解析に使用します。`jq`がない場合は、各コマンドから末尾の`\\| jq ...`を削除して生のJSONレスポンスを読み取るか、jqlang.orgから`jq`をインストールしてください。

export DATAROBOT_ENDPOINT=[https://app.datarobot.com/api/v2](https://app.datarobot.com/api/v2)
export DATAROBOT_API_TOKEN=<your-api-token>

置換を開始する¶

curl -X POST "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/replacement" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": "'"${NEW_ARTIFACT_ID}"'",
    "strategy": "rolling",
    "config": {
      "warmupDurationMinutes": 10,
      "keepOldVersionMinutes": 60
    }
  }'

202 AcceptedとReplacementの本文を返します。プラットフォームは${NEW_ARTIFACT_ID}から候補のProtonを作成し、Readinessプローブを通過するのを待ってから、それをアクティブに昇格させ、古いProtonを破棄します。

一般的なエラー応答：

コード	原因
`404`	ワークロードまたはアーティファクトが見つからないか、呼び出し元からアクセスできません。
`422`	置換がすでに進行中であるか、ワークロードにアクティブなProtonがないか、新しいアーティファクトが互換性検証に失敗しました。

オプション：同じ呼び出し内でオートスケーリングを設定する¶

候補のProtonがすでに設定されたオートスケーリングで開始するように、リクエストにruntimeを含めます：

curl -X POST "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/replacement" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": "'"${NEW_ARTIFACT_ID}"'",
    "strategy": "rolling",
    "config": {"warmupDurationMinutes": 10, "keepOldVersionMinutes": 60},
    "runtime": {
      "containerGroups": [{
        "name": "default",
        "containers": [{"name": "agent", "resourceAllocation": {"cpu": 2, "memory": "4GB"}}],
        "autoscaling": {
          "enabled": true,
          "minReplicaCount": 2,
          "maxReplicaCount": 10,
          "policies": [{
            "scalingMetric": "cpuAverageUtilization",
            "target": 70
          }]
        }
      }]
    }
  }'

ゼロスケーリングに代わる方法

バースト性のあるワークロードやトラフィックが少ないワークロードの場合は、httpRequestsConcurrencyにminReplicaCount: 0を指定し、アイドル時にレプリカ数が0になるようにします。トレードオフは、アイドル期間後にトラフィックが再開する際にコールドスタートが発生することです。レイテンシーの影響を受けやすいワークロードの場合は、minReplicaCount: 1を指定します。スケーリング指標を参照してください。

runtimeを省略した場合、新しいアーティファクトではワークロードの現在のランタイムが再利用されます。

置換の監視¶

置換のステータスは2つの方法で観察できます。GET /replacementを介して直接観察するか、Protonを検査するかです。

# Active replacement snapshot
curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/replacement" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq '{status, strategy, candidateArtifactId, candidateProtonIds}'

# Per-proton view: summary state only
curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/protons" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq '.data[] | {id, artifactId, role, status}'

置換スナップショット（ReplacementStatus）は、以下の状態を経由します。

submitted -> initializing -> promoting -> finalizing -> completed

実行中、候補Proton（ProtonStatus）は以下の状態を経由します。

{"id": "lat_abc123", "artifactId": "art_v1", "role": "active",    "status": "running"}
{"id": "lat_def456", "artifactId": "art_v2", "role": "candidate", "status": "warming"}

置換がcompletedになるまで待ちます。プラットフォームはすべての移行を自動的に実行します。promotingとfinalizingの間にクライアントのアクションは必要ありません。候補が provisioning、launching、またはwarmingで停止した場合は、プレディケートテーブルとデバッグについてライフサイクルの状態を参照してください。

置換中、WorkloadレベルのステータスはアクティブなProtonのままになります

候補の中間状態（Proton専用であり、Workloadレベルに表示されることのないwarmingなど）は、/workloads/{id}/protons/を介してのみ確認できます。置換中に GET /workloads/{id}を呼び出すと、引き続きアクティブなProtonのrunningステータスが表示されます。Workload/protonの予測については、ライフサイクルの状態を参照してください。

候補のレプリカごとの詳細（ログテール、コンテナごとの準備状況、再起動回数）については、候補のProtonで直接statusDetailsを呼び出してください。リストおよび取得Protonエンドポイントには埋め込まれていません。

CANDIDATE_ID=$(curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/protons" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  | jq -r '.data[] | select(.role == "candidate") | .id')|

curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/protons/${CANDIDATE_ID}/statusDetails" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq '.'

ライフサイクルイベントの監視¶

/events エンドポイントは、置換の作成、候補のrunningへの到達、トラフィックの切り替え、古いprotonのドレインなど、置換の経緯を記録します。

curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/events" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq '.data[] | {timestamp, eventType, details}'

置換中のOpenTelemetryによる監視¶

ワークロードのOpenTelemetryログ、トレース、および指標は、/api/v2/otel/workload/{workload_id}/... にあるプラットフォームのオブザーバビリティ基盤を通じて公開されます（注：単数の workload。entityType 列挙型は deployment、use_case、experiment_container、custom_application、または workload です）：

curl -s "${DATAROBOT_ENDPOINT}/otel/workload/${WORKLOAD_ID}/logs/" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

curl -s "${DATAROBOT_ENDPOINT}/otel/workload/${WORKLOAD_ID}/traces/" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

curl -s "${DATAROBOT_ENDPOINT}/otel/workload/${WORKLOAD_ID}/metrics/" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

OTel基盤は、置換中のアクティブなProtonと候補のProtonの両方を集約します。Proton単位またはレプリカ単位の分離については、置換の監視で説明されているWorkload APIの/protons/{proton_id}/statusDetailsエンドポイントを使用してください。

最終状態の確認¶

置換がcompletedに到達すると、候補が昇格し、古いProtonがティアダウンされます。以下のコマンドを実行して、最終状態を確認します。

curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/protons" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq '.data[] | {id, artifactId, role, status}'

新しいアーティファクトと active の役割を持つ単一のprotonが表示されるはずです。

{"id": "lat_def456", "artifactId": "art_v2", "role": "active", "status": "running"}

ワークロードレベルのビューは次のようになります。

curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq '{status, artifactId, importance, endpoint}'

artifactId は ${NEW_ARTIFACT_ID} になり、endpoint は置換前と変わらないはずです。これがAPI駆動パスのポイントです。

置換履歴¶

過去の置換は /workloads/{id}/history（ページ分割された Replacement エントリー）に表示されます。

curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/history" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

「昨日の14:30にどのアクティブなアーティファクトがあったか？」などの疑問や、置換の連鎖に役立ちます。各エントリーには、候補とアクティブなprotonのID、およびタイムスタンプが含まれています。

置換のキャンセル¶

候補が失敗していて、ローリングウィンドウがタイムアウトするのを待ちたくない場合は、アクティブな置換をキャンセルします。

curl -X DELETE "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/replacement" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

202 Accepted を返します。プラットフォームは置換を status: canceling に設定して候補を元に戻し（状態は finalizing を経て移行します）、ワークロードは元のアーティファクトがアクティブなままの置換前の状態に戻ります。

Infrastructure-as-Codeに代わる方法（Pulumi）¶

Infrastructure-as-Codeは、artifact_id を変更時置換の属性として扱うことで、ワークロードレベルの再構築という1つの置換形態をモデル化します。これを変更すると、PulumiまたはTerraformがトリガーされ、アップタイムを維持するために delete_before_replace = false を指定して新しいワークロードを立ち上げ、古いワークロードをティアダウンします。

import pulumi
import pulumi_datarobot as datarobot
# Requires pulumi-datarobot >= 0.10.38

prod = datarobot.Workload(
    "agent-prod",
    name="agent-prod",
    artifact_id=new_artifact_id,            # bump this -> triggers IaC replace
    importance="high",
    runtime={"container_groups": [{"replica_count": 2, "containers": [{
        "name": "agent",
        "resource_allocation": {"cpu": 2, "memory": 4294967296},
    }]}]},
    opts=pulumi.ResourceOptions(delete_before_replace=False),
)

重要な違い：IaCはワークロードを置換し、APIはprotonを置換する

IaCの置換はワークロードを再構築します。つまり、エンドポイントのURLが変更されます。POST /workloads/{id}/replacement は安定したワークロードの下でprotonを入れ替えるため、エンドポイントは維持されます。どちらもローリングですが、エンドポイントを維持するのは片方だけです。完全なIaCの比較と「どちらを使用すべきか」のガイダンスについては、Pulumiによるワークロードの管理を参照してください。