opsgateApprovalWatchToolsConfigurationGitHub

도구 참조

English

Kubernetes, 노트 읽기 도구에는 ops:read가 필요합니다. 각 도구는 provider를 활성화했을 때만 등록됩니다. Kubernetes 네임스페이스는 설정에 따라 필터링하며, 네임스페이스 거부 목록이 우선합니다. Kubernetes 시크릿을 다루는 도구는 없습니다. 읽기 전용 메타데이터와 로그에도 민감한 정보가 드러날 수 있습니다.

도구 용도 주요 인자, 기본값, 제한
k8s_clusters 설정 순서대로 클러스터 이름, 컨텍스트, 보호 여부, 네임스페이스·로그·쓰기 정책과 연결 상태 없음; 클러스터마다 discovery 조회 제한 2초
k8s_overview 노드 상태와 허용된 네임스페이스의 워크로드/이벤트 cluster(아래 규칙 적용)
k8s_list 지원하는 리소스 목록 필수 kind; namespace=""(허용된 모든 네임스페이스); label_selector=""(필터 없음), Kubernetes 레이블 선택자 문법; limit=100, 1–500으로 보정
k8s_get 민감한 정보를 정리한 객체 YAML과 최근 1시간의 관련 이벤트 최대 50개 필수 kind, name; 네임스페이스 스코프 리소스는 namespace 필수, 클러스터 스코프 리소스는 생략
k8s_env 컨테이너가 실제로 받는 환경 변수와 마운트된 설정, 각 값의 출처 필수 namespace, name; kind="pod"(pod, deployment, statefulset, daemonset, replicaset, job, cronjob 및 별칭); container=""(일반·init 컨테이너 전체); ConfigMap 값은 show_configmap_data=true일 때만 표시; 마운트된 텍스트는 키당 8 KiB, 호출당 64 KiB로 제한
k8s_service_check 서비스 호스트 이름의 DNS 설정과 준비된 백엔드 점검(설정만 확인하며 DNS 질의·연결을 보내지 않고 NetworkPolicy는 평가하지 않음) 필수 namespace(조회하는 쪽 네임스페이스), host(소문자 DNS 이름, 최대 253바이트, IP 주소 불가); 선택 port(서비스 포트 번호 또는 이름), pod(DNS 설정을 가져올 같은 네임스페이스의 파드); 클러스터 도메인은 cluster.local로 가정하고, 도메인까지 적은 이름은 다른 도메인도 허용; 조회 후보, Service, 선택자에 맞는 파드(최대 500개), EndpointSlice를 확인; 다른 허용 네임스페이스의 같은 이름 Service를 최대 10개 제안
k8s_logs 파드 로그(하나 이상의 클러스터에서 allow_logs=true일 때 도구 등록) 필수 namespace, pod; 일반/init/ephemeral 컨테이너를 통틀어 정확히 하나일 때만 container 생략 가능; tail=200, 1–max_log_lines로 보정(기본 상한 500); since=""(시간 필터 없음), 양수 Go 기간 표기(최대 168h); previous=false; grep="", 문자열 그대로 대소문자 구분 없이 부분 검색; 스트림 상한 1 MiB
k8s_events 네임스페이스 이벤트 namespace=""(허용된 모든 네임스페이스); warnings_only=true; since="1h", 양수 Go 기간 표기(최대 168h); limit=50, 1–500으로 보정
action_link 조회 전용: 현재 Plan으로 카탈로그 조치를 검증하고 승인 URL·이름·요약 반환; 실행 없음 필수 tool, arguments 객체; 선택 source(기본 ai, 또는 rule); ops:read; 활성 카탈로그 조치와 클러스터별 action_approval_url이 있으면 등록
k8s_remediation_options 조회 전용: 이미지 받기 실패, 실패·정체된 배포, 반복 재시작/OOM, 멈추거나 연결할 수 없는 컨트롤러 소유 파드에 현재 상태 기반 카탈로그 선택지 제공. 고정 영어·한국어 이유와 source=rule 필수 namespace, name(파드); 사라진 파드는 선택 workload=kind/name 힌트. action_approval_url과 활성화·허용된 조치만 제공. 이미지 최대 5개와 재시작·삭제(총 7개). 없으면 빈 actions와 hint; 규칙.
k8s_rollout_restart 파드 템플릿을 갱신해 워크로드 재시작 필수 kind(deployment/statefulset/daemonset), namespace, name; rollout_restart 허용 설정 필요
k8s_scale 워크로드 복제본 수 설정 필수 kind(deployment/statefulset), namespace, name, replicas(0–max_replicas, 기본 상한 10); scale 허용 설정 필요; 결과에 이전 파드 수로 돌아가는 되돌리기 링크가 붙음(되돌리기)
k8s_delete_pod UID 사전 조건을 적용한 특정 파드 삭제 필수 namespace, name; delete_pod 허용 설정 필요; 링크는 컨트롤러 소유 파드만 허용, MCP는 소유자 없는 파드에 경고
k8s_restore_image 삭제 중이 아닌 소유 ReplicaSet의 준비된 파드에서 준비되어 실행 중인 컨테이너로 확인한 이미지로 Deployment 컨테이너 이미지 복원. 이미지만 바뀌고 설정은 되돌리지 않음 필수 namespace, name(Deployment), container, expected_image(현재 이미지와 정확히 일치), image(복원할 이미지와 정확히 일치); 선택 revert: true는 이 Deployment의 ReplicaSet 이력에 있는, 정상 동작이 확인되지 않은 이미지를 받음(되돌리기에 사용); restore_image 허용 설정 필요; 패치 직전 재확인; 승인 시간 창 없음; 결과에 되돌리기 링크가 붙음(되돌리기)
host_units 호스트 provider: 허용한 systemd 유닛의 상태 인자 없음. 호스트 provider 참고
host_unit_logs 호스트 provider: 유닛 하나의 마스킹한 저널 끝부분 필수 unit; lines=100, 최대 500
host_restart_unit 호스트 provider: systemd와 polkit을 거쳐 유닛 하나 재시작 필수 unit; systemd.units와 systemd.restart에 모두 맞아야 함; 카탈로그 조치, 되돌리기 없음
host_containers 호스트 provider: 허용한 Docker 컨테이너의 상태 인자 없음
host_container_logs 호스트 provider: 컨테이너 하나의 마스킹한 로그 끝부분 필수 container; lines=100, 최대 500
host_restart_container 호스트 provider: Docker 컨테이너 하나 재시작 필수 container; docker.containers와 docker.restart에 모두 맞아야 함; 실행 계획이 전체 컨테이너 ID를 고정; 카탈로그 조치, 되돌리기 없음
note_search 노트 내용/파일명에서 문자열 그대로 검색, 발췌문과 검색한 항목 수 제공 필수 query(1–4096 UTF-8 바이트); 선택 folder, tag, case_sensitive=false; limit=20, 최대 100
note_read 노트 텍스트와 파일/줄 메타데이터 필수 path, .md 생략 가능; offset_line=1, max_lines=400, 최대 2000
note_list 폴더를 먼저 표시한 뒤 .md/.canvas/.base 파일 표시 folder=""(볼트 루트), recursive=false, limit=200, 최대 1000; 잘림 여부 보고
note_recent 수정 시간순 노트 limit=20, 최대 100; days=7, 최대 365
note_links 노트에 포함된 위키 링크/임베드/상대 Markdown 링크와 이 노트를 가리키는 백링크 필수 path; 정확한 경로나 중복되지 않는 기본 파일명으로 대상 확인; 찾지 못한 대상 보고
note_tags frontmatter/인라인 태그 수 또는 일치하는 노트 선택 tag; 중첩 태그 포함; 코드 블록과 제목 무시
note_create 노트와 아직 없는 상위 폴더 생성 필수 path, content; allow_write=true, ops:write, 사람의 승인 필요
note_append 노트 끝이나 정확히 일치하는 제목이 하나뿐일 때 그 아래에 내용 추가 필수 path, content; 선택 heading(최대 1024바이트); 같은 쓰기 조건
note_replace 정확한 부분 문자열 치환 필수 path, 비어 있지 않은 old_text, new_text; 치환 횟수는 expected_count=1과 일치해야 함; 같은 쓰기 조건
note_trash 충돌 시 접미사를 붙여 로컬 .trash에 노트 보존 필수 path; 같은 쓰기 조건; 영구 삭제하지 않음

