6) Using the Argo Rollouts as an RESTful API

---

2022.04. 이장재 📧 cine0831@gmail.com 📂 https://github.com/jangjaelee 📒 http://www.awx.kr

---

 

Overview

Argo Rollouts는 API 명세 파일은 제공 하고 있지만, Argo CD와 같이 Swagger UI - REST API Documentation Tool을 지원하고 있지 않습니다.

본 문서는 API 명세서를 브라우저에서 편하게 보기 위해 Swagger UI를 설치하고, Argo Rollouts의 RESTful APIs의 간략한 사용방법을 다룹니다.

💡 시작하기에 앞서 Argo Rollouts의 UI Dashboard가 반드시 설치되어 있어야 하오니 필자의 지난 글 중 Installing Argo Rollouts 설치편을 참조 하시어 UI Dashboard를 활성화(설치)를 해주시기 바랍니다.

Installing Argo Rollouts - Argo Rollouts 설치편

 

🛑 Argo Rollouts의 Swagger UI - Rest API Documentation 기능은 정식으로 제공하는 기능이 아니므로 오류가 있을 수 있으며, Production 환경에서의 사용은 지양하며 모든 책임은 사용자에게 있습니다.

 

Prerequisites

• kubectl command-line tool
• Helm command-line tool
• jq command-line tool
• Argo Rollouts UI Dashboard
• Argo Rollouts Kubectl Plugin

 

Step 1. Swagger UI - REST API Documentation Tool

What is Swagger?

Swagger UI를 설치하기에 앞서 Swagger에 대해서 간략하게 요약 하면, 다음과 같습니다.

• Open Api Specification(OAS)를 위한 Framework
• API들이 가지고 있는 스펙(spec)을 명세, 관리할 수 있는 프로젝트/도구

그중 Swagger UI는 API 사용 방법을 사용자가 브라우저에서 직접 API 호출을 통해 알려주는 대화명 API 도구 입니다.

Step 1.1. Installing Swagger UI

Swagger UI를 설치하기 위해 Helm chart를 추가 및 업데이트 합니다.

$ helm repo add cetic https://cetic.github.io/helm-charts
"cetic" has been added to your repositories

$ helm repo update
...Successfully got an update from the "codecentric" chart repository
Update Complete. ⎈Happy Helming!⎈

Helm chart의 values를 환경에 맞게 정의하여 사용하기 위해 defualt values를 추출 하고, 수정 합니다.

$ helm show values cetic/swaggerui > swagger-ui-values.yaml

추출한 파일 swagger-ui-values.yaml 파일에서swaggerui.jsonUrl : <API 명세파일 위치 Url> 필드와 swaggerui.server.url : <Argo Rollouts UI Dashboard Url> 필드를 본인의 환경에 맞게 수정 합니다.

💡swaggerui.json Url에는 Argo Rollouts의 API 명세파일의 URL(아래 링크)를 넣어주세요.

🔗 https://raw.githubusercontent.com/argoproj/argo-rollouts/master/pkg/apiclient/rollout/rollout.swagger.json

또는 필자의 YAML을 다운 받아 swaggerui.server.url 필드만 수정하여 사용하셔도 됩니다.

$ curl -sOL https://raw.githubusercontent.com/jangjaelee/tutorials-argo-rollouts/main/swagger/swagger-ui-values.yaml

참고로 필자의 YAML 파일을 editor로 열어보면 deployment.extraEnv.value필드를 /swagger-ui으로 사용하고 있으며, 해당 필드는 경로(Path)를 의미 합니다. 기본값은 / 입니다.

helm chart values를 수정이 완료 되었으면 Swagger UI를 설치를 해보겠습니다.

—namespace는 Argo Rollouts이 설치된 네임스페이스명을 입력 하시기 바랍니다.

$ helm install argo-rollouts cetic/swaggerui --namespace argo-rollouts -f swagger-ui-values.yaml
NAME: argo-rollouts-swagger-ui
LAST DEPLOYED: Mon Apr 25 11:50:36 2022
NAMESPACE: argo-rollouts
STATUS: deployedin:#argo-rollouts 
REVISION: 1
TEST SUITE: None
NOTES:
1. Get the application URL by running these commands:
  export NODE_PORT=$(kubectl get --namespace argo-rollouts -o jsonpath="{.spec.ports[0].nodePort}" services argo-rollouts-swaggerui)
  export NODE_IP=$(kubectl get nodes --namespace argo-rollouts -o jsonpath="{.items[0].status.addresses[0].address}")
  echo "swagger-ui URL: http://$NODE_IP:$NODE_PORT"

