[CI/CD] PersistentVolumeClaim(PVC)를 활용한 GitHub Actions에서 Checkout 없는 자동 배포

GitHub Actions 환경에서 Actions Runner Controller(ARC)의 역할과, checkout 없이도 배포할 수 있는 방법을 설명하고, 발생할 수 있는 오류에 대해 정리합니다.

1. Actions Runner Controller(ARC)란 무엇인가?

Actions Runner Controller(ARC)는 GitHub Actions의 Self hosted runner(Pod)를 Kubernetes 클러스터에서 오케스트레이션하고 자동으로 스케일링하는 Kubernetes 연산자입니다. ARC는 GitHub Actions에서 요청하는 워크플로우에 맞춰 Runner(Pod)의 개수를 자동으로 조정하여 필요한 자원만큼만 사용하게 해 줍니다. 다음은 ARC의 주요 기능입니다.

• 자동 스케일링: 필요한 만큼 Runner Pod를 자동으로 생성하고 제거하여 자원을 효율적으로 관리합니다.
• 임시 Runner: 작업이 완료되면 해당 Runner Pod가 자동으로 제거됩니다.
• 워크플로우 트리거: 리포지토리에서 워크플로우가 트리거되면 GitHub Actions 서비스에서 해당 Runner를 호출해 작업을 실행합니다.

ARC 구성 요소

• AutoScalingRunnerSet: GitHub Actions API를 호출해 Runner 그룹을 설정하고, 필요한 경우 Runner 수를 동적으로 확장 또는 축소합니다.
• Runner ScaleSet 수신기: GitHub Actions 서비스와 연결된 수신기로, 작업이 실행 가능한지 여부를 검사하고, 적합한 Runner에게 작업을 전달합니다.
• EphemeralRunnerSet: 임시 러너를 생성하여 작업이 끝난 후 제거합니다.

INSTALLATION_NAME="arc-runner-set-dev"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/axccoe/test-springboot-jdk17"
GITHUB_PAT="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"

helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

2. Checkout 없이 배포하는 방법

GitHub Actions 워크플로우에서 보통 actions/checkout 단계를 사용하여 리포지토리를 Runner에서 복제한 후 작업을 진행합니다. 하지만 일부 배포 과정에서는 이미 빌드된 아티팩트(JAR 파일 등)를 사용하여 바로 배포를 할 수 있습니다. 이런 경우, checkout 단계 없이도 배포가 가능합니다. 그러나 이를 위해서는 몇 가지 전제 조건이 필요합니다.

조건

• 빌드 아티팩트가 이미 존재하는 경우: 빌드 단계에서 생성된 JAR 파일, 패키지 등 아티팩트를 미리 저장소(예: Azure Blob Storage)에 업로드한 후, 배포 단계에서는 해당 아티팩트를 가져와 배포만 진행할 수 있습니다.
• PersistentVolume(PV) 설정: PVC를 통해 Runner의 작업 디렉터리(/home/runner/_work)에 영구적인 스토리지를 연결하여, 아티팩트를 유지하거나 외부 저장소로부터 필요한 파일을 가져오는 방식으로 해결할 수 있습니다.

 

3. Error: Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under ... 에러의 원인

에러 메시지

Error: Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under '/home/runner/_work/test-springboot-jdk17/test-springboot-jdk17/.github/workflows/actions/deploy-ssh-blob-vm'. Did you forget to run actions/checkout before running your local action?

 

에러 발생 원인

이 에러는 GitHub Actions Runner가 특정 파일(action.yml, Dockerfile)을 찾지 못했을 때 발생합니다. 이는 다음과 같은 상황에서 발생할 수 있습니다.

1. actions/checkout 누락: 일반적으로 checkout 단계에서 리포지토리를 복제해야 하지만, 이 단계가 생략되었거나 누락되어 Runner가 리포지토리를 찾지 못하는 경우
2. 작업 디렉터리(/home/runner/_work) 미존재 또는 비어 있음: Runner가 작업 디렉터리에 파일을 저장하지 못하거나, PVC가 마운트되지 않으면 해당 디렉터리가 생성되지 않거나 비어 있을 수 있습니다.
3. PVC/PV 설정 문제: Runner Pod에서 영구적인 스토리지(PV/PVC)를 사용하지 않아 작업 디렉터리가 휘발성으로 처리되는 경우.

