メインコンテンツまでスキップ

K8S Agentのインストール

1. 事前準備事項​

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

  • Agentイメージのアップロード — exem-k8s-agent、exem-container-agentイメージを、顧客環境のContainer Registryに事前にアップロードします。
  • Namespaceの作成 — インストールするNamespaceを直接作成します。
注記

インストールスクリプトがNamespaceを自動的に作成しない理由は、削除時にNamespaceに属するすべてのリソースが一緒に削除される危険があるためです。直接作成したNamespaceで動作するよう意図的に設計されています。

2. 対応環境​

項目内容
OSLinux
RuntimeDocker 18.06.2-ce以上
Containerd 1.4.9以上
CRI-O 1.20以上
PlatformKubernetes (Deployment)
Rancher
Cocktail Cloud
Accordion
PaaS-TA
Kakao Cloud
ProtocolgRPC 9009 → Receiver
K8s APIv1.13以上
4.16.3

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

exemONE Web UIでYAMLを生成・ダウンロードした後、クラスターに配備します。

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

clipboard

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

clipboard

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

clipboard

  1. 内容を確認し、必要な場合はYAMLファイルを修正します。

clipboard

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

clipboard

  1. 画面に表示されたコマンドでクラスターに配備します。

    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権限の説明

    設定値用途
    allowHostDirVolumePlugintruecontainer-agentが各ノードのcgroup、プロセス情報、ランタイムソケットを読み取り、コンテナのCPU/Memory/Networkメトリックを収集します。この権限がないと、コンテナメトリックの収集ができません
    runAsUserRunAsAnycgroupファイルとランタイムソケット(crio.sockなど)がroot所有のため、container-agentがroot(uid 0)で実行されないと、コンテナ一覧の照会およびメトリック収集ができません。非root実行時はpermission deniedが発生します
    seLinuxContextRunAsAnyOpenShiftノードはSELinuxがデフォルトで有効になっており、一般コンテナはホストファイルへのアクセスが遮断されます。spc_tタイプを設定することで、マウントされたホストファイルシステムとランタイムソケットを読み取れるようになります
    fsGroupRunAsAnyホストからマウントしたcgroup、procなどのファイルグループの所有権は多様であるため、特定のグループに強制すると、ファイル読み取りに失敗する可能性があります

    volumes権限の説明

    volumeタイプ必須用途
    hostPathOホストファイルシステム(/)をマウントしてcgroup、プロセス情報を読み取り、ランタイムソケット(crio.sock、containerd.sock、docker.sock)でコンテナの一覧と状態を照会します
    configMapOConfigMapをenvFromで参照し、receiverアドレス、クラスター名などのエージェント設定を環境変数として注入します
    projectedOServiceAccountトークンを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