본문으로 건너뛰기

설치하기

사전 준비 사항​

설치 전 아래 두 가지를 준비합니다.

  • Agent 이미지 업로드 — exem-k8s-agent, exem-container-agent 이미지를 고객사 환경의 Container Registry에 미리 업로드합니다.
  • Namespace 생성 — 설치할 Namespace를 직접 생성합니다.
노트

설치 스크립트가 Namespace를 자동으로 생성하지 않는 이유는, 삭제 시 Namespace에 속한 모든 리소스가 함께 삭제될 위험이 있기 때문입니다. 직접 생성한 Namespace에서 동작하도록 의도적으로 설계되어 있습니다.

화면으로 설치하기​

엑셈원 웹 UI에서 YAML을 생성·다운로드한 뒤 클러스터에 배포합니다.

  1. 좌측 하단 계정 메뉴에서 [설정]으로 이동합니다.

clipboard

  1. [플랫폼 > 쿠버네티스]를 클릭합니다.
  2. [Install Agent]를 클릭해 YAML 파일 내보내기 화면을 엽니다.

clipboard

  1. Agent 구성과 설정 항목을 확인합니다. 각 항목의 설명은 Description을 참고합니다.

clipboard

  1. 내용을 확인하고 필요한 경우 YAML 파일을 수정합니다.

clipboard

  1. [다운로드] 버튼을 클릭해 YAML 파일을 저장합니다.

clipboard

  1. 화면에 표시된 명령어로 클러스터에 배포합니다.

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

Helm으로 설치하기​

Helm Chart를 사용해 Agent를 설치할 수 있습니다. 설치 방법은 제품기술팀에 문의하세요.

배포 버전 확인하기​

클러스터에 배포된 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}"

문제 해결​

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를 배포합니다.

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 실패 시 절차를 따릅니다.

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를 배포합니다.

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