[실전 서버리스 06] Wrangler 완전정복, 설정·바인딩·시크릿

워커스로 개발하다 보면 랭글러라는 도구를 하루에도 수십 번 쓰게 된다. 개발, 배포, 로그 확인, 설정 관리까지 다 랭글러로 한다. 서버리스 개발의 작업대라고 할 수 있다. 이번 편은 이 랭글러를 제대로 다루는 법, 특히 설정 파일과 바인딩, 시크릿 관리를 정리한다.

랭글러에 익숙해지는 게 서버리스 생산성의 절반이다. 매일 쓰는 도구라 조금만 더 알아도 작업이 훨씬 매끄러워진다.

1. 설정 파일, 프로젝트의 청사진

랭글러 설정 파일은 워커 프로젝트의 청사진이다. 워커 이름, 진입점 코드, 호환성 날짜, 그리고 무엇보다 이 워커가 연결할 자원들을 여기에 적는다. 데이터베이스, 스토리지, 정기 작업 같은 걸 이 파일에서 워커에 묶는다.

이 설정 파일을 이해하는 게 중요한 이유는, 워커가 무엇에 접근할 수 있는지가 다 여기서 정해지기 때문이다. 데이터베이스를 쓰려면 여기에 그 연결을 적어야 하고, 스토리지를 쓰려면 마찬가지다. 설정 파일이 워커의 권한과 연결을 선언하는 곳이다.

주의할 점 하나. 설정 파일은 프로젝트 루트에 하나만 있어야 하고, 상위 폴더에 잘못된 설정 파일이 있으면 충돌이 난다. 나도 상위 폴더에 남아 있던 설정 파일 때문에 헤맨 적이 있다. 설정 파일의 위치와 유일성을 확실히 관리하는 게 좋다.

설정 파일을 프로젝트의 청사진이라 부르는 이유는, 이 파일만 보면 워커가 무엇에 연결되고 어떻게 동작하는지 파악되기 때문이다. 그래서 이 파일을 깔끔하게 관리하는 게 중요하다. 여기가 지저분하면 워커의 연결 관계가 헷갈리고, 나중에 문제가 생겼을 때 어디를 봐야 할지 모른다.

조금 더 실무적으로, 설정 파일의 호환성 날짜라는 항목이 은근히 중요하다. 플랫폼이 업데이트되며 동작이 바뀔 수 있는데, 이 날짜가 어느 시점의 동작을 기준으로 삼을지 고정해준다. 그래서 플랫폼이 바뀌어도 내 워커는 안정적으로 같은 동작을 유지한다. 이 안정성 장치를 이해하고 관리하는 게 좋다.

한 가지 더, 랭글러는 팀 협업에도 유리하다. 설정 파일이 프로젝트에 함께 저장되니, 다른 사람이 그 프로젝트를 받으면 같은 설정으로 개발할 수 있다. 환경 설정을 말로 전달하거나 문서로 관리하는 대신, 설정 파일 하나가 그 역할을 한다. 혼자 개발하다 나중에 누군가와 함께하게 돼도 이 구조가 도움이 된다.

2. 바인딩, 워커와 자원 연결

바인딩은 워커가 다른 자원에 접근하는 통로다. 데이터베이스 바인딩을 설정하면 워커 코드 안에서 그 이름으로 데이터베이스를 부를 수 있다. 스토리지 바인딩, 환경 변수 바인딩도 마찬가지다. 바인딩이 곧 워커의 손발인 셈이다.

이 방식의 장점은 코드가 깔끔해진다는 것이다. 데이터베이스 주소나 접속 정보를 코드에 박아 넣는 대신, 바인딩이라는 이름으로 추상화된 통로를 쓴다. 코드는 그냥 이 바인딩을 통해 데이터베이스를 부르고, 실제 연결은 플랫폼이 처리한다. 접속 정보 관리의 부담이 준다.

바인딩을 설정하면 로컬 개발에서도 그대로 작동한다. 로컬에서 테스트할 때도 바인딩을 통해 로컬 데이터베이스나 스토리지에 접근한다. 그래서 로컬과 배포 환경의 코드가 같다. 환경마다 다른 접속 코드를 짤 필요가 없어 개발이 단순해진다.

바인딩이 코드를 깔끔하게 한다는 걸 실감한 건 접속 정보를 옮길 때였다. 접속 정보를 코드에 박아뒀다면 환경이 바뀔 때마다 코드를 고쳐야 하지만, 바인딩으로 추상화하면 코드는 그대로 두고 바인딩만 바꾸면 된다. 코드와 설정을 분리하는 이 원칙이 유지보수를 크게 편하게 한다.

3. 시크릿, 비밀 정보 관리

API 키나 비밀번호 같은 민감한 정보는 코드에 절대 넣으면 안 된다. 코드에 박으면 저장소에 그대로 남아 유출 위험이 크다. 이런 건 시크릿으로 따로 관리한다. 랭글러로 시크릿을 등록하면, 그 값은 안전하게 저장되고 코드에서는 바인딩처럼 이름으로만 접근한다.

시크릿과 일반 환경 변수의 차이는 민감도다. 공개돼도 되는 설정값은 설정 파일에 환경 변수로 두지만, 절대 노출되면 안 되는 값은 시크릿으로 관리한다. 시크릿은 설정 파일이나 코드에 값이 남지 않고, 플랫폼이 암호화해 보관한다. 이 구분을 지키는 게 보안의 기본이다.