Error 해결 방안

• PersistentVolumeClaim(PVC) 설정: PVC를 설정하여 GitHub Actions Runner의 작업 디렉터리를 영구적으로 유지할 수 있게 합니다.
• actions/checkout 대체: checkout 없이 배포하려면, 이미 저장된 빌드 아티팩트를 배포 시점에 외부 저장소(Azure Blob Storage 등)에서 가져오는 작업을 추가해야 합니다.

 

4. PersistentVolumeClaim(PVC)와 Checkout 없이 배포

PVC 설정

PVC를 사용하면 GitHub Actions Runner가 작업하는 디렉터리(/home/runner/_work)를 영구적으로 유지할 수 있습니다. 이를 통해 Runner Pod가 재시작되더라도 이전에 작업했던 파일들이 사라지지 않도록 보장합니다. 다음은 PVC를 설정하는 방법입니다.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: work
  namespace: arc-runners
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: azurefile-csi-nfs
  


vi pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: cache-maven
  namespace: arc-runners
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi
  storageClassName: azurefile-csi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: work
  namespace: arc-runners
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi
  storageClassName: azurefile-csi

이 PVC는 5Gi 크기로, 여러 Runner Pod가 동시에 읽고 쓸 수 있도록 설정됩니다. arc-runners 네임스페이스에 생성됩니다.

 

checkout 없이 배포

GitHub Actions에서 checkout 없이 배포하려면, 이미 생성된 빌드 아티팩트를 활용하는 것이 핵심입니다. 이를 위해서는 다음의 전제 조건이 충족되어야 합니다.

• 빌드 아티팩트가 미리 저장된 상태: JAR 파일 등 빌드 산출물이 외부 저장소(Azure Blob Storage 등)에 이미 업로드되어 있어야 합니다.
• Persistent Volume Claim(PVC) 설정: 실행기가 배포를 위해 사용하는 디렉토리(/home/runner/_work 등)가 영구적으로 유지되도록 PVC를 설정합니다.

PersistentVolumeClaim(PVC)를 설정해 디렉터리를 영구적으로 유지하면, Pod가 재시작되거나 다른 실행기가 할당되더라도 동일한 스토리지에 접근할 수 있습니다.

''' 
 
 - name: Upload jar file to Object Storage
      run: |
        az storage blob upload \
          --account-name ${{ vars.AZURE_COMMON_STORAGE_ACCOUNT }} \
          --container-name ${{ vars.AZURE_COMMON_ARTIFACT_CONTAINER }} \
          --file ./target/*.jar \
          --name ${{ vars.APP_NAME }}.jar \
          --overwrite \
          --auth-mode login
      shell: bash

'''

  deploy-dev:
    name: (${{ inputs.environment }}) Deploy using ssh and blob
    runs-on: "${{ inputs.runner }}"
    needs: build
    if: ${{ inputs.environment == 'dev' }}
    steps:
      - name: Deploy java app
        uses: ./.github/workflows/actions/deploy-ssh-blob-vm
        with:
          environment: "${{ inputs.environment }}"
          storage-account: "${{ vars.AZURE_COMMON_STORAGE_ACCOUNT }}"
          storage-container: "${{ vars.AZURE_COMMON_ARTIFACT_CONTAINER }}"
          storage-access-key: "${{ secrets.AZURE_COMMON_STORAGE_ACCESS_KEY }}"
          ssh-private-key: "${{ secrets.AZURE_VM_SSH_PRIVATE_KEY_DEV }}"
          vm-prefix: "${{ vars.AZURE_VM_PREFIX }}"
          vm-suffix: "vm"
          vm-ip: "${{ secrets.AZURE_VM_IP_DEV }}"
          vm-user: "${{ vars.AZURE_VM_USER }}"
          app-name: "${{ vars.APP_NAME }}"
'''

 

deploy 상에 checkout 없이도 이제 잘 배포됨을 확인할 수 있습니다.