Rover CLI로 GraphQL 스키마 관리하기
GraphQL을 사용하다 보면 스키마를 관리하는 일이 점점 중요해지는데요. 팀원이 늘어나고 서비스가 커지면서 “이 필드 바꿔도 기존 클라이언트에 문제 없을까?”, “지금 운영 중인 스키마가 정확히 뭐였지?” 같은 고민이 생기기 마련이잖아요? 😅
이럴 때 큰 도움이 되는 도구가 바로 Apollo에서 만든 Rover CLI입니다. 이번 글에서는 Rover CLI의 설치부터 주요 명령어, CI/CD 파이프라인 연동까지 쭉 다뤄보겠습니다.
Rover CLI란?
Rover는 Apollo GraphQL에서 제공하는 공식 CLI 도구입니다. GraphQL 스키마를 레지스트리에 올리거나 운영 중인 서버에서 스키마를 가져오거나 스키마 변경이 기존 클라이언트를 망가뜨리지 않는지 미리 검증하는 등 스키마 생명주기 전반을 터미널에서 관리할 수 있게 해줍니다.
과거에는 apollo라는 이름의 CLI가 있었는데 공식 지원이 종료되면서 Rover가 그 역할을 이어받았습니다.
Rover는 Rust로 작성되어 실행 속도가 빠르고 graph, subgraph, supergraph 같은 명시적인 명령어 체계를 갖추고 있어서 훨씬 직관적이에요.
설치
설치 방법은 여러 가지가 있는데요. npm을 통한 글로벌 설치가 가장 간단합니다.
npm i -g @apollo/rover프로젝트의 개발 의존성으로 설치하고 싶다면 이렇게 할 수도 있고요.
npm i --save-dev @apollo/rover
npx rover --versioncurl을 선호하시는 분들은 아래 명령어로 바로 설치할 수 있습니다.
curl -sSL https://rover.apollo.dev/nix/latest | shMac에서 Homebrew를 사용하신다면 한 줄이면 됩니다.
brew install rover설치가 끝나면 버전을 확인해봅시다.
rover --version인증 설정
Rover의 대부분 명령어는 Apollo GraphOS와 통신하기 때문에 API 키로 인증을 해야 합니다. 아직 계정이 없으시면 Apollo Studio에서 무료로 가입하실 수 있습니다.
터미널에서 rover config auth 명령어를 실행하면 API 키를 입력하라는 안내가 나옵니다.
rover config auth설정 페이지에서 Personal API Key를 생성한 다음 붙여넣으면 인증 완료입니다.
Go to https://go.apollo.dev/r/auth and create a new Personal API key.
Copy the key and paste it into the prompt below.
> ********
Successfully saved API key.설정이 잘 됐는지 확인하려면 whoami 명령어를 쓰면 됩니다.
rover config whoamiChecking identity of API key against the registry.
Key Type: USER
User ID: gh.DaleSeo여러 Apollo 계정을 사용해야 한다면 프로파일을 분리할 수 있습니다. AWS CLI 인증 정보 관리에서 다룬 프로파일 개념과 비슷하다고 보시면 됩니다.
rover config auth --profile work
rover graph fetch my-graph@prod --profile workCI/CD 환경에서는 보통 환경 변수로 키를 전달합니다.
export APOLLO_KEY=your-api-key-here스키마 조회
운영 중인 GraphQL 서버의 스키마가 궁금할 때 rover graph introspect 명령어로 바로 확인할 수 있습니다.
rover graph introspect http://localhost:4000/graphql인증이 필요한 서버라면 -H 옵션으로 헤더를 추가합니다.
rover graph introspect http://localhost:4000/graphql \
-H "Authorization: Bearer my-token"GraphOS 레지스트리에 등록된 스키마를 가져오고 싶다면 rover graph fetch를 사용합니다.
@ 뒤에 variant 이름을 붙여서 어떤 환경의 스키마를 가져올지 지정할 수 있어요.
rover graph fetch my-graph@production
rover graph fetch my-graph@staging --output schema.graphql--output 옵션을 쓰면 결과를 파일로 저장할 수 있어서 편리합니다.
introspect와 fetch의 결과를 파이프로 연결하면 실행 중인 서버의 스키마를 바로 레지스트리에 올릴 수도 있는데요.
rover graph introspect http://localhost:4000 \
| rover graph publish my-graph@dev --schema -이런 식으로 명령어를 조합하면 별도의 스크립트 없이도 스키마를 유연하게 관리할 수 있어요.
스키마 검증
스키마를 변경하기 전에 “이 변경이 기존 클라이언트를 깨뜨리지 않을까?” 확인하는 것이 정말 중요한데요.
rover graph check 명령어가 바로 이 역할을 합니다.
rover graph check my-graph@production --schema ./schema.graphql이 명령어는 세 가지 검사를 수행합니다.
우선 빌드 검사(build check)로 스키마가 유효한 GraphQL 정의인지 확인합니다. 다음으로 오퍼레이션 검사(operation check)에서는 최근 클라이언트가 실제로 사용한 쿼리와 비교해서 깨지는 것이 없는지 감지하죠. 마지막으로 린트 검사(lint check)는 네이밍 컨벤션이나 모범 사례를 따르고 있는지 점검해줍니다.
특히 오퍼레이션 검사가 강력한데요. GraphOS에 수집된 실제 트래픽 데이터를 기반으로 판단하기 때문에 “이론적으로 깨질 수 있는” 변경이 아니라 “실제로 영향 받는 클라이언트가 있는” 변경만 경고해줍니다.
린트만 따로 실행할 수도 있습니다.
rover graph lint my-graph@production --schema ./schema.graphql필드명이 camelCase인지, 타입명이 PascalCase인지, enum 값이 SCREAMING_SNAKE_CASE인지 같은 규칙을 검사해주는데 팀 전체가 일관된 스키마 스타일을 유지하는 데 꽤 유용합니다.
스키마 배포
검증까지 마쳤다면 이제 스키마를 레지스트리에 배포할 차례입니다.
rover graph publish my-graph@staging --schema ./schema.graphql배포하고 나면 Apollo Studio에서 변경 이력을 한눈에 확인할 수 있고 팀원과 스키마를 공유하기도 편해집니다.
Federation 환경에서의 사용
마이크로서비스 아키텍처에서 Apollo Federation을 사용하고 있다면 rover subgraph 명령어를 사용합니다.
단일 그래프 대신 여러 서브그래프가 모여 하나의 슈퍼그래프를 구성하는 구조이기 때문에 명령어도 이에 맞게 구분되어 있죠.
어떤 서브그래프가 있는지 먼저 확인해볼 수 있고요.
rover subgraph list my-supergraph@staging특정 서브그래프의 스키마를 가져오거나 배포하는 것도 어렵지 않습니다.
rover subgraph fetch my-supergraph@production --name accounts
rover subgraph publish my-supergraph@staging \
--name accounts \
--schema ./accounts/schema.graphql \
--routing-url https://accounts.example.com/graphql서브그래프를 변경하기 전에도 단독 그래프와 마찬가지로 check 명령어로 검증하는 게 좋습니다.
rover subgraph check my-supergraph@production \
--name accounts \
--schema ./accounts/schema.graphql이 검사는 서브그래프의 변경이 전체 슈퍼그래프 구성에 문제를 일으키지 않는지까지 확인해줍니다.
로컬에서 슈퍼그래프 합성
GraphOS 없이 로컬에서 슈퍼그래프를 합성하고 싶다면 rover supergraph compose를 쓸 수 있습니다.
먼저 설정 파일을 작성합니다.
federation_version: =2.13.0
subgraphs:
accounts:
routing_url: http://localhost:4001/graphql
schema:
file: ./subgraphs/accounts/schema.graphql
products:
routing_url: http://localhost:4002/graphql
schema:
file: ./subgraphs/products/schema.graphql스키마 소스는 로컬 파일(file), 실행 중인 서버(subgraph_url), GraphOS 레지스트리(graphref + subgraph) 중 하나를 지정할 수 있습니다.
rover supergraph compose --config ./supergraph.yaml
rover supergraph compose --config ./supergraph.yaml --output supergraph.graphql합성된 슈퍼그래프 스키마를 파일로 출력하면 Apollo Router에 직접 전달해서 사용할 수 있습니다.
rover dev로 로컬 개발
개발할 때 가장 자주 쓰게 되는 명령어가 바로 rover dev입니다.
로컬에서 Apollo Router를 띄우고 스키마 파일이 바뀌면 자동으로 재합성해주는 핫 리로딩을 지원하기 때문에 개발 속도가 훨씬 빨라집니다.
rover dev --supergraph-config supergraph.yaml실행하면 http://localhost:4000에서 Sandbox가 열리고 바로 쿼리를 테스트할 수 있습니다.
GraphOS에 이미 등록된 그래프가 있다면 --graph-ref 옵션으로 원격 스키마를 기반으로 개발할 수도 있어요.
rover dev --graph-ref my-graph@staging이 방식이 좋은 이유는 팀에서 운영 중인 전체 슈퍼그래프를 로컬로 가져온 뒤 내가 담당하는 서브그래프만 로컬 버전으로 교체할 수 있다는 거예요. 대규모 설정 파일을 로컬에 유지할 필요가 없어서 편리하죠.
원격 스키마에 로컬 오버라이드를 적용하고 싶다면 두 옵션을 함께 쓸 수도 있습니다.
rover dev --graph-ref my-graph@staging \
--supergraph-config supergraph-override.yaml이전에 Apollo Connectors 소개와 사용법에서 rover dev를 사용해본 적이 있는데요.
Connectors 개발 시에도 스키마 변경 사항을 실시간으로 반영해주기 때문에 개발이 훨씬 수월해집니다.
⚠️
rover dev는 로컬 개발 전용이니 프로덕션 환경에서는 사용하지 마세요.
CI/CD 연동
Rover의 진가는 CI/CD 파이프라인에서 발휘됩니다. PR이 올라올 때마다 스키마 변경을 자동으로 검증하고 메인 브랜치에 머지되면 스키마를 배포하는 워크플로우를 구성할 수 있거든요.
GitHub Actions를 사용하는 경우 Apollo에서 제공하는 공식 액션을 활용하면 됩니다.
name: Schema Check
on: pull_request
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: apollographql-gh-actions/install-rover@v1
- uses: apollographql-gh-actions/rover-subgraph-check@v1
with:
apollo-key: ${{ secrets.APOLLO_KEY }}
graph-ref: ${{ vars.APOLLO_GRAPH_REF }}
name: products
schema: ./schema.graphql메인 브랜치에 푸시되면 스키마를 자동 배포하는 워크플로우도 비슷합니다.
name: Publish Schema
on:
push:
branches: [main]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: apollographql-gh-actions/install-rover@v1
- uses: apollographql-gh-actions/rover-subgraph-publish@v1
with:
apollo-key: ${{ secrets.APOLLO_KEY }}
graph-ref: ${{ vars.APOLLO_GRAPH_REF }}
name: products
schema: ./schema.graphql
routing-url: https://products.example.com/graphql이렇게 설정해두면 스키마 변경으로 인한 장애를 미리 잡을 수 있고 배포도 자동화되니 실수가 줄어들죠.
마치며
지금까지 Apollo Rover CLI로 GraphQL 스키마를 조회하고 검증하고 배포하는 과정을 살펴봤는데요.
Rover를 한번 써보면 스키마 관리가 확 편해지는 걸 느끼실 겁니다.
특히 check 명령어를 CI에 연동해두면 스키마 변경으로 인한 예상치 못한 장애를 크게 줄일 수 있으니 팀에서 GraphQL을 사용하고 계시다면 도입을 강력히 추천드립니다.
REST API를 GraphQL로 통합하는 방법이 궁금하시다면 Apollo Connectors 소개와 사용법을, GraphQL의 기본적인 API 호출 방법이 궁금하시다면 GraphQL API 호출하기를, Apollo Server를 사용한 백엔드 개발에 관심이 있으시다면 Apollo Server로 GraphQL API 만들기를 참고해주세요.
Rover CLI에 대한 더 자세한 내용은 아래 공식 문서에서 확인하실 수 있습니다.
This work is licensed under
CC BY 4.0
