Kubernetes Enterprise 플러그인

Kubernetes 플러그인은 클러스터 하나를 Konduo 자원 하나로 등록하고 기본적으로 읽기 전용 운영 현황을 제공한다. 개요, 노드, 워크로드, 네트워크, 설정 참조, 스토리지, 가용성 정책, 경고 이벤트, 진단, 권한, 구성 관계 화면과 이에 대응하는 읽기 전용 MCP resource/tool이 포함된다. 통제된 리소스 변경은 명시적으로 활성화해야 하며 MCP에는 노출하지 않는다.

이 문서는 플러그인을 설치하는 개발자가 아니라 클러스터를 등록하고 관찰·진단·운영하는 관리자를 위한 안내서다. 처음 등록한다면 빠른 시작, 기존 연결의 문제를 조사한다면 권한 화면과 문제 해결 점검표, 변경 기능을 열어야 한다면 통제된 리소스 운영 부분부터 읽는다.

5분 빠른 시작

1. Konduo가 대상 클러스터 안에서 실행되면 in_cluster, 밖에서 실행되면 제한된 전용 kubeconfig를 준비한다.
2. 전체 클러스터를 관찰할 때는 deploy/rbac/cluster-observer.yaml, 특정 Namespace만 관찰할 때는 각 Namespace에 맞게 deploy/rbac/namespace-observer.yaml을 적용한다. 예제의 observed-namespace와 ServiceAccount subject는 실제 배포 환경에 맞게 바꾼다.
3. Konduo의 리소스 추가 화면에서 Kubernetes 플러그인을 선택한다. 연결 방식, 조회 범위, 읽기 전용 운영 모드를 설정하고 kubeconfig를 붙여 넣거나 in-cluster ServiceAccount를 선택한다.
4. 리소스를 저장한 뒤 연결 검사와 운영 > 권한을 확인한다. 필요한 화면의 권한만 허용이어야 하며, 사용하지 않는 기능의 권한까지 넓힐 필요는 없다.
5. 운영 > 개요에서 Node 준비 상태, 워크로드 상태, 문제 Pod와 경고 Event를 확인한다. 메트릭이 필요하면 Prometheus 호환 메트릭 타겟을 연결하고 external 또는 managed 모드를 선택한다.
6. 생성·편집·즉시 작업·삭제가 필요할 때만 operation_mode=controlled_write로 바꾸고, 필요한 Namespace와 리소스 종류에 해당하는 creator, updater, operator, deleter Role을 각각 추가한다.

연결 성공은 모든 화면의 근거를 읽을 수 있다는 뜻이 아니다. API discovery만 성공하고 일부 읽기 권한이 빠진 경우 연결은 정상이어도 화면에는 limited, partial 또는 unavailable이 표시될 수 있다. 이때 먼저 권한 화면을 확인한다.

연결 방식 선택

관찰할 클러스터 안에서 Konduo를 실행하는 경우

connection_mode=in_cluster를 권장한다. 가장 간단하고 안전한 방식이다. 플러그인은 Pod에 투영된 ServiceAccount 토큰과 CA, Kubernetes API 주소를 사용한다. Kubernetes가 투영 토큰을 교체하면 client-go가 이후 요청에서 토큰 파일을 다시 읽는다. deploy/rbac/의 namespace 또는 cluster observer 예제를 Konduo ServiceAccount에 적용한다.

클러스터 밖에서 Konduo를 실행하는 경우

connection_mode=kubeconfig를 선택하고 이 용도로 만든 kubeconfig를 붙여 넣는다. ~/.kube/config의 YAML을 활용할 수 있지만, 먼저 대상 cluster와 context, 최소 권한 identity만 남겨야 한다. 선택한 user에는 다음 중 하나만 포함한다.

• 내장 bearer token
• 내장 client-certificate-data와 client-key-data

사설 CA를 쓰는 클러스터는 certificate-authority-data도 내장한다. current-context와 다른 context를 선택할 때만 context_name을 입력한다.

관리형 클러스터 kubeconfig는 자격 증명을 갱신하려고 exec를 사용하는 경우가 많다. 이 플러그인은 로컬 프로그램을 실행하지 않으므로 해당 파일을 거부한다. 붙여 넣은 단기 토큰은 만료 후 연결할 수 없다. 가능하면 in-cluster 방식을 쓰고, 그렇지 않으면 교체 절차가 명확한 별도 관찰용 identity를 운영한다.

Bootstrap 엔드포인트와 자동 failover

kubeconfig 또는 in-cluster 설정의 API 서버는 고정 대상이 아니라 최초 연결을 위한 bootstrap seed다. 첫 연결이 성공하면 플러그인은 내장 default/kubernetes Service의 모든 EndpointSlice를 합쳐 식별한 API 서버를 수집하고 각 주소의 연결 상태를 확인한다. 모니터 화면의 엔드포인트 영역에는 처음 입력한 주소와 식별된 control-plane API 주소가 함께 표시된다. EndpointSlice가 비어 있고 노드 조회 권한이 있으면 control-plane 노드 주소를 제한적인 보조 목록으로 사용한다.

이 목록과 정상 상태는 Konduo 리소스 메타데이터에 저장된다. 이후 호출에서 bootstrap 주소가 응답하지 않으면 저장된 정상 주소를 순서대로 확인하고 연결 가능한 주소를 선택한다. 다른 클러스터로 잘못 연결되지 않도록 선택 전에 내장 default/kubernetes Service UID가 저장된 클러스터 ID와 같은지 검증한다. 조회, 진단, 관리형 메트릭과 통제된 운영 작업 모두 선택된 주소를 사용한다. 단, 쓰기 요청 실패 후 다른 서버로 동일 요청을 재전송하지는 않는다. 실제 작업을 보내기 전에 주소를 선택하므로 중복 실행 위험을 만들지 않는다.

선택 Namespace 관찰자는 namespace-observer.yaml에 포함된 default Namespace 전용 endpoint observer Role/RoleBinding도 적용해야 한다. 이 권한이 없어도 bootstrap 주소로는 연결할 수 있지만 전체 엔드포인트 표시, 동일 클러스터 검증과 자동 failover는 보장되지 않는다. 어떤 주소가 네트워크 또는 인증서 정책 때문에 Konduo에서 직접 접근할 수 없으면 해당 주소는 비정상 엔드포인트로 표시되고 failover 후보에서 제외된다.

설정 항목 참조

연결과 조회 범위

