Operator を使用して、エアギャップ環境の Kubernetes に IDOT をインストールする

オンラインで編集する

「 IDOT 」オペレーター（ Helm ）を使用することで、エアギャップ環境の Kubernetes 環境に、 OpenTelemetry Collectorの Instana ディストリビューション（ IDOT ）をインストールできます。 このオペレーターは、 Kubernetes にネイティブに統合された方法で OpenTelemetry コレクターを展開・管理し、コレクターインスタンスのライフサイクル管理を自動化します。

前提条件

エアギャップ方式のターゲットシステムについて：

  • Kubernetes 1.32.x そしてその後
  • Helm 3.16.x そしてその後
  • skopeo ローカルレジストリにイメージを書き込むために使用されるマシンにインストールされた
  • Instana バックエンドへのネットワーク接続
  • すべてのクラスタノードからアクセス可能で、 Docker Registry（ V2 API ）をサポートするローカルコンテナレジストリ（例： Docker Registry、Harbor、またはNexus）。

必要な資料（所属組織の内部ルートを通じて入手したもの）：

  • IDOT Helm チャートパッケージの操作方法（.tgz ファイル）
  • IDOT 回収容器の画像（.tar ファイル）
  • OpenTelemetry オペレーター用コンテナイメージ（.tar ファイル）
  • kubectl コンテナイメージ（.tarKubernetes ジョブに必要なファイル）
  • kube-rbac-proxy コンテナイメージ（オペレーター.tar に必要なファイル）。

必須情報:

  • Instana エージェントキー（対象の Instana のUIから取得したもの）
  • Instana バックエンドのエンドポイント（ホストとポート）
  • ローカルレジストリのアドレス（例： registry.example.internal:5000）。

設定値の確認方法：

これらのパラメータは、 Instana のUIで、「 Agent & collectors 」＞「 OpenTelemetry Collectors 」の下に表示されます
  • [コレクターのインストール ] > [ Kubernetes オペレーター] をクリックします。
  • インストールコマンドでは：
    • INSTANA_KEY: フラグ -a の後に続くエージェントキーを探してください。
    • INSTANA_OTEL_ENDPOINT_GRPC: フラグ -e の後に続く「 gRPC 」というエンドポイントを探してください。
    • INSTANA_OTEL_ENDPOINT_HTTP: フラグ -H の後に続く「 HTTP 」というエンドポイントを探してください。

システムの完全な動作要件については、 「 IDOT 」の動作要件をご覧ください。

インターネットに接続されたマシンでのアーティファクトのダウンロード

「 IDOT 」演算子のチャート（ Helm ）は、公式の「 Instana 」リポジトリ（ Helm ）で確認できます：

  • リポジトリ URL : https://instana.github.io/instana-otel-collector
  • チャート オペレーター名 ： instana-otel-collector-chart-operator

インターネットに接続されたマシンで、以下の手順を実行してください：

手順 1: Instana Helm リポジトリを追加する

helm repo add instana-otel https://instana.github.io/instana-otel-collector
helm repo update

ステップ 2：最新のオペレーター「 Helm 」のチャートを入手する

# Create a directory to store the artifacts
mkdir /tmp/idot-airgap
cd /tmp/idot-airgap

# Pulls the latest version of chart operator always
helm pull instana-otel/instana-otel-collector-chart-operator

このコマンドは、現在のディレクトリにファイル .tgz を作成します。 ファイル名には、. instana-otel-collector-chart-operator-latest.tgzのようなチャートバージョンが含まれています。

ステップ3：コンテナイメージをダウンロードして保存する

必要な画像を取得し、アーカイブファイルに保存します：

