Datapan에서 공공데이터 응답을 릴리스하는 방법

Datapan은 공공데이터 API 응답을 데이터 팩으로 묶어 CLI와 제품에서 사용할 수 있게 만드는 프로젝트예요. API에서 응답 파일을 받으면 먼저 형식과 내용을 검사하고, 공개할 버전을 정한 뒤, 실제 설치 결과와 현재 상태를 차례로 확인합니다.

응답 파일을 받은 시점에 확인한 사실은 두 가지예요. 원천이 값을 돌려줬고 응답 형식이 맞았다는 점입니다. 제품에서 이 파일을 사용하려면 릴리스 버전, 설치 결과, 관찰 시각, 화면에 표시할 상태가 더 필요해요. Datapan은 이 항목을 한 저장소에서 한꺼번에 판정하지 않고 단계별로 나누어 관리합니다.

이 글에서는 응답 파일이 Data, Registry, CLI, Health, Atlas를 거치는 순서와 각 단계가 남기는 근거를 설명할게요.

공공데이터 응답이 제품에 도착하는 과정

전체 흐름은 원천 관찰, 데이터 팩 생성, 공개 릴리스, 설치 확인, 상태 관찰, 제품 표시의 여섯 단계로 이어져요. 앞 단계가 만든 파일과 기록은 다음 단계의 입력이 됩니다.

datapan-data는 선택한 원천을 검증해 후보 데이터 팩을 만들어요. 데이터 팩에는 값만 들어가지 않습니다. schema, freshness, quality, lineage, release identity를 함께 묶습니다. datapan-registry는 이 묶음의 source identity, policy, provenance, release manifest를 관리해요.

공개가 끝나면 datapan-cli가 소비자 환경에서 릴리스를 설치하고 읽어 봅니다. datapan-health는 정해진 시각과 범위 안에서 source 상태를 관찰해요. 공개 클라이언트인 Atlas는 검증된 읽기 전용 데이터 팩과 현재 증거 상태를 화면에 전달합니다. production promotion과 rollback은 infra에서 실행하고 기록해요.

각 저장소가 확인하는 대상은 서로 달라요. Data는 후보 파일의 품질을 확인하고, Registry는 공개할 파일의 정체성을 고정합니다. CLI는 공개된 파일을 설치할 수 있는지 확인하고, Health는 현재 관찰 결과를 남겨요. Atlas는 전달받은 상태를 바꾸지 않고 보여줍니다.

재사용 가능한 데이터의 네 가지 조건

Datapan에서 다음 단계로 파일을 넘길 때 확인하는 항목은 identity, input, action, failure state예요.

Identity는 어떤 릴리스를 다루는지 알려 줍니다. Input에는 검증한 파일과 manifest, policy가 들어가요. Action은 생성, 검증, 설치, 관찰처럼 실제로 수행한 작업입니다. Failure state는 필요한 근거가 없거나 값이 맞지 않을 때 다음 단계가 어떤 상태를 표시할지 정해요.

이 네 항목은 receipt에 기계가 읽을 수 있는 형태로 남습니다. Receipt를 보면 특정 시각에 어떤 immutable input을 대상으로 어떤 작업이 끝났는지 확인할 수 있어요. 형식이 맞는 fixture로 receipt schema와 거부 조건을 시험할 수도 있습니다. Fixture 결과의 evidence_class는 그대로 유지되기 때문에 공개 릴리스나 실제 provider 관찰 기록으로 바뀌지 않아요.

현재 상태를 판단할 근거가 부족하면 Health는 unknown을, Atlas는 unavailable을 사용합니다. 테스트용 fixture나 검토 중인 candidate로 빈자리를 채우지 않아요. 화면에는 확인이 끝난 범위만 current로 표시됩니다.

Data와 Registry가 릴리스를 만드는 과정

Data는 검토할 데이터, schema, freshness, quality, lineage를 하나의 versioned bundle로 묶어 후보를 만들어요. Release manifest에는 이번 버전에 포함된 파일과 각 파일의 digest가 기록됩니다. 다음 단계는 manifest와 실제 파일의 digest를 비교해 같은 릴리스를 받았는지 확인해요.

