K8S Agent のインストール

1. 事前準備​

インストール前に、以下の 2 つを準備します。

• Agent イメージのアップロード — exem-k8s-agent、exem-container-agent イメージを、事前に顧客環境の Container Registry にアップロードします。
• Namespace の作成 — インストール先の Namespace をあらかじめ作成します。

2. サポート環境​

3. 画面からインストールする​

exemONE の Web UI で YAML を生成・ダウンロードし、クラスターにデプロイします。

1. 画面左下のアカウントメニューから [設定] に移動します。

2. [プラットフォーム > Kubernetes] をクリックします。
3. [Install Agent] をクリックして YAML ファイルのエクスポート画面を開きます。

4. Agent の構成と設定項目を確認します。各項目の説明は Description を参照してください。

5. 内容を確認し、必要に応じて YAML ファイルを修正します。

6. [ダウンロード] ボタンをクリックして YAML ファイルを保存します。

7. 画面に表示されたコマンドでクラスターにデプロイします。

   kubectl apply -f <다운로드한-yaml-파일>
   

4. Helm でインストールする​

Helm Chart を使用して Agent をインストールできます。インストール方法については、製品技術チームにお問い合わせください。

5. デプロイされたバージョンを確認する​

クラスターにデプロイされた Agent イメージのバージョンを、以下のコマンドで確認します。

# exem-k8s-agent 버전 확인
kubectl get deployments -n exem-one exem-k8s-agent -o jsonpath="{..image}"

# exem-container-agent 버전 확인
kubectl get daemonsets -n exem-one exem-container-agent -o jsonpath="{..image}"

6. トラブルシューティング​

6-1. Container Registry の ImagePull が失敗する場合​

顧客の Container Registry へのアクセス権限がなく、イメージを取得できない場合です。

担当者にアクセス権限を依頼するか、アクセス可能な Secret のみを提供された場合は、以下の手順に従います。

1. Secret 名を確認します。

   kubectl get secret -n <NAMESPACE>
   

2. ダウンロードした YAML ファイルの Deployment と DaemonSet それぞれの spec.template.spec に、以下の内容を追加します。

   imagePullSecrets:
     - name: <SECRET_NAME>
   

   適用例:

   # Deployment (exem-k8s-agent)
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: exem-k8s-agent
     namespace: {{xm_conf.namespace}}
   spec:
     template:
       spec:
         imagePullSecrets:
           - name: <SECRET_NAME>
   
   # DaemonSet (exem-container-agent)
   apiVersion: apps/v1
   kind: DaemonSet
   metadata:
     name: exem-container-agent
     namespace: {{xm_conf.namespace}}
   spec:
     template:
       spec:
         imagePullSecrets:
           - name: <SECRET_NAME>
   

3. 修正した YAML で Agent をデプロイします。

6-2. Docker Container Registry の権限を K8s に適用する必要がある場合​

https://kubernetes.io/ko/docs/tasks/configure-pod-container/pull-image-private-registry/ 上記の Kubernetes 公式ドキュメントを参考に、secret を直接作成します。

すでに Docker が Registry にログインしている場合:

kubectl create secret -n <NAMESPACE> generic regcred \
    --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
    --type=kubernetes.io/dockerconfigjson

Container Registry の接続アカウントを提供された場合:

kubectl create secret docker-registry regcred \
    --docker-server=<your-registry-server> \
    --docker-username=<your-name> \
    --docker-password=<your-pword> \
    --docker-email=<your-email> \
    -n <NAMESPACE>

Secret 作成後は、上記の Container Registry の ImagePull が失敗する場合 の手順に従います。

6-3. Docker Registry に直接イメージを push する必要がある場合​

1. デプロイ済みのイメージ tar ファイルを、Docker コマンドが使用できるサーバーにアップロードします。

2. ローカルの Docker Registry にイメージをロードします。

   docker load -i <IMAGE_NAME>.tar
   