설정	기본값	설명
connection_mode	kubeconfig	kubeconfig 붙여넣기 또는 in_cluster ServiceAccount를 선택한다.
kubeconfig	없음	kubeconfig 모드에서만 표시되는 민감 필드다. 최대 256 KiB의 제한된 단일 연결 구성을 붙여 넣는다.
context_name	비어 있음	비워 두면 current-context를 사용한다. 다른 context를 명시할 때만 입력한다.
scope_mode	cluster	클러스터 전체 또는 selected_namespaces 범위를 선택한다.
namespaces	없음	선택 Namespace 모드의 필수값이다. 쉼표나 줄바꿈으로 구분한다.
operation_mode	read_only	controlled_write는 UI와 플러그인 작업 경로만 연다. Kubernetes RBAC는 별도로 부여해야 한다.
timeout_seconds	10	개별 Kubernetes API 요청 제한 시간이다. 1~30초를 허용한다.
allow_insecure_tls	false	인증서 검증을 끄는 실험 환경 전용 옵션이다. 운영에서는 사용하지 않는다.

메트릭

설정	기본값	설명
metrics_enabled	true	메트릭 기반 Monitor, 알림, 진단 및 수집 설정을 사용한다.
metric_collection_mode	external	기존 Prometheus 계열 시계열을 조회하거나 managed 수집을 사용한다.
metric_cluster_label_key	없음	외부 메트릭에 여러 클러스터가 섞였을 때 클러스터를 구분할 라벨 Key다.
metric_cluster_label_value	없음	위 라벨에서 이 Kubernetes 자원을 식별하는 값이다.
metric_collection_interval_seconds	60	관리형 수집 주기다. 30~3600초를 허용한다.
metric_collection_timeout_ms	10000	관리형 수집 한 번의 제한 시간이다. 1000~30000 ms를 허용한다.
collect_resource_metrics	true	Metrics API에서 Node, Pod, 컨테이너 CPU·메모리 사용량을 수집한다.
collect_supervisor_metrics	true	동일 인증으로 API 서버 /metrics의 허용된 K3s/RKE2 및 API 서버 메트릭을 수집한다.

메트릭 설정은 메트릭 타겟 연결을 대신하지 않는다. external은 조회할 타겟이, managed는 수집 결과를 쓸 Prometheus 호환 타겟이 리소스 메트릭 연결에 지정되어 있어야 한다.

보안 경계

kubeconfig는 256 KiB 이하이며 cluster/user/context 항목 수에도 상한이 있다. 외부 파일 참조, exec, auth-provider, basic auth, impersonation, proxy URL, extension, HTTP 서버는 거부한다. 안전하지 않은 TLS는 실험 환경 전용 설정을 명시한 때만 허용하며 운영 환경에서는 절대 사용하지 않는다.

플러그인은 Secret 내용을 요청하지 않는다. 관리자 전용 ConfigMap 조회는 크기 상한과 마스킹을 적용한 값만 반환한다. Pod 로그는 선택한 컨테이너의 제한된 구간만 읽는다. Pod 터미널 exec는 별도의 관리자 전용 보호 경로에서 실행 중인 컨테이너와 고정 /bin/sh만 연다. 두 기능 모두 MCP·진단·백그라운드 수집에는 노출하지 않는다. 범용 apply, 임의 exec 명령, 임의 Kubernetes API/patch, 임의 resource selector도 제공하지 않는다. 경고 이벤트는 개수와 길이를 제한하고 민감 정보 형태를 제거한 뒤 반환한다.

관찰 범위와 권한

• scope_mode=cluster: 읽을 수 있는 모든 namespace와 node를 관찰한다.
• scope_mode=selected_namespaces: namespaces에 쉼표나 줄바꿈으로 대상을 입력하며 namespace 자원 조회를 해당 목록으로 제한한다.
• operation_mode=read_only: 기본값이다. controlled_write는 보호된 화면과 action route만 활성화하며 Kubernetes 권한을 부여하지 않는다.
• timeout_seconds: 1~30초를 허용한다.

권한 화면은 SelfSubjectAccessReview로 실제 허용 범위를 설명한다. 일부 현황 조회 권한이 없어도 API 서버에 연결할 수 있다면 클러스터 장애로 표시하지 않고 limited 또는 partial 근거를 제공한다. SelfSubjectReview를 이용한 identity 표시는 클러스터 권한에 따라 생략될 수 있다.

observer RBAC 예제에는 wildcard resource/verb가 없으며 Secret, Pod 로그, exec, 변경 API 권한도 없다. ConfigMap과 ServiceAccount에는 명시적인 읽기 권한만 부여한다. namespace 관찰 예제는 관찰할 namespace마다 적용한다. 로그가 필요한 경우에만 cluster-log-reader.yaml 또는 Namespace별 namespace-log-reader.yaml을 추가한다. 선택형 cluster-operator.yaml, namespace-operator.yaml은 별도로 제공하며 통제 작업에 필요한 patch/create와 Pod 터미널의 정확한 pods/exec create 권한만 포함한다.

관리형 supervisor 메트릭에는 /metrics 비리소스 URL의 get 권한이 추가로 필요하다. cluster observer 예제에는 이 권한이 포함된다. namespace observer는 namespace 자원 조회를 Role에 유지하고 /metrics용 ClusterRole과 ClusterRoleBinding을 별도로 제공한다. Role로는 비리소스 URL 권한을 부여할 수 없기 때문이다. 권한 화면에서도 이 항목을 별도로 표시한다.

관리형 Metrics API 수집에는 metrics.k8s.io의 nodes, pods에 대한 get, list 권한도 필요하다. cluster observer 예제에는 둘 다 포함되며 namespace observer는 관찰 대상 namespace의 Pod 메트릭 권한만 부여한다.

리소스 인벤토리 탭을 사용하려면 갱신된 observer 예제의 명시적 읽기 권한이 추가로 필요하다. Namespace observer는 Service, EndpointSlice, Ingress, PVC, PDB, HPA, ConfigMap, ServiceAccount를 읽고 cluster observer는 여기에 PV와 StorageClass를 더한다. 예제는 Secret API 권한을 의도적으로 부여하지 않는다.

RBAC 예제 선택

목적	적용할 예제	주의 사항
전체 클러스터 읽기	cluster-observer.yaml	Node와 cluster 범위 리소스까지 읽는다.
선택 Namespace 읽기	namespace-observer.yaml	관찰할 Namespace마다 observed-namespace를 바꿔 적용한다.
전체 클러스터 Pod 로그	cluster-log-reader.yaml	민감할 수 있는 pods/log의 get만 별도로 부여한다.
선택 Namespace Pod 로그	namespace-log-reader.yaml	로그를 허용할 Namespace마다 따로 적용한다.
Pod 터미널	namespace-operator.yaml 또는 cluster-operator.yaml	대상 Namespace의 pods/exec create만 추가한다.
롤아웃 재시작·CronJob 즉시 실행	namespace-operator.yaml 또는 cluster-operator.yaml	patch와 제한된 Job create만 부여한다.
새 리소스 생성	namespace-*-creator.yaml	워크로드·네트워크·설정·스토리지·가용성 정책 중 필요한 종류만 선택한다.
기존 리소스 편집	namespace-*-updater.yaml	워크로드·네트워크·설정·가용성 정책별 update 권한을 분리한다.
리소스 삭제	namespace-*-deleter.yaml	삭제할 종류에만 delete를 부여한다. PVC는 별도 예제를 사용한다.

