아티팩트 검증
앱 배포로 내려온 아티팩트를 Agent가 워크플로우 실행 전에 검사해요.
검사에 실패하면 워크플로우는 한 스텝도 실행되지 않고 잡이 실패로 끝나요.
검사는 두 단계예요.
| 단계 | 확인하는 것 | 신뢰 기점 |
|---|---|---|
| 체크섬 | 전송 중 파일이 손상되지 않았는지 | Deplite 서버가 계산한 값 |
| 서명 | 이 아티팩트를 내 CI가 만들었는지 | 기기에 직접 둔 공개키 파일 |
체크섬은 서버가 알려준 값이라 서버를 신뢰하는 범위 안에서만 의미가 있어요.
서명은 기기에 있는 공개키로 확인하므로 서버를 신뢰하지 않아도 성립해요.
서명 검증에는 별도 도구가 필요하지 않아요.
cosign sign-blob --key가 만든 서명을 Agent가 직접 확인하므로 기기에 cosign을 설치하지 않아도 돼요.
공개키 준비
CI에서 사용할 키 쌍을 만들어요.
cosign generate-key-paircosign.key는 CI 시크릿 저장소에만 두고, cosign.pub은 배포 대상 기기마다 복사해요.
sudo install -D -m 0444 -o root -g root cosign.pub /etc/deplite/keys/app.pub이 파일이 검증의 기준점이에요.
Deplite 서버가 바꿀 수 없는 값이어야 하므로 root 소유의 읽기 전용으로 두기를 권해요.
한 기기에서 여러 앱을 운영한다면 앱마다 <application_id>.pub 이름으로 둘 수 있어요.
해당 파일이 없으면 Agent는 app.pub을 사용해요.
워크플로우가 자체 검증 단계를 갖고 있다면 그 단계가 읽는 키 경로도 같은 파일로 맞춰주세요.
앱별 키만 두고 워크플로우는 app.pub을 가리키는 상태라면, Agent 검증이 성공하더라도 워크플로우 쪽에서 키를 찾지 못해 배포가 멈춰요.
릴리스에 서명 첨부
CI에서 아티팩트를 만든 뒤 서명하고, 릴리스를 만들 때 서명도 함께 등록해요.
cosign sign-blob \
--key cosign.key \
--tlog-upload=false \
--yes \
--output-signature app.tar.gz.sig \
app.tar.gz--tlog-upload=false는 공개 투명성 로그에 릴리스 존재를 남기지 않는 설정이에요.
Agent는 이 로그를 조회하지 않으므로 두 방식 모두 그대로 검증돼요.
등록할 수 있는 키는 ECDSA(P-256/384/521)와 RSA(2048비트 이상)예요.
cosign generate-key-pair의 기본값인 ECDSA P-256을 그대로 사용하면 돼요.
Ed25519 키는 cosign이 sign-blob을 지원하지 않아 서명 자체를 만들 수 없으므로 등록 단계에서 거절돼요.
위 명령은 cosign v2 기준이에요.
v3부터는 sign-blob의 옵션이 달라지므로 cosign version으로 확인해주세요.
동작 모드
공개키 파일이 있는지가 기본 동작을 결정해요.
| 기기 상태 | 릴리스 상태 | 결과 |
|---|---|---|
| 공개키 있음 | 서명 있음 | 검증 후 배포 |
| 공개키 있음 | 서명 없음 | 잡 실패 |
| 공개키 있음 | 서명이 맞지 않음 | 잡 실패 |
| 공개키 없음 | 서명 있음 | 잡 실패 (아래 옵트인으로 완화 가능) |
| 공개키 없음 | 서명 없음 | 배포하되 잡 로그에 미검증으로 남김 |
공개키를 한 번 두면 그 뒤로는 서명을 뺀 릴리스가 통과하지 못해요.
검증을 끄는 결정이 기기에만 남고 서버 쪽에서는 내릴 수 없도록 하기 위한 동작이에요.
환경변수
| 변수 | 기본값 | 설명 |
|---|---|---|
DEPLITE_ARTIFACT_VERIFY | auto | require로 두면 검증할 수 없는 아티팩트를 항상 거부해요.off는 서명 검사를 생략하며 체크섬 검사는 유지해요.유효 값은 auto, require, off이고 대소문자를 구분하지 않아요. 알 수 없는 값은 auto로 처리해요. |
DEPLITE_ARTIFACT_KEY_DIR | /etc/deplite/keys | 공개키를 찾을 디렉토리예요. |
DEPLITE_ARTIFACT_TRUST_SERVER_KEY | 꺼짐 | 1로 두면 기기에 공개키가 없을 때 서버가 보낸 공개키로 검증해요. |
DEPLITE_ARTIFACT_TRUST_SERVER_KEY는 서버가 보낸 키로 서버가 보낸 서명을 확인하는 방식이라 전송 중 변조는 잡지만, 서버 자체가 침해된 경우에는 도움이 되지 않아요.
공개키를 기기에 배치하기 전까지의 임시 수단으로만 사용해주세요.
워크플로우에서 검증 여부 확인
Agent가 어떤 검사를 끝냈는지 각 step에 환경변수로 알려줘요.
| 변수 | 값 |
|---|---|
DEPLITE_ARTIFACT_SIGNATURE_VERIFIED | 서명을 실제로 검증했으면 1, 아니면 0 |
DEPLITE_ARTIFACT_CHECKSUM_VERIFIED | 체크섬을 실제로 대조했으면 1, 아니면 0 |
두 변수는 아티팩트를 내려받는 잡에서만 설정되고, 이 기능이 없던 이전 버전 Agent에서는 설정되지 않아요.
그래서 워크플로우에 자체 검증 단계를 남겨 두더라도 아래처럼 쓰면 새 Agent에서는 건너뛰고 이전 버전에서는 그대로 수행돼요.
if [ "${DEPLITE_ARTIFACT_SIGNATURE_VERIFIED:-0}" = "1" ]; then
echo "agent already verified the signature"
else
cosign verify-blob --key "$APP_PUBLIC_KEY_FILE" ...
fi값은 Agent가 검증을 마친 뒤에 채우므로 워크플로우의 env: 블록이나 서버가 보낸 파라미터로는 바꿀 수 없어요.
이 변수로 건너뛸 수 있는 것은 검증 명령 자체예요.
워크플로우가 따로 확인하는 조건(공개키 파일이 있는지 등)은 그대로 실행되므로, 공개키 준비 섹션의 키 배치와 어긋나 있으면 여전히 그 지점에서 멈춰요.
잡 로그
검증 결과는 잡 로그의 system 스트림에 남아요.
artifact signature verified with local key /etc/deplite/keys/app.pubartifact is unverified: the release carries no signature and there is no public key at ...the public key sent by the server differs from ...; verifying with the local key
세 번째 메시지는 키 교체 중에 정상적으로 나타날 수 있어요.
어느 경우에도 검증은 기기의 공개키로 수행하므로 잡은 그대로 진행돼요.
키 교체
공개키를 교체하면 이전 키로 서명된 릴리스는 그 기기에서 더 이상 배포되지 않아요.
롤백 대상으로 남겨 둘 버전이 있다면 새 키로 다시 서명해 릴리스를 만든 뒤 기기의 공개키를 교체해주세요.
컨테이너 이미지 릴리스
컨테이너 이미지는 서명이 레지스트리에 함께 저장되므로 Agent가 아니라 워크플로우가 cosign verify로 확인해요.
이 경우에는 기기에 cosign이 필요해요.
레지스트리 접근에 쓰이는 단기 자격증명은 잡 로그에서 자동으로 가려지지만, 워크플로우에서 직접 출력하지 않도록 주의해주세요.
docker login에는 --password-stdin을 사용하기를 권해요.