---
title: "Add-on 설치 및 관리"
slug: "k8s-k8suse-addon-manage"
updated: 2026-09-17T09:07:38Z
published: 2026-09-17T09:07:38Z
canonical: "guide.ncloud-docs.com/k8s-k8suse-addon-manage"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add-on 설치 및 관리

VPC 환경에서 이용 가능합니다.

## Add-on 설치 및 관리

Add-on을 설치하고, 설정과 버전을 변경하며, 삭제하는 방법을 설명합니다. Canary 업그레이드를 지원하는 Add-on의 마이너 버전 상향은 [Canary 업그레이드](/docs/k8s-k8suse-addon-manage#Canary%EC%97%85%EA%B7%B8%EB%A0%88%EC%9D%B4%EB%93%9C)를 참조해 주십시오.

### 클러스터 생성 시 함께 설치

클러스터를 생성할 때 **Add-on** 단계에서 설치할 Add-on을 함께 지정합니다. 지정한 Add-on은 클러스터가 생성되는 과정에서 함께 설치됩니다. 클러스터 생성 전체 절차는 [Ncloud Kubernetes Service 시작](/docs/k8s-k8sstart)을 참조해 주십시오.

지정하는 항목은 다음과 같습니다.

- Add-on 선택: 설치할 Add-on의 체크 박스를 클릭하여 선택해 주십시오. 여러 Add-on을 한 번에 지정할 수 있습니다.
- 버전 선택: Add-on의 **버전** 선택 박스에서 설치할 버전을 선택해 주십시오.
- 설정값 입력: **[상세 설정]** 버튼을 클릭한 다음 **Add-on 추가** 팝업 창에서 설정값을 입력하고 **[저장]** 버튼을 클릭해 주십시오. 입력하지 않으면 기본값으로 설치됩니다.

### 운영 중 Add-on 설치

운영 중인 클러스터에 설치되지 않은 Add-on을 추가합니다. 이미 설치된 Add-on은 설치됨으로 표시되며 선택할 수 없습니다.

운영 중인 클러스터에 Add-on을 설치하는 방법은 다음과 같습니다.

1. 클러스터 상세의 **[Add-on]** 탭 메뉴를 클릭해 주십시오.
2. **[Add-on 가져오기]** 버튼을 클릭해 주십시오.
3. **Add-on 가져오기** 팝업 창이 나타나면 설치할 Add-on의 체크 박스를 클릭하여 선택해 주십시오.
4. **버전** 선택 박스에서 설치할 버전을 클릭하여 선택해 주십시오.
5. 설정값을 입력하려면 **[상세 설정]** 버튼을 클릭한 다음 **Add-on 추가** 팝업 창에서 입력하고 **[저장]** 버튼을 클릭해 주십시오. 입력하지 않으면 기본값으로 설치됩니다.
6. **[가져오기]** 버튼을 클릭해 주십시오. 설치가 시작됩니다.

### 설정 변경 및 버전 업그레이드

설치된 Add-on의 버전과 설정값을 변경합니다. **Add-on 수정** 팝업 창은 현재 설정값이 입력된 상태로 열립니다.

참고

Canary 업그레이드를 지원하는 Add-on은 이 절차로 같은 마이너 버전 안의 패치 버전 변경만 가능합니다. 마이너 버전을 올리려면 [Canary 업그레이드](/docs/k8s-k8suse-addon-manage#Canary%EC%97%85%EA%B7%B8%EB%A0%88%EC%9D%B4%EB%93%9C)를 사용해 주십시오. Canary 업그레이드가 진행 중인 동안에는 수정과 삭제를 수행할 수 없습니다.

설치된 Add-on을 수정하는 방법은 다음과 같습니다.

1. 클러스터 상세의 **[Add-on]** 탭 메뉴를 클릭해 주십시오.
2. 수정할 Add-on을 선택한 다음 **[수정]** 버튼을 클릭해 주십시오. **Add-on 수정** 팝업 창이 나타납니다.
3. 필요시 버전을 변경해 주십시오. 버전은 클러스터와 호환되는 범위에서 클릭하여 선택할 수 있습니다.
4. 필요시 설정값을 수정해 주십시오.
5. **충돌 관리 (충돌 해결)**​에서 방식을 클릭하여 선택해 주십시오. 자세한 내용은 [충돌 관리](/docs/k8s-k8suse-addon-manage#%EC%B6%A9%EB%8F%8C%EA%B4%80%EB%A6%AC)를 참조해 주십시오.
6. **[저장]** 버튼을 클릭해 주십시오. 변경이 적용됩니다.

참고

변경 사항이 거부되거나 검증에 실패하면, 직전 정상 상태(버전 및 설정값)로 자동 복원을 시도합니다. 단, 적용은 완료되었으나 이후 런타임이 비정상인 경우(예: 컨테이너 재시작 반복), 자동 복원 대상이 아닙니다.

#### 충돌 관리

Add-on은 기본 설정값에 사용자가 입력한 설정값을 반영해 최종 구성을 만들고, 이를 클러스터에 적용합니다. 입력하지 않은 항목은 기본 설정값을 사용합니다. 설정값을 입력해 구성을 바꾸는 것은 충돌이 아니며, 충돌은 사용자가 클러스터에서 직접(예: `kubectl edit`) 수정해 둔 필드에만 발생합니다. 직접 수정한 필드가 없으면 어느 방식을 선택해도 결과는 같습니다.

**Add-on 수정** 팝업 창의 **충돌 관리 (충돌 해결)**​에서 선택할 수 있는 방식은 다음과 같습니다.

| 방식 | 설명 |
| --- | --- |
| Overwrite (덮어쓰기) | 기본 방식으로 사용자가 직접 수정한 필드가 있어도 최종 구성 값으로 덮어씀. 충돌로 작업이 실패하지 않음 |
| Preserve (기존 설정 유지) | 사용자가 직접 수정한 필드는 그대로 두고, 나머지만 최종 구성 값으로 갱신. 직접 수정한 값이 이 값과 충돌하면 작업이 실패할 수 있음 |

### Add-on 삭제

설치된 Add-on을 클러스터에서 제거합니다. 설치된 Add-on을 삭제하는 방법은 다음과 같습니다.

1. 클러스터 상세의 **[Add-on]** 탭 메뉴를 클릭해 주십시오.
2. 삭제할 Add-on을 선택한 다음 **[삭제]** 버튼을 클릭해 주십시오.
3. **Add-on 삭제** 팝업 창의 내용을 확인하고 삭제할 Add-on의 이름을 입력한 다음 **[삭제]** 버튼을 클릭해 주십시오. 삭제가 시작됩니다.

주의

삭제하면 Add-on을 통해 설치된 리소스가 제거됩니다. 삭제 전에 Add-on 리소스에 의존하는 워크로드가 클러스터에 남아 있지 않은지 확인해 주십시오. 단, 사용자 데이터가 남아 있는 리소스(예: 사용 중인 볼륨 스냅샷)는 보호를 위해 보존될 수 있으며, 보존된 리소스는 필요할 때 직접 정리해 주십시오.

## Canary 업그레이드

Canary 업그레이드는 Add-on의 새 마이너 버전을 기존 버전과 나란히 설치하고, 워크로드를 점진적으로 전환해 검증한 다음 새 버전으로 확정하는 업그레이드 방식입니다. 문제가 발견되면 새 버전을 제거하고 기존 버전으로 돌아갈 수 있습니다. 다음 세 단계로 진행됩니다.

- 시작: 새 버전을 기존 버전과 나란히 설치합니다. 기존 버전은 그대로 운영됩니다.
- 검증: 워크로드를 새 버전으로 점진적으로 전환하며 정상 동작을 확인합니다.
- 확정 또는 취소: 확정하면 새 버전이 운영 버전이 되고 기존 버전이 제거됩니다. 취소하면 새 버전이 제거되고 기존 버전이 유지됩니다.

Canary 업그레이드를 지원하는 Add-on은 [Add-on 목록](/docs/k8s-k8suse-addon-catalog)에서 확인해 주십시오. **[캐너리 업그레이드]** 버튼은 Canary 업그레이드를 지원하는 Add-on을 선택했을 때만 활성화되며, Add-on이 활성 상태가 아니거나 업그레이드할 수 있는 버전이 없으면 비활성화됩니다.

참고

Canary 업그레이드를 지원하는 Add-on은 설치된 버전 계열마다 Revision 식별자를 가집니다. Revision은 버전의 메이저·마이너 버전에서 파생됩니다(예: 버전 `1.30.3`의 Revision은 `1-30`). 검증 단계에서는 두 Revision이 클러스터에 함께 존재하며, 콘솔의 작업 결과 상세 표에서 각 Revision을 확인할 수 있습니다.

### 시작 전 확인 사항

Canary 업그레이드를 시작하기 전에 다음 사항을 확인해 주십시오.

- 업그레이드할 수 있는 버전은 **캐너리 시작** 팝업 창의 **대상 버전** 선택 박스에 표시됩니다. 현재 버전의 다음 마이너 버전이 제공됩니다.
- 시작할 때 새 버전에 적용할 설정값을 지정할 수 있습니다. 지정하지 않으면 현재 설정값을 그대로 사용하고, 지정하면 현재 설정값을 대체합니다.
- Canary 업그레이드가 진행되는 동안에는 다음 작업을 수행할 수 없습니다. 확정 또는 취소로 종결한 다음 수행해 주십시오.
  - 해당 Add-on의 수정과 삭제
  - 클러스터의 Kubernetes 버전 업그레이드
  - 같은 Add-on의 새로운 Canary 업그레이드

### Canary 상태 확인

Canary 업그레이드가 진행 중인 Add-on은 기존 상태와 별도로 Canary 상태를 가집니다. Add-on의 **[작업 결과 상세 보기]** 버튼을 클릭하면 운영 중인 버전과 Canary 버전이 Revision, 상태와 함께 표시됩니다. Canary 상태는 다음과 같습니다.

| 상태 | 의미 | 가능한 작업 |
| --- | --- | --- |
| 캐너리 설치 중 | 새 버전 설치 중 | 완료 대기 |
| 캐너리 실행 중 | 두 버전이 함께 동작하는 검증 단계 | 확정, 취소 |
| 캐너리 설치 실패 | 새 버전 설치 실패 | 시작 재시도, 취소 |
| 캐너리 완료 진행 중 | 확정 작업 진행 중 | 완료 대기 |
| 캐너리 완료 실패 | 확정 작업 실패 | 확정 재시도 |
| 캐너리 취소 진행 중 | 취소 작업 진행 중 | 완료 대기 |
| 캐너리 취소 실패 | 취소 작업 실패 | 취소 재시도 |

### Canary 업그레이드 시작

Add-on의 새 버전을 기존 버전과 나란히 설치합니다.

1. 클러스터 상세의 **[Add-on]** 탭 메뉴를 클릭해 주십시오.
2. 대상 Add-on을 선택한 다음 **[캐너리 업그레이드]** 버튼을 클릭해 주십시오.
3. **캐너리 시작** 팝업 창이 나타나면 **대상 버전** 선택 박스에서 업그레이드할 버전을 클릭하여 선택해 주십시오.
4. 필요시 새 버전에 적용할 설정값을 입력해 주십시오.
5. 안내 내용을 확인한 다음 **[시작]** 버튼을 클릭해 주십시오. 새 버전 설치가 시작됩니다.

설치가 완료되면 Canary 상태가 캐너리 실행 중으로 바뀌고 검증 단계가 시작됩니다.

### 워크로드 전환

검증 단계에서 워크로드는 계속 기존 Revision을 사용합니다. 사용자가 클러스터에서 직접 워크로드를 새 Revision으로 전환하며 확인하고, 영향 범위가 작은 네임스페이스부터 순차적으로 진행하는 것을 권장합니다. 전환 방법은 Add-on마다 다릅니다. [Add-on 목록](/docs/k8s-k8suse-addon-catalog)에서 해당 Add-on의 Canary 업그레이드 항목을 참고해 주십시오.

### 확정 및 취소

검증을 마쳤으면 확정 또는 취소로 종결합니다. 대상 Add-on의 **[작업 결과 상세 보기]** 버튼을 클릭하면 Canary 상태에 따라 가능한 작업의 버튼이 활성화됩니다.

- 확정: **[확정]** 버튼을 클릭해 주십시오. **캐너리 완료** 팝업 창에서 변경 내용을 확인하고 되돌릴 수 없음에 동의하는 체크 박스를 클릭하여 선택한 다음 **[확정]** 버튼을 클릭해 주십시오. 새 버전이 운영 버전이 되고 기존 Revision이 제거됩니다. 확정한 다음에는 되돌릴 수 없습니다.
- 취소: **[취소]** 버튼을 클릭해 주십시오. **캐너리 취소** 팝업 창의 내용을 확인한 다음 **[취소 실행]** 버튼을 클릭해 주십시오. 새 Revision이 제거되고 기존 버전이 유지됩니다.

주의

확정과 취소는 제거되는 Revision을 사용 중인 워크로드를 대신 전환해 주지 않습니다. 확정 전에는 모든 워크로드가 새 Revision으로 전환되었는지, 취소 전에는 새 Revision으로 전환한 워크로드를 기존 Revision으로 되돌렸는지 확인해 주십시오.

### Canary 작업 실패 시 확인

작업이 실패하면 Canary 상태가 캐너리 설치 실패, 캐너리 완료 실패, 캐너리 취소 실패 중 하나로 표시되고, 실패 사유는 **[작업 결과 상세 보기]** 버튼을 클릭해 상태 로그 메시지에서 확인할 수 있습니다. 시작이 실패해도 기존 버전은 계속 운영됩니다. 확정이나 취소가 실패하면 제거 작업이 일부만 진행된 상태일 수 있으므로, 메시지를 확인한 다음 같은 작업을 다시 시도해 마무리해 주십시오.

참고

시작 재시도는 **[캐너리 업그레이드]** 버튼으로 같은 버전에 대해서만 가능합니다. 설정값은 재시도할 때 수정할 수 있습니다. 다른 버전으로 진행하려면 취소한 다음 새로 시작해 주십시오.

Canary 업그레이드의 시작, 확정, 취소는 [Cluster Add-on Canary 업그레이드 API](/docs/nks-canaryaddon)로도 수행할 수 있습니다.

## 작업 실패 시 확인

작업이 실패하면 Add-on의 상태가 설치 실패, 업데이트 실패, 삭제 실패 중 하나로 표시되고, **[작업 결과 상세 보기]** 버튼을 클릭하면 상태 로그 메시지에 원인이 표시됩니다. 메시지를 확인해 설정값이나 버전, 충돌 관리 방식을 조정한 다음 다시 시도해 주십시오.