# /exec

`/exec` 스킬은 `kubectl exec`의 AI 기반 버전입니다. 대상을 자연어로 설명하면 에이전트가 올바른 메커니즘을 선택합니다: 실행 중인 컨테이너로의 일반 `exec`, 대상에 사용 가능한 셸이 없을 때 임시 디버그 컨테이너, 또는 노드의 권한 있는 셸.

세션은 사용자와 에이전트가 동시에 연결된 **tmux** 창 내에서 실행됩니다. 사용자가 입력하고, 에이전트가 입력하며, 출력은 실시간으로 표시됩니다.

```text
/exec                              # prompts for a target
/exec api                          # shell into the api pod (container auto-picked)
/exec api/sidecar                  # shell into a specific container
/exec node worker-3                # root shell on a node
/exec debug api                    # ephemeral debug container alongside api
```

자연어 범위 지정(네임스페이스, 레이블 셀렉터, 워크로드 이름)이 지원됩니다([개요](/ko/reference/skills/overview/) 참조).

:::note[사용자 호출만 가능]
`/exec`은 `disable-model-invocation: true`로 제공되므로 에이전트는 자체적으로 셸을 시작하지 않습니다 — 사용자가 명시적으로 `/exec`을 입력할 때만 실행됩니다. 아래의 권한 있는 모드를 고려한 의도적인 설계입니다.
:::

:::caution[보안]
`/exec`은 사용자와 에이전트 모두가 입력할 수 있는 대화형 셸을 엽니다. 노드 및 디버그 컨테이너 모드는 호스트 수준 접근(`hostPID`, `hostNetwork`, `/host`에 마운트된 호스트 파일 시스템)이 있는 권한 있는 파드를 생성합니다. 붙여넣은 시크릿, 환경 변수, 명령 출력 등 창에 표시되는 모든 내용은 에이전트가 읽고 모델에 전송될 수 있습니다. 전체 신뢰 모델은 [보안](/ko/concepts/security/)을 참조하십시오.
:::

---

## 요구 사항

`tmux`가 `$PATH`에 설치되어 있어야 합니다. 없으면 스킬이 실행되지 않습니다.

---

## 모드

에이전트는 설명에서 대상을 확인하고 다음 중 하나를 선택합니다.

### 1. 파드 컨테이너 (기본값)

사용 가능한 셸이 있는 실행 중인 파드의 기본값입니다. `kubectl exec -it <pod> -c <container> -- <shell>`과 동일하며, 파드에 컨테이너가 하나이거나 하나가 명확히 기본인 경우 자동 선택됩니다.

:::note[동작]
- 셸 자동 감지 (`bash`, `sh`, `ash` 순)
- `<pod>/<container>`로 지정하지 않는 한 컨테이너는 파드 사양에서 추론됨
- 사용 가능한 셸이 없으면 자동으로 디버그 컨테이너 모드로 대체
:::

### 2. 디버그 컨테이너

대상 컨테이너가 distroless, scratch, 또는 기타 셸이 없을 때 자동으로 트리거되거나 `/exec debug <pod>`로 명시적으로 지정합니다. `kubectl debug -it <pod> --target=<container> --image=<toolbox>`와 동일하며, 대상의 프로세스 네임스페이스를 공유하여 `/proc/<pid>/root`를 통해 파일 시스템을, 동일한 netns에서 네트워크를 검사할 수 있습니다.

:::note[동작]
- 대상 컨테이너와 프로세스 네임스페이스 공유
- 대상의 파일 시스템은 `/proc/1/root`에서 접근 가능
- 기본적으로 `nicolaka/netshoot` 사용 (`--image`로 교체 가능)
:::

### 3. 노드

호스트 수준 디버깅(kubelet 로그, `journalctl`, `crictl`, 네트워크 네임스페이스)을 위한 노드의 권한 있는 루트 셸. `hostPID`, `hostNetwork`, `/host`에 마운트된 호스트 파일 시스템을 가진 대상 노드에 스케줄된 단기 권한 있는 파드로 구현됩니다.

:::note[동작]
- 파드는 "default" 네임스페이스에 생성됨 (별도 지정이 없는 한)
- 사용자가 에이전트에게 지시할 때 파드 삭제
- 기본적으로 `nicolaka/netshoot` 사용
:::

---

## 세션이 열리는 방식

에이전트가 대상을 확인하고 기본 `exec` 또는 `debug` 명령을 시작한 후:

1. 설명적인 이름(예: `kstack-exec-api-server`)으로 분리된 tmux 세션을 시작합니다.
2. 데스크탑에서 새 터미널 창을 열고 해당 세션에 연결을 시도합니다 — 셸이 바로 앞에 나타납니다.
3. 채팅에 정확한 `tmux attach` 명령을 출력하여 어느 터미널에서도 수동으로 연결할 수 있습니다 (SSH, 원격 에디터, 또는 창 생성 실패 시 유용).

```text
Session ready.
  Target: pod/api-5f9c-bnt4m (container: server)
  tmux:   tmux attach -t kstack-exec-api-server
```

사용자와 에이전트는 같은 창을 공유합니다. 둘 다 명령을 입력할 수 있으며 전체 출력을 볼 수 있습니다. 토큰을 절약하기 위해 에이전트는 창에서 보수적으로 읽으므로 에이전트에게 최신 변경 사항을 따라잡도록 유도해야 할 수 있습니다. 에이전트에게 세션을 종료하도록 지시하면 생성된 파드를 종료합니다.

---

## 에이전트에게 전달되는 내용

세션을 시작하는 것 외에도 스킬은 에이전트에게 세션 내에서 어떻게 동작해야 하는지 안내합니다:

- 질문에 답할 수 있는 최소 권한 모드를 선택합니다 — 디버그 컨테이너보다 일반 exec를, 노드 셸보다 디버그 컨테이너를 우선합니다. 현재 모드에서 사용자가 요청하는 내용을 확인할 수 없을 때만 에스컬레이션합니다.
- 토큰 절약을 위해 tmux 창에서 보수적으로 읽습니다. 프롬프트 없이 큰 버퍼를 재읽는 대신 사용자가 뒤로 스크롤하도록 유도합니다.
- 창에 표시되는 모든 내용(환경 변수, 명령 출력, 붙여넣은 텍스트)을 잠재적으로 민감한 것으로 처리합니다 — 사용자가 요청하지 않는 한 채팅에 다시 표시하지 않습니다.
- 사용자가 완료 신호를 보내면 세션을 종료합니다: 셸 종료, tmux 세션 종료, 스킬이 생성한 파드(디버그 컨테이너, 노드 셸 파드) 삭제.

---

## 옵션

<dl>
  <dt>`--image <image>`</dt>
  <dd>노드 및 디버그 컨테이너 모드에 사용할 이미지 (기본값 <code>netshoot</code>).</dd>

  <dt>`--attach`</dt>
  <dd>새 세션을 시작하는 대신 기존 kstack tmux 세션에 에이전트를 연결합니다.</dd>

  <dt>`--detach`</dt>
  <dd>분리된 상태로 새 세션을 시작합니다 — 터미널 창이 열리지 않으며 수동으로 연결합니다.</dd>
</dl>

[개요](/ko/reference/skills/overview/)의 글로벌 플래그도 적용됩니다.