skopeo copy --all docker://icr.io/instana/idot:latest oci-archive:idot-latest.tar
skopeo copy --all docker://ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator:<OPENTELEMETRY_OPERATOR_VERSION> oci-archive:opentelemetry-operator.tar
skopeo copy --all docker://registry.k8s.io/kubectl:<KUBECTL_VERSION> oci-archive:kubectl.tar
skopeo copy --all docker://quay.io/brancz/kube-rbac-proxy:<KUBE_RBAC_PROXY_VERSION> oci-archive:kube-rbac-proxy.tar
注:
  • を適切なバージョンに KUBECTL_VERSION 置き換えてください。例えば、など v1.35.2。
  • を適切なバージョンに KUBE_RBAC_PROXY_VERSION 置き換えてください。例えば、など v0.21.1。
  • を適切なバージョンに OPENTELEMETRY_OPERATOR_VERSION 置き換えてください。例えば、など 0.147.0。

ステップ4：転送用のアーティファクトを準備する

エアギャップ環境への転送に備え、以下のファイルを用意しておいてください：

  • instana-otel-collector-chart-operator-latest.tgz （ Helm のチャート）
  • idot-latest.tar ( IDOT Collector コンテナイメージ)
  • opentelemetry-operator.tar （ OpenTelemetry のコンテナイメージ）
  • kubectl.tar （ kubectl のコンテナイメージ）
  • kube-rbac-proxy.tar (kube-rbac-proxy コンテナイメージ)

ステップ5：アーティファクトをエアギャップ環境に移行する

これらのアーティファクトを、ローカルレジストリにアクセスできるエアギャップ環境内のマシンに転送してください。 USBメモリなどの物理メディアを使用して、転送を完了してください。