예제는 konduo Namespace의 konduo-kubernetes-observer ServiceAccount를 대상으로 한다. 다른 ServiceAccount나 kubeconfig identity를 사용한다면 RoleBinding/ClusterRoleBinding의 subject도 그 identity에 맞춰야 한다. controlled_write와 Konduo 역할이 설정되어 있어도 Kubernetes RBAC가 없으면 작업은 거부되며, 반대로 Kubernetes RBAC만 있어도 읽기 전용 모드에서는 변경 버튼이 나타나지 않는다.

화면별 사용 안내

리소스 왼쪽 메뉴는 모니터링, 진단, 운영으로 구분된다. 같은 상태를 세 화면에서 중복 표시하는 구조가 아니다.

• 모니터링은 시간에 따른 메트릭 추세와 알림·이상 징후 판단에 사용한다.
• 진단은 현재 API 근거와 저장된 메트릭을 규칙에 따라 해석하고 다음 조치를 제안한다.
• 운영은 Kubernetes API에서 읽은 현재 객체, 관계, 권한을 살펴보고 허용된 변경 작업을 실행한다.

운영 탭의 권장 확인 순서는 다음과 같다.

1. 개요: Node 준비 상태, 워크로드 건전성, 문제 Pod, 경고 Event를 먼저 본다.
2. 워크로드: Namespace·종류·상태·이름으로 좁히고 행을 선택해 조건, Replica, 컨테이너, 관련 Pod와 경고 Event를 확인한다.
3. Pod 로그: 워크로드의 Pod 행에서 로그 보기를 선택해 제한된 최근 로그를 확인한다. Konduo 관리자 권한과 별도 Kubernetes pods/log 권한이 모두 있어야 보이고 동작한다.
4. 네트워크, 설정, 스토리지, 가용성 정책: 객체 종류별 현재 구성을 조회한다. + 버튼과 행 작업은 통제 운영 모드와 대응 권한이 있을 때만 보인다.
5. 노드와 경고 이벤트: 배치 위치, pressure, 재시작, 스케줄링 실패의 직접 근거를 확인한다.
6. 구성 관계: 한 객체를 중심으로 상·하위 연결을 단계적으로 추적한다.
7. 권한: 비어 있거나 사용할 수 없는 화면이 있을 때 실제 Kubernetes 허용 범위를 확인한다.

Pod 로그 보기

워크로드 목록의 Pod 행에서 로그 보기를 누르면 문맥형 로그 화면이 열린다. Pod 상태는 간결한 요약으로 표시되고 첫 일반 컨테이너가 자동으로 선택된다. 다른 일반·초기화·임시 컨테이너는 하나의 선택상자에서 전환할 수 있다. 최근 15분·1시간·6시간·24시간 중 한 구간에서 마지막 50·100·200·500줄을 읽는다. 이전에 종료된 컨테이너 인스턴스의 로그와 대소문자를 구분하지 않는 결과 검색도 지원한다. 응답은 128 KiB, 한 줄은 16 KiB로 제한되며 실시간 follow, 다운로드 및 여러 Pod 집계는 지원하지 않는다. 대화형 접속은 권한 경계가 더 강한 별도의 Pod 행 작업으로 제공한다.

로그는 애플리케이션 비밀을 포함할 수 있으므로 일반 observer에 권한을 합치지 않았다. Konduo 관리자에게 kubernetes-plugin.pod-logs.read가 있어야 하고, Kubernetes identity에는 대상 Namespace의 pods/log get이 필요하다. 운영 > 권한에서 해당 subresource의 실제 허용 여부를 확인할 수 있다.

Pod 터미널 열기

워크로드 목록의 Pod 행에서 터미널 열기를 선택한다. 문맥형 화면은 Pod를 요약하고 첫 실행 중 일반 컨테이너를 자동 선택하며, 다른 일반·임시 컨테이너로 전환할 수 있다. 시작 쉘은 /bin/sh로 고정되며 별도 쉘 선택이나 임의 명령 문자열, Kubernetes API 경로, subresource는 입력할 수 없다. 다른 쉘이 이미지에 설치되어 있다면 접속한 뒤 전환한다. /bin/sh가 없는 이미지에는 터미널을 열 수 없으므로 Pod 로그를 사용하거나 쉘이 포함된 이미지를 사용한다.

operation_mode=controlled_write, Konduo 관리자 권한 kubernetes-plugin.pod-terminal.open, 대상 Namespace의 Kubernetes pods/exec create가 모두 필요하다. 스트림을 열기 직전에 Pod를 다시 조회하여 UID, 컨테이너 실행 상태, /bin/sh, SelfSubjectAccessReview를 재검증한다. 터미널 행 작업은 Pod가 Running이고 일반 컨테이너가 모두 Ready일 때만 사용할 수 있다. Pod가 교체됐다면 워크로드를 새로고침한 뒤 다시 연다.

세션은 공통 웹 터미널의 ticket·WebSocket 정책을 사용하므로 origin, 입력 크기, 유휴 제한, 최대 수명, 감사 이벤트가 동일하게 적용된다. API failover가 선택한 정상 엔드포인트를 사용하며 사용자 전용·공유 불가 세션이다. MCP·진단에는 노출하지 않고 세션이나 transcript를 저장하지 않으며 화면을 닫으면 Kubernetes exec도 종료한다.

각 목록의 상태 배지는 마지막 수집이 완전하고 최신인지 간단히 보여 준다. 배지를 선택하면 수집 시각, 캐시 여부, 누락 권한과 잘림 근거를 볼 수 있다. 정상 배지라고 해서 모든 리소스에 변경 권한이 있다는 뜻은 아니다.

리소스 인벤토리와 구성 관계