3. ロードされたイメージ名、タグ、Image ID を確認します。

   docker images
   

4. 確認した Image ID をもとに、Docker Registry への push パスを設定します。

   docker tag <IMAGE_ID> <Docker-registry URL>/<IMAGE_NAME>:<IMAGE_TAG>
   

5. タグが正しく設定されたか確認します。

   docker images
   

6. イメージを push します。

   docker push <Docker-registry URL>/<IMAGE_NAME>:<IMAGE_TAG>
   

7. push 完了後、Kubernetes に Agent をデプロイします。

6-4. OpenShift で exem-container-agent がデプロイされない場合​

SecurityContextConstraints（SCC）権限が serviceaccount にバインドされているか確認します。SCC 関連の作業は、通常は顧客担当者に依頼する必要があります。

直接 SCC を適用する必要がある場合:

1. 以下の内容で scc.yaml を作成します。

   apiVersion: security.openshift.io/v1
   kind: SecurityContextConstraints
   metadata:
     name: exem-one-hostpath-scc
   allowHostDirVolumePlugin: true
   runAsUser:
     type: RunAsAny
   seLinuxContext:
     type: RunAsAny
   fsGroup:
     type: RunAsAny
   volumes:
     - hostPath
     - configMap
     - projected
     - secret
   users:
     - system:serviceaccount:exemone:exemone
   

   SCC 権限の説明

   設定	値	用途
   allowHostDirVolumePlugin	true	container-agent が各ノードの cgroup、プロセス情報、ランタイムソケットを読み取り、コンテナの CPU/Memory/Network メトリックを収集します。この権限がないと、コンテナメトリックの収集ができません
   runAsUser	RunAsAny	cgroup ファイルとランタイムソケット（crio.sock など）が root 所有であるため、container-agent が root（uid 0）で実行されないと、コンテナ一覧の取得およびメトリック収集ができません。非 root で実行すると permission denied が発生します
   seLinuxContext	RunAsAny	OpenShift ノードは SELinux がデフォルトで有効になっており、一般的なコンテナはホストファイルへのアクセスがブロックされます。spc_t タイプを設定することで、マウントされたホストファイルシステムとランタイムソケットを読み取れるようになります
   fsGroup	RunAsAny	ホストからマウントされる cgroup、proc などのファイルのグループ所有権はさまざまであるため、特定のグループに強制するとファイルの読み取りに失敗する場合があります

   volumes 権限の説明

   volume タイプ	必須	用途
   hostPath	O	ホストファイルシステム（/）をマウントして cgroup、プロセス情報を読み取り、ランタイムソケット（crio.sock、containerd.sock、docker.sock）でコンテナの一覧と状態を取得します
   configMap	O	ConfigMap を envFrom で参照し、receiver アドレスやクラスター名などのエージェント設定を環境変数として注入します
   projected	O	ServiceAccount トークンを Pod に自動マウントし、K8s API Server の認証に使用します。Informer で Pod/Node などのリソースを取得する際に必要です
   secret	任意	顧客の Container Registry からイメージを取得する際に imagePullSecrets を使用する場合に必要です。パブリックレジストリまたは別の認証方式を使用する場合は不要です

2. SCC を適用します。

   oc apply -f scc.yaml
   

3. SCC の作成を確認します。

   kubectl get scc -n <NAMESPACE>
   

4. serviceaccount に SCC をバインドします。

   oc adm policy add-scc-to-user exem-one-hostpath-scc -z <SERVICEACCOUNT> -n <NAMESPACE>
   

5. SCC 権限の適用後、exem-container-agent DaemonSet YAML の spec.template.spec.containers に以下の securityContext を追加します。

   securityContext:
     runAsUser: 0
     seLinuxOptions:
       type: spc_t
     capabilities:
       drop: ["ALL"]
   

6. exem-container-agent を再デプロイします。

   kubectl delete -f exem-k8s-agent.yaml
   kubectl apply -f exem-k8s-agent.yaml