이미지 복원은 원본 파드의 컨트롤러 UID, 파드·컨테이너의 준비 및 실행 상태와 명세 이미지의 정확한 일치를 검사합니다. 상태 이미지 참조는 Docker Hub·기본 태그 표기를 정규화한 뒤 일치해야 하고, SHA-256/SHA-512 런타임 imageID가 필요하며 digest 고정 이미지는 그 값도 같아야 합니다. 실행 전에 다시 검사하고 namespace에 ReplicaSet이나 파드가 500개를 넘으면 안전하게 거부합니다. 준비 상태는 애플리케이션 정상 동작을 보장하지 않으며 레지스트리 태그는 바뀔 수 있습니다.

노트 검색, 태그 및 링크 도구는 마스킹된 텍스트를 대상으로 동작합니다.

노트 경로는 슬래시로 구분한 볼트 기준 상대 경로이며, Unicode 바이트를 그대로 유지합니다. 경로 길이는 최대 1024바이트이고, 제외된 경로는 없는 경로처럼 처리합니다. 노트 텍스트는 신뢰할 수 없는 데이터로 취급합니다. 노트 도구는 문서에 명시한 범위를 벗어난 숫자 입력을 거부합니다. 볼트 내부의 안전한 심볼릭 링크를 지원하되 순환 참조를 방지합니다. 검색 범위는 항목 100000개와 디렉터리 깊이 128단계로 제한하며, 링크와 백링크는 각각 최대 1000개를 반환합니다.

