Apigee Hybrid를 버전 1.3.6으로 업그레이드

버전 1.3.6으로 업그레이드 개요

Apigee Hybrid 업그레이드 절차는 다음과 같은 섹션으로 정리됩니다.

  1. 준비
    1. 서비스 계정 만들기 및 업데이트
    2. 환경 그룹 계획
    3. 재정의 파일 복사 및 업데이트
  2. Istio 및 cert-manager 업그레이드
  3. Hybrid 런타임 버전 1.3 설치
  4. 삭제

기본 요건

준비

  1. (권장사항) 버전 1.2 $APIGEECTL_HOME/ 디렉터리의 백업 사본을 만듭니다. 예를 들면 다음과 같습니다.
    tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME
  2. (권장사항) Cassandra 백업 및 복구의 안내에 따라 Cassandra 데이터베이스를 백업합니다.
  3. Kubernetes 플랫폼을 다음과 같이 업그레이드합니다. 도움이 필요하면 플랫폼 문서를 참조하세요.
    플랫폼 업그레이드할 버전
    GKE 1.15.x
    Anthos 1.5
    AKS 1.16.x(Anthos 연결 클러스터 사용)
  4. Hybrid 설치에서 Apigee Connect를 사용하지 않는 경우 Apigee Connect를 사용 설정합니다.
    1. Apigee Connect API가 사용 설정되었는지 확인합니다.
      gcloud services list | grep apigeeconnect
      
      apigeeconnect.googleapis.com         Apigee Connect API
    2. 사용 설정되지 않았다면 Apigee Connect API를 사용 설정합니다.
      gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID

      여기서 $PROJECT_ID는 Google Cloud 프로젝트 ID입니다.

    3. 다음 예시와 같이 명령줄에서 gcloud 인증 사용자 인증 정보를 가져옵니다.

      TOKEN=$(gcloud auth print-access-token)

      토큰이 입력되었는지 확인하려면 다음 예시와 같이 echo를 사용합니다.

      echo $TOKEN

      그러면 토큰이 인코딩된 문자열로 표시됩니다.

      자세한 내용은 gcloud 명령줄 도구 개요를 참조하세요.

    4. 조직에서 Apigee Connect가 사용 설정되어 있는지 확인합니다.
      curl -H "Authorization: Bearer $TOKEN" \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

      여기서 $ORG_NAME은 조직의 ID입니다.

      출력에 다음이 포함되었다면

            "name" : "features.mart.connect.enabled",
            "value" : "true"

      Apigee Connect가 사용 설정된 것입니다.

    5. Apigee Connect가 사용 설정되지 않은 경우 Apigee Connect 에이전트 역할을 MART 서비스 계정에 할당합니다.
      gcloud projects add-iam-policy-binding $PROJECT_ID \
        --member serviceAccount:apigee-mart@$PROJECT_ID.iam.gserviceaccount.com \
        --role roles/apigeeconnect.Agent
    6. 다음 명령어를 사용하여 Apigee Connect를 사용 설정합니다.
      curl -H "Authorization: Bearer $TOKEN" -X PUT \
        -H "Content-Type: application/json" \
        -d '{
          "name" : "'"$ORG_NAME"'",
          "properties" : {
            "property" : [ {
              "name" : "features.hybrid.enabled",
              "value" : "true"
            }, {
              "name" : "features.mart.connect.enabled",
              "value" : "true"
            } ]
          }
        }' \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"
      

      출력에 다음 두 속성이 포함되면 Apigee Connect가 성공적으로 사용 설정된 것입니다.

            {
              "name": "features.mart.connect.enabled",
              "value": "true"
            },
            {
              "name": "features.hybrid.enabled",
              "value": "true"
            }
      
  5. apigee-watcher 서비스 계정을 만듭니다. Apigee Watcher는 v1.3에서 도입된 새로운 서비스 계정입니다. 조직 수준의 변경사항에 대한 동기화 담당자를 살피고 이러한 변경사항을 적용하여 Istio 인그레스를 구성합니다.

    기본 Hybrid 디렉터리에서 다음을 실행합니다.

    ./tools/create-service-account apigee-watcher ./service-accounts
  6. Apigee 런타임 에이전트 역할을 감시자 서비스 계정에 할당합니다.
    gcloud projects add-iam-policy-binding $PROJECT_ID \
      --member serviceAccount:apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com \
      --role roles/apigee.runtimeAgent

    여기서 PROJECT_ID는 Google Cloud 프로젝트 ID입니다. 서비스 계정 이메일 주소가 이 패턴과 다른 경우 적절하게 변경합니다.

    출력에는 다음을 포함한 모든 서비스 계정과 역할의 목록이 포함되어야 합니다.

      ...
    - members:
      - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
      role: roles/apigee.runtimeAgent
      ...
  7. 라우팅할 환경 그룹을 계획합니다. Apigee Hybrid 1.3은 routingRules 대신 환경 그룹을 사용하여 기본 경로 라우팅을 관리합니다. Hybrid 구성에서 routingRules를 사용하는 경우 라우팅을 복제하기 위해 환경 그룹을 설계합니다.

    환경 그룹을 하나 이상 만들어야 합니다.

    환경 그룹 정보를 참조하세요.

  8. 재정의 파일을 업데이트합니다.
    1. 재정의 파일의 사본을 만듭니다.
    2. gcpk8sCluster 스탠자를 업데이트합니다.

      다음 구성 속성은 Hybrid 버전 1.3에서 교체되었습니다.

      • gcpRegiongcp:region으로 변경
      • gcpProjectIDgcp:projectID으로 변경
      • gcpProjectIDRuntimegcp:gcpProjectIDRuntime으로 변경
      • k8sClusterNamek8s:clusterName으로 변경
      • k8sClusterRegionk8s:clusterRegion으로 변경

      예를 들어 다음 구조를

      gcpRegion: gcp region
      gcpProjectID: gcp project ID
      gcpProjectIDRuntime: gcp project ID
      
      k8sClusterName: name
      k8sClusterRegion: region

      다음과 같이 바꿉니다.

      gcp:
       projectID: gcp project ID
       region: gcp region
       gcpProjectIDRuntime: gcp project ID # optional. This is only required if you
                                             # want logger/metrics data to be sent in
                                             # different gcp project.
      
      k8sCluster:
       name: gcp project ID
       region: gcp region
      
    3. 재정의 파일에 이미 고유한 인스턴스 식별자가 없는 경우 하나를 추가합니다.
      # unique identifier for this installation. 63 chars length limit
      instanceID: ID

      여기에서 ID는 'my-hybrid-131-installation' 또는 'acmecorp-hybrid-131'과 같이 Hybrid 설치에 대한 고유 식별자입니다.

    4. 감시자(apigee-watcher) 서비스 계정을 재정의 파일에 추가합니다.
      # Note: the SA should have the "Apigee Runtime Agent" role
      watcher:
       serviceAccountPath: "service account file"
    5. 측정항목(apigee-metrics) 서비스 계정을 재정의 파일에 추가합니다.
      metrics:
       serviceAccountPath: "service account file"
    6. virtualhosts: 스탠자를 업데이트하여 routingRules를 환경 그룹으로 바꿉니다.
      1. -name: 이름을 환경 그룹의 이름으로 바꿉니다. 각 환경 그룹에 하나씩 여러 개의 이름 항목을 포함할 수 있습니다.
      2. hostAliases:[] 이 줄을 삭제합니다.
      3. sslCertPath:sslKeyPath: 항목을 유지하거나 추가합니다.
      4. 모든 routingRules 항목을 삭제합니다.

      예를 들면 다음이

      virtualhosts:
        - name: default
          hostAliases:
            - "*.acme.com"
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key
          routingRules:
            - paths:
              - /foo
              - /bar
            - env: my-environment

      다음과 같이 바뀝니다.

      virtualhosts:
        - name: example-env-group
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key
    7. martconnectAgent: 스탠자를 업데이트합니다.
      1. mart: 아래의 hostAlias:, sslCertPath:, sslKeyPath: 항목을 삭제합니다.
      2. connectAgent: 스탠자를 추가합니다.
      3. connectAgent: 아래에 serviceAccountPath: 항목을 추가하고 Apigee Connect Agent 역할이 할당된 서비스 계정 파일의 경로를 제공합니다(일반적으로 MART 서비스 계정).

      예를 들면 다음이

      mart:
        hostAlias: "mart.apigee-hybrid-docs.net"
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
        sslCertPath: ./certs/fullchain.pem
        sslKeyPath: ./certs/privkey.key

      다음과 같이 바뀝니다.

      mart:
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
      
      connectAgent:
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json