** Please be patient while the chart is being deployed **

Step 1.2. Connect to Swagger UI

Swagger UI 설치를 완료 했으니 이제 브라우저를 사용하여 접속해보겠습니다.

Helm chart를 사용하여 Swaager UI를 설치하면 기본적으로 Kubernetes의 NodePort를 사용하게 됩니다.

다음 명령을 사용하여 접속 정보를 획득 합니다.

$ export NODE_PORT=$(kubectl get --namespace argo-rollouts -o jsonpath="{.spec.ports[0].nodePort}" services argo-rollouts-swaggerui)

$ export NODE_IP=$(kubectl get nodes --namespace argo-rollouts -o jsonpath="{.items[0].status.addresses[0].address}")

$ echo "swagger-ui URL: http://$NODE_IP:$NODE_PORT"
swagger-ui URL: http://192.168.1.101:31737

Swagger Ui의 URL이 http://192.168.1.101:31737 라는 것을 알 수 있습니다. 브라우저에서 획득한 URL로 접속합니다.

만약, deployment.extraEnv.value를 수정 했다면 Path 까지 입력 해야 합니다.

ex) http://192.168.1.101:31737/swagger-ui/

RolloutService의 API 명세서를 보면 Rollouts의 상태를 볼 수 있는 watch, restart, retry, undo, abort 그리고 canary 및 blue/green 배포 진행시 승인을 위한 promote 등이 지원되는 것을 알 수 있습니다.

Step 1.3. Setting Ingress

💡 Argo Rollouts API로 접속을 하기 위해서는 Argo Rollouts UI Dashboard가 필요하며 UI Dashboard는 필자의 지난 글 Installing Argo Rollouts 편의 UI Dashboard 활성화를 참조하시기 바랍니다.

Installing Argo Rollouts - Argo Rollouts 설치편

 

Service의 NodePort로 Swagger-UI에 접속해서 API 사용방법을 살펴보면 Argo Rollouts의 API 서버가 아닌 Swagger-UI의 Request URL로 표기되며 해당 URL로 API를 호출하면 404 Not Found 에러가 발생합니다.

Swagger-UI에서 접속한 hostname을 사용하기 때문에 발생하는 문제로 Ingress를 사용하여 해결하겠습니다.

Argo Rollout UI Dashboard의 Ingress에서 Swagger-UI 접속을 위한 backend를 추가 합니다.

$ kubectl get ing/argo-rollouts-dashboard -n argo-rollouts -o wide
NAME                      CLASS   HOSTS                 ADDRESS         PORTS     AGE
argo-rollouts-dashboard   nginx   argorollouts.awx.kr   192.168.1.181   80, 443   11d

$ kubectl edit ing/argo-rollouts-dashboard -n argo-rollouts

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
.
.
.
spec:
  ingressClassName: nginx
  rules:
  - host: argorollouts.awx.kr
    http:
      paths:
      - backend:
          service:
            name: argo-rollouts-swaggerui
            port:
              number: 8080
        path: /swagger-ui
        pathType: Prefix
.
.
.

spec.rules.http.paths.backend.service.name 필드는 Swagger UI의 Service Object를 spec.rules.http.paths 필드는 Swagger UI의 URI Path를 사용 합니다.

필자의 경우 접속 호스트로 argorollouts.awx.kr을 사용하였으며, path로 /swagger-ui를 사용하였으로 접속 URL은 http://argorollouts.awx.kr/swagger-ui/ 입니다.

지금까지 Swagger UI 설치를 알아 보았습니다.

   

Step 2. Using REST APIs

이번 단계에서는 Argo Rollouts Service의 REST APIs를 사용하여 아래의 방법들을 알아 보겠습니다.

• 업데이트 - Update Application (rollout.SetImageRequest)
• 승격 - Promote (rollout.PromoteRolloutRequest)
• 재시작 - Restart (rollout.RestartRolloutRequest)
• 복원 - Undo[Rollback] (rollout.UndoRolloutRequest)
• 중단 - Abort (rollout.AbortRolloutRequest)
• 재시도 - Retry (rollout.RetryRolloutRequest)
• 보기 - Watch (rollout.WatchRolloutRequest)

Step 2.1. Deploy a Demo Application

간다한 데모 애플리케이션을 배포 합니다.

# rollout object
$ kubectl apply -f https://raw.githubusercontent.com/jangjaelee/tutorials-argo-rollouts/main/demo/canary/canary-rollout.yaml

# service object for canary-demo
$ kubectl apply -f https://raw.githubusercontent.com/jangjaelee/tutorials-argo-rollouts/main/demo/canary/canary-service.yaml