쓰기 미리보기에는 unified diff(생성 시 /dev/null과 비교), 현재 해시, 결과 해시가 들어갑니다. 약 8 KiB에서 출력을 자르고 잘렸음을 표시합니다. 실행(Apply) 단계에서는 승인 당시의 해시, 크기, 수정 시간을 다시 검사합니다. 새 노트는 원자적으로 생성하며, 동시에 다른 작업이 생성한 파일을 덮어쓰지 않습니다. 노트를 갱신할 때는 임시 파일을 동기화한 뒤 rename으로 교체합니다.

Linux에서는 원본을 승인된 .trash 경로로 원자적으로 이동한 뒤 노트를 검증하며, 기존 항목을 덮어쓰지 않습니다. 이동 도중 다른 작업이 노트를 교체하거나 편집하면 .trash 내 복구 경로와 함께 오류를 반환합니다. 필요하면 그 파일을 복원하세요. 계획(Plan) 후 대상 경로에 다른 항목이 생기면 이동이 실패하고 원본은 그대로 남습니다. 원본과 .trash는 RENAME_NOREPLACE를 사용하는 renameat2를 지원하는 같은 파일시스템에 있어야 하며, 이 조건을 충족하지 않으면 원본을 유지한 채 이동이 실패합니다.

다른 플랫폼에서는 승인된 내용의 복사본을 디스크에 안전하게 저장한 뒤 원본을 검사하고 제거합니다. 마지막 검사와 제거 사이에 외부에서 원본을 교체하면 교체한 내용이 유실될 수 있으므로, 이런 플랫폼에서는 버전별 백업이나 동기화 이력을 사용하세요.

기존의 마지막 줄바꿈 정책은 유지합니다. 내용이나 치환에 쓰는 각 입력의 상한은 256 KiB입니다. create, append, replace 도구는 이스케이프를 포함한 원시 JSON 인자를 528 KiB까지 허용하고, trash는 기본 16 KiB 제한을 유지합니다.