• 네트워크는 Service, EndpointSlice, Ingress의 타입이 고정된 요약을 읽는다. Selector와 포트 정책, endpoint 준비 상태는 제공하지만 endpoint 주소는 숨긴다. EndpointSlice가 없는 Service, Ready endpoint가 없는 Service, pending LoadBalancer, ExternalName 누락은 서로 다른 상태 코드로 구분한다.
• 설정은 ConfigMap과 ServiceAccount의 실제 구성, 그리고 ConfigMap, Secret, ServiceAccount, imagePullSecret 참조를 함께 제공한다. ConfigMap과 ServiceAccount 직접 조회에는 관리자 전용 kubernetes.resources.configuration_content.read 권한과 대응 Kubernetes RBAC가 필요하다. ConfigMap 텍스트 값은 크기 상한을 적용하고 자격증명으로 의심되는 Key와 본문 패턴을 마스킹한다. 바이너리 값은 Key와 크기만 표시하며 Secret 값과 ServiceAccount token 값은 요청하거나 반환하지 않는다. 상세 화면은 ConfigMap Key를 복사 가능한 문서로 표시하고 포트·Condition 같은 반복 객체는 카드로 구분한다. 단순 참조는 배지 목록으로 표시하며 값이 없는 선택 구역은 숨긴다.
• MCP와 구성 관계는 kubernetes.resources.sensitive_references.read로 보호된 별도 참조 전용 경로를 계속 사용한다. 이 경로는 허용된 Pod template 참조만 파생하며 ConfigMap/Secret API를 호출하지 않는다.
• 스토리지는 상한이 있는 PVC 요약과, cluster 범위에서 권한이 있을 때 PV와 StorageClass 요약을 제공한다. StorageClass parameters, CSI handle, 원본 node affinity는 숨긴다.
• 가용성 정책은 PDB 상태와 HPA 대상/Replica 범위를 허용된 condition 및 metric 종류 요약과 함께 제공한다.

네 route 모두 Namespace/종류/이름 필터와 설정된 관찰 범위를 검증하고, Namespace/종류/이름 순으로 결정적으로 정렬한다. 전체 응답 512 KiB 제한보다 낮은 300행·320 KiB 인벤토리 예산을 적용한다. partial, truncated, errors, pagination, 간단한 조회 상태 배지는 실제 빈 결과와 권한 부족, 후속 페이지 실패, 상한 도달을 구분한다. 결과는 30초 동안 캐시한다.

구성 관계는 Service→EndpointSlice/선택 Pod, EndpointSlice→Pod/Node, Ingress→Service, 워크로드→ConfigMap/ServiceAccount 참조, Pod→PVC, PVC→PV, PV→StorageClass, PDB→선택 Pod, HPA→scale 대상을 연결한다. 원본 인벤토리 객체나 manifest는 evidence에 넣지 않는다. 일반 구성 관계 route에는 민감 참조 권한이 없으므로 Secret과 imagePullSecret 이름은 의도적으로 제외한다.

구성 관계 그래프 사용

그래프는 전체 클러스터를 한 번에 축소해 보여 주지 않고 선택한 중심 오브젝트 주변만 표시한다. 기본은 1단계이며 필요할 때 2단계로 확장한다. 화면에 표시하는 오브젝트는 최대 13개로 제한되며, 더 많은 연결은 노드의 숨겨진 연결 수와 아래 들어오는 관계·나가는 관계 목록에서 확인한다.

• 오브젝트를 선택하거나 그래프 노드를 누르면 그 오브젝트가 새 중심이 된다.
• 뒤로는 이전 중심으로, 포커스 초기화는 처음 선택된 중심과 1단계로 돌아간다.
• 배치 초기화는 현재 중심과 표시 범위를 유지하면서 드래그로 흐트러진 배치를 단계별 자동 배치로 다시 정돈한다.
• 노드는 드래그할 수 있고 캔버스는 확대·축소와 이동을 지원한다.
• 노드를 우클릭하면 속성 보기로 해당 운영 탭의 상세 화면을 열 수 있다. 수정 지원 객체이고 통제 운영 권한이 있으면 리소스 편집도 표시된다.
• 아래 관계 목록의 포커스를 사용하면 그래프에서 겹친 노드를 찾지 않고 바로 인접 오브젝트로 이동할 수 있다.

그래프에서 오브젝트를 찾을 수 없다는 오류가 나면 먼저 구성 관계를 새로고침한다. 객체가 교체되어 UID가 바뀌었거나, 현재 필터·조회 범위·권한에서 객체를 다시 읽을 수 없으면 이전 그래프 노드로 상세 화면을 열지 않는다.

운영 상태 해석

• 정상 연결은 Kubernetes discovery 성공을 뜻한다. limited는 누락 화면이 꼭 필요할 때만 해당 읽기 권한을 추가하라는 의미다.
• 노드 대상 fingerprint는 불변 값인 metadata.uid를 사용하므로 교체된 노드를 기존 노드와 혼동하지 않는다.
• 워크로드와 구성 관계 응답에는 상한이 있다. truncated=true는 첫 버전의 수집 상한에 도달했다는 뜻이며 클러스터 데이터 손실을 의미하지 않는다. 한 요청은 Kubernetes 목록을 리소스별 최대 3페이지, 500개 객체, 4 MiB 안에서 읽고 플러그인 응답은 512 KiB로 제한한다. 다음 페이지에서 실패하면 앞서 읽은 항목을 버리지 않고 partial=true와 제한 근거를 함께 반환한다.
• 개요·Event·진단·구성 관계 스냅샷은 30초, 노드·워크로드는 60초, 권한은 5분 동안 재사용한다. 같은 스냅샷의 동시 요청은 Kubernetes API 호출 하나로 합친다. 응답의 snapshot.observed_at, age_seconds, stale, cache_hit으로 관찰 시각과 재사용 여부를 확인한다. 연결 설정이나 자격 증명이 바뀌면 별도 지문을 사용하므로 이전 캐시를 재사용하지 않는다.
• 개요의 전체 워크로드 수는 Pod뿐 아니라 지원하는 controller(Deployment, StatefulSet, DaemonSet, Job, CronJob)까지 포함한 자원 현황 행 수다. 0건을 완전한 근거로 해석하기 전에 partial과 truncated를 함께 확인해야 한다.
• 노드와 워크로드 행은 Konduo health_status(healthy, warning, critical, unknown)와 Kubernetes 원본 native_status를 분리한다. Namespace, 종류, 상태, 이름, 문제 항목 필터로 상한이 있는 현황을 좁힐 수 있다.
• 행을 선택하면 허용 목록으로 제한된 condition, replica 수, owner 식별자, 컨테이너 상태, 이미지, 관련 Event 조회 문맥을 상세 sheet에서 본다. 환경 변수, Secret/ConfigMap 내용, 자격 증명, taint value는 반환하지 않는다. 통제 운영 모드에서는 지원되는 controller 행에 보호된 작업도 표시한다.
• Namespace 필터는 인스턴스에 설정된 Namespace 범위를 벗어날 수 없다. partial, evidence_available, truncated는 실제 0건과 조회 불가 근거를 구분한다.
• 경고 Event는 상한이 적용된 현재 Kubernetes API 관찰 결과이며 영구 장애 이력이 아니다. 15분, 1시간, 6시간 조회 기간은 API가 아직 보존한 Event를 거를 뿐, 요청한 전체 구간의 데이터가 존재함을 보장하지 않는다.
• Event 요약은 사유, 대상 종류, Namespace별 발생 횟수를 제공한다. first_observed_at과 last_observed_at은 결정적인 Kubernetes timestamp fallback을 사용한다. truncated=true이면 필요한 경우 정확한 Namespace와 함께 pagination.next_cursor로 다음 페이지를 조회한다. Event가 없다는 사실을 과거 장애가 없었다는 근거로 해석하면 안 된다. Cursor는 Kubernetes가 만든 불투명한 연속 토큰이며 로그나 오류 메시지에 기록하면 안 된다. 플러그인은 Cursor 길이와 문자를 검증하고 Event 목록 요청에만 전달한다.
• 진단은 서버가 만든 고정 영문 문장이 아니라 안정적인 구조화 finding이다. 각 finding은 stable key, 심각도와 상태 코드, 현지화 메시지/조치 key, 상한이 적용된 구조화 근거, 영향 대상 식별자, 관련 Event ID, 명시적인 근거 가용성을 가진다.
• 초기 snapshot 상관관계는 비정상 노드와 배치 Pod, 비정상 controller와 selector가 일치하는 Pod, 해당 대상과 최근 경고 Event를 연결한다. FailedScheduling이 있는 Pending Pod, CrashLoop/이미지 pull 오류, OOM 근거, replica 부족, 실패 Job은 서로 다른 상태 코드를 사용한다. 로그, exec, 환경 변수, 오브젝트 secret은 읽지 않는다.
• 권한 매트릭스는 거부 또는 확인 불가 항목을 먼저 표시하고 영향 화면과 진단을 명시한다. RoleBinding 생성이나 권한 확대는 수행하지 않는다.
• 구성 관계 화면은 Node, Pod, controller, ReplicaSet 및 허용된 리소스 오브젝트를 UID 기반 시각 그래프로 제공한다. Namespace, 워크로드, 노드, 상태 필터로 수집 범위를 먼저 좁힌 뒤 중심 오브젝트의 1~2단계 관계를 탐색한다.
• 진단은 API 연결, Node Ready condition, Pod phase/restart, RBAC 범위를 근거로 판단하며 클러스터를 변경하지 않는다.