시크릿을 등록할 때 실무적인 함정이 하나 있다. 값을 붙여넣을 때 앞뒤에 눈에 안 보이는 공백이나 줄바꿈이 섞이면, 그 공백까지 시크릿에 포함돼 인증이 실패한다. 나도 이것 때문에 한참 헤맸다. 시크릿 값은 앞뒤 공백을 깔끔히 다듬어 등록하는 게 좋다.

시크릿 관리는 보안의 첫 단추다. API 키 하나가 코드에 박혀 저장소에 올라가면, 그게 유출돼 큰 사고로 이어질 수 있다. 그래서 민감 정보는 처음부터 시크릿으로 관리하는 습관을 들여야 한다. 나중에 분리하려면 이미 저장소 이력에 남아 있어 완전히 지우기 어렵다. 처음부터 제대로 하는 게 답이다.

시크릿의 앞뒤 공백 함정은 사소해 보여도 실제로 많이 겪는 사고다. 값을 복사해 붙일 때 딸려온 보이지 않는 공백이나 줄바꿈이 인증을 깨뜨린다. 겉보기엔 값이 맞는데 자꾸 인증이 실패해서 원인을 못 찾고 헤매게 된다. 그래서 시크릿을 등록할 땐 앞뒤를 다듬는 걸 습관으로 해두는 게 좋다.

4. 로컬 개발과 배포

랭글러는 로컬 개발 환경도 제공한다. 배포하기 전에 로컬에서 워커를 실행해 테스트할 수 있다. 이게 중요한 이유는, 매번 실제 배포해서 확인하면 느리고 번거롭기 때문이다. 로컬에서 빠르게 돌려보고, 잘 되면 배포하는 흐름이 효율적이다.

로컬 개발 환경은 실제 배포 환경을 상당히 비슷하게 흉내 낸다. 바인딩도 작동하고, 데이터베이스와 스토리지도 로컬 버전으로 연결된다. 그래서 로컬에서 잘 되면 배포해도 대체로 잘 된다. 다만 완전히 같지는 않아서, 로컬과 배포 환경의 미묘한 차이로 생기는 문제도 가끔 있다.

배포는 앞서 말했듯 명령어 한 줄이다. 랭글러가 코드를 묶어 엣지에 올리고, 시작 시간 같은 정보를 알려준다. 배포 후에는 실시간 로그를 볼 수 있어서, 실제 요청이 어떻게 처리되는지 관찰할 수 있다. 문제가 생기면 이 로그가 첫 번째 단서다.

로컬 개발 환경이 배포 환경을 흉내 낸다지만 완전히 같지는 않다는 점을 알아둬야 한다. 로컬에서 잘 되던 게 배포하면 미묘하게 다르게 동작하는 경우가 있다. 그래서 배포 후에는 실제 환경에서 다시 확인하는 절차가 필요하다. 로컬 통과가 배포 성공을 보장하지는 않는다는 걸 기억해야 한다.

5. 운영 습관

랭글러를 오래 쓰면서 몇 가지 운영 습관이 생겼다. 첫째, 배포 후에는 항상 실제로 사이트가 정상인지 확인한다. 배포가 성공했다는 것과 사이트가 잘 돈다는 건 다르기 때문이다. 특히 주요 페이지가 제대로 뜨는지 눈으로 확인하는 습관이 사고를 막는다.

둘째, 캐시를 신경 쓴다. 정적 자산을 업데이트했는데 캐시 때문에 옛 버전이 계속 나오는 경우가 있다. 그래서 자산 주소에 버전 표시를 붙여 캐시를 갱신하는 방식을 쓴다. 앞서 SEO 시리즈에서도 다룬 캐시 관리가 여기서도 중요하다.

정리하면 랭글러는 설정 파일로 프로젝트를 정의하고, 바인딩으로 자원을 연결하고, 시크릿으로 민감 정보를 관리하는 서버리스 개발의 작업대다. 여기까지가 워커스의 기초다. 다음 편부터는 데이터를 다루는 D1 데이터베이스로 들어간다. 엣지의 SQLite가 어떻게 동작하고 어떻게 설계하는지를 파고든다.

운영 습관에서 배포 후 확인을 강조하는 이유는, 배포 성공과 정상 작동이 다르기 때문이다. 랭글러가 배포됐다고 알려줘도, 실제 사이트가 잘 도는지는 눈으로 봐야 안다. 주요 페이지를 열어보고, 로그를 확인하고, 이상이 없는지 살피는 이 짧은 확인이 큰 사고를 막는다.

운영 습관을 정리하면, 배포 후 확인과 캐시 관리 두 가지가 핵심이다. 배포됐다고 끝이 아니라 실제로 도는지 보고, 자산을 바꿨으면 캐시가 갱신되는지 챙긴다. 이 두 가지를 매 배포의 마무리 절차로 두면, 배포는 됐는데 사이트가 이상한 상황을 대부분 예방한다. 배포는 올리는 것보다 확인이 절반이다.

덧붙이면, 랭글러에 익숙해질수록 서버리스 개발이 손에 붙는다. 처음엔 명령어 하나하나가 낯설지만, 매일 쓰다 보면 설정과 배포, 로그 확인이 자연스러운 흐름이 된다. 좋은 도구에 익숙해지는 건 시간이 걸리지만, 그 투자가 이후의 모든 개발 속도를 높여준다. 작업대를 잘 갖추는 게 곧 생산성이다.

또 하나, 랭글러의 로그 기능은 문제 해결의 첫 도구다. 배포한 워커에서 실시간으로 무슨 일이 일어나는지 로그로 볼 수 있어서, 오류가 나면 여기서 단서를 찾는다. 어떤 요청이 어떻게 처리되고 어디서 실패하는지가 로그에 남는다. 이 로그를 읽을 줄 아는 것만으로 디버깅 시간이 크게 준다.