설치와 업그레이드

원문 보기 위키 갱신 2026.10.03

설치와 업그레이드 (Installation and upgrades)

출처: 문서

본문

Kubernetes에 설치 (Installation on Kubernetes)

연산자 매니페스트를 직접 사용 (Directly using the operator manifest)

연산자는 kubectl로 적용되는 YAML 매니페스트를 통해, Kubernetes의 다른 리소스처럼 설치할 수 있어요.

이 마이너 릴리스의 최신 연산자 매니페스트는 다음과 같이 설치할 수 있어요:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.30/releases/cnpg-1.30.1.yaml

이는 다음으로 확인할 수 있어요:

kubectl rollout status deployment \
  -n cnpg-system cnpg-controller-manager

`kubectl`용 `cnpg` 플러그인 사용 (Using the `cnpg` plugin for `kubectl`)

cnpg 플러그인을 사용해 정적 매니페스트에 있는 기본 구성 옵션을 오버라이드할 수 있어요.

예를 들어 기본 최신 매니페스트를 생성하되 watch 네임스페이스를 특정 네임스페이스로만 변경하려면 다음을 실행할 수 있어요:

kubectl cnpg install generate \
  --watch-namespace "specific-namespace" \
  > cnpg_for_specific_namespace.yaml

더 포괄적인 예시는 "cnpg 플러그인" 문서를 참조하세요.

:::warning GKE에 CloudNativePG를 배포할 때 오류(... failed to call webhook...)가 나면, 공식 문서와 이 이슈에 설명된 대로, 기본적으로 워커 노드와 컨트롤 플레인 사이의 트래픽이 일부 특정 포트를 제외하고 방화벽에 의해 차단된다는 점을 알아두세요. webhook 서비스의 targetPort를 허용된 포트 중 하나로 변경하거나, 방화벽에서 webhook 포트(9443)를 열어야 해요. :::

Helm 차트 사용 (Using the Helm Chart)

연산자는 제공되는 Helm 차트로 설치할 수 있어요.

OLM 사용 (Using OLM)

CloudNativePG는 Operator Lifecycle Manager (OLM)로 OperatorHub.io에서 직접 설치할 수도 있어요.

Red Hat OpenShift 배포를 위해, EDB는 Red Hat OpenShift Container Platform을 통해 제공되는 CloudNativePG의 인증된 버전을 제공하고 완전히 지원해요.

배포에 대한 세부 사항 (Details about the deployment)

Kubernetes에서 연산자는 기본적으로 cnpg-system 네임스페이스에 Kubernetes Deployment로 설치돼요. 이 Deployment의 이름은 설치 방법에 따라 달라져요. 매니페스트나 cnpg 플러그인으로 설치하면 기본적으로 cnpg-controller-manager라고 불러요. Helm으로 설치하면 기본 이름이 cnpg-cloudnative-pg예요.

:::note Helm에서는 "values.yaml" 파일의 fullnameOverride 필드로 Deployment 이름을 커스터마이징할 수 있어요. :::

kubectl의 describe 명령으로 더 많은 정보를 얻을 수 있어요:

$ kubectl get deployments -n cnpg-system
NAME                READY   UP-TO-DATE   AVAILABLE   AGE
<deployment-name>   1/1     1            1           18m

kubectl describe deploy \
  -n cnpg-system \
  <deployment-name>

다른 Deployment와 마찬가지로 ReplicaSet 위에 있으며 롤링 업그레이드를 지원해요. CloudNativePG 연산자의 기본 구성은 단일 레플리카의 Deployment와 함께 제공되며, 이는 대부분의 설치에 적합해요. pod가 실행 중인 노드에 더 이상 도달할 수 없게 되면 pod는 다른 노드에 다시 스케줄링돼요.

연산자 레벨에서 고가용성이 필요하다면—연산자가 리더 선출을 지원하므로—Deployment 구성에 여러 레플리카를 지정할 수 있어요. 또한 테인트와 톨러레이션을 활용해 연산자가 실제 PostgreSQL 클러스터가 실행 중인 노드와 같은 노드에서 실행되지 않도록 할 수 있어요(자체 관리 Kubernetes 설치에서는 컨트롤 플레인을 포함할 수도 있음).