Istio 및 cert-manager 업그레이드

Apigee Hybrid 버전 1.3에서는 cert-manager v0.14.2를 사용하여 인증서를 관리 및 확인하고, Anthos Service Mesh(ASM) 버전 1.5.7 이상과 함께 제공된 Istio 배포를 사용하여 런타임 인그레스 게이트웨이를 생성 및 관리해야 합니다.

Istio 1.4.6을 ASM 1.5.7 이상으로 업그레이드

  1. 다운타임을 최소화하기 위해 Istio 배포와 HPA에는 각각 복제본이 2개 이상 있어야 합니다. 다음 명령어를 실행하여 복제본 수를 결정합니다.
    kubectl -n istio-system get deployments # list of deployments
    kubectl -n istio-system get hpa # list of hpa
  2. 복제본이 하나만 있는 각 배포를 수정하고 replicas:2개 이상으로 늘립니다.
    kubectl -n istio-system edit deployment name

    예:

    spec:
      progressDeadlineSeconds: 600
      replicas: 2
  3. 복제본이 하나만 있는 각 HPA를 수정하고 minReplicas:2개 이상으로 늘립니다.
    kubectl -n istio-system edit hpa name

    예를 들면 다음과 같습니다.

    spec:
      maxReplicas: 5
      minReplicas: 2
    
  4. ASM 다운로드 및 설치의 설치 안내에 따라 ASM을 다운로드 및 설치합니다.
  5. 설치 후에는 버전 명령어를 실행하여 1.5.x가 올바르게 설치되었는지 확인합니다.
    ./bin/istioctl version
    
    client version: 1.5.8-asm.0
    apigee-mart-ingressgateway version:
    citadel version: 1.4.6
    galley version: 1.4.6
    ingressgateway version: 1.5.8-asm.0
    pilot version: 1.4.6
    policy version: 1.4.6
    sidecar-injector version: 1.4.6
    telemetry version: 1.4.6
    pilot version: 1.5.8-asm.0
    data plane version: 1.4.6 (1 proxies), 1.5.8-asm.0 (2 proxies)