Registry의 release cadence 문서는 candidate refresh부터 공개 후 확인까지의 순서를 설명합니다. Candidate refresh는 dry run으로 실행하고, 내용 변화가 있으면 review로 보냅니다. 원천 관찰에 실패한 결과는 변화 없음으로 기록하지 않아요.

공개 준비는 생성, 검증, ready 판정, packaging, manifest 기반 receipt 확인 순서로 진행됩니다. 공개 후에는 익명 환경에서 pointer, payload, manifest, Registry, source, policy binding을 다시 확인해요. 이 값이 하나라도 다르면 다음 단계로 넘기지 않습니다.

소비자 확인에 실패한 경우에는 이전 pointer와 payload로 rollback한 뒤 그 릴리스를 다시 검증하거나, manual_hold로 작업을 멈춰요. Rollback을 선택하면 이전 binding의 익명 검증 receipt와 복구된 CLI observation을 시간순으로 확인합니다.

CLI가 공개된 릴리스를 확인하는 과정

Registry가 릴리스를 공개하면 CLI는 소비자 입장에서 설치를 확인해요. CLI의 Registry release 문서에 공개 릴리스 구조와 설치 방법이 정리되어 있습니다.

Consumer smoke receipt에는 CLI revision, Registry 배포 revision, Registry와 manifest의 SHA-256, install 결과, doctor 결과, 관찰 시각, rollback 상태가 들어가요. 이 receipt는 생산자가 만든 publication receipt와 별도로 남습니다. 두 receipt는 같은 immutable release를 가리켜야 해요.

현재 저장소에서 확인할 수 있는 범위는 receipt schema와 offline rejection policy까지예요. 공개된 provider를 대상으로 consumer smoke를 실행한 결과나 실제 rollback 관찰 결과는 이 근거에 포함되지 않습니다. 해당 결과를 말하려면 같은 release identity로 이어진 실행 receipt가 더 필요해요.

Health와 Atlas가 상태를 보존하는 방법

CLI가 설치를 확인한 뒤에는 Health가 source의 현재 상태를 관찰해요. 공개된 offline fixture worker는 고정된 Registry와 policy 입력으로 동시성, timeout, redaction, 종료 상태 처리를 시험합니다. 이 worker는 provider를 호출하지 않아요.

실제 상태 판단에는 sample 수와 관찰 시각, control 상태가 함께 필요합니다. Sample이 부족하거나 관찰이 오래됐거나 근거가 충돌하면 Health는 unknown을 유지해요. 한 번의 timeout을 바로 incident로 분류하지 않는 이유는 이전 글에서 자세히 다뤘습니다.

Atlas는 검증된 immutable data pack을 읽기 전용으로 소비해요. 화면에 전달할 때 dataState, provenance, freshness, transform, rights, quality, limitation을 함께 보존합니다. 필요한 dependency가 없거나 digest가 맞지 않으면 unavailable을 표시해요.

이 방식에서는 근거가 늦게 도착하면 화면도 더 오래 unavailable 상태에 머물 수 있습니다. 운영자는 어느 receipt가 빠졌는지 확인해야 해요. 현재 자료에는 이 작업량과 가용성 변화를 측정한 수치가 없습니다.

현재 구현된 범위와 다음 검증

현재 자료에서 확인한 범위는 각 단계의 schema, receipt, admission, failure-state 계약이에요. Data는 후보 데이터 팩을 만들고, Registry는 공개 identity를 고정하며, CLI는 설치 결과를 기록합니다. Health와 Atlas는 확인할 근거가 부족한 상태를 unknown과 unavailable로 유지해요.

다음 검증에서는 하나의 public release identity를 사용해 publication, consumer smoke, rollback, provider observation을 순서대로 실행해야 합니다. 같은 identity로 이어진 receipt가 모이면 처리 시간과 운영 작업량도 측정할 수 있어요.

이 글에서 설명한 구조를 다른 데이터 릴리스에 적용하려면 각 단계의 owner, immutable input, 수행 시각, failure state를 먼저 정하면 됩니다. 이후 단계는 앞 단계가 남긴 receipt를 입력으로 사용해요. 긴 글 읽어주셔서 감사합니다.