# service object for canary-demn-preview
$ kubectl apply -f https://raw.githubusercontent.com/jangjaelee/tutorials-argo-rollouts/main/demo/canary/canary-preview-service.yaml

배포한 데모 애플리케이션의 상태를 확인 합니다.

$ kubectl get all,rollouts
NAME                              READY   STATUS    RESTARTS   AGE
pod/canary-demo-6f8b8d584-65hsj   1/1     Running   0          21s
pod/canary-demo-6f8b8d584-68pr7   1/1     Running   0          21s
pod/canary-demo-6f8b8d584-88zmm   1/1     Running   0          21s
pod/canary-demo-6f8b8d584-bsl6p   1/1     Running   0          21s
pod/canary-demo-6f8b8d584-dc4zr   1/1     Running   0          21s

NAME                          TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)   AGE
service/canary-demo           ClusterIP   10.103.189.238   <none>        80/TCP    67s
service/canary-demo-preview   ClusterIP   10.103.248.196   <none>        80/TCP    93s
service/kubernetes            ClusterIP   10.96.0.1        <none>        443/TCP   41d

NAME                                    DESIRED   CURRENT   READY   AGE
replicaset.apps/canary-demo-6f8b8d584   5         5         5       21s

NAME                              DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
rollout.argoproj.io/canary-demo   5         5         5            5           21s

$ kubectl argo rollouts get rollout canary-demo
Name:            canary-demo
Namespace:       default
Status:          ✔ Healthy
Strategy:        Canary
  Step:          8/8
  SetWeight:     100
  ActualWeight:  100
Images:          argoproj/rollouts-demo:blue (stable)
Replicas:
  Desired:       5
  Current:       5
  Updated:       5
  Ready:         5
  Available:     5

NAME                                    KIND        STATUS     AGE   INFO
⟳ canary-demo                           Rollout     ✔ Healthy  101s
└──# revision:1
   └──⧉ canary-demo-6f8b8d584           ReplicaSet  ✔ Healthy  81s   stable
      ├──□ canary-demo-6f8b8d584-4tdq5  Pod         ✔ Running  81s   ready:1/1
      ├──□ canary-demo-6f8b8d584-fdkkc  Pod         ✔ Running  81s   ready:1/1
      ├──□ canary-demo-6f8b8d584-kvmf8  Pod         ✔ Running  81s   ready:1/1
      ├──□ canary-demo-6f8b8d584-n5k76  Pod         ✔ Running  81s   ready:1/1
      └──□ canary-demo-6f8b8d584-zsg8c  Pod         ✔ Running  81s   ready:1/1

컨테이너 이미지 tag가 blue인 데모 애플리케이션이 배포 되었습니다.

Step 2.2. Update Application (rollout.SetImageRequest)

컨테이너 이미지 tag를 blue에서 green으로 업데이트 합니다.

$ curl -s -L -X 'PUT' \
  'https://argorollouts.awx.kr/api/v1/rollouts/default/canary-demo/set/canary-demo/argoproj%2Frollouts-demo/green' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "rollout": "canary-demo",
  "container": "canary-demo",
  "image": "argoproj/rollouts-demo",
  "tag": "green",
  "namespace": "default"
}' | jq

kubectl argo rollouts get rollout canary-demo
Name:            canary-demo
Namespace:       default
Status:          ॥ Paused
Message:         CanaryPauseStep
Strategy:        Canary
  Step:          1/8
  SetWeight:     20
  ActualWeight:  20
Images:          argoproj/rollouts-demo:blue (stable)
                 argoproj/rollouts-demo:green (canary)
Replicas:
  Desired:       5
  Current:       5
  Updated:       1
  Ready:         5
  Available:     5

NAME                                     KIND        STATUS         AGE    INFO
⟳ canary-demo                            Rollout     ॥ Paused       3m33s
├──# revision:2
│  └──⧉ canary-demo-67fc7c4899           ReplicaSet  ✔ Healthy      8s     canary
│     └──□ canary-demo-67fc7c4899-dthw8  Pod         ✔ Running      8s     ready:1/1
└──# revision:1
   └──⧉ canary-demo-6f8b8d584            ReplicaSet  ✔ Healthy      3m13s  stable
      ├──□ canary-demo-6f8b8d584-4tdq5   Pod         ✔ Running      3m13s  ready:1/1
      ├──□ canary-demo-6f8b8d584-fdkkc   Pod         ✔ Running      3m13s  ready:1/1
      ├──□ canary-demo-6f8b8d584-kvmf8   Pod         ✔ Running      3m13s  ready:1/1
      ├──□ canary-demo-6f8b8d584-n5k76   Pod         ◌ Terminating  3m13s  ready:1/1
      └──□ canary-demo-6f8b8d584-zsg8c   Pod         ✔ Running      3m13s  ready:1/1

