버전 1.3.6으로 업그레이드 개요
Apigee Hybrid 업그레이드 절차는 다음과 같은 섹션으로 정리됩니다.
- 준비
- 서비스 계정 만들기 및 업데이트
- 환경 그룹 계획
- 재정의 파일 복사 및 업데이트
- Istio 및 cert-manager 업그레이드
- Hybrid 런타임 버전 1.3 설치
- 삭제
선행 조건
- Apigee Hybrid 버전 1.2 이전 버전에서 업데이트하는 경우 Apigee Hybrid를 버전 1.2로 업그레이드에 대한 안내를 참조하세요.
준비
- (권장사항) 버전 1.2
$APIGEECTL_HOME/
디렉터리의 백업 사본을 만듭니다. 예를 들면 다음과 같습니다.tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME
- (권장사항) Cassandra 백업 및 복구의 안내에 따라 Cassandra 데이터베이스를 백업합니다.
- Kubernetes 플랫폼을 다음과 같이 업그레이드합니다. 도움이 필요하면 플랫폼 문서를 참조하세요.
플랫폼 업그레이드할 버전 GKE 1.15.x Anthos 1.5 AKS 1.16.x(Anthos 연결 클러스터 사용) - Hybrid 설치에서 Apigee Connect를 사용하지 않는 경우 Apigee Connect를 사용 설정합니다.
- Apigee Connect API가 사용 설정되었는지 확인합니다.
gcloud services list | grep apigeeconnect apigeeconnect.googleapis.com Apigee Connect API
- 사용 설정되지 않았다면 Apigee Connect API를 사용 설정합니다.
gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID
여기서 $PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
-
다음 예시와 같이 명령줄에서
gcloud
인증 사용자 인증 정보를 가져옵니다.TOKEN=$(gcloud auth print-access-token)
토큰이 입력되었는지 확인하려면 다음 예시와 같이
echo
를 사용합니다.echo $TOKEN
그러면 토큰이 인코딩된 문자열로 표시됩니다.
자세한 내용은 gcloud 명령줄 도구 개요를 참조하세요.
- 조직에서 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가 사용 설정된 것입니다.
- 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
- 다음 명령어를 사용하여 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" }
- Apigee Connect API가 사용 설정되었는지 확인합니다.
apigee-watcher
서비스 계정을 만듭니다. Apigee Watcher는 v1.3에서 도입된 새로운 서비스 계정입니다. 조직 수준의 변경사항에 대한 동기화 담당자를 살피고 이러한 변경사항을 적용하여 Istio 인그레스를 구성합니다.기본 Hybrid 디렉터리에서 다음을 실행합니다.
./tools/create-service-account apigee-watcher ./service-accounts
- 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 ...
- 라우팅할 환경 그룹을 계획합니다.
Apigee Hybrid 1.3은
routingRules
대신 환경 그룹을 사용하여 기본 경로 라우팅을 관리합니다. Hybrid 구성에서routingRules
를 사용하는 경우 라우팅을 복제하기 위해 환경 그룹을 설계합니다.환경 그룹을 하나 이상 만들어야 합니다.
환경 그룹 정보를 참조하세요.
- 재정의 파일을 업데이트합니다.
- 재정의 파일의 사본을 만듭니다.
- gcp 및 k8sCluster 스탠자를 업데이트합니다.
다음 구성 속성은 Hybrid 버전 1.3에서 교체되었습니다.
gcpRegion
이gcp:region
으로 변경gcpProjectID
이gcp:projectID
으로 변경gcpProjectIDRuntime
이gcp:gcpProjectIDRuntime
으로 변경k8sClusterName
이k8s:clusterName
으로 변경k8sClusterRegion
이k8s: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
- 재정의 파일에 이미 고유한 인스턴스 식별자가 없는 경우 하나를 추가합니다.
# unique identifier for this installation. 63 chars length limit instanceID: ID
여기에서 ID는 '
my-hybrid-131-installation
' 또는 'acmecorp-hybrid-131
'과 같이 Hybrid 설치에 대한 고유 식별자입니다. - 감시자(
apigee-watcher
) 서비스 계정을 재정의 파일에 추가합니다.# Note: the SA should have the "Apigee Runtime Agent" role watcher: serviceAccountPath: "service account file"
- 측정항목(
apigee-metrics
) 서비스 계정을 재정의 파일에 추가합니다.metrics: serviceAccountPath: "service account file"
virtualhosts:
스탠자를 업데이트하여routingRules
를 환경 그룹으로 바꿉니다.-name:
이름을 환경 그룹의 이름으로 바꿉니다. 각 환경 그룹에 하나씩 여러 개의 이름 항목을 포함할 수 있습니다.hostAliases:[]
이 줄을 삭제합니다.sslCertPath:
및sslKeyPath:
항목을 유지하거나 추가합니다.- 모든
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
mart
및connectAgent:
스탠자를 업데이트합니다.mart:
아래의hostAlias:
,sslCertPath:
,sslKeyPath:
항목을 삭제합니다.connectAgent:
스탠자를 추가합니다.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 이상으로 업그레이드
- 다운타임을 최소화하기 위해 Istio 배포와 HPA에는 각각 복제본이 2개 이상 있어야 합니다.
다음 명령어를 실행하여 복제본 수를 결정합니다.
kubectl -n istio-system get deployments # list of deployments
kubectl -n istio-system get hpa # list of hpa
- 복제본이 하나만 있는 각 배포를 수정하고
replicas:
를2
개 이상으로 늘립니다.kubectl -n istio-system edit deployment name
예를 들면 다음과 같습니다.
spec: progressDeadlineSeconds: 600 replicas: 2
- 복제본이 하나만 있는 각 HPA를 수정하고
minReplicas:
를2
개 이상으로 늘립니다.kubectl -n istio-system edit hpa name
예를 들면 다음과 같습니다.
spec: maxReplicas: 5 minReplicas: 2
- ASM 다운로드 및 설치의 설치 안내에 따라 ASM을 다운로드 및 설치합니다.
- 설치 후에는 버전 명령어를 실행하여 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 업그레이드
- 현재 cert-manager 배포를 삭제합니다.
kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook
- Kubernetes 버전을 확인합니다.
kubectl version
- 다음 명령어를 실행하여 Jetstack에서 cert-manager를 설치합니다.
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml
Hybrid 런타임 설치
- 변수에 최신 버전 번호를 저장합니다.
export VERSION=$(curl -s \ https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
- 변수가 버전 번호로 채워져 있는지 확인합니다. 다른 버전을 사용하려면 해당 버전을 대신 환경 변수에 저장하면 됩니다. 예를 들면 다음과 같습니다.
echo $VERSION 1.3.6
사용 중인 운영체제에 해당하는 출시 패키지를 다운로드합니다.
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
- 현재
apigeectl/
디렉터리의 이름을 백업 디렉터리 이름으로 바꿉니다. 예를 들면 다음과 같습니다.mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/
-
다운로드한 gzip 파일 콘텐츠를 Hybrid 기본 디렉터리에 추출합니다. 예를 들면 다음과 같습니다.
tar xvzf filename.tar.gz -C hybrid-base-directory
cd
명령어를 사용하여 기본 디렉터리로 이동합니다.-
tar 콘텐츠는 기본적으로 이름에 해당 버전과 플랫폼이 포함된 디렉터리로 확장됩니다(예:
./apigeectl_1.0.0-f7b96a8_linux_64
). 이 디렉터리의 이름을apigeectl
로 바꿉니다.mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
apigee-system
에서apigee-resources-install
작업을 삭제합니다.kubectl -n apigee-system delete job apigee-resources-install
- 이전 CRD를 삭제합니다.
kubectl delete crd apigeetelemetries.apigee.cloud.google.com
externalSeedHost
속성을 사용하여 재정의 파일의cassandra:
스탠자를 업데이트합니다. 이 속성은 새 Hybrid 버전 1.3.6 설치에서 버전 1.2 설치와 동일한 Kubernetes 클러스터를 사용하도록 도와줍니다. 이 단계는 일회성으로 Hybrid 버전 1.2에서 버전 1.3.6 이상으로 업그레이드하는 경우에만 필요합니다.- 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
externalSeedHost
속성 값을 추가합니다.cassandra: externalSeedHost: Cassandra_node_IP
여기서 Cassandra_node_IP는 cassandra 노드의 IP입니다(앞의 예시에서
10.68.8.24
).
- 1.2.0 설치를 업그레이드하는 동일한 Kubernetes 클러스터에서 기존 Cassandra의 IP 주소 중 하나를 찾습니다.
- 새
apigeectl/
디렉터리에서apigeectl init
,apigeectl apply
,apigeectl check-ready
를 실행합니다.- Hybrid 1.3.6을 초기화합니다.
apigeectl init -f overrides_1.3.yaml
여기서 overrides_1.3.yaml은 편집된 override.yaml 파일입니다.
- Hybrid 버전 1.3에서
--dry-run
플래그의 구문은 실행 중인kubectl
버전에 따라 다릅니다.kubectl
의 버전을 확인합니다.gcloud version
- 테스트 실행으로 오류가 있는지 확인합니다.
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
- 재정의를 적용합니다. 설치에 따라 프로덕션 환경 또는 데모/실험용 환경의 안내를 선택하여 따릅니다.
프로덕션
프로덕션 환경의 경우 각 하이브리드 구성요소를 개별적으로 업그레이드하고 다음 구성요소로 진행하기 전에 업그레이드된 구성요소의 상태를 확인해야 합니다.
- 재정의를 적용하여 Cassandra를 업그레이드합니다.
apigeectl apply -f overrides_1.3.yaml --datastore
- 완료를 확인합니다.
kubectl -n namespace get pods
여기서 namespace는 Apigee Hybrid 네임스페이스입니다.
포드가 준비된 경우에만 다음 단계로 진행합니다.
- 재정의를 적용하여 원격 분석 구성요소를 업그레이드하고 완료를 확인합니다.
apigeectl apply -f overrides_1.3.yaml --telemetry
kubectl -n namespace get pods
- 재정의를 적용하여 조직 수준 구성요소(MART, Watcher, Apigee Connect)를 업그레이드하고 완료를 확인합니다.
apigeectl apply -f overrides_1.3.yaml --org
kubectl -n namespace get pods
- 재정의를 적용하여 환경을 업그레이드합니다. 다음 두 가지 중에서 선택할 수 있습니다.
- 한 번에 하나의 환경에 재정의를 적용하고 완료를 확인합니다. 환경마다 이 단계를 반복합니다.
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
- 한 번에 하나의 환경에 재정의를 적용하고 완료를 확인합니다. 환경마다 이 단계를 반복합니다.
데모/실험용
대부분의 데모 또는 실험용 환경에서는 모든 구성요소에 재정의를 한 번에 적용할 수 있습니다. 데모/실험용 환경의 규모가 크고 복잡하거나 프로덕션 환경을 비슷하게 모방하는 경우 프로덕션 환경 업그레이드 안내를 참조하세요.
apigeectl apply -f overrides_1.3.yaml
- 상태를 파악합니다.
apigeectl check-ready -f overrides_1.3.yaml
자세한 내용은 GKE Hybrid 설정 - 5단계: GKE에 Hybrid 설치를 참조하세요.
- 재정의를 적용하여 Cassandra를 업그레이드합니다.
- 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
값을 확인합니다. - 모든 포드가 실행되면 재정의 파일에서
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.2.0 virtualHost 라우팅 세부정보를 삭제합니다.
$APIGEECTL_HOME-v1.2/apigeectl delete -s virtualhost -f 1.2.0_overrides.yaml
여기서 $APIGEECTL_HOME-v1.2는
apigeectl
버전 1.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 인스턴스 사용 중단
cd
를 사용해 새로 설치된apigeectl
디렉터리로 이동합니다.tools/cas_cleanup.sh
스크립트를 실행합니다.이 스크립트는 Cassandra 링에서 이전 Cassandra 포드를 사용 중지하고 이전 STS를 삭제하며 PVC를 삭제합니다.
bash cas_cleanup.sh Apigee namespace
Istio 버전 1.4.6 리소스 삭제
- 다음 명령어를 실행하여 가장 최근의 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)'
- 다음 명령어를 실행하여 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으로 성공적으로 업그레이드되었습니다.
- Hybrid 1.3.6을 초기화합니다.