메트릭은 아래 별도 Monitor에서 제공하며 API snapshot 화면에는 포함하지 않는다. 진단 API snapshot은 Pod 로그 근거, exec, 범용 자동 조치를 사용하지 않는다. 제한된 직접 로그 조회는 운영 > 워크로드의 Pod 행 작업으로 별도로 제공한다.

통제된 리소스 운영

워크로드 변경이 명시적으로 필요한 자원이 아니면 operation_mode=read_only를 유지한다. 선택 Namespace 범위에서는 Konduo가 운영해도 되는 Namespace에만 namespace-operator.yaml을 적용한다. cluster operator 예제는 권한 범위가 더 넓으므로 클러스터 전체 운영이 필요한 경우에만 사용한다.

워크로드 목록의 행 작업은 역할을 명확히 나눈다.

• 연필 아이콘 리소스 편집: Deployment·StatefulSet의 Replica와 주 이미지, DaemonSet의 주 이미지, CronJob의 스케줄·일시 중지를 구조화 폼 또는 YAML로 바꾼다.
• 재생 아이콘 워크로드 즉시 작업: Deployment, StatefulSet, DaemonSet은 롤아웃 재시작을, CronJob은 현재 템플릿으로 Job 하나 생성을 실행한다. 종류별 작업이 하나뿐이므로 별도 작업 선택 상자는 표시하지 않는다.
• 휴지통 아이콘 리소스 삭제: 지원 controller를 영향 분석 후 삭제한다.

모든 작업은 현재 오브젝트를 다시 읽고 UID와 resourceVersion을 검증한다. 대상 Namespace, API group, resource, verb에 대한 SelfSubjectAccessReview도 통과해야 한다. 기본 제출은 Kubernetes server-side dry-run이며 실제 실행에는 화면에 표시된 확인값이 필요하고 Konduo RBAC도 그대로 적용된다. 현재 plugin action proxy는 운영자가 입력한 사유를 감사 저장소에 보존하지 않으므로 플러그인도 변경 사유를 입력받지 않는다. 롤아웃 성공 응답은 reconciliation 시작을 뜻하며 목록은 진행 상태가 submitted 또는 progressing인 동안 짧은 주기로 다시 조회한다. 최근 실행 ID와 검증·요청·진행·완료 상태는 새로고침된 행과 상세 화면에서 확인한다. Controller 상세의 관련 Pod는 긴 카드를 반복하지 않고 제한된 표로 표시한다. 자동 rollback은 수행하지 않는다.

Pod에는 범용 재시작 API가 없으므로 Pod 삭제를 재시작으로 제공하지 않는다. 소유 controller 작업을 사용해야 한다. 임의 YAML, GVR, URL, JSON patch, kubectl 명령도 입력받지 않는다.

구조화 리소스 생성

controlled_write에서는 개요와 각 리소스 페이지의 + 버튼으로 다음 생성 기능을 제공한다.

• 워크로드: Deployment, StatefulSet, DaemonSet, Job, CronJob
• 네트워크: Service, Ingress
• 설정: ConfigMap, ServiceAccount
• 스토리지: PersistentVolumeClaim
• 가용성 정책: PodDisruptionBudget, HorizontalPodAutoscaler

워크로드 폼은 이미지, 컨테이너 시작 command와 args, 포트, CPU/메모리 request·limit, 비밀정보가 아닌 환경 변수와 종류별 Replica, 업데이트 전략, Job 실행 및 CronJob 스케줄 필드를 제공한다. command와 args는 줄 단위의 제한된 문자열 목록으로 YAML 배열과 상호 변환된다. Ingress는 host/path/backend와 기존 TLS Secret 이름만 참조하며 Secret 값을 읽지 않는다. ServiceAccount의 API Token 자동 마운트는 기본적으로 끈다.