:::note[연산자 구성 (Operator configuration)] 일부 기본 옵션을 오버라이드해 연산자의 기본 동작을 변경할 수 있어요. 자세한 내용은 "Operator configuration" 섹션을 참조하세요. :::

업그레이드 (Upgrades)

:::info[Important] 일부 버전은 추가 단계가 필요할 수 있으므로, 업그레이드를 수행하기 전에 릴리스 노트를 주의 깊게 읽어보세요. :::

CloudNativePG 연산자 업그레이드는 두 단계 과정이에요:

컨트롤러와 관련 Kubernetes 리소스 업그레이드
각 PostgreSQL pod에서 실행되는 인스턴스 매니저 업그레이드

릴리스 노트에 달리 명시되지 않는 한, 첫 번째 단계는 보통 일반 Kubernetes 설치의 경우 새 버전의 매니페스트를 적용하거나, 사용 중인 배포판의 네이티브 패키지 매니저를 사용해 수행해요(위 섹션의 지침을 따르세요).

두 번째 단계는 컨트롤러를 갱신한 후 자동으로 트리거돼요. 기본적으로 이는 배포된 모든 PostgreSQL 클러스터의 롤링 업데이트를 시작해, 한 번에 한 인스턴스씩 새 인스턴스 매니저를 사용하도록 업그레이드해요. 롤링 업데이트는 primaryUpdateStrategy 옵션이 관장하는 스위치오버로 끝나요. 기본값인 unsupervised는 스위치오버를 자동으로 완료해요. supervised로 설정하면 사용자가 kubectl용 cnpg 플러그인으로 새 프라이머리 인스턴스를 수동으로 승격해야 해요.

:::note[롤링 업데이트 (Rolling updates)] 이 과정은 롤링 업데이트(Rolling Updates) 페이지에서 깊이 다뤄져요. :::

:::info[Important] primaryUpdateStrategy가 기본값인 unsupervised로 설정된 경우, 연산자 업그레이드가 PostgreSQL 클러스터에서 스위치오버를 트리거해 (보통 무시할 만한) 다운타임을 일으켜요. PostgreSQL Cluster에 인스턴스가 하나뿐이면, supervised 값은 primaryUpdateStrategy에 지원되지 않으므로 인스턴스가 자동으로 재시작돼요. 어느 경우든 애플리케이션은 PostgreSQL에 다시 연결해야 해요. :::

기본 롤링 업데이트 동작은 인스턴스 매니저의 인플레이스(in-place) 업데이트로 대체할 수 있어요. 이 접근 방식은 PostgreSQL 인스턴스 재시작이 필요하지 않으므로 클러스터 안에서 스위치오버를 피할 수 있어요. 기본적으로 비활성화된 이 기능은 아래에 자세히 설명돼요.

업그레이드 분산 (Spread Upgrades)

기본적으로 모든 PostgreSQL 클러스터가 동시에 롤아웃되어, 특히 여러 클러스터를 관리할 때 리소스 사용량이 급증할 수 있어요. CloudNativePG는 연산자 레벨의 두 가지 구성 옵션을 제공해 클러스터 롤아웃 사이 또는 같은 클러스터 안의 인스턴스 사이에 지연을 도입해, 시간에 따라 리소스 사용량을 분산하도록 돕습니다:

CLUSTERS_ROLLOUT_DELAY: 서로 다른 PostgreSQL 클러스터의 롤아웃 사이에 기다릴 초 수 정의 (기본값: 0)
INSTANCES_ROLLOUT_DELAY: 같은 PostgreSQL 클러스터 안의 개별 인스턴스 롤아웃 사이에 기다릴 초 수 정의 (기본값: 0)

인스턴스 매니저의 인플레이스 업데이트 (In-place updates of the instance manager)

기본적으로 CloudNativePG는 연산자가 갱신될 때마다 클러스터의 롤링 업데이트를 발행해요. 연산자와 함께 제공되는 새 인스턴스 매니저가 init 컨테이너를 통해 각 PostgreSQL pod에 추가돼요.