노트를 갱신할 때는 현재 상태가 바뀌지 않았는지 확인한 뒤 rename으로 교체합니다. 검사와 rename 사이에 외부에서 편집한 내용은 덮어쓸 수 있으므로, 버전별 백업이나 동기화 이력을 사용하세요. 새 노트의 미리보기도 크면 자르고 생략한 줄 수를 표시합니다.

Kubernetes 읽기 도구의 숫자 입력에 0을 지정하면 기본값을 사용하고, 그 외에 범위를 벗어난 값은 범위 안으로 보정합니다. 쓰기 작업의 복제본 수는 보정 없이 검증합니다. 반환하는 모든 텍스트에는 server.max_output_bytes(기본값 65536)가 적용됩니다. 호출의 제한 시간(server.tool_timeout, 기본값 30s)은 도구가 취소 신호를 따를 때 적용됩니다.

Kubernetes 네임스페이스 입력은 DNS-1123 레이블이어야 합니다. 객체의 name, pod, container 입력은 DNS-1123 하위 도메인으로 검증합니다.

k8s_list와 k8s_get이 지원하는 kind 값은 대소문자를 구분하지 않습니다. 괄호 안은 별칭입니다: pods (po, pod), deployments (deploy, deployment), statefulsets (sts, statefulset), daemonsets (ds, daemonset), replicasets (rs, replicaset), jobs (job), cronjobs (cronjob), services (svc, service), ingresses (ing, ingress), configmaps (cm, configmap), persistentvolumeclaims (pvc, persistentvolumeclaim), persistentvolumes (pv, persistentvolume), nodes (no, node), namespaces (ns, namespace).

Nodes, PersistentVolumes, Namespaces는 클러스터 스코프 리소스이므로 namespace를 생략하세요. 네임스페이스 허용 목록과 거부 목록은 Namespace 객체를 이름으로 필터링하지만, Nodes와 PersistentVolumes는 제한하지 않습니다. k8s_overview에 표시하는 노드도 이 제한을 받지 않습니다. 네임스페이스 스코프 리소스와 이벤트는 네임스페이스에 따라 필터링하며, 허용 목록이 비어 있으면 아무것도 허용하지 않습니다. 클러스터 스코프 접근은 RBAC으로 제한하세요.

읽기 전용 RBAC을 바탕으로 설정하고, 배포 전에 실제로 허용하는 권한을 검토하세요. 이 매니페스트는 기존 opsgate 네임스페이스에 ServiceAccount를 만들고, ClusterRole과 ClusterRoleBinding을 생성합니다. 시크릿을 제외한 지원 리소스, 이벤트, 파드 로그와 discovery.k8s.io의 EndpointSlice에 클러스터 전체 get/list/watch 권한을 부여합니다. 접근 범위를 좁히려면 네임스페이스 RoleBinding을 사용하세요.

kubeconfig의 exec 및 auth-provider 자격 증명 플러그인은 허용하지 않습니다. 수명이 짧은 ServiceAccount 토큰처럼 플러그인이 필요 없는 자격 증명을 사용하세요. kubeconfig의 소유권과 접근 권한도 안전하게 관리하세요.

k8s_clusters를 제외한 모든 Kubernetes 도구는 cluster 인자를 받습니다. 클러스터가 여러 개이면 필수이며, 하나이면 생략할 수 있습니다. 지정한 이름이 없거나 필수 인자를 생략하면 설정된 이름 목록과 함께 호출을 거부합니다. k8s_overview도 한 클러스터만 조회합니다. 먼저 k8s_clusters로 대상을 확인하고, 쓰기 전에 사용자에게 클러스터 이름을 명시합니다. 이전 출력의 클러스터를 다음 호출의 대상으로 추정하지 않습니다.