읽기 전용 모드에서는 만들기 동작을 표시하지 않는다. Namespace는 설정된 조회 범위에서 선택하며, 구조화 폼과 YAML 전문가 모드를 제공한다. YAML은 허용된 종류의 단일 문서만 strict typed decode하며 API group, GVR, URL 또는 JSON patch를 임의로 지정할 수 없다. 중복 Key, 여러 문서, alias/anchor, merge key, custom tag, 알 수 없는 필드, status와 고위험 Pod 설정은 거부한다. 실제 요청 직전에 정확한 Namespace, API group, resource, create verb로 SelfSubjectAccessReview를 수행한다. 기본 제출은 Kubernetes server-side dry-run이며 실제 생성은 dry-run을 끄고 CREATE 확인 문구를 입력해야 한다. 성공하면 관련 인벤토리 캐시를 비우고 현재 페이지를 다시 조회한다. 생성 창을 닫았다가 다시 열면 이전 입력값은 초기화되며, Namespace 선택 상자의 흐린 글자는 기본값이 아니라 안내 문구다. Namespace를 명시적으로 선택해야 한다. 같은 이름이 이미 있으면 기존 객체를 성공으로 간주하지 않고 명시적으로 실패한다.

deploy/rbac/namespace-*-creator.yaml 중 필요한 Role만 허용 Namespace에 적용한다. 예제는 wildcard를 사용하지 않으며 Secret, PV, StorageClass, Role, RoleBinding 생성 권한을 포함하지 않는다. ConfigMap 입력은 Key/값/전체 크기를 제한하고 자격증명으로 의심되는 Key와 인라인 값을 거부한다. Secret 생성과 값 조회는 지원하지 않는다. Secret, PV, StorageClass, Role, RoleBinding 생성과 복제는 지원하지 않는다.

통제된 구조화/YAML 리소스 수정

Deployment, StatefulSet, DaemonSet, CronJob, Service, Ingress, ConfigMap, ServiceAccount, PDB 및 HPA는 목록 행의 연필 아이콘 또는 구성 관계 노드의 리소스 편집으로 구조화 폼 또는 YAML 수정 창을 연다. 상세 sheet는 조회에 집중하며 별도의 중복 수정 경로를 제공하지 않는다. Job과 PVC는 초기 수정 범위에서 제외한다. 구조화 폼은 라이브 typed 객체를 복사한 뒤 자신이 소유한 필드만 바꾸므로 폼이 표현하지 않는 필드를 삭제하지 않는다. YAML은 라이브 객체를 정제한 canonical 초안으로 시작하며 Secret이나 기존 자격증명 값은 브라우저에 전달하지 않는다.

수정 직전에 객체를 다시 조회하여 UID와 resourceVersion을 고정하고 정확한 update SelfSubjectAccessReview 및 typed Update server-side dry-run을 수행한다. 식별자, immutable 필드, credential-like 값 또는 고위험 Pod spec 변경은 거부한다. 사전 검증은 변경을 적용하지 않고 API 서버 검증만 수행한다. 실제 반영에는 간단한 확인 문구 APPLY가 필요하며 동시 변경으로 resourceVersion이 달라지면 목록을 새로고침한 뒤 편집 창을 다시 열어야 한다. 성공하면 관련 목록 캐시를 비우고 reconciliation 중인 워크로드를 다시 조회한다. 결과에는 Manifest나 값 대신 변경 경로 수와 fingerprint만 기록한다. 필요한 Namespace에 deploy/rbac/namespace-*-updater.yaml 중 해당 Role만 적용하며 생성·수정 동작은 MCP에 노출하지 않는다.

통제된 구조화 리소스 삭제

삭제는 controlled_write에서 선택한 지원 리소스의 목록 행 작업에만 노출되며, 상세 sheet는 조회와 수정에 집중한다. Deployment, StatefulSet, DaemonSet, Job, CronJob, Service, Ingress, ConfigMap, ServiceAccount, PDB, HPA와 별도로 보호되는 PVC 삭제를 지원한다. 일괄 삭제, 임의 Manifest/GVR, 강제 삭제, finalizer 제거, Namespace/Node/RBAC 삭제 및 MCP 삭제 인터페이스는 제공하지 않는다.

플러그인은 대상을 typed client로 다시 조회하고 선택 시점 UID와 resourceVersion이 현재 값과 같은지 확인한다. 이어서 상한이 있는 직접 영향 분석, 정확한 Namespace/API group/resource/delete SelfSubjectAccessReview와 Kubernetes API server dry-run을 수행한다. 실제 실행은 server dry-run을 다시 통과해야 하며, 화면 옆에 계속 표시되는 대상의 리소스 이름만 확인란에 입력한다. 최종 삭제에는 UID/resourceVersion precondition과 Foreground 전파를 적용한다. NotFound 및 이미 종료 중인 대상은 성공으로 간주하지 않고 명시적으로 보고한다.

PVC는 phase, 요청 용량, StorageClass, 바인딩된 PV와 조회 가능한 reclaim policy를 추가로 표시하며, 조회 가능한 Pod가 마운트 중인 Claim은 삭제를 차단한다. 권한은 필요한 deploy/rbac/namespace-*-deleter.yaml만 Namespace별로 적용하고 observer, operator 또는 creator Role을 넓히지 않는다.

진단 실행과 문제 해결

리소스 사이드 메뉴는 모니터링, 진단, 운영을 분리한다. 운영 화면에는 API 스냅샷 개요, 자원 현황, 이벤트, 구성 관계 및 권한을 배치한다. 진단 finding과 명시적 진단 실행은 진단 화면에만 두며 운영 자원 현황 탭과 혼합하지 않는다.

진단 작업 공간은 요약, 노드, 스케줄링, 워크로드, 컨테이너, 용량, Control Plane, 이력, 상세 분석 탭으로 구분한다.

1. 진단 화면을 열면 요약 조회가 bounded Kubernetes API 근거를 최초 수집한다. 이후에는 요약 테이블 우측의 진단 새로고침으로 명시적으로 갱신한다.
2. 요약 테이블에서 분류별 상태, 진단 시각, 근거와 다음 조치를 확인한다. 스냅샷은 5분 후 오래된 근거가 되고 30분 동안 사용하지 않으면 만료된다. 갱신에 실패해도 마지막 성공 스냅샷은 유지된다.
3. 분류별 상세 탭에서 표준 finding, 영향 대상의 불변 UID, 정제된 Event ID, owner/배치 문맥, 근거 최신성, 다음 조치를 확인한다. 소스가 없으면 정상 0이 아니라 unavailable이다.
4. 이력은 위임된 논리 메트릭에만 사용한다. 조회 구간은 1시간, 6시간, 24시간, 7일, 14일, 30일로 제한하며 최소 5개 샘플과 50% coverage가 필요하다. transient, repeated, sustained는 가용 근거의 시간 패턴이지 근거 범위를 넘는 확정 판정이 아니다.

