---
title: 플러그인으로 kubectl 확장
# reviewers:
# - juanvallejo
# - soltysh
description: kubectl 플러그인을 작성하고 설치해서 kubectl을 확장한다.
content_type: task
---

<!-- overview -->

이 가이드는 [kubectl](/ko/docs/reference/kubectl/kubectl/) 확장을 설치하고 작성하는 방법을 보여준다. 핵심 `kubectl` 명령을 쿠버네티스 클러스터와 상호 작용하기 위한 필수 구성 요소로 생각함으로써, 클러스터 관리자는
플러그인을 이러한 구성 요소를 활용하여 보다 복잡한 동작을 만드는 수단으로 생각할 수 있다. 플러그인은 새로운 하위 명령으로 `kubectl` 을 확장하고, 주요 배포판에 포함되지 않은 `kubectl` 의 새로운 사용자 정의 기능을 허용한다.



## {{% heading "prerequisites" %}}


동작하는 `kubectl` 바이너리가 설치되어 있어야 한다.



<!-- steps -->

## kubectl 플러그인 설치

플러그인은 이름이 `kubectl-` 로 시작되는 독립형 실행 파일이다. 플러그인을 설치하려면, 실행 파일을 `PATH` 에 지정된 디렉터리로 옮기면 된다.

[Krew](https://krew.dev/)를 사용하여 오픈소스에서 사용 가능한
kubectl 플러그인을 검색하고 설치할 수도 있다. Krew는 쿠버네티스 SIG CLI 커뮤니티에서 관리하는
플러그인 관리자이다.

{{< caution >}}
Krew [플러그인 인덱스](https://krew.sigs.k8s.io/plugins/)를 통해 사용할 수 있는 kubectl 플러그인은
보안 감사를 받지 않는다. 써드파티 플러그인은 시스템에서 실행되는 임의의
프로그램이므로, 사용자는 이를 인지한 상태에서 설치하고 실행해야 한다.
{{< /caution >}}

### 플러그인 디스커버리

`kubectl` 은 유효한 플러그인 실행 파일을 `PATH` 에서 검색하는 `kubectl plugin list` 명령을 제공한다.
이 명령을 실행하면 `PATH` 에 있는 모든 파일을 탐색한다. 실행 가능하고, `kubectl-` 로 시작하는 모든 파일은 이 명령의 출력 결과에 *`PATH` 에 있는 순서대로* 표시된다.
실행 파일이 *아닌* 파일이 `kubectl-` 시작하는 경우 경고가 포함된다.
서로의 이름과 겹치는 유효한 플러그인 파일에 대한 경고도 포함된다.

[Krew](https://krew.dev/)를 사용하여 커뮤니티가 관리하는
[플러그인 인덱스](https://krew.sigs.k8s.io/plugins/)에서 `kubectl`
플러그인을 검색하고 설치할 수 있다.

#### 제한 사항

현재 기존 `kubectl` 명령을 덮어 쓰는 플러그인을 생성할 수 없다. 예를 들어, 플러그인 `kubectl-version` 을 만들면 기존의 `kubectl version` 명령이 항상 우선하므로, 플러그인이 실행되지 않는다. 이 제한으로 인해, 플러그인을 사용하여 기존 `kubectl` 명령에 새로운 하위 명령을 추가할 수도 *없다*. 예를 들어, 플러그인 이름을 `kubectl-create-foo` 로 지정하여 `kubectl create foo` 하위 명령을 추가하면 해당 플러그인이 무시된다.

`kubectl plugin list` 는 이를 시도하는 유효한 플러그인에 대한 경고를 표시한다.

## kubectl 플러그인 작성

커맨드-라인 명령을 작성할 수 있는 프로그래밍 언어나 스크립트로 플러그인을 작성할 수 있다.

플러그인 설치 또는 사전 로딩이 필요하지 않다. 플러그인 실행 파일은
`kubectl` 바이너리에서 상속된 환경을 받는다.
플러그인은 이름을 기반으로 구현할 명령 경로를 결정한다.
예를 들어, `kubectl-foo` 라는 플러그인은 `kubectl foo` 명령을 제공한다.
`PATH` 어딘가에 플러그인 실행 파일을 설치해야 한다.

### 플러그인 예제

```bash
#!/bin/bash

# 선택적 인수 처리
if [[ "$1" == "version" ]]
then
    echo "1.0.0"
    exit 0
fi

# 선택적 인수 처리
if [[ "$1" == "config" ]]
then
    echo "$KUBECONFIG"
    exit 0
fi

echo "I am a plugin named kubectl-foo"
```

### 플러그인 사용

플러그인을 사용하려면, 실행 가능하게 만든다.

```shell
sudo chmod +x ./kubectl-foo
```

그리고 `PATH` 의 어느 곳에나 옮겨 놓는다.

```shell
sudo mv ./kubectl-foo /usr/local/bin
```

이제 플러그인을 `kubectl` 명령으로 호출할 수 있다.

```shell
kubectl foo
```

```
I am a plugin named kubectl-foo
```

모든 인수와 플래그는 그대로 실행 파일로 전달된다.

```shell
kubectl foo version
```
```
1.0.0
```

모든 환경 변수도 실행 파일로 그대로 전달된다.

```bash
export KUBECONFIG=~/.kube/config
kubectl foo config

```
```
/home/<user>/.kube/config
```

```shell
KUBECONFIG=/etc/kube/config kubectl foo config
```

```
/etc/kube/config
```

또한, 플러그인으로 전달되는 첫 번째 인수는 항상 호출된 위치의 전체 경로이다(위의 예에서 `$0` 은 `/usr/local/bin/kubectl-foo` 와 동일하다).

### 플러그인 이름 지정

위 예제에서 볼 수 있듯이, 플러그인은 파일명을 기반으로 구현할 명령 경로를 결정한다. 플러그인이 대상으로 하는 명령 경로의 모든 하위 명령은 대시(`-`)로 구분된다.
예를 들어, 사용자가 `kubectl foo bar baz` 명령을 호출할 때마다 호출되는 플러그인은 파일명이 `kubectl-foo-bar-baz` 이다.

#### 플래그와 인수 처리

{{< note >}}
플러그인 메커니즘은 플러그인 프로세스에 대한 사용자 정의, 플러그인 특정 값 또는 환경 변수를 생성하지 *않는다*.

이전 kubectl 플러그인 메커니즘은 `KUBECTL_PLUGINS_CURRENT_NAMESPACE` 와 같이 더이상 사용하지 않는 환경 변수를 제공했다.
{{< /note >}}

kubectl 플러그인은 전달된 모든 인수를 파싱하고 유효성을 검사해야 한다.
플러그인 작성자를 대상으로 하는 Go 라이브러리에 대한 자세한 내용은 [커맨드 라인 런타임 패키지 사용](#커맨드-라인-런타임-패키지-사용)을 참고한다.

다음은 사용자가 추가 플래그와 인수를 제공하면서 플러그인을 호출하는 추가 사례이다. 이것은 위 시나리오의 `kubectl-foo-bar-baz` 플러그인을 기반으로한다.

`kubectl foo bar baz arg1 --flag=value arg2` 를 실행하면, kubectl의 플러그인 메커니즘은 먼저 가장 긴 가능한 이름을 가진 플러그인을 찾으려고 시도한다. 여기서는
`kubectl-foo-bar-baz-arg1` 이다. 해당 플러그인을 찾지 못하면, kubectl은 대시로 구분된 마지막 값을 인수(여기서는 `arg1`)로 취급하고, 다음으로 가장 긴 가능한 이름인 `kubectl-foo-bar-baz` 를 찾는다.
이 이름의 플러그인을 찾으면, kubectl은 해당 플러그인을 호출하여, 플러그인 이름 뒤에 모든 인수와 플래그를 플러그인 프로세스의 인수로 전달한다.

예:

```bash
# 플러그인 생성
echo -e '#!/bin/bash\n\necho "My first command-line argument was $1"' > kubectl-foo-bar-baz
sudo chmod +x ./kubectl-foo-bar-baz

# $PATH에 있는 디렉터리로 옮겨 플러그인을 "설치"
sudo mv ./kubectl-foo-bar-baz /usr/local/bin

# 플러그인을 kubectl이 인식하는지 확인
kubectl plugin list
```

```
The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-foo-bar-baz
```

```
# test that calling your plugin via a "kubectl" command works
# even when additional arguments and flags are passed to your
# plugin executable by the user.
kubectl foo bar baz arg1 --meaningless-flag=true
```

```
My first command-line argument was arg1
```

보시다시피, 사용자가 지정한 `kubectl` 명령을 기반으로 플러그인을 찾았으며, 모든 추가 인수와 플래그는 플러그인 실행 파일이 발견되면 그대로 전달된다.

#### 대시와 언더스코어가 있는 이름

`kubectl` 플러그인 메커니즘은 플러그인 파일명에 대시(`-`)를 사용하여 플러그인이 처리하는 하위 명령 시퀀스를 분리하지만, 파일명에
언더스코어(`_`)를 사용하여 커맨드 라인 호출에 대시를 포함하는 플러그인 명령을 생성할 수 있다.

예:

```bash
# 파일명에 언더스코어(_)가 있는 플러그인 생성
echo -e '#!/bin/bash\n\necho "I am a plugin with a dash in my name"' > ./kubectl-foo_bar
sudo chmod +x ./kubectl-foo_bar

# $PATH에 플러그인을 옮긴다
sudo mv ./kubectl-foo_bar /usr/local/bin

# 이제 kubectl을 통해 플러그인을 사용할 수 있다
kubectl foo-bar
```

```
I am a plugin with a dash in my name
```

참고로 플러그인 파일명에 언더스코어를 추가해도 `kubectl foo_bar` 와 같은 명령을 사용할 수 있다.
위 예에서 명령은 대시(`-`) 또는 언더스코어(`_`)을 사용하여 호출할 수 있다.

```bash
# 대시를 포함한 사용자 정의 명령을 사용할 수 있다
kubectl foo-bar
```

```
I am a plugin with a dash in my name
```

```bash
# 언더스코어를 포함한 사용자 정의 명령을 사용할 수도 있다
kubectl foo_bar
```

```
I am a plugin with a dash in my name
```

#### 이름 충돌과 오버셰도잉(overshadowing)

`PATH` 의 다른 위치에 동일한 파일명을 가진 여러 플러그인이 있을 수 있다.
예를 들어, `PATH` 값이 `PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins` 로 주어지고, `kubectl-foo` 플러그인을 복사한 파일이 `/usr/local/bin/plugins` 와 `/usr/local/bin/moreplugins` 에 있을 수 있다.
`kubectl plugin list` 명령의 출력 결과는 다음과 같다.

```bash
PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins kubectl plugin list
```

```
The following kubectl-compatible plugins are available:

/usr/local/bin/plugins/kubectl-foo
/usr/local/bin/moreplugins/kubectl-foo
  - warning: /usr/local/bin/moreplugins/kubectl-foo is overshadowed by a similarly named plugin: /usr/local/bin/plugins/kubectl-foo

error: one plugin warning was found
```

위 시나리오에서, `/usr/local/bin/moreplugins/kubectl-foo` 아래의 경고는 이 플러그인이 실행되지 않을 것임을 알려준다. 대신, `PATH` 에 먼저 나타나는 실행 파일인 `/usr/local/bin/plugins/kubectl-foo` 는 항상 발견되고 `kubectl` 플러그인 메카니즘에 의해 먼저 실행된다.

이 문제를 해결하는 방법은 `kubectl` 와 함께 사용하려는 플러그인의 위치가 `PATH` 에 항상에서 먼저 오도록 하는 것이다. 예를 들어, `kubectl` 명령 `kubectl foo` 가 호출될 때마다 항상 `/usr/local/bin/moreplugins/kubectl-foo` 를 사용하려면, `PATH` 의 값을 `/usr/local/bin/moreplugins:/usr/local/bin/plugins` 로 변경한다.

#### 가장 긴 실행 파일명의 호출

플러그인 파일명으로 발생할 수 있는 또 다른 종류의 오버셰도잉이 있다. 사용자의 `PATH` 에 `kubectl-foo-bar` 와 `kubectl-foo-bar-baz` 라는 두 개의 플러그인이 있다면, `kubectl` 플러그인 메커니즘은 항상 주어진 사용자의 명령에 대해 가장 긴 가능한 플러그인 이름을 선택한다. 아래에 몇 가지 예가 있다.

```bash
# 주어진 kubectl 명령의 경우, 가장 긴 가능한 파일명을 가진 플러그인이 항상 선호된다
kubectl foo bar baz
```

```
Plugin kubectl-foo-bar-baz is executed
```

```bash
kubectl foo bar
```

```
Plugin kubectl-foo-bar is executed
```

```bash
kubectl foo bar baz buz
```

```
Plugin kubectl-foo-bar-baz is executed, with "buz" as its first argument
```

```bash
kubectl foo bar buz
```

```
Plugin kubectl-foo-bar is executed, with "buz" as its first argument
```

이 디자인 선택은 필요한 경우 여러 파일에 플러그인 하위 명령을 구현할 수 있도록 하고 이러한 하위 명령을 "부모" 플러그인 명령 아래에 중첩할 수 있도록 한다.

```bash
ls ./plugin_command_tree
```

```
kubectl-parent
kubectl-parent-subcommand
kubectl-parent-subcommand-subsubcommand
```

### 플러그인 경고 확인

위에서 언급한 `kubectl plugin list` 명령을 사용하여 `kubectl` 에 의해 플러그인이 표시되는지 확인하고, `kubectl` 명령으로 호출되지 못하게 하는 경고가 없는지 확인할 수 있다.

```bash
kubectl plugin list
```

```
The following kubectl-compatible plugins are available:

test/fixtures/pkg/kubectl/plugins/kubectl-foo
/usr/local/bin/kubectl-foo
  - warning: /usr/local/bin/kubectl-foo is overshadowed by a similarly named plugin: test/fixtures/pkg/kubectl/plugins/kubectl-foo
plugins/kubectl-invalid
  - warning: plugins/kubectl-invalid identified as a kubectl plugin, but it is not executable

error: 2 plugin warnings were found
```

### 커맨드 라인 런타임 패키지 사용

kubectl 용 플러그인을 작성하고 있고 Go를 사용한다면,
[cli-runtime](https://github.com/kubernetes/cli-runtime) 유틸리티 라이브러리를
사용할 수 있다.

이 라이브러리는 사용자의
[kubeconfig](/ko/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
파일을 파싱이나 업데이트하거나, REST 스타일의 요청을 API 서버에 작성하거나, 구성 및 출력과
관련된 플래그를 바인딩하기 위한 헬퍼를 제공한다.

CLI 런타임 리포지터리에 제공된 도구 사용법의 예제는
[샘플 CLI 플러그인](https://github.com/kubernetes/sample-cli-plugin)을 참고한다.

## kubectl 플러그인 배포

다른 사람이 사용할 수 있는 플러그인을 개발한 경우, 이를 패키징하고, 배포하고
사용자에게 업데이트를 제공하는 방법을 고려해야 한다.

### Krew {#distributing-krew}

[Krew](https://krew.dev/)는 플러그인을 패키징하고 배포하는 크로스-플랫폼
방식을 제공한다. 이렇게 하면, 모든 대상 플랫폼(리눅스, 윈도우, macOS 등)에
단일 패키징 형식을 사용하고 사용자에게 업데이트를 제공한다.
Krew는 또한 다른 사람들이 여러분의 플러그인을 검색하고 설치할 수 있도록
[플러그인 인덱스](https://krew.sigs.k8s.io/plugins/)를
유지 관리한다.


### 네이티브 / 플랫폼 별 패키지 관리 {#distributing-native}

다른 방법으로는, 리눅스의 `apt` 나 `yum`,
윈도우의 Chocolatey, macOS의 Homebrew와 같은 전통적인 패키지 관리자를 사용할 수 있다.
새 실행 파일을 사용자의 `PATH` 어딘가에 배치할 수 있는 패키지 관리자라면
어떤 패키지 관리자도 괜찮다.
플러그인 작성자로서, 이 옵션을 선택하면 각 릴리스의 여러 플랫폼에서
kubectl 플러그인의 배포 패키지를
업데이트해야 한다.

### 소스 코드 {#distributing-source-code}

소스 코드를 게시(예를 들어, Git 리포지터리)할 수 있다. 이
옵션을 선택하면, 해당 플러그인을 사용하려는 사람이 코드를 가져와서,
빌드 환경을 설정하고(컴파일이 필요한 경우), 플러그인을 배포해야 한다.
컴파일된 패키지를 사용 가능하게 하거나, Krew를 사용하면 설치가
더 쉬워진다.

## {{% heading "whatsnext" %}}

* Go로 작성된 플러그인의
  [자세한 예제](https://github.com/kubernetes/sample-cli-plugin)에 대해서는
  샘플 CLI 플러그인 리포지터리를 확인한다.
  궁금한 사항이 있으면,
  [SIG CLI 팀](https://github.com/kubernetes/community/tree/master/sig-cli)에 문의한다.
* kubectl 플러그인 패키지 관리자인 [Krew](https://krew.dev/)에 대해 읽어본다.