Canary 전략으로 배포가 진행되고 있으며, Pod 1개를 교체 후 가중치 기반의 정의한 작업 절차에 따라 일지 중지(Paused) 상태를 유지 합니다.

Step 2.3. Promote (rollout.PromoteRolloutRequest)

일시 중지된 배포 단계를 계속 진행 합니다.

curl -s -L -X 'PUT' \
  'https://argorollouts.awx.kr/api/v1/rollouts/default/canary-demo/promote' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "canary-demo",
  "namespace": "default",
  "full": false
}' | jq

$ kubectl argo rollouts get rollout canary-demo
Name:            canary-demo
Namespace:       default
Status:          ◌ Progressing
Message:         more replicas need to be updated
Strategy:        Canary
  Step:          4/8
  SetWeight:     60
  ActualWeight:  50
Images:          argoproj/rollouts-demo:blue (stable)
                 argoproj/rollouts-demo:green (canary)
Replicas:
  Desired:       5
  Current:       5
  Updated:       3
  Ready:         4
  Available:     4

NAME                                     KIND        STATUS               AGE    INFO
⟳ canary-demo                            Rollout     ◌ Progressing        8m9s
├──# revision:2
│  └──⧉ canary-demo-67fc7c4899           ReplicaSet  ◌ Progressing        4m44s  canary
│     ├──□ canary-demo-67fc7c4899-dthw8  Pod         ✔ Running            4m44s  ready:1/1
│     ├──□ canary-demo-67fc7c4899-qtztp  Pod         ✔ Running            14s    ready:1/1
│     └──□ canary-demo-67fc7c4899-nbfmv  Pod         ◌ ContainerCreating  1s     ready:0/1
└──# revision:1
   └──⧉ canary-demo-6f8b8d584            ReplicaSet  ✔ Healthy            7m49s  stable
      ├──□ canary-demo-6f8b8d584-4tdq5   Pod         ✔ Running            7m49s  ready:1/1
      ├──□ canary-demo-6f8b8d584-fdkkc   Pod         ✔ Running            7m49s  ready:1/1
      └──□ canary-demo-6f8b8d584-zsg8c   Pod         ◌ Terminating        7m49s  ready:1/1

$ kubectl argo rollouts get rollout canary-demo
Name:            canary-demo
Namespace:       default
Status:          ✔ Healthy
Strategy:        Canary
  Step:          8/8
  SetWeight:     100
  ActualWeight:  100
Images:          argoproj/rollouts-demo:green (stable)
Replicas:
  Desired:       5
  Current:       5
  Updated:       5
  Ready:         5
  Available:     5

NAME                                     KIND        STATUS        AGE    INFO
⟳ canary-demo                            Rollout     ✔ Healthy     8m47s
├──# revision:2
│  └──⧉ canary-demo-67fc7c4899           ReplicaSet  ✔ Healthy     5m22s  stable
│     ├──□ canary-demo-67fc7c4899-dthw8  Pod         ✔ Running     5m22s  ready:1/1
│     ├──□ canary-demo-67fc7c4899-qtztp  Pod         ✔ Running     52s    ready:1/1
│     ├──□ canary-demo-67fc7c4899-nbfmv  Pod         ✔ Running     39s    ready:1/1
│     ├──□ canary-demo-67fc7c4899-hhh7l  Pod         ✔ Running     26s    ready:1/1
│     └──□ canary-demo-67fc7c4899-mvz5c  Pod         ✔ Running     13s    ready:1/1
└──# revision:1
   └──⧉ canary-demo-6f8b8d584            ReplicaSet  • ScaledDown  8m27s

Step 2.4. Restart (rollout.RestartRolloutRequest)

모든 Pod를 재시작 합니다.

curl -s -L -X 'PUT' \
  'https://argorollouts.awx.kr/api/v1/rollouts/default/canary-demo/restart' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "canary-demo",
  "namespace": "default"
}' | jq

Step 2.5. Undo[Rollback] (rollout.UndoRolloutRequest)

업데이트 이전의 상태로 원복(Undo) 합니다.

curl -s -L -X 'PUT' \
  'https://argorollouts.awx.kr/api/v1/rollouts/default/canary-demo/undo/1' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "rollout": "canary-demo",
  "revision": 1,
  "namespace": "default"
}' | jq

Step 2.6. Abort (rollout.AbortRolloutRequest)