표준 스냅샷에서 특정 객체의 추가 근거가 필요할 때만 상세 분석을 사용한다. 허용 대상은 Node, Deployment, StatefulSet, DaemonSet, Job, CronJob, Pod다. auto는 객체에 맞는 기본 프로필을 선택하며 명시적 프로필은 node_impact, workload_convergence, pod_stability다. 작업 시작과 결과 조회 시 Namespace 범위를 다시 적용한다. UID를 입력하면 교체된 객체를 잘못 분석하지 않는다.

상세 분석 작업은 비동기 프로세스 로컬 임시 결과다. 최대 256개 작업과 64 MiB 결과, 프로세스 전체 동시 실행 4개, 리소스별 2개, 30초 강제 제한을 적용한다. 완료/부분 완료는 45분, 실패는 60분, 취소는 15분 보존하며 어떤 항목도 6시간 stale 상한을 넘지 않는다. 동일한 실행 중 또는 최근 작업은 중복 실행하지 않는다. 플러그인을 재시작하면 모두 사라진다. 연결 설정이나 자격 증명을 회전하면 이전 작업을 숨기고 다시 실행할 수 없게 한다. 이 작업은 Connected Diagnostics의 리소스 간 영구 보고서를 대체하지 않는다.

문제 해결 상태:

• partial: 대상 근거는 수집했지만 경고 Event 같은 선택 근거를 사용할 수 없다. warnings를 확인하며 전체 성공이나 전체 실패로 해석하지 않는다.
• failed: 연결, 현재 observer 권한, 대상 UID, Namespace 범위를 확인한 뒤 새 작업을 시작한다. 실패한 자격 증명 원문은 결과에 포함하지 않는다.
• cancelled: 운영자가 취소했거나 플러그인이 종료되었다.
• expired_or_inaccessible: TTL 만료, 플러그인 재시작, 권한 회수, 리소스 범위 불일치, 연결 지문 변경 중 하나다. 이 상태에서는 이전 작업 메타데이터를 노출하지 않는다.
• backpressure: 같은 리소스의 다른 작업이 끝날 때까지 기다린다. API client QPS를 높여도 고정된 분석 동시 실행 상한은 늘어나지 않는다.

상세 분석은 Pod 로그, 환경 변수, Secret/ConfigMap 내용을 읽지 않고 exec를 사용하지 않는다. 임의 GVR, URL, kubectl, PromQL, MCP 실행 인터페이스도 없다. Event 메시지는 문자열/바이트 상한을 적용하고 URL 자격 증명, bearer token, API key, JWT 형태 문자열을 제거한다.

메트릭과 Monitor

메트릭을 활성화한 뒤 두 수집 모드 중 하나를 선택한다. 두 모드 모두 generic metric linkage에서 수집 결과를 조회하거나 저장할 Prometheus 호환 메트릭 타겟을 선택해야 한다.

• external: 선택한 source에 이미 존재하는 메트릭을 조회한다. 단일 클러스터 source라면 추가 selector가 필요 없다. 여러 클러스터 메트릭이 섞여 있으면 discovery 결과를 확인하고 metric_cluster_label_key와 metric_cluster_label_value를 설정한다.
• managed: 기존 kubeconfig 또는 in-cluster ServiceAccount로 읽기 전용 Kubernetes API 객체를 조회하고, 상한이 있는 kube-state-metrics 호환 스냅샷을 생성해 선택한 메트릭 타겟에 쓴다. exporter, 별도 URL, 별도 자격 증명은 필요 없다. Core가 불변 konduo_resource_instance_id 격리 라벨을 기록하고 조회에 강제한다.

관리형 수집의 기본 주기는 60초이며 30~3600초, 제한 시간은 1~30초로 설정할 수 있다. Node condition, Pod phase·재시작·waiting reason, 지원 workload 가용성, Pod CPU·메모리 request/limit을 수집한다. collect_resource_metrics=true이면 동일한 kubeconfig 또는 ServiceAccount로 metrics.k8s.io를 조회해 Node 및 Pod/컨테이너 CPU·메모리 사용량도 수집한다. cluster 범위에서는 Node와 Pod를, 선택 namespace 범위에서는 해당 namespace의 Pod만 조회한다. Metrics Server가 설치되어 있어야 하며 observer에는 metrics.k8s.io의 nodes, pods에 대한 get, list 권한이 필요하다. 객체·샘플 상한을 적용하며 일부 조회 실패나 잘림은 정상 0이 아니라 부분 수집 실패로 기록한다.

collect_supervisor_metrics=true이면 같은 API 서버와 인증 transport를 사용해 HTTPS /metrics를 요청한다. K3s server는 --supervisor-metrics로 실행해야 하며, 일반적으로 supervisor/API 포트 6443에서 endpoint가 노출된다. 공식 문서에 정의된 K3s/RKE2 cluster-management metric family와 필수 API server metric family만 적재한다. API server 시계열은 mapping pack이 사용하는 code, verb, histogram bucket, request kind 차원으로 집계해 group/version/resource 고카디널리티가 커지지 않게 한다. redirect, 임의 endpoint, 무제한 응답은 거부한다. /metrics가 꺼져 있거나 권한이 없으면 API 상태 스냅샷은 유지하고 실행 결과를 부분 실패로 기록한다. K3s/RKE2 supervisor endpoint가 없는 클러스터에서는 이 옵션을 끈다.

관리형 모드는 kubelet endpoint를 proxy하지 않으며 Metrics API의 현재 사용량 gauge를 Konduo 메트릭 타겟에 주기적으로 저장한다. 이를 통해 Node CPU·메모리와 컨테이너 CPU·메모리 쿼리를 지원한다. cAdvisor 누적 counter와 의미가 다르므로 별도 konduo_kubernetes_*_usage_* 메트릭과 관리형 쿼리를 사용한다. throttling과 OOM은 외부 kubelet/cAdvisor 시계열이 필요하다. 루트 파일시스템 사용률은 node-exporter의 node_filesystem_* 시계열이 필요하며 kubelet/cAdvisor 메트릭으로 분류하지 않는다.

공통 metric_label_filters는 core가 관리하며 임의 PromQL을 입력받지 않는다.

Monitor는 Cluster Health, Nodes, Workloads, Capacity, 선택 Control Plane 및 선택 K3s/RKE2 Supervisor 행으로 나뉜다. Cluster Health는 관리형 수집 신선도, Ready Node 비율, 가용하지 않은 workload, Pending/Failed Pod를 구분한다. Nodes는 정규화된 CPU·메모리 사용률과 Memory/Disk/PID pressure를 제공한다. Workloads는 CPU·메모리, 재시작, throttling Top 10과 CrashLoopBackOff, OOM, 실패 Job 근거를 제공한다. Capacity는 CPU·메모리 request, limit 및 allocatable 대비 request 비율을 비교한다. Control Plane은 API 서버 오류율, P99 지연시간, 처리 중 요청을 제공하고 Supervisor는 해당 K3s/RKE2 family가 있을 때 최소 인증서 잔여 시간과 비정상 내장 로드밸런서 backend 수를 제공한다.

