Consul을 v1.6.x로 업그레이드

Consul을 v1.6.x로 업그레이드 (Upgrade Consul to v1.6.x)

이 페이지는 Consul 배포를 v1.6.x로 업데이트하고 복제 데이터를 유지하는 프로세스를 설명해요.

출처: 문서

본문

이 페이지는 Consul 배포를 v1.6.x로 업데이트하고 복제 데이터를 유지하는 프로세스를 설명합니다.

소개 (Introduction)

이 가이드는 복제를 유지하면서 >= 1.2.4 및 < 1.6.10 버전의 Consul을 사용하는 다중 데이터센터 Consul 배포를 가장 잘 업그레이드하는 방법을 설명합니다. 1.2.4보다 오래된 버전을 사용하고 있다면 Upgrading to 1.2.4 가이드를 검토하세요. ACL 시스템의 변경으로 인해 이 업그레이드의 일부로 ACL 토큰 마이그레이션을 수행해야 합니다. 1.6.x 시리즈는 레거시 ACL 토큰을 지원한 마지막 시리즈이므로 이 마이그레이션은 1.6.x 릴리스 시리즈를 지나기 전에 반드시 수행해야 합니다. 이 업그레이드 과정에서 참조에 유용할 수 있는 문서는 다음과 같습니다:

• Upgrading Legacy ACL tokens — 레거시 ACL 토큰 업그레이드 및 모드 간 차이에 대한 정보를 찾을 수 있습니다.
• Configuration — 레거시 ACL 및 새 ACL 구성 옵션에 대한 자세한 내용을 찾을 수 있습니다. 레거시 ACL 구성 옵션은 1.4.0부터 더 이상 사용되지 않는 것으로 나열됩니다.

이 가이드에서는 두 개의 데이터센터(DC)가 있는 예제를 사용하며 이를 DC1과 DC2라고 합니다. DC1이 기본 데이터센터입니다.

요구 사항 (Requirements)

• 모든 Consul 서버는 >= 1.2.4 및 < 1.6.10 버전의 Consul이어야 합니다.

가정 (Assumptions)

이 가이드는 다음을 가정합니다:

• 최소 두 개의 데이터센터가 구성되어 있고 ACL 복제가 활성화되어 있습니다. 여러 데이터센터를 사용하지 않는다면 복제 관련 지침을 건너뛰고 따라갈 수 있습니다.
• 이미 ACL 토큰 마이그레이션을 수행하지 않았습니다. 수행했다면 관련 단계를 모두 건너뛰세요.

고려 사항 (Considerations)

릴리스 간에 상당히 많은 변경 사항이 있습니다. 주요 변경 사항은 Specific Version Details 페이지에 언급되어 있습니다. 더 세분화된 세부 사항은 전체 changelog에서 찾을 수 있습니다. 업그레이드 전에 이러한 변경 사항을 검토하는 것이 좋습니다.

두 가지 매우 주목할 만한 항목:

• 1.6.2는 더 엄격한 JSON 디코딩을 도입했습니다. 이전에 무시되었던 잘못된 JSON이 이제 오류를 유발할 수 있습니다(예: 서비스 정의의 Connect: null). [GH#6680] 참조.
• 1.6.3은 http_max_conns_per_client 제한을 도입했습니다. 기본값은 200입니다. 이전에는 클라이언트당 연결이 무제한이었습니다. [GH#7159]

절차 (Procedure)

1. 해당 DC의 Consul 서버에서 다음 curl 명령을 실행하여 기본 데이터센터(DC1)의 복제 상태를 확인하세요:

$ curl --silent --header "X-Consul-Token: $MASTER_TOKEN" localhost:8500/v1/acl/replication?pretty

다음과 유사한 출력을 받아야 합니다:

{
  "Enabled": false,
  "Running": false,
  "SourceDatacenter": "",
  "ReplicatedIndex": 0,
  "LastSuccess": "0001-01-01T00:00:00Z",
  "LastError": "0001-01-01T00:00:00Z"
}

기본 데이터센터(acl_datacenter로 표시)는 항상 복제가 비활성화된 것으로 표시되므로, 실제로 복제가 발생하고 있어도 이는 정상입니다.

2. 해당 DC의 Consul 서버에서 다음 curl 명령을 실행하여 DC2의 복제 상태를 확인하세요:

$ curl --silent --header "X-Consul-Token: $MASTER_TOKEN" localhost:8500/v1/acl/replication?pretty

다음과 유사한 출력을 받아야 합니다:

{
  "Enabled": true,
  "Running": true,
  "SourceDatacenter": "dc1",
  "ReplicatedIndex": 9,
  "LastSuccess": "2020-09-10T21:16:15Z",
  "LastError": "0001-01-01T00:00:00Z"
}

3. General Upgrade Process에 따라 DC2 에이전트를 버전 1.6.10으로 업그레이드하세요. 모든 DC1 에이전트는 1.2.4로 유지하세요. 그 후 다음과 같은 로그 메시지가 표시되기 시작해야 합니다:

2020/09/08 15:51:29 [DEBUG] acl: Cannot upgrade to new ACLs, servers in acl datacenter have not upgraded - found servers: true, mode: 3
2020/09/08 15:51:32 [ERR] consul: RPC failed to server 192.168.5.2:8300 in DC "dc1": rpc error making call: rpc: can't find service ConfigEntry.ListAll

경고 (Warning): 기본 데이터센터(acl_datacenter에 지정된 것)를 마지막으로 업그레이드하는 것이 중요합니다. 기본 데이터센터를 먼저 업그레이드하면 다른 데이터센터 간의 복제가 깨집니다. 다른 데이터센터를 먼저 업그레이드하면 레거시 모드로 전환되고 기본 데이터센터의 복제가 계속 작동합니다.

4. DC2에서 복제가 여전히 작동하는지 확인하세요.

DC2의 Consul 서버에서:

$ curl --silent --header "X-Consul-Token: $MASTER_TOKEN" localhost:8500/v1/acl/replication?pretty
$ curl --silent --header "X-Consul-Token: $MASTER_TOKEN" localhost:8500/v1/acl/list?pretty

ReplicatedIndex 값을 확인하세요.

다음 내용으로 test-ui-token.json이라는 새 토큰을 만드는 페이로드가 포함된 새 파일을 만드세요:

test-ui-token.json

{
  "Name": "UI Token",
  "Type": "client",
  "Rules": "key \"\" { policy = \"write\" } node \"\" { policy = \"read\" } service \"\" { policy = \"read\" }"
}

DC1의 Consul 서버에서 해당 파일을 사용하여 새 토큰을 만드세요:

$ curl --request PUT --header "X-Consul-Token: $MASTER_TOKEN" --data @test-ui-token.json localhost:8500/v1/acl/create

DC2의 Consul 서버에서:

$ curl --silent --header "X-Consul-Token: $MASTER_TOKEN" "localhost:8500/v1/acl/replication?pretty"
$ curl --silent --header "X-Consul-Token: $MASTER_TOKEN" "localhost:8500/v1/acl/list?pretty"

ReplicatedIndex가 증가했고 새 토큰이 나열되어야 합니다. CLI ACL 명령을 사용하려고 하면 다음 오류가 발생합니다:

Failed to retrieve the token list: Unexpected response code: 500 (The ACL system is currently in legacy mode.)

이는 Consul이 레거시 모드이기 때문입니다. ACL CLI 명령은 작동하지 않으며 이전 ACL HTTP 엔드포인트를 사용해야 합니다(그래서 위에서 consul CLI 클라이언트 대신 curl을 사용하는 것입니다).

5. General Upgrade Process에 따라 DC1 에이전트를 버전 1.6.10으로 업그레이드하세요.

완료되면 서버 에이전트에서 다음과 같은 로그 항목이 표시되어야 합니다:

2020/09/10 22:11:49 [DEBUG] acl: transitioning out of legacy ACL mode

6. 해당 DC의 Consul 서버에서 다음 curl 명령을 실행하여 DC2에서 복제가 여전히 작동하는지 확인하세요:

$ curl --silent --header "X-Consul-Token: $MASTER_TOKEN" "localhost:8500/v1/acl/replication?pretty"

다음과 유사한 출력을 받아야 합니다:

{
  "Enabled": true,
  "Running": true,
  "SourceDatacenter": "dc1",
  "ReplicationType": "tokens",
  "ReplicatedIndex": 259,
  "ReplicatedRoleIndex": 1,
  "ReplicatedTokenIndex": 260,
  "LastSuccess": "2020-09-10T22:11:51Z",
  "LastError": "2020-09-10T22:11:43Z"
}

7. 레거시 ACL 토큰을 새 ACL 시스템으로 마이그레이션하세요.

이 단계는 1.6.x보다 높은 버전으로 업그레이드하기 전에 반드시 완료해야 합니다.

업그레이드 후 구성 변경 (Post-Upgrade Configuration Changes)

1.4.0 이전 버전의 Consul에서 이동할 때 ACL 관련 구성 옵션 중 여러 개가 이름이 바뀌었음을 알 수 있습니다. 1.6.x 릴리스 시리즈에서는 이전 버전과의 호환성이 유지되므로 기존 구성 옵션은 업그레이드 후에도 계속 작동하지만, 더 새 버전으로 이동할 때 문제를 피하려면 지금 업데이트하고 싶을 것입니다.

다음은 변경해야 할 사항입니다:

• acl_datacenter는 이제 primary_datacenter로 이름이 바뀌었습니다(docs 검토).
• acl_default_policy, acl_down_policy, acl_ttl, acl_*_token 및 enable_acl_replication 옵션은 이제 다음과 같이 지정됩니다(docs 검토):

acl {
  enabled                  = true/false
  default_policy           = "..."
  down_policy              = "..."
  policy_ttl               = "..."
  role_ttl                 = "..."
  enable_token_replication = true/false
  enable_token_persistence = true/false
  tokens {
    master       = "..."
    agent        = "..."
    agent_master = "..."
    replication  = "..."
    default      = "..."
  }
}

기존 구성 파일을 복사하고 변경한 다음 consul validate $CONFIG_FILE1_PATH $CONFIG_FILE2_PATH ...를 사용하여 검증하여 구성 변경이 유효한지 확인할 수 있습니다.

구성이 검증 검사를 통과하면 이전 구성 파일을 새 구성 파일로 교체하고 각 데이터센터에서 리더 에이전트를 마지막으로 남겨두고 한 번에 하나의 서버로 클러스터를 천천히 다시 롤링하세요.

더 알아보기 (Learn more)

• General Upgrade Process
• Specific Version Details
• Upgrading Legacy ACL tokens