모든 진행을 중단 합니다.

curl -s -L -X 'PUT' \
  'https://argorollouts.awx.kr/api/v1/rollouts/default/canary-demo/abort' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "namespace": "string"
}' | jq

$ kubectl argo rollouts get rollout canary-demo
Name:            canary-demo
Namespace:       default
Status:          ✖ Degraded
Message:         RolloutAborted: Rollout aborted update to revision 3
Strategy:        Canary
  Step:          0/8
  SetWeight:     0
  ActualWeight:  25
Images:          argoproj/rollouts-demo:blue (canary)
                 argoproj/rollouts-demo:green (stable)
Replicas:
  Desired:       5
  Current:       6
  Updated:       1
  Ready:         4
  Available:     4

NAME                                     KIND        STATUS               AGE  INFO
⟳ canary-demo                            Rollout     ✖ Degraded           36m
├──# revision:3
│  └──⧉ canary-demo-6f8b8d584            ReplicaSet  ✔ Healthy            36m  canary
│     ├──□ canary-demo-6f8b8d584-lvwwj   Pod         ✔ Running            45s  ready:1/1
│     ├──□ canary-demo-6f8b8d584-qf7qc   Pod         ◌ Terminating        17s  ready:1/1
│     └──□ canary-demo-6f8b8d584-6sn54   Pod         ◌ Terminating        4s   ready:1/1
└──# revision:2
   └──⧉ canary-demo-67fc7c4899           ReplicaSet  ◌ Progressing        33m  stable
      ├──□ canary-demo-67fc7c4899-8mghs  Pod         ◌ Terminating        16m  ready:1/1
      ├──□ canary-demo-67fc7c4899-dxnfg  Pod         ✔ Running            16m  ready:1/1
      ├──□ canary-demo-67fc7c4899-mdqjt  Pod         ✔ Running            16m  ready:1/1
      ├──□ canary-demo-67fc7c4899-47hz6  Pod         ◌ ContainerCreating  3s   ready:0/1
      ├──□ canary-demo-67fc7c4899-dpds6  Pod         ◌ ContainerCreating  3s   ready:0/1
      └──□ canary-demo-67fc7c4899-nbgqb  Pod         ✔ Running            3s   ready:1/1

Step 2.7. Retry (rollout.RetryRolloutRequest)

실패 또는 중단된 배포를 재시도 합니다.

curl -s -L -X 'PUT' 'https://argorollouts.awx.kr/api/v1/rollouts/default/canary-demo/retry' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "canary-demo",
  "namespace": "default"
}' | jq

Step 2.8. Watch (rollout.WatchRolloutRequest)

kubectl argo rollouts get rollout canary-demo와 동일한 기능으로 REST API를 사용하여 JSON으로 결과를 받습니다.

$ curl -s -L -X 'GET' \
  'https://argorollouts.awx.kr/api/v1/rollouts/default/canary-demo/info/watch' \
  -H 'Content-Type: application/json' \
| jq

지금까지 Argo Rollouts을 REST APIs를 사용하는 방법과 Swagger UI를 사용하여 API 명세서를 보는 방법을 알아 보았습니다.

REST API를 잘 활용하면 CI/CD 파이프라인 구축에 용이하게 사용할 수 있을 듯 합니다.

 

Argo Rollouts Official Website

• Website
  • https://argoproj.github.io
  • https://argoproj.github.io/rollouts
  • https://argoproj.github.io/argo-rollouts/
• GitHub
  • https://github.com/argoproj/argo-rollouts
  • for AppMesh
    • https://github.com/argoproj/argo-rollouts/tree/master/rollout/trafficrouting/appmesh
    • https://github.com/argoproj/argo-rollouts/pull/1606
    • https://github.com/argoproj/argo-rollouts/commit/5f0f8b4558467f5a1a09e7d08057ccf9973c01c7
  • REST API Spec
    • https://raw.githubusercontent.com/argoproj/argo-rollouts/master/pkg/apiclient/rollout/rollout.swagger.json
• Artifact Hub
  • https://artifacthub.io/packages/helm/argo/argo-rollouts
• Slack
  • https://argoproj.github.io/community/join-slack

 

Swagger UI Official Website

• Website
  • https://swagger.io/tools/swagger-ui/
• GitHub
  • https://github.com/swagger-api/swagger-ui
• Artifact Hub
  • https://artifacthub.io/packages/helm/cetic/swaggerui

 

Reference

• https://jjingho.tistory.com/8
• https://velog.io/@jwpark06/Swagger-API-명세-만드는-법-2-웹-문서용-Swagger-ui-사용

 

END