cert-manager 업그레이드

  1. 현재 cert-manager 배포를 삭제합니다.
    kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook
  2. Kubernetes 버전을 확인합니다.
    kubectl version
  3. 다음 명령어를 실행하여 Jetstack에서 cert-manager를 설치합니다.
    kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml 

Hybrid 런타임 설치

  1. 변수에 최신 버전 번호를 저장합니다.
    export VERSION=$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
  2. 변수가 버전 번호로 채워져 있는지 확인합니다. 다른 버전을 사용하려면 해당 버전을 대신 환경 변수에 저장하면 됩니다. 예를 들면 다음과 같습니다.
    echo $VERSION
      1.3.6
  3. 사용 중인 운영체제에 해당하는 출시 패키지를 다운로드합니다.

    Mac 64비트:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_64.tar.gz

    Linux 64비트:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_64.tar.gz

    Mac 32비트:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_32.tar.gz

    Linux 32비트:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz
  4. 현재 apigeectl/ 디렉터리의 이름을 백업 디렉터리 이름으로 바꿉니다. 예를 들면 다음과 같습니다.
    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 
  5. 다운로드한 gzip 파일 콘텐츠를 Hybrid 기본 디렉터리에 추출합니다. 예를 들면 다음과 같습니다.

    tar xvzf filename.tar.gz -C hybrid-base-directory
  6. cd 명령어를 사용하여 기본 디렉터리로 이동합니다.
  7. tar 콘텐츠는 기본적으로 이름에 해당 버전과 플랫폼이 포함된 디렉터리로 확장됩니다(예: ./apigeectl_1.0.0-f7b96a8_linux_64). 이 디렉터리의 이름을 apigeectl로 바꿉니다.

    mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
  8. apigee-system에서 apigee-resources-install 작업을 삭제합니다.
    kubectl -n apigee-system delete job apigee-resources-install
  9. 이전 CRD를 삭제합니다.
    kubectl delete crd apigeetelemetries.apigee.cloud.google.com
  10. externalSeedHost 속성을 사용하여 재정의 파일의 cassandra: 스탠자를 업데이트합니다. 이 속성은 새 Hybrid 버전 1.3.6 설치에서 버전 1.2 설치와 동일한 Kubernetes 클러스터를 사용하도록 도와줍니다. 이 단계는 일회성으로 Hybrid 버전 1.2에서 버전 1.3.6 이상으로 업그레이드하는 경우에만 필요합니다.
    1. 1.2.0 설치를 업그레이드하는 동일한 Kubernetes 클러스터에서 기존 Cassandra의 IP 주소 중 하나를 찾습니다.
      kubectl -n namespace get pods -o wide

      여기서 namespace는 Apigee Hybrid 네임스페이스입니다.

      Cassandra 노드의 IP 주소를 기록해 둡니다. 예를 들면 다음과 같습니다.

      kubectl -n apigee get pods -o wide
      NAME                  READY   STATUS    RESTARTS   AGE   IP          NODE
      apigee-cassandra-0    1/1     Running   0          33d   10.68.8.24   gke-example-cluster-rc5-apigee-data-c8bf1234-09kc
      apigee-cassandra-1    1/1     Running   0          16d   10.68.8.33   gke-example-cluster-rc5-apigee-data-c9221ee7-10kc
      apigee-cassandra-2    1/1     Running   0          23h   10.68.9.11   gke-example-cluster-rc5-apigee-data-d123e456-11kc
    2. externalSeedHost 속성 값을 추가합니다.
      cassandra:
       externalSeedHost: Cassandra_node_IP

      여기서 Cassandra_node_IP는 cassandra 노드의 IP입니다(앞의 예시에서 10.68.8.24).

  11. apigeectl/ 디렉터리에서 apigeectl init, apigeectl apply, apigeectl check-ready를 실행합니다.
    1. Hybrid 1.3.6을 초기화합니다.
      apigeectl init -f overrides_1.3.yaml

      여기서 overrides_1.3.yaml은 편집된 override.yaml 파일입니다.

    2. Hybrid 버전 1.3에서 --dry-run 플래그의 구문은 실행 중인 kubectl 버전에 따라 다릅니다. kubectl의 버전을 확인합니다.
      gcloud version
    3. 테스트 실행으로 오류가 있는지 확인합니다.

      kubectl 버전 1.17 이하:

      apigeectl apply -f overrides_1.3.yaml --dry-run=true

      kubectl 버전 1.18 이상:

      apigeectl apply -f overrides_1.3.yaml --dry-run=client
    4. 재정의를 적용합니다. 설치에 따라 프로덕션 환경 또는 데모/실험용 환경의 안내를 선택하여 따릅니다.

      프로덕션

      프로덕션 환경의 경우 각 하이브리드 구성요소를 개별적으로 업그레이드하고 다음 구성요소로 진행하기 전에 업그레이드된 구성요소의 상태를 확인해야 합니다.

      1. 재정의를 적용하여 Cassandra를 업그레이드합니다.
        apigeectl apply -f overrides_1.3.yaml --datastore
      2. 완료를 확인합니다.
        kubectl -n namespace get pods

        여기서 namespace는 Apigee Hybrid 네임스페이스입니다.

        포드가 준비된 경우에만 다음 단계로 진행합니다.

      3. 재정의를 적용하여 원격 분석 구성요소를 업그레이드하고 완료를 확인합니다.
        apigeectl apply -f overrides_1.3.yaml --telemetry
        kubectl -n namespace get pods
      4. 재정의를 적용하여 조직 수준 구성요소(MART, Watcher, Apigee Connect)를 업그레이드하고 완료를 확인합니다.
        apigeectl apply -f overrides_1.3.yaml --org
        kubectl -n namespace get pods
      5. 재정의를 적용하여 환경을 업그레이드합니다. 다음 두 가지 중에서 선택할 수 있습니다.
        • 한 번에 하나의 환경에 재정의를 적용하고 완료를 확인합니다. 환경마다 이 단계를 반복합니다.
          apigeectl apply -f overrides_1.3.yaml --env env_name
          kubectl -n namespace get pods

          여기서 env_name은 업그레이드하는 환경의 이름입니다.

        • 한 번에 모든 환경에 재정의를 적용하고 완료 여부를 확인합니다.
          apigeectl apply -f overrides_1.3.yaml --all-envs
          kubectl -n namespace get pods

      데모/실험용

      대부분의 데모 또는 실험용 환경에서는 모든 구성요소에 재정의를 한 번에 적용할 수 있습니다. 데모/실험용 환경의 규모가 크고 복잡하거나 프로덕션 환경을 비슷하게 모방하는 경우 프로덕션 환경 업그레이드 안내를 참조하세요.

      1. apigeectl apply -f overrides_1.3.yaml
      2. 상태를 파악합니다.
        apigeectl check-ready -f overrides_1.3.yaml

      자세한 내용은 GKE Hybrid 설정 - 5단계: GKE에 Hybrid 설치를 참조하세요.

    5. Hybrid 1.3을 설정하고 실행한 후에는 모든 Cassandra 노드(이전 노드 및 새 노드)가 동일한 Cassandra 클러스터에 포함되는지 확인합니다. Cassandra 노드 중 하나에서 다음 명령어를 실행합니다.
      kubectl -n namespace get pods
      kubectl -n namespace exec old Cassandra pod -- nodetool status

      다음 출력 예시에서 10.68.8.24는 버전 1.2.0에서 비롯된 것이며 externalSeedHost로 사용한 노드 IP입니다. 10.68.7.11은 버전 1.3.6에서 비롯된 것입니다.

      Datacenter: dc-1
      ================
      Status=Up/Down
      |/ State=Normal/Leaving/Joining/Moving
      --  Address     Load        Tokens       Owns (effective)  Host ID                               Rack
      UN  10.68.8.24  379.41 KiB  256          50.8%             11bbd43b-af64-464b-a96d-0d6dd0521de1  ra-1
      UN  10.68.7.11  1.35 MiB    256          49.2%             0b4d9e08-f353-413a-b4a9-7d18a8d07e58  ra-1

      같은 클러스터에 있지 않은 경우 externalSeedHost 값을 확인합니다.

    6. 모든 포드가 실행되면 재정의 파일에서 externalSeedHost를 제거하고 --datastore 옵션을 사용하여 apigeectl apply를 다시 실행합니다.
      apigeectl apply --datastore -f overrides_1.3.6.yaml

    삭제

    모든 포드가 정상이고 ASM 엔드포인트가 새 설치에 유효함을 확인한 후 삭제할 수 있습니다.

    • Hybrid 1.2 리소스
    • 이전 Cassandra 인스턴스
    • Istio 1.4.6 리소스

    Hybrid 1.2.0 리소스 삭제

    1. 1.2.0 virtualHost 라우팅 세부정보를 삭제합니다.
      $APIGEECTL_HOME-v1.2/apigeectl delete -s virtualhost -f 1.2.0_overrides.yaml

      여기서 $APIGEECTL_HOME-v1.2apigeectl 버전 1.2 디렉터리를 백업한 디렉터리입니다.

    2. 엔드포인트가 계속 정상적으로 작동하고 있고 1.3.0 구성요소가 모두 작동 중임을 확인한 경우 다음 명령어를 실행하여 Hybrid 1.2.0 리소스를 삭제합니다.
      $APIGEECTL_HOME-v1.2/apigeectl delete -c "mart,connect-agent,synchronizer,runtime,udca,metrics,logger" \
        -f 1.2.0_overrides.yaml

    이전 Cassandra 인스턴스 사용 중단

    1. cd를 사용해 새로 설치된 apigeectl 디렉터리로 이동합니다.
    2. tools/cas_cleanup.sh 스크립트를 실행합니다.

      이 스크립트는 Cassandra 링에서 이전 Cassandra 포드를 사용 중지하고 이전 STS를 삭제하며 PVC를 삭제합니다.

      bash cas_cleanup.sh Apigee namespace

    Istio 버전 1.4.6 리소스 삭제

    1. 다음 명령어를 실행하여 가장 최근의 Istio v.1.4.6 리소스를 삭제합니다.
      kubectl delete all -n istio-system --selector \
        'app in (apigee-mart-istio-ingressgateway, galley, security, istio-nodeagent, istio-mixer, sidecarInjectorWebhook, istio-mixer)'
    2. 다음 명령어를 실행하여 Istio 1.4.6 설치에서 이전 작업을 삭제합니다.
      kubectl -n istio-system delete job istio-init-crd-10-1.4.6
      kubectl -n istio-system delete job istio-init-crd-11-1.4.6
      kubectl -n istio-system delete job istio-init-crd-14-1.4.6

    수고하셨습니다. Apigee Hybrid 버전 1.3.6으로 성공적으로 업그레이드되었습니다.