# Copy to USB on the source system
cp /tmp/idot-airgap/* /media/usb/
umount /media/usb

# On the air-gapped system, mount and copy
mount /dev/sdb1 /mnt/usb
cp /mnt/usb/* /tmp/idot-airgap/
umount /mnt/usb

Operator を使用した IDOT のインストール

手順 1: 画像をローカルレジストリに追加する

ローカルレジストリにアクセスできるマシンで、イメージアーカイブを読み込み、プッシュします：

skopeo copy --all --dest-tls-verify=false oci-archive:idot-latest.tar docker://<YOUR_LOCAL_REGISTRY>/instana/idot:latest
skopeo copy --all --dest-tls-verify=false oci-archive:opentelemetry-operator.tar docker://<YOUR_LOCAL_REGISTRY>/opentelemetry-operator/opentelemetry-operator:0.147.0
skopeo copy --all --dest-tls-verify=false oci-archive:kubectl.tar docker://<YOUR_LOCAL_REGISTRY>/instana/kubectl:v1.35.2
skopeo copy --all --dest-tls-verify=false oci-archive:kube-rbac-proxy.tar docker://<YOUR_LOCAL_REGISTRY>/instana/kube-rbac-proxy:v0.21.1
注： YOUR_LOCAL_REGISTRY を実際のレジストリアドレスに置き換えてください。 registry.example.internal:5000例：

ステップ 2: ローカルの「 Helm 」チャートを使用して、 IDOT Operator をインストールします

  1. オペレーター専用のネームスペースを作成します：
    kubectl create namespace instana-otel-operator

  2. ローカルのchartパッケージを使用して、 IDOT オペレーターをインストールします：

    クラスタにレジストリのミラーが設定されていない場合は、必要なすべてのイメージについて、イメージリポジトリをローカルレジストリに設定してください。 クラスタでレジストリミラーが設定されている場合、イメージのフラグ --set を省略できます。

    helm install instana-otel-operator /tmp/idot-airgap/instana-otel-collector-chart-operator-latest.tgz \
  --namespace instana-otel-operator \
  --create-namespace \
  --set clusterName=<CLUSTER_NAME> \
  --set instanaEndpoint=<INSTANA_ENDPOINT> \
  --set instanaKey=<INSTANA_KEY> \
  --set daemonset.enabled=true \
  --set statefulset.enabled=true \
  --set statefulset.image.repository=<YOUR_LOCAL_REGISTRY>/instana/idot \
  --set statefulset.image.tag=latest \
  --set daemonset.image.repository=<YOUR_LOCAL_REGISTRY>/instana/idot \
  --set daemonset.image.tag=latest \
  --set instana.kubectl.image.repository=<YOUR_LOCAL_REGISTRY>/instana/kubectl \
  --set instana.kubectl.image.tag=v1.35.2 \
  --set opentelemetry-operator.manager.image.repository=<YOUR_LOCAL_REGISTRY>/opentelemetry-operator/opentelemetry-operator \
  --set opentelemetry-operator.manager.image.tag=0.147.0 \
  --set opentelemetry-operator.kubeRBACProxy.image.repository=<YOUR_LOCAL_REGISTRY>/instana/kube-rbac-proxy \
  --set opentelemetry-operator.kubeRBACProxy.image.tag=v0.21.1
    注： CLUSTER_NAME、 INSTANA_ENDPOINT、 およびINSTANA_KEYは必須パラメータです。 また、、 kubeRBACProxy および opentelemetry-operator のイメージについて kubectl、利用可能な最新バージョンに置き換えてください。

ステップ3：オペレーターのインストールを確認する

  1. コマンドラインから、オペレーター・ポッドのステータスを確認します：
    kubectl get pods -n instana-otel-operator

    予期される出力:

    NAME                                     READY   STATUS    RESTARTS   AGE
instana-otel-operator-7d9f8b5c6d-xk2lm   2/2     Running   0          30s
idot-daemonset-agent-szpth               1/1     Running   0          25s
idot-statefulset-0                       1/1     Running   0          25s
  2. コマンドラインから、カスタムリソース定義（CRD）がインストールされていることを確認します：
    kubectl get crd | grep opentelemetry

    予期される出力:

    instrumentations.opentelemetry.io              2026-03-16T14:15:24Z
opampbridges.opentelemetry.io                  2026-03-16T14:15:24Z
opentelemetrycollectors.opentelemetry.io       2026-03-16T14:15:24Z
targetallocators.opentelemetry.io              2026-03-16T14:15:24Z
    注： 出力には「 OpenTelemetryCollector 」CRDが含まれている必要があります。
  3. コマンドラインから、 OpenTelemetryCollector のカスタムリソースを確認します：
    kubectl get opentelemetrycollector -n instana-otel-operator

    予期される出力:

    NAME               MODE          VERSION   READY   AGE     IMAGE                        MANAGEMENT
idot-daemonset     daemonset     0.147.0   1/1     8m45s   icr.io/instana/idot:latest   managed
idot-statefulset   statefulset   0.147.0   1/1     8m44s   icr.io/instana/idot:latest   managed
  4. コマンドラインから、コレクターのログを確認します：
    kubectl logs -n instana-otel-operator -l app.kubernetes.io/managed-by=opentelemetry-operator

    起動に成功したメッセージを確認してください：

    Starting otelcol...
Everything is ready. Begin running and processing data.
  5. Instana のUIから、コレクターが表示されていることを確認してください：
    1. ナビゲーションメニューから、 「Platforms 」＞「 Kubernetes 」をクリックします。
    2. 「CLUSTER_NAME」 と表示されている OpenTelemetry コレクター をクリックしてください。

コレクターの設定を更新する

コレクターの設定を更新するには、 OpenTelemetryCollector カスタムリソースを編集します：

kubectl edit opentelemetrycollector idot-daemonset -n instana-otel-operator
kubectl edit opentelemetrycollector idot-statefulset -n instana-otel-operator

オペレーターは変更を自動的に検出し、それに応じてコレクターポッドを更新します。

Operator を使用して、 Kubernetes クラスター内の IDOT をアップグレードする

IDOT をアップグレードするには：

  1. 新しいアーティファクトをダウンロードします。 「インターネットに接続されたマシンでのアーティファクトのダウンロード」 を参照してください。
  2. 画像をローカルレジストリに書き込む。 手順 1 を参照：画像をローカルレジストリに追加する。
  3. の代わりに、コマンド helm upgrade を実行 helm installしてください。 コマンド構文については、「 手順 2: ローカルの ` Helm ` チャートを使用して ` IDOT ` オペレーターをインストールする」 を参照してください。

オペレーターは、管理対象のコレクターインスタンスのアップグレードを自動的に処理します。

Operator を使用して、 Kubernetes クラスターから ` IDOT ` をアンインストールする

  1. 「 Helm 」チャートをアンインストールします：
    helm uninstall instana-otel-operator -n instana-otel-operator
  2. オプション：名前空間を削除する：
    kubectl delete namespace instana-otel-operator

Operator を使用して、エアギャップ化された OpenShift （OCP）環境に IDOT をインストールする

エアギャップ環境の OpenShift に IDOT をインストールする手順は、 Kubernetes の場合と同じですが、以下の点が異なります：

  • OpenShift ローカルレジストリとして使用できる組み込みの画像レジストリが備わっています。
  • 可能な kubectl 場合は、の代わりにコマンド oc を使用してください。

前提条件

手順 1: OCP の内部レジストリを公開する

内部レジストリのルートがすでに公開されているかどうかを確認してください：

oc get route -n openshift-image-registry

ルートが存在しない場合は、公開してください：

oc patch configs.imageregistry.operator.openshift.io/cluster \
  --patch '{"spec":{"defaultRoute":true}}' \
  --type=merge

レジストリのホスト名を取得する：

oc get route default-route -n openshift-image-registry -o jsonpath='{.spec.host}'

出力は以下のようになります。 default-route-openshift-image-registry.apps.<CLUSTER_DOMAIN>

ステップ 2: 画像を OCP 内部レジストリにプッシュする

画像を保存するためのプロジェクトを作成します：

oc new-project idot-images

OCPトークンを使用してレジストリにログインしてください：

TOKEN=$(oc whoami --show-token)
podman login default-route-openshift-image-registry.apps.<CLUSTER_DOMAIN> \
  -u kubeadmin \
  -p $TOKEN \
  --tls-verify=false

画像を押し込んでください：

skopeo copy --all oci-archive:idot-latest.tar \
  docker://default-route-openshift-image-registry.apps.<CLUSTER_DOMAIN>/idot-images/instana/idot:latest \
  --dest-tls-verify=false

skopeo copy --all oci-archive:opentelemetry-operator.tar \
  docker://default-route-openshift-image-registry.apps.<CLUSTER_DOMAIN>/idot-images/opentelemetry-operator/opentelemetry-operator:0.147.0 \
  --dest-tls-verify=false

skopeo copy --all oci-archive:kubectl.tar \
  docker://default-route-openshift-image-registry.apps.<CLUSTER_DOMAIN>/idot-images/kubectl:v1.35.2 \
  --dest-tls-verify=false

skopeo copy --all oci-archive:kube-rbac-proxy.tar \
  docker://default-route-openshift-image-registry.apps.<CLUSTER_DOMAIN>/idot-images/instana/kube-rbac-proxy:v0.21.1 \
  --dest-tls-verify=false
注： CLUSTER_DOMAIN を、ご使用の OCP クラスタドメイン（例：）に置き換えて airgap-ocp.cp.fyre.ibm.comください。

ステップ3：画像の取得権限を付与する

オペレーターに、プロジェクト idot-images からイメージを取得するための名前空間へのアクセス権を付与します：

oc policy add-role-to-group system:image-puller system:serviceaccounts:instana-otel-operator \
  -n idot-images

ステップ4：イメージミラーリングの設定

以下の設定 ImageDigestMirrorSetを作成して、OCPがイメージのプルを自動的に内部レジストリにリダイレクトするように設定します：

cat <<EOF | oc apply -f -
apiVersion: config.openshift.io/v1
kind: ImageDigestMirrorSet
metadata:
  name: idot-operator-mirror
spec:
  imageDigestMirrors:
  - mirrors:
    - image-registry.openshift-image-registry.svc:5000/idot-images/instana/idot
    source: icr.io/instana/idot
    mirrorSourcePolicy: NeverContactSource
  - mirrors:
    - image-registry.openshift-image-registry.svc:5000/idot-images/opentelemetry-operator/opentelemetry-operator
    source: ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator
    mirrorSourcePolicy: NeverContactSource
  - mirrors:
    - image-registry.openshift-image-registry.svc:5000/idot-images/instana/kube-rbac-proxy
    source: quay.io/brancz/kube-rbac-proxy
    mirrorSourcePolicy: NeverContactSource
  - mirrors:
    - image-registry.openshift-image-registry.svc:5000/idot-images/kubectl
    source: registry.k8s.io/kubectl
    mirrorSourcePolicy: NeverContactSource
EOF

この設定はすべてのノードに反映 MachineConfigOperator されます。 先に進む前に、すべてのノードが更新されるまでお待ちください：

oc wait mcp/worker --for condition=updated --timeout=300s
oc wait mcp/master --for condition=updated --timeout=300s

ステップ 5: 「 IDOT 」オペレーターをインストールする

helm install instana-otel-operator /tmp/idot-airgap/instana-otel-collector-chart-operator-latest.tgz \
  --namespace instana-otel-operator \
  --create-namespace \
  --set clusterName=<CLUSTER_NAME> \
  --set instanaEndpoint=<INSTANA_ENDPOINT> \
  --set instanaKey=<INSTANA_KEY> \
  --set daemonset.enabled=true \
  --set statefulset.enabled=true
注： CLUSTER_NAME、 INSTANA_ENDPOINT、 およびINSTANA_KEYは必須パラメータです。

手順 6：インストールを確認する

手順 3：「オペレーターのインストール確認」 に従って、インストールを確認してください。 可能な kubectl 場合は、の代わりにコマンド oc を使用してください。

トラブルシューティング

ImagePullBackOff または ErrImagePull

Helm のリリースにあるイメージリポジトリとタグが、ローカルレジストリにプッシュされた内容と一致していることを確認してください。 OpenShift クラスタでは、該当 kubectl する場合は の代わりに コマンド oc を使用してください：

# Check what the pod is requesting
oc describe pod -n instana-otel-operator <POD_NAME> | grep "Image:"

# Check what is available in the local registry (standard registry)
curl -s http://<YOUR_LOCAL_REGISTRY>/v2/instana/idot/tags/list

# For OCP internal registry, use oc or skopeo instead
oc get imagestreamtag -n idot-images
skopeo list-tags docker://default-route-openshift-image-registry.apps.<CLUSTER_DOMAIN>/idot-images/instana/idot --tls-verify=false

不一致がある場合は、正しい画像にタグを付け直して再度プッシュするか、正しい --set image.repository 値で再インストールしてください。

Helm チャートが見つかりません

ファイル .tgz が見つからない場合は、ファイルのパスとファイル名を確認してください：

ls -lh /tmp/idot-airgap/*.tgz

Instana のUIにコレクターが表示されない

接続エラーや認証エラーがないか、Podのログを確認してください：

kubectl logs -n instana-otel-operator -l app.kubernetes.io/managed-by=opentelemetry-operator | grep -i error

instanaEndpoint および instanaKey の値が正しいこと、およびコレクターがクラスター内から Instana エンドポイントにアクセスできることを確認してください。

オペレーターがコレクターを作成していない

オペレーターがコレクター・ポッドを作成していない場合は、以下を確認してください：

  1. オペレーターが実行中であることを確認してください：
    kubectl get pods -n instana-otel-operator
kubectl logs -n instana-otel-operator -l app.kubernetes.io/name=opentelemetry-operator
  2. OpenTelemetryCollector のカスタムリソースを確認してください：
    kubectl get opentelemetrycollector -n instana-otel-operator
  3. CRDがインストールされていることを確認してください：
    kubectl get crd opentelemetrycollectors.opentelemetry.io

アーキテクチャが不適切なイメージが原因でPodが失敗する

ポッドが以下のエラーで失敗した場合exec format error、間違ったアーキテクチャ用のイメージがダウンロードされてしまいました。 この問題を解決するには、以下の手順を実行します:

  1. 手順 3 を再度実行します：`--target-architecture` フラグ --override-arch を指定してコンテナイメージをダウンロードし、保存します。
  2. 修正した画像をエアギャップ環境に転送してください。
  3. 修正した画像を読み込み、ローカルレジストリに書き込みます。
  4. 既存のポッドを削除して、強制的に再起動させます：
    kubectl delete pods -n instana-otel-operator --all