그러나 이 동작은 구성으로 변경해, 컨테이너를 살아 있게 유지하는 PID 1 프로세스인 인스턴스 매니저의 인플레이스 업데이트를 활성화할 수 있어요.

내부적으로 CloudNativePG의 각 인스턴스 매니저는 무결성 검증 단계를 성공적으로 완료하고 모든 내부 프로세스를 우아하게 종료한 후 기존 실행 파일을 대체하는 새 실행 파일의 주입을 지원해요. 새 바이너리로 재시작하면 인스턴스 매니저는 이미 실행 중인 postmaster를 매끄럽게 채택해요.

그 결과 PostgreSQL 프로세스는 업데이트에 영향받지 않아 스위치오버를 수행할 필요가 없어요. 반대편의 단점은, 시작 후 Pod가 변경되어 불변성(immutability)의 순수한 개념을 깨는 것이에요.

이 기능을 활성화하려면 연산자 구성에서 ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES 환경 변수를 'true'로 설정하세요.

인플레이스 업그레이드 과정은 Pod 안의 init 컨테이너 이미지를 변경하지 않아요. 따라서 Pod 정의는 현재 연산자 버전을 반영하지 않아요.

버전 간 호환성 (Compatibility among versions)

CloudNativePG는 시맨틱 버저닝(semantic versioning)을 따릅니다. 같은 API 버전 내의 연산자 릴리스는 각각 이전 것과 호환돼요. 현재 API 버전은 v1이며, 연산자의 1.x.y 버전에 해당해요.

새 기능 외에도 새 버전의 연산자에는 버그 수정과 안정성 개선이 포함돼요. 때문에 최신 버전의 연산자로 업그레이드할 것을 강력히 권장해요. 각 버전은 가장 안전하고 안정적인 Postgres 환경을 유지하기 위해 릴리스되기 때문이에요.

CloudNativePG는 현재 최소한 매달 연산자의 새 버전을 릴리스해요. 각 버전이 나올 때마다 업데이트를 적용할 수 없다면, 버전을 건너뛰지 않고 각 버전을 순서대로 업그레이드해 주기적으로 최신 상태가 되도록 권장해요.

릴리스 노트 페이지에는 CloudNativePG의 릴리스된 모든 버전에서 도입된 변경 사항의 상세 목록이 있고, 더 새로운 버전으로 업그레이드하기 전에 반드시 읽어야 해요.

대부분의 버전은 직접 업그레이드 가능하며, 그 경우 일반 Kubernetes 설치에 새 매니페스트를 적용하거나 선택한 배포판의 네이티브 패키지 매니저를 사용하는 것으로 충분해요.

버전이 직접 업그레이드 불가능하면, 새 버전을 설치하기 전에 이전 버전을 제거해야 해요. 이는 사용자 데이터에는 영향이 없고 연산자 자체에만 영향을 줘요.

1.30.0, 1.29.2, 1.28.4로 업그레이드 (Upgrading to 1.30.0, 1.29.2, or 1.28.4)

:::info[Important] 모든 CloudNativePG 사용자가 버전 1.30.0으로, 또는 적어도 현재 마이너 릴리스의 최신 안정 버전(예: 1.29.2 또는 1.28.4)으로 업그레이드할 것을 강력히 권장해요. :::

이 릴리스들은 업그레이드 전에 검토할 가치가 있는 변경 사항을 도입해요. 두 가지는 1.30.0, 1.29.2, 1.28.4에 적용되는 보안 변경이에요: 연산자 측 비밀번호 인코딩(CVE-2026-55765)과 search_path 강화(CVE-2026-55769). 나머지 세 가지는 1.30.0에서만 새로 도입된 것이에요: 선언적 역할 관리를 위한 DatabaseRole 리소스, per-cluster Lease를 통한 안전한 프라이머리 선출, 인스턴스 매니저의 상태 포트에서 연산자-인스턴스 인증(GHSA-7qwx-x8ff-3px9). 또한 1.29.1 또는 1.28.3보다 오래된 릴리스에서 업그레이드한다면, CVE-2026-44477의 metrics-exporter 권한 분리도 적용돼요. 각각 아래 자체 하위 섹션에서 다뤄져요.

연산자 측 비밀번호 인코딩 (`CVE-2026-55765`)

1.30.0, 1.29.2, 1.28.4 버전부터 보안상 이유로(CVE-2026-55765 / GHSA-w3gf-xc94-wvmj) CloudNativePG는 CREATE/ALTER ROLE 문을 발행하기 전에 역할 비밀번호를 연산자 측(PostgreSQL 관점에서 클라이언트 측)에서 SCRAM-SHA-256으로 인코딩해요. 그 결과 PostgreSQL 파서에 도달하는(그리고 pg_stat_statements나 pgaudit 같은 확장이 관찰할 수 있는) 리터럴은 pg_authid.rolpassword에 들어가는 것과 동일한 해시이며, 평문 비밀은 절대 아니에요. 인코딩은 연산자가 소비하는 모든 basic-auth Secret에 적용돼요: postgres 슈퍼유저 시크릿, 애플리케이션 사용자 시크릿, 모든 managed-role 비밀번호 시크릿. MD5 또는 SCRAM-SHA-256 섀도우 형태로 제공된 비밀번호는 변경 없이 전달돼요.

PostgreSQL 14부터 password_encryption은 기본적으로 scram-sha-256이므로, 기존 설치가 이 변경에 영향받을 것이라고 예상하지 않아요.

클러스터가 password_encryption을 명시적으로 scram-sha-256이 아닌 값(예: md5)으로 오버라이드했고 PostgreSQL(연산자가 아닌)이 비밀번호를 어떻게 해시할지 결정하게 하려면, 연산자가 소비하는 각 basic-auth Secret에 cnpg.io/passwordPassthrough: "enabled" 어노테이션을 설정해 옵트아웃하세요. 그러면 연산자가 비밀번호 값을 그대로 전달하고, PostgreSQL이 자체 password_encryption GUC에 따라 인코딩해요.

:::warning cnpg.io/passwordPassthrough 어노테이션은 Cluster 리소스가 아니라 basic-auth Secret 자체에 설정해야 해요. Cluster에 두면 효과가 없고, 연산자는 비밀번호를 PostgreSQL로 보내기 전에 계속 SCRAM-SHA-256 인코딩을 적용해요. :::

:::warning cnpg.io/passwordPassthrough: "enabled"로 설정하면 연산자가 Secret의 password 값을 그대로 전달해요. 그 값이 평문이면, password_encryption = md5 클러스터에서 흔하듯, pg_stat_statements나 pgaudit 같은 확장이 이를 관찰해요. :::

자세한 내용은 "연산자 측 인코딩 옵트아웃"을 참조하세요.

`search_path` 강화 (`CVE-2026-55769`)

1.30.0, 1.29.2, 1.28.4 버전부터 보안상 이유로(CVE-2026-55769 / GHSA-x8c2-3p4r-v9r6) CloudNativePG는 PostgreSQL에 여는 모든 연결에서 search_path를 고정된 pg_catalog, public, pg_temp로 고정해, 테넌트가 제어하는 ALTER DATABASE/ALTER ROLE 설정이 더 이상 연산자 발행 쿼리가 비한정(unqualified) 객체 이름을 해석하는 방식에 영향줄 수 없게 해요. PgBouncer 통합이 사용하는 SECURITY DEFINER 조회 함수는 업그레이드 후 첫 리컨실레이션 중에 자체 고정된 search_path로 자동 재생성돼요. 이유는 스키마 해석과 search_path 강화를 참조하세요.

이 변경은 커스텀 모니터링 쿼리에도 영향을 줘요. 이제 search_path가 pg_catalog, public, pg_temp로 고정된 트랜잭션 안에서 실행되기 때문이에요. 커스텀 메트릭 중 비한정 이름으로 다른 사용자 정의 스키마에 있는 객체를 참조하는 것이 있으면, 업그레이드 후에도 계속 해석되도록 스키마 한정(예: myschema.mytable)을 붙이세요. 사용자 작성 부트스트랩(postInit*)과 논리 가져오기 후처리 SQL은 영향받지 않아요. 표준 "$user", public 해석으로 계속 실행돼요.

`DatabaseRole` 리소스를 사용한 선언적 역할 관리

1.30.0부터 PostgreSQL 역할을 클러스터의 .spec.managed.roles 스탠자에 인라인으로 선언하는 대신 독립형 DatabaseRole 리소스로 관리할 수도 있어요. 이는 옵트인 개선이며 업그레이드 시 조치가 필요 없어요: 기존 인라인 역할은 변경 없이 계속 동작하고, 인라인 managed.roles 방식은 완전히 지원되며 유지돼요.

기존 인라인 역할을 중단 없이 DatabaseRole 아래로 옮기려면, 먼저 DatabaseRole을 만들고 그런 다음에만 .spec.managed.roles에서 해당 항목을 제거하세요. 둘 다 존재하는 동안 Cluster 스펙이 항상 우선하므로, 인라인 항목이 사라진 후에만 관리가 인계돼요. 전체 절차는 인라인 managed 역할에서 마이그레이션을 참조하세요.

DatabaseRole은 ensure: absent를 지원하지 않아요: 인라인 managed.roles 스탠자가 ensure: absent로 역할을 드롭하는 곳에서, DatabaseRole은 대신 databaseRoleReclaimPolicy 필드에 의존해요. databaseRoleReclaimPolicy: delete로 리소스를 삭제해 PostgreSQL에서 역할을 드롭하거나, 기본 retain을 유지해 역할을 그대로 두세요.

안전한 프라이머리 선출 (Safe primary election)

1.30.0부터 CloudNativePG는 per-cluster Kubernetes Lease를 통해 프라이머리 승격을 조정해, 어떤 순간에도 최대 한 인스턴스가 스스로 승격하도록 보장해요. 이 동작은 자동으로 활성화되며 구성이 필요 없어요. 리스 타이밍은 선택적으로 .spec.primaryLease로 튜닝할 수 있어요 ("안전한 프라이머리 선출" 참조).

:::warning 이 기능은 연산자가 coordination.k8s.io API 그룹의 Lease 객체를 관리해야 해요. 번들 연산자 매니페스트와 Helm 차트는 필요한 권한을 자동으로 부여해요. 연산자의 RBAC를 직접 관리한다면, 업그레이드 전에 coordination.k8s.io API 그룹의 leases에 대한 create, get, list, update, watch 동사를 추가해야 해요. 그렇지 않으면 프라이머리가 승격할 수 없어요. :::

연산자-인스턴스 인증 (`GHSA-7qwx-x8ff-3px9`)

1.30.0부터 연산자는 인스턴스 매니저 상태 포트의 민감한 엔드포인트(백업, pg_controldata, 부분 WAL 아카이브, 인스턴스 매니저 업그레이드)에 대한 호출을 메모리 내 클라이언트 인증서 고정으로 인증해요. 이는 자동으로 활성화되며 구성이 필요 없어요. 상태·헬스·프로브 엔드포인트는 인증되지 않은 채 남아요. 이 보호에는 엄격한 요구사항이 있어요: 상태 포트는 반드시 TLS로 서비스되어야 하는데, 이는 v1.24부터 기본이었어요. 이 강화는 백포트되지 않아요. 1.30.0보다 이전 릴리스에서는 NetworkPolicy로 상태 포트(TCP 8000)를 계속 제한하세요. 그곳에서 여전히 보안 경계로 남아요. 자세한 내용은 연산자-인스턴스 인증을 참조하세요.

Metrics exporter 권한 분리 (`CVE-2026-44477`)

이는 1.29.1 또는 1.28.3보다 오래된 릴리스에서 업그레이드하는 경우에만 적용돼요(예: 1.29.0, 1.28.2 또는 그 이전 버전). 이미 1.29.1, 1.28.3 이상인 설치에는 이미 이 변경이 있어요.

CVE-2026-44477 / GHSA-423p-g724-fr39의 수정은 metrics exporter가 postgres 슈퍼유저 대신 pg_monitor 권한만 있는 전용 cnpg_metrics_exporter 역할로 인증하게 만듭니다.

사용자 소유 테이블을 읽는 커스텀 모니터링 쿼리나, PUBLIC CONNECT가 회수된 데이터베이스에 대해 target_databases: '*'를 사용하는 쿼리는 cnpg_metrics_exporter에 대한 명시적 GRANT 문이 필요해요. 모니터링 문서의 "커스텀 쿼리 권한과 안전성"과 "metrics exporter 역할 수동 생성"을 참조하세요.

릴리스 산출물 검증 (Verifying release assets)

CloudNativePG는 모든 공식 릴리스 산출물에 암호학적으로 서명해요. 이 서명을 검증하면 산출물이 공식 저장소에서 나왔고 자동화된 릴리스 워크플로를 통해 발행됐음을 보장해요.

:::info 자세한 내용은 "릴리스 무결성과 공급망" 섹션을 참조하세요. :::

사전 요구사항 (Prerequisites)

서명 검증: cosign CLI
SBOM과 Provenance: Docker Buildx(Docker Desktop과 현대 Docker 버전에 포함)

연산자 YAML 배포 검증 (Verifying the Operator YAML Deployment)

직접 YAML 매니페스트로 설치할 때, GitHub Release 페이지에 제공된 해당 번들(.sigstore.json 파일)으로 매니페스트 파일을 검증해야 해요.

다음 명령을 실행하세요:

cosign verify-blob \
  cnpg-{version}.yaml \
  --bundle cnpg-{version}.sigstore.json \
  --certificate-identity-regexp "^https://github.com/cloudnative-pg/cloudnative-pg/.github/workflows/release-publish.yml@refs/tags/v" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

SLSA provenance 검증 (Verifying SLSA provenance)

릴리스 바이너리를 검증하려면 GitHub release에서 산출물과 provenance 파일(multiple.intoto.jsonl)을 모두 다운로드한 후 다음을 실행하세요:

slsa-verifier verify-artifact <ARTIFACT> \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/cloudnative-pg/cloudnative-pg

연산자 컨테이너 이미지 검증 (Verifying the operator container images)

CloudNativePG 연산자 이미지의 서명을 검증하려면 다음 명령을 실행하세요:

cosign verify ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
  --certificate-identity-regexp="^https://github.com/cloudnative-pg/cloudnative-pg/.github/workflows/release-publish.yml@refs/tags/v" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"

완전한 투명성을 위해 OCI 증명(attestations)을 제공해요. SBOM(Software Bill of Materials)이나 빌드 provenance를 검사하려면 docker buildx imagetools 명령을 사용하세요.

SBOM을 SPDX 형식으로 보려면:

docker buildx imagetools inspect ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
  --format '{{ json (index .SBOM "linux/amd64").SPDX }}'

SLSA Provenance(빌드 세부 사항)를 검사하려면:

docker buildx imagetools inspect ghcr.io/cloudnative-pg/cloudnative-pg:{tag} \
  --format '{{ json (index .Provenance "linux/amd64").SLSA }}'

:::info SLSA Build Level 3 준수 검증은 "SLSA provenance 검증"을 참조하세요. :::

PostgreSQL operand 이미지 검증 (Verifying PostgreSQL operand images)

CloudNativePG는 postgres-containers 프로젝트(operand 이미지라고도 함)의 일부로 지원되는 모든 PostgreSQL 버전의 컨테이너 이미지를 유지 관리해요.

특정 operand 이미지의 서명을 검증하려면:

cosign verify ghcr.io/cloudnative-pg/postgresql:{tag} \
  --certificate-identity-regexp="^https://github.com/cloudnative-pg/postgres-containers/" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"

SBOM을 SPDX 형식으로 보려면:

docker buildx imagetools inspect ghcr.io/cloudnative-pg/postgresql:{tag} \
  --format '{{ json (index .SBOM "linux/amd64").SPDX }}'

SLSA Provenance(빌드 세부 사항)를 검사하려면:

docker buildx imagetools inspect ghcr.io/cloudnative-pg/postgresql:{tag} \
  --format '{{ json (index .Provenance "linux/amd64").SLSA }}'

설치와 업그레이드