각 Kubernetes 도구의 출력은 cluster: <name> 줄로 시작합니다. k8s_clusters는 클러스터마다 이 줄을 표시하며 kubeconfig 경로, 서버 URL, 자격 증명은 출력하지 않습니다. 연결 실패 시 민감한 연결 정보가 드러나지 않도록 진단 메시지를 제한합니다. 한 클러스터의 실패는 나머지 결과에 영향을 주지 않습니다. 로그·쓰기 도구는 하나 이상의 클러스터에서 허용하면 등록하고, 선택한 클러스터에서 꺼져 있으면 호출을 거부합니다. 네임스페이스 규칙, ConfigMap 값 공개 여부, 로그 제한, 쓰기 허용 목록, 최대 복제본 수는 모두 선택한 클러스터의 설정을 따릅니다. 보호된 클러스터는 쓰기마다 사람의 승인을 새로 받아야 합니다.

마스킹과 객체 정리

k8s_logs의 grep은 마스킹된 텍스트를 검색합니다.

공유 internal/redact 계층은 PEM 개인 키, Authorization/Proxy-Authorization 헤더, Basic/Bearer 자격 증명, JWT 형태의 토큰, URL 비밀번호를 마스킹합니다. AWS 액세스 키 ID, GitHub, GitLab, Slack, Stripe live 키, OpenAI/Anthropic 형식 키, Google API 키, Telegram 봇, opsgate의 og_at_, og_rt_, og_st_ 토큰(접두사 뒤 base64url 문자 43개)의 알려진 패턴도 마스킹합니다.

:/=로 값을 지정하거나 구조화된 인자로 값을 전달할 때는 password/passwd/pwd, secret/client_secret, token/access_token/refresh_token, api_key/apikey/access_key/secret_key/private_key, credential/credentials, auth_token, session_id, cookie, set-cookie, invite를 민감한 키로 취급합니다. db_password처럼 밑줄로 연결한 접두사가 붙은 키도 포함하며, 대소문자는 구분하지 않습니다. 구조화된 인자 맵과 슬라이스는 재귀적으로 순회해 검사합니다. 성공 응답의 텍스트, 오류, 감사 로그 인자를 마스킹하지만, 모든 비밀값을 가린다고 보장하지는 않습니다. 알려지지 않은 형식이나 임의의 데이터 속에 들어 있는 비밀값은 마스킹을 놓칠 수 있습니다.

k8s_get은 템플릿을 포함한 메타데이터에서 managedFields와 kubectl.kubernetes.io/last-applied-configuration도 제거합니다. ConfigMap의 data와 binaryData는 키를 유지하되, show_configmap_data=true가 아니면 값 대신 바이트 수를 표시합니다. 환경 변수 이름에 pass, secret, token, key, credential, auth, dsn, private, cert, database_url이 포함되면 리터럴 value 필드를 [REDACTED]로 바꾸며, 대소문자는 구분하지 않습니다. 파드와 지원하는 워크로드 템플릿(CronJobs 포함)의 일반/init/ephemeral 컨테이너에 이 규칙을 적용합니다. 다른 리터럴 값은 공통 마스킹 규칙에 일치하지 않으면 그대로 보입니다. valueFrom 참조도 그대로 보여 주며, 참조하는 값을 조회하지는 않습니다.

k8s_env는 같은 네임스페이스의 ConfigMap을 호출당 한 번씩 조회하고, 환경 변수 덮어쓰기 순서와 $(VAR) 치환 결과를 표시합니다. 치환한 값을 다시 치환하지 않으며, 마운트에 지정한 항목과 subPath 파일만 보여 줍니다. 민감한 환경 변수·키 이름에 해당하는 값과 Secret 값은 숨깁니다. Secret API를 호출하지 않으므로 Secret envFrom의 키 목록은 알 수 없으며, 기존 변수와 이름이 겹칠 가능성을 표시합니다. 파드의 downward 필드는 실제 값으로 표시하지만, 워크로드의 필드와 리소스 참조는 자리표시자로 남깁니다. 바이너리 파일은 크기만 표시하고 subPathExpr는 해석하지 않습니다. 이미지에 포함된 파일은 확인할 수 없습니다.