각 패널은 관리형 수집, kube-state-metrics, metrics.k8s.io, kubelet/cAdvisor, node-exporter, API 서버 또는 supervisor 메트릭 필요 여부를 선언한다. unavailable, invalid_config, multiple_cluster_label_values, requires_managed_collection, mapping_requires_metric_validation은 관찰값 0과 다르다. source 메트릭이 실제로 존재하고 label이 한 클러스터를 가리키는지 검증하기 전에는 빈 결과를 정상 0으로 해석하지 않는다.

메트릭과 anomaly rule은 EE overlay에만 있으며 CE에는 Kubernetes 전용 쿼리나 패널이 추가되지 않는다.

메트릭 이상 징후와 영향 상관관계

초기 Enterprise rule pack은 Node NotReady와 pressure, 워크로드 replica 부족, Pending Pod, 재시작 급증, CrashLoopBackOff, OOM, CPU throttling, 노드 파일시스템, Job 실패 및 선택적 API server 오류율·지연시간을 다룬다. 각 규칙은 logical metric, 임계값, 평가 window와 for 지속시간을 선언하므로 일시적 spike와 지속 장애를 구분한다. 규칙 override와 reset은 core가 소유하고 모든 변경에는 audit 기록이 필요하다.

메트릭이 없거나 오래되었거나 조회에 실패한 경우에는 정상 0 또는 anomaly로 평가하지 않고 evidence_unavailable로 분리한다. Warning Event는 보존이 짧은 보조 근거일 뿐 단독 트리거가 아니다. 영향 조회는 metric 대상에서 Node, Pod, ReplicaSet, 상위 Workload, 구조화 진단 및 Event ID를 읽기 전용으로 연결한다. 동일 루트 Kubernetes UID에서 파생된 symptom은 규칙과 무관한 SHA-256 fingerprint로 묶고, 영향 오브젝트와 그룹 수에는 각각 20개 상한을 적용한다. 자동 remediation, 임의 PromQL, 백그라운드 로그 수집 또는 scale/rollout/cordon/drain 작업은 수행하지 않는다.

문제 해결 점검표

증상 또는 상태	확인할 사항
연결 검사 실패	kubeconfig의 server, CA data, 선택 context, 토큰·인증서 만료를 확인한다. exec, 외부 파일 참조, HTTP 서버가 있으면 제한된 kubeconfig로 다시 만든다.
연결은 정상이지만 limited 또는 partial	운영 > 권한에서 거부된 get/list와 영향 화면을 확인하고 필요한 observer 규칙만 추가한다.
설정 화면이 비거나 ConfigMap 내용이 없음	Konduo 관리자 역할, kubernetes.resources.configuration_content.read, Kubernetes의 ConfigMap·ServiceAccount 읽기 권한을 모두 확인한다. Secret 값은 정상 동작에서도 표시되지 않는다.
Pod 로그가 열리지 않음	Konduo 관리자 역할과 kubernetes-plugin.pod-logs.read, 대상 Namespace의 pods/log get, Pod·컨테이너가 아직 존재하는지 확인한다. 이전 로그는 컨테이너 런타임에 남아 있을 때만 조회된다.
Pod 터미널이 열리지 않음	operation_mode=controlled_write, Konduo 관리자와 kubernetes-plugin.pod-terminal.open, 대상 Namespace의 pods/exec create, Running/Ready 상태와 이미지의 /bin/sh를 확인한다. Pod 교체나 엔드포인트 변경 뒤에는 워크로드를 새로고침한다.
진단이 unavailable	진단 화면에 처음 진입한 직후 수집이 끝날 때까지 기다리거나 새로고침한다. 계속되면 연결, Node·Pod·Event 읽기 권한과 화면의 수집 경고를 확인한다.
관리형 메트릭이 부분 실패	Metrics Server와 metrics.k8s.io 권한을 확인한다. K3s/RKE2 /metrics를 쓰지 않으면 collect_supervisor_metrics=false로 설정한다.
Node CPU·메모리가 없음	collect_resource_metrics=true, Metrics Server 설치, cluster 범위의 Node 및 Pod 또는 선택 Namespace의 Pod 메트릭 권한을 확인한다. /metrics만으로 Node 사용량을 만들지 않는다.
작업 버튼이 없음	operation_mode=controlled_write, Konduo action 권한, 해당 행의 지원 종류, creator/updater/operator/deleter Kubernetes RBAC를 확인한다. Pod, Job 수정처럼 의도적으로 지원하지 않는 조합도 있다.
K8S_OPERATION_TARGET_STALE 또는 수정 충돌	다른 작업으로 resourceVersion이 바뀌었다. 목록을 새로고침하고 행 작업을 다시 열어 현재 객체로 검증한다.
사전 검증은 성공하지만 실제 작업은 실패	dry-run 이후 객체 변경 여부, 확인 문구, 실제 verb 권한을 다시 확인한다. 실제 실행도 대상 재조회와 server dry-run을 반복한다.
삭제할 객체를 찾을 수 없음	다른 도구가 이미 삭제했거나 필터 목록이 캐시된 상태일 수 있다. 목록을 새로고침하고 객체 UID가 새로 만들어졌는지 확인한다.
성공 메시지 뒤 목록이 그대로임	작업 진행 상태 자동 조회가 끝날 때까지 기다린다. 상태 추적 대상이 아니거나 외부 변경이면 새로고침 버튼으로 캐시를 우회한다.
관계 그래프 속성을 열 수 없음	구성 관계를 새로고침하고 현재 Namespace·상태 필터와 읽기 권한을 확인한다. 그래프는 UID가 바뀐 객체를 이전 객체로 간주하지 않는다.

오류 메시지에 kubeconfig, 토큰, 인증서·Secret 원문을 붙이지 않는다. 지원 요청에는 플러그인 버전, Kubernetes 배포판과 버전, 연결 방식, 조회 범위, 오류 코드, 발생 시각, 권한 화면의 거부 항목만 제공한다.

호환성 검증

플러그인은 client-go v0.36.3을 고정하고 Kubernetes 1.34.x~1.36.x에 공통으로 존재하는 안정 API만 사용한다. 릴리스 CI에서는 평탄화한 observer kubeconfig로 TestKubernetesLiveReadOnlyContract를 1.36.x와 1.34.x 클러스터에 각각 실행해야 한다. 로컬에서 실제 클러스터 검사가 건너뛰어졌다면 해당 버전이 릴리스 인증을 통과했다는 뜻이 아니다.