「SAP AI Core 기술 연재」 제4회.

SAP AI Core의 관리 작업 중, Git 리포지토리(Repository) 관리(6.1절)와 애플리케이션 관리(6.2절)를 다룬다. 지난 회차(#3)는 초기 설정(Cloud Foundry/Kyma)을 다루었다. 다음 회차(#5)는 관리②(리소스 그룹·각종 시크릿 관리)를 다룬다.

SAP AI Core에서 사용하는 외부 프로그램·도구용 시크릿(Secret)을 생성함으로써, 인증 정보를 유출하지 않고 이들을 연결할 수 있다.

GitHub·Docker·Amazon Web Services S3 스토리지와 같은 외부 도구를 SAP AI Core와 병용함으로써 버전 관리·컨테이너화·클라우드 스토리지의 이점을 활용할 수 있다. 안정적인 인터넷 연결이 있다면 콘텐츠는 원격에서 이용 가능하다.

관리 작업은 기본적으로 한 번만 수행하는 절차이다. 다만 도구의 추가·삭제 등 필요에 따라 절차를 반복해서 실행할 수 있다.

Note: SAP AI Core 인스턴스를 설정하기 전에, 초기 설정 작업을 완료해 두어야 한다(#3 참조)

또한, GitOps에 의한 템플릿 동기화 메커니즘 자체는 #2 「내부 동작: 동기화와 프로세스 플로우」에서 이미 해설하였다. 본 기사에서는 그 설정을 실제로 수행하는 API 절차를 다룬다.

이후의 curl 예제에서 사용하는 $AI_API_URL 및 $TOKEN 환경 변수 설정은 #3을 참조한다.

자신의 Git 리포지토리를 사용하여 SAP AI Core의 템플릿을 버전 관리할 수 있다. SAP AI Core 인스턴스로의 GitOps 온보딩(Onboarding)은 Git 리포지토리의 설정과 콘텐츠의 동기화로 구성된다.

Git 리포지토리는 퍼스널 액세스 토큰(Personal Access Token, PAT)을 생성하여 SAP AI Core에 등록함으로써 관리한다. PAT는 인증 정보를 유출하지 않고 GitHub 리포지토리로의 접속을 허용·제어하는 수단이다.

Remember: BTP 내의 SAP AI Core 액세스 인증 정보·인증서의 로테이션(Rotation)은 리전 정책에 따라 사용자 자신의 책임으로 수행한다

전제 조건

• 초기 설정이 완료되어 있을 것
• 인터넷을 통해 Git 리포지토리에 접속할 수 있을 것
• Git 리포지토리의 퍼스널 액세스 토큰을 생성했을 것
• GitLab 호스트의 리포지토리를 온보딩하는 경우, 리포지토리 URL에 .git 접미사(Suffix)가 포함되어 있을 것
• 리포지토리 내에 시크릿이 존재하지 않을 것(시크릿이 사용되고 있는 경우, 콘텐츠를 동기화할 수 없다)

시크릿을 포함한 리포지토리를 동기화할 수 없는 것은 단순한 기술적 제약이 아니다. 인증 정보를 Git 관리 하에 두지 않고, 시크릿은 SAP AI Core 측의 메커니즘(#5에서 다룸)으로 관리하게 하기 위한 설계이다. 회피 방법을 찾는 것이 아니라, 시크릿을 리포지토리로부터 분리한다는 전제로 구성을 설계한다.

Note: 리소스를 동기화할 때는 특히 1개 테넌트(Tenant) 내에서 여러 리포지토리 또는 애플리케이션을 사용하는 경우, 이름 충돌이 없는지 확인한다. 동기화 시 문제가 발생하는 경우에는 1개 테넌트당 리포지토리 또는 애플리케이션을 1개만 사용할 것을 권장한다.

이 권장 사항은 #2에서 해설한 리소스의 범위와 관계가 있다. 템플릿(Executable)은 테넌트 레벨의 리소스이며, 테넌트 내의 모든 리소스 그룹에서 공유된다. 즉, 리소스 그룹을 나누더라도 템플릿의 네임스페이스(Namespace)는 나뉘지 않기 때문에, 여러 리포지토리를 동일한 테넌트에 등록하면 이름 충돌이 일어나기 쉽다.

다음의 리포지토리 URL은 모두 동일한 리포지토리로 간주된다.

절차

{{apiurl}}/v2/admin/repositories 엔드포인트에 POST 요청을 전송하고, 인증 정보를 포함한다.

curl --location --request POST "$AI_API_URL/v2/admin/repositories" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
...

파라미터는 다음과 같다.

• url: Git 리포지토리의 URL
• username: Git 리포지토리에 접속하는 (서비스) 사용자
• password: Git의 퍼스널 액세스 토큰

Tip: 2개의 테넌트(Tenant) 간에 리포지토리를 공유하는 경우, 각 테넌트에서 개별적으로 리포지토리를 추가하고 동일한 username과 password를 지정합니다.

서드파티 API 플랫폼을 사용하는 경우에도, 동일한 엔드포인트(Endpoint)에 JSON 형식의 바디(Body)로 POST 요청을 전송합니다.

{{apiurl}}/v2/admin/repositories

엔드포인트에 PATCH 요청을 전송하여 변경 내용을 포함합니다.

curl --location --request PATCH "$AI_API_URL/v2/admin/repositories" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
...

지정하는 파라미터(Parameter)는 추가 시와 동일합니다 (url, username, password).

Note: 공식 문서에서는 Curl 예시는 /v2/admin/repositories로, 서드파티 API 플랫폼 예시는 /v2/admin/repositories/{{repositoryName}}로 엔드포인트 기재 방식이 다릅니다 (후술할 "공식 문서의 기재 불일치" 참조).

URL이 유효하지 않거나 오류를 포함하는 경우, 또는 리포지토리가 더 이상 필요하지 않은 경우, 연결된 Git 리포지토리를 삭제합니다.

삭제 후에는 해당 리포지토리를 애플리케이션의 소스 리포지토리로 선택할 수 없게 됩니다.

curl --location --request DELETE "{{apiurl}}/v2/admin/repositories/{{repositoryName}}"

서드파티 API 플랫폼을 사용하는 경우에도, 동일한 엔드포인트에 리포지토리 이름을 포함하여 DELETE 요청을 전송합니다.

Git 리포지토리를 추가한 후, 리포지토리 내의 템플릿을 동기화하기 위해 애플리케이션을 생성합니다.

• 첫 번째 동기화에는 시간이 소요됩니다. 완료 시점은 애플리케이션의 상태(Status)를 통해 확인할 수 있습니다.
• 첫 동기화 이후에는 시스템이 약 3분마다 자동으로 템플릿을 동기화합니다.
• 수동 동기화 요청도 가능합니다.

Note: 동일한 소스를 동기화하려는 애플리케이션을 중복해서 생성하지 마십시오. 2개의 앱이 동일한 repositoryURL, revision, path를 가지는 경우 동기화에 실패합니다.

절차

{{apiurl}}/v2/admin/applications 엔드포인트에 POST 요청을 전송하여 애플리케이션의 상세 정보를 포함합니다.

curl --location --request POST "$AI_API_URL/v2/admin/applications" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
...

파라미터 제약 사항은 다음과 같습니다.

• applicationName: 애플리케이션 이름. 3~64자여야 하며, (사용 가능한 문자는 영숫자, 하이픈(-), 언더스코어(_)뿐이며, 마침표(.)나 슬래시(/)는 포함할 수 없습니다. 리포지토리의 폴더 구조를 그대로 명명에 사용할 경우 변환 규칙이 필요합니다) [A-Za-z0-9\-\_]+와 일치해야 합니다.
• repositoryUrl: 등록된 Git 리포지토리의 URL. 대소문자를 구분하며, 등록된 리포지토리의 URL과 완전히 일치해야 합니다.
• revision: 대상 리비전(Revision). HEAD는 최신 리비전을 가리킵니다.
• path: 동기화 대상 템플릿이 포함된 폴더로의 경로(Path)

각 애플리케이션은 리포지토리 내의 특정 경로와 리비전을 참조하므로, 동일한 repositoryUrl에 대해 여러 개의 애플리케이션을 생성할 수 있습니다.

결과

GitOps 설정이 완료되면, Git 리포지토리 내의 템플릿은 SAP AI Core로 자동 동기화됩니다. 동기화는 약 3분마다 실행됩니다.

{{apiurl}}/v2/admin/applications/{{appName}}/status 엔드포인트에 GET 요청을 전송합니다. appName에는 애플리케이션 생성 시 지정한 이름을 입력합니다.

curl --location --request GET "$AI_API_URL/v2/admin/applications/{{appName}}/status" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'

출력 예시는 다음과 같다.

{
"healthStatus": "Healthy",
"message": "successfully synced (all tasks run)",
...

※ 공식 문서의 출력 예시에는 표기 오류(ServingTemaplate라는 철자 및 syncedStartedAt 값의 인용부호 불일치)가 포함되어 있다. 위 내용은 오류를 수정한 형태로 게재하였다.

애플리케이션은 약 3분 간격으로 GitHub 리포지토리와 자동 동기화된다. 수동으로 동기화를 요청하려면 다음 엔드포인트를 사용한다.

{{apiurl}}/admin/applications/{{appName}}/refresh

Note: 공식 문서에서는 이 엔드포인트에만 /v2 경로가 기재되어 있지 않다 (후술할 "공식 문서의 기재 불일치" 참조).

{{apiurl}}/v2/admin/applications 엔드포인트에 GET 요청을 전송한다.

{{apiurl}}/v2/admin/applications/{{appName}} 엔드포인트에 PATCH 요청을 전송하고, 변경 내용을 바디(Body)에 포함한다.

{{apiurl}}/v2/admin/applications/{{appName}} 엔드포인트에 DELETE 요청을 전송한다.

Git 리포지토리 관리 및 애플리케이션 관리 엔드포인트를 정리한다.

Git 리포지토리

• 추가:
  POST /v2/admin/repositories

• 편집:
  PATCH /v2/admin/repositories

• 삭제:
  DELETE /v2/admin/repositories/{{repositoryName}}

애플리케이션

• 생성:
  POST /v2/admin/applications

• 목록:
  GET /v2/admin/applications

• 편집:
  PATCH /v2/admin/applications/{{appName}}

• 삭제:
  DELETE /v2/admin/applications/{{appName}}

• 상태 확인:
  GET /v2/admin/applications/{{appName}}/status

• 수동 동기화:
  {{apiurl}}/admin/applications/{{appName}}/refresh

본 문서의 대상 범위 내에서 공식 문서의 다음과 같은 기재 불일치를 확인하였다. 구현 시에는 최신 공식 API 레퍼런스를 확인할 것을 권장한다.

• 6.1.2 리포지토리 편집 엔드포인트: Curl 예시는 /v2/admin/repositories로, 서드파티 API 플랫폼 예시는 /v2/admin/repositories/{{repositoryName}}로 기재가 서로 다름
• 수동 동기화 엔드포인트: 이 엔드포인트에만 /v2 경로가 기재되어 있지 않음
• 상태 확인 JSON 출력 예시: ServingTemaplate라는 철자 오류 및 syncedStartedAt 값의 인용부호 불일치가 포함되어 있음

공식 문서의 5장에는 SAP AI Core 관련 미션·튜토리얼 목록이 게재되어 있다.

• Getting Started (시작하기): Booster를 사용한 Free 플랜에서의 SAP AI Core · SAP AI Launchpad 프로비저닝 (Provisioning) -
  Generative AI (생성형 AI): Setup (BTP 환경 구축), Orchestration (복수 벤더의 LLM을 사용한 생성형 AI 워크플로우, 생성형 AI SDK를 이용한 프롬프트 · 임베딩 (Embedding) 기초), Foundation Models (SAP AI Core에 포함된 파운데이션 LLM의 각종 유스케이스 탐색) -
  Predictive AI (예측형 AI): SAP AI Core의 기초, 첫 번째 예측 AI 워크플로우 생성, 머신러닝 (ML) 코드를 운영 클라우드로 이전

• Git 리포지토리 (Repository) 등록은 PAT (Personal Access Token, 퍼스널 액세스 토큰)를 사용하여 수행하며, /v2/admin/repositories 엔드포인트에서 추가 · 편집 · 삭제한다 - 리포지토리 내에 시크릿 (Secret)이 존재하면 콘텐츠를 동기화할 수 없다

• 이름 충돌을 피하기 위해, 1개 테넌트 (Tenant)당 리포지토리 · 애플리케이션은 하나씩 생성하는 것을 권장한다

• 애플리케이션은 repositoryUrl · revision · path의 조합으로 템플릿의 동기화 대상을 지정한다. 동일한 조합을 가진 앱을 중복 생성하면 동기화에 실패한다 - 동일 리포지토리에 대해서는, 경로 (Path) · 리비전 (Revision)이 다르면 여러 개의 애플리케이션을 생성할 수 있다

• 최초 동기화 후에는 약 3분 간격으로 자동 동기화되며, /refresh 엔드포인트를 통해 수동 동기화도 가능하다 - 다음(#5)에는 관리② (리소스 그룹 · 각종 시크릿 관리)를 다룬다

• 퍼스널 액세스 토큰 (PAT, Personal Access Token): 인증 정보 자체를 전달하지 않고 Git 리포지토리로의 접속을 허용 · 제어하기 위한 토큰 -

• 애플리케이션 (Application): SAP AI Core에서, Git 리포지토리 내의 특정 경로 · 리비전의 템플릿을 동기화하는 단위 -

• 리비전 (Revision): 동기화 대상으로 하는 Git의 리비전. HEAD는 최신 리비전을 가리킨다 -

• GitOps: Git 리포지토리를 유일한 진실의 원천 (Single Source of Truth)으로 삼고, 그 내용을 실행 환경으로 자동 동기화하는 운영 방식