k8s_env는 k8s_get의 민감한 키 규칙에 해당하는 downward API 레이블·어노테이션 값을 조회하거나 치환하기 전에 마스킹하고, k8s_list는 같은 규칙에 해당하는 키를 사용하는 레이블 선택자를 거부합니다.

공통 제한

웹 승인을 하면 원래 호출을 한 번 실행합니다. 쓰기 도구는 저장된 결과를 조회하는 선택 인자 approval_id를 받으며, 첫 호출에서는 생략하세요. 같은 인자로 재호출해도 다시 실행하지 않습니다. approval.wait는 웹 승인 사용 시 기본 25s(최대 55s, 0이면 대기 안 함)이며 대기 중에는 결과를 바로 반환합니다.

웹 승인이 켜져 있으면 읽기 전용 approval_status(ops:read)를 제공합니다. 필수 인자 approval_id로 요청자 본인의 tool, target, status(pending, running, applied, not_applied, rejected)와 결과가 있으면 result를 조회합니다. 다른 사용자와 알 수 없거나 만료된 ID에는 같은 응답을 반환합니다. 도구 정책, 감사 로그, 출력 제한을 적용합니다. 결과는 원래 만료 시각까지, 실행 후 최소 10분까지 메모리에 보관합니다.

읽기 도구는 원시 JSON 인자를 최대 16 KiB까지 받습니다. 쓰기 인자의 기본 상한도 16 KiB이지만, note_create, note_append, note_replace는 528 KiB까지 허용합니다. JSON 이스케이프도 이 크기에 포함됩니다. 승인 요약의 상한은 max(64 KiB, argument limit + 16 KiB)로, 기본 도구는 64 KiB, 노트 내용을 다루는 도구는 544 KiB입니다. 화면에 표시할 마스킹한 인자도 각 도구의 인자 제한을 넘을 수 없습니다. 노트 미리보기에는 별도로 약 8 KiB의 표시 제한이 있습니다.

공유 래퍼는 4 MiB를 초과하는 provider 출력을 통째로 생략합니다. 그 이하는 텍스트를 마스킹한 뒤 server.max_output_bytes(기본값 64 KiB)에 맞춰 자르며, 오류도 같은 방식으로 처리합니다. provider별 수집 제한이 더 작으면 그 제한도 적용됩니다. 제한 시간은 도구가 취소 신호를 따를 때 적용됩니다. 쓰기 작업은 계획(Plan)과 실행(Apply)에 각각 별도의 server.tool_timeout(기본값 30s)을 적용하며, 사람이 승인할 때까지 기다리는 시간은 제외합니다.

action_link는 재시작, 이미지 복구, 규모 조정, 컨트롤러 소유 파드 삭제만 지원합니다. ops:write 없이 서버 등록 상태, 호출자 도구 정책, 카탈로그 인자와 타입, 현재 대상 허용 목록을 검사합니다. 추가 인자(arguments 안의 source, approval_id 포함)와 마스킹된 값은 거부합니다. 링크는 /approve/action/{tool} 형식이며, 승인하려면 브라우저 사용자의 쓰기 스코프와 새 검토가 필요합니다. 승인 문서를 참고하세요.

복구 도구는 actions, label, url, container, current_image, image를 유지하고 tool, label_ko, reason, reason_ko, hint, pod_gone을 추가합니다. source는 이제 일관되게 rule이며, 이전 ReplicaSet 이름은 source_replicaset에 담습니다. 규칙 선택은 쓰기를 수행하지 않습니다. 후보 검증과 워크로드 조회는 namespace당 500개 초과 또는 부분 목록이면 거부합니다. 승인 브라우저는 쓰기 스코프·사용자 도구 정책·허용 목록을 독립적으로 확인하고 계획 → 사람 승인 → 재계획 → 적용 → 감사를 따릅니다.