Kubernetes CRD 업그레이드

Kubernetes CRD 업그레이드 (Upgrade Kubernetes CRDs)

consul-helm 버전 0.30.0 이상으로 업그레이드할 때 필요한 변경 사항을 설명하는 문서예요. centralConfig, defaultProtocol, proxyDefaults, meshGateway 전역 모드, connect-service-protocol 어노테이션 및 구성 항목 마이그레이션을 다뤄요.

출처: 문서

본문

다음을 사용한다면 consul-helm 버전 >= 0.30.0으로 업그레이드할 때 몇 가지 변경이 필요합니다:

• connectInject.centralConfig.enabled
• connectInject.centralConfig.defaultProtocol
• connectInject.centralConfig.proxyDefaults
• meshGateway.globalMode
• connect 어노테이션 consul.hashicorp.com/connect-service-protocol

Central Config 활성화 (Central Config Enabled)

이전에 centralConfig.enabled를 false로 설정했다면:

connectInject:
  centralConfig:
    enabled: false

대신 server.extraConfig와 client.extraConfig를 사용해야 합니다:

client:
  extraConfig: |
    {"enable_central_service_config": false}
server:
  extraConfig: |
    {"enable_central_service_config": false}

이전에 true로 설정했다면 이제 기본값이 true이므로 변경이 필요하지 않지만, 원하면 구성에서 제거할 수 있습니다.

기본 프로토콜 (Default Protocol)

이전에 다음을 설정했다면:

connectInject:
  centralConfig:
    defaultProtocol: 'http' # or any value

이제 커스텀 리소스를 사용해 새 및 기존 서비스의 프로토콜을 관리해야 합니다:

1. 업그레이드하려면 먼저 Consul >= 1.9.0을 실행 중인지 확인하세요. Consul 버전 업그레이드 방법에 대한 자세한 내용은 Consul Version Upgrade를 참조하세요. 이 버전은 커스텀 리소스를 지원하는 데 필요합니다.
2. 다음으로 Helm values를 수정합니다:
   • defaultProtocol 구성을 제거합니다. 이는 기존 서비스에 영향을 주지 않습니다.
3. 이제 새 Helm values로 Helm 차트를 최신 버전으로 업그레이드할 수 있습니다.
4. 이제부터 새 서비스는 프로토콜을 설정하려면 ServiceDefaults 리소스가 필요합니다:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: my-service-name
spec:
  protocol: 'http'

5. 기존 서비스는 이전에 설정된 프로토콜을 유지합니다. 해당 프로토콜을 변경하려면 해당 서비스의 service-defaults 구성 항목을 ServiceDefaults 리소스로 마이그레이션해야 합니다. 구성 항목 마이그레이션을 참조하세요.

참고 이 설정은 서비스를 처음 실행한 후 프로토콜을 변경하는 것을 지원하지 않고 보조 데이터센터에서 작동하지 않았기 때문에 제거되었습니다.

Proxy Defaults

이전에 다음을 설정했다면:

connectInject:
  centralConfig:
    proxyDefaults: |
      {
        "key": "value" // or any values
      }

업그레이드하려면 다음 단계를 수행해야 합니다:

1. Helm values에서 설정을 제거해야 합니다. 이 구성은 클러스터가 처음 생성될 때만 읽히므로 기존 클러스터에는 영향이 없습니다.
2. 그런 다음 Helm 차트를 업그레이드할 수 있습니다.
3. 나중에 proxy defaults 설정을 변경하려면 proxy-defaults 구성 항목에 대한 구성 항목 마이그레이션 지침을 따라야 합니다. 이를 위해서는 Consul >= 1.9.0이 필요합니다.

참고 이 설정은 초기 설치 후 변경할 수 없었기 때문에 제거되었습니다.

메시 게이트웨이 모드 (Mesh Gateway Mode)

이전에 다음을 설정했다면:

meshGateway:
  globalMode: 'local' # or any value

업그레이드하려면 다음 단계를 수행해야 합니다:

1. Helm values에서 설정을 제거해야 합니다. 이 구성은 클러스터가 처음 생성될 때만 읽히므로 기존 클러스터에는 영향이 없습니다.
2. 그런 다음 Helm 차트를 업그레이드할 수 있습니다.
3. 나중에 proxy-defaults에서 모드나 다른 설정을 변경하려면 구성 항목 마이그레이션 지침을 따라 proxy-defaults 구성 항목을 ProxyDefaults 리소스로 마이그레이션해야 합니다. 이를 위해서는 Consul >= 1.9.0이 필요합니다.

참고 이 설정은 초기 설치 후 변경할 수 없었기 때문에 제거되었습니다.

connect-service-protocol 어노테이션 (connect-service-protocol Annotation)

메시 서비스 중 consul.hashicorp.com/connect-service-protocol 어노테이션이 설정된 것이 있다면, 예:

apiVersion: apps/v1
kind: Deployment
...
spec:
  template:
    metadata:
      annotations:
        "consul.hashicorp.com/connect-inject": "true"
        "consul.hashicorp.com/connect-service-protocol": "http"
  ...

업그레이드하려면 다음 단계를 수행해야 합니다:

1. Consul >= 1.9.0을 실행 중인지 확인하세요.
2. 다음으로 기존 배포에서 이 어노테이션을 제거합니다. 서비스가 처음 생성될 때만 어노테이션이 사용되었으므로 배포에는 영향이 없습니다.
3. 이제 Helm 차트를 최신 버전으로 업그레이드할 수 있습니다.
4. 이제부터 새 서비스는 프로토콜을 설정하려면 ServiceDefaults 리소스가 필요합니다:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: my-service-name
spec:
  protocol: 'http'

5. 기존 서비스는 이전에 설정된 프로토콜을 유지합니다. 해당 프로토콜을 변경하려면 해당 서비스의 service-defaults 구성 항목을 ServiceDefaults 리소스로 마이그레이션해야 합니다.

참고 어노테이션은 프로토콜 변경을 지원하지 않고 보조 데이터센터에서 지원되지 않았기 때문에 제거되었습니다.

구성 항목 마이그레이션 (Migrating Config Entries)

Consul에 이미 존재하는 구성 항목은 Kubernetes에서 관리하려면 Kubernetes 커스텀 리소스로 마이그레이션해야 합니다:

1. 구성 항목의 kind와 name을 결정합니다. 예를 들어 프로토콜은 kind: service-defaults이고 name이 서비스 이름과 같은 구성 항목으로 설정됩니다. 또 다른 예에서 proxy-defaults 구성은 kind: proxy-defaults 및 name: global을 가집니다.
2. kind와 name을 결정했으면 Consul을 쿼리해 내용을 가져옵니다:

$ consul config read -kind <kind> -name <name>

이를 위해서는 Consul 서버 또는 클라이언트 파드로 kubectl exec해야 합니다. ACL을 사용한다면 -token 플래그로 전달되는 ACL 토큰도 필요합니다. 예:

$ kubectl exec consul-server-0 -- consul config read -name foo -kind service-defaults
{
    "Kind": "service-defaults",
    "Name": "foo",
    "Protocol": "http",
    "MeshGateway": {},
    "Expose": {},
    "CreateIndex": 60,
    "ModifyIndex": 60
}

3. 이제 구성 항목에 대한 Kubernetes 리소스를 만들 준비가 되었습니다. 다음과 같을 것입니다:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: foo
  annotations:
    'consul.hashicorp.com/migrate-entry': 'true'
spec:
  protocol: 'http'

• apiVersion은 항상 consul.hashicorp.com/v1alpha1입니다.
• kind는 Consul kind의 CamelCase 버전입니다. 예: proxy-defaults는 ProxyDefaults가 됩니다.
• metadata.name은 구성 항목의 name입니다.
• metadata.annotations에는 "consul.hashicorp.com/migrate-entry": "true" 어노테이션이 포함됩니다.
• 네임스페이스는 서비스가 배포된 네임스페이스여야 합니다. ProxyDefaults는 Consul이 배포된 네임스페이스를 권장합니다.
• spec의 내용은 JSON 키에서 YAML 키로의 변환입니다. CreateIndex, ModifyIndex 및 빈 객체가 있는 키(예: "Expose": {})는 무시할 수 있습니다.

예를 들어:

{
  "Kind": "service-defaults",
  "Name": "foo",
  "Protocol": "http",
  "MeshGateway": {},
  "Expose": {},
  "CreateIndex": 60,
  "ModifyIndex": 60
}

는 다음과 같이 됩니다:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: foo
  annotations:
    'consul.hashicorp.com/migrate-entry': 'true'
spec:
  protocol: 'http'

그리고:

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "MeshGateway": {
    "Mode": "local"
  },
  "Config": {
    "local_connect_timeout_ms": 1000,
    "handshake_timeout_ms": 10000
  },
  "CreateIndex": 60,
  "ModifyIndex": 60
}

는 다음과 같이 됩니다:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
  annotations:
    'consul.hashicorp.com/migrate-entry': 'true'
spec:
  meshGateway:
    mode: local
  config:
    # Note that anything under config for ProxyDefaults will use the exact
    # same keys.
    local_connect_timeout_ms: 1000
    handshake_timeout_ms: 10000

4. kubectl apply를 실행해 Kubernetes 리소스를 적용합니다.
5. 다음으로 성공적으로 동기화되었는지 확인합니다:

$ kubectl get servicedefaults foo
NAME              SYNCED   AGE
foo               True     1s

6. SYNCED 상태가 True이면 이 구성 항목의 마이그레이션이 성공한 것입니다.
7. SYNCED 상태가 False이면 kubectl describe를 사용해 동기화 실패 이유를 확인합니다:

$ kubectl describe servicedefaults foo
...
Status:
  Conditions:
    Last Transition Time:  2021-01-12T21:03:29Z
    Message:               migration failed: Kubernetes resource does not match existing Consul config entry: consul={...}, kube={...}
    Reason:                MigrationFailedError
    Status:                False
    Type:                  Synced

가장 가능성 있는 이유는 Kubernetes 리소스의 내용이 Consul 리소스와 일치하지 않기 때문입니다. Kubernetes 리소스를 Consul 리소스와 일치하도록 변경하세요 (CreateIndex, ModifyIndex 및 Meta 키는 무시). 8. SYNCED 상태가 true가 되면 리소스를 변경할 수 있으며 변경 사항이 Consul에 동기화됩니다.

더 알아보기 (Learn more)

• 구성 항목
• Upgrade Guide