기록 저장소

GitHub Actions에서 커밋 해시 기반 Docker 이미지 태그로 배포 자동화하기

hwara_ — Fri, 29 May 2026 12:32:21 +0900

GitHub Actions에서 커밋 해시 기반 Docker 이미지 태그로 배포 자동화하기

이번 글에서는 GitHub Actions를 이용해 Docker 이미지를 빌드하고, 커밋 해시 기반 태그로 이미지를 푸시한 뒤, Kubernetes 배포에 사용하는 Kustomize overlay 파일까지 자동으로 수정하는 과정을 정리합니다.

현재 프로젝트에서는 로컬 Kubernetes 환경에 서비스를 배포하고 있으며, 이미지는 로컬 private registry에 푸시합니다. 이후 Argo CD가 Git 저장소의 변경 사항을 감지해 클러스터에 배포하는 GitOps 흐름을 사용하고 있습니다.

전체 흐름은 다음과 같습니다.

main 브랜치에 코드가 push됨
GitHub Actions가 실행됨
커밋 해시를 기반으로 Docker 이미지 태그 생성
Docker Compose로 각 서비스 이미지 빌드 및 push
Kustomize overlay의 이미지 태그 수정
변경된 kustomization.yaml을 다시 GitHub에 commit/push
Argo CD가 변경 사항을 감지하고 배포

현재 사용 중인 GitHub Actions 예시

name: CD Local GitOps

on:
  push:
    branches:
      - main

  workflow_dispatch:

permissions: {}

concurrency:
  group: cd-local-gitops-main
  cancel-in-progress: false

env:
  REGISTRY: 172.25.46.10:32000

jobs:
  build-push-and-update-overlay:
    name: Build, push, and update local overlay
    if: github.actor != 'github-actions[bot]' && github.ref_name == 'main'
    permissions:
      contents: write
    runs-on: [self-hosted, Linux, X64]
    steps:
      - name: Check out repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
        with:
          ref: ${{ github.ref_name }}
          persist-credentials: true

      - name: Check Docker access
        run: docker version

      - name: Set image tag
        run: |
          echo "IMAGE_TAG=${GITHUB_SHA::12}" >> "$GITHUB_ENV"
          echo "TAG=${GITHUB_SHA::12}" >> "$GITHUB_ENV"

      - name: Create Compose env placeholders
        shell: bash
        run: |
          set -euo pipefail

          services=(
            api-gateway
            user-service
            product-service
            order-service
            payment-service
            notification-service
          )

          for service in "${services[@]}"; do
            env_file="services/${service}/.env"
            if [ ! -f "${env_file}" ]; then
              touch "${env_file}"
            fi
          done

      - name: Build and push service images
        shell: bash
        run: |
          set -euo pipefail

          docker compose -f docker/services.yaml build
          docker compose -f docker/services.yaml push

      - name: Set up Kustomize
        uses: imranismail/setup-kustomize@2ba527d4d055ab63514ba50a99456fc35684947f

      - name: Commit and push overlay update
        shell: bash
        run: |
          set -euo pipefail

          git fetch origin main
          git rebase origin/main

          services=(
            user-service
            product-service
            order-service
            payment-service
            notification-service
            api-gateway
          )

          pushd k8s/services/overlays/local
          for service in "${services[@]}"; do
            kustomize edit set image "${service}=${REGISTRY}/${service}:${IMAGE_TAG}"
          done
          popd

          if git diff --quiet -- k8s/services/overlays/local/kustomization.yaml; then
            echo "No overlay image tag changes to commit."
            exit 0
          fi

          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add k8s/services/overlays/local/kustomization.yaml
          git commit -m "chore: update local image tags ${IMAGE_TAG}"
          git push

Workflow 실행 조건 설정

먼저 workflow의 실행 조건과 공통 설정은 다음과 같습니다.

on:
  push:
    branches:
      - main

  workflow_dispatch:

permissions: {}

concurrency:
  group: cd-local-gitops-main
  cancel-in-progress: false

env:
  REGISTRY: 172.25.46.10:32000

on.push.branches는 main 브랜치에 commit이 push되었을 때 workflow를 실행한다는 의미입니다.

workflow_dispatch:

workflow_dispatch는 GitHub Actions 페이지에서 사용자가 직접 workflow를 실행할 수 있도록 하는 설정입니다. 자동 실행뿐만 아니라 필요할 때 수동으로 배포를 실행할 수 있습니다.

permissions: {}

전역 permissions는 비워두고, 실제 권한이 필요한 job에서만 필요한 권한을 부여하도록 구성했습니다. 이렇게 하면 workflow 전체에 불필요한 권한이 부여되는 것을 줄일 수 있습니다.

concurrency:
  group: cd-local-gitops-main
  cancel-in-progress: false

concurrency는 동시에 실행되는 workflow를 제어하기 위한 설정입니다. 동일한 concurrency group을 사용하는 workflow가 중복 실행되지 않도록 제한할 수 있습니다.

이 설정이 필요한 이유는 이미지 빌드와 배포가 동시에 여러 번 실행될 경우, 어떤 이미지 태그가 최신 상태인지 혼란스러워질 수 있기 때문입니다. 특히 GitOps 방식에서는 Git 저장소의 최종 상태가 실제 배포 상태의 기준이 되므로, 배포 관련 workflow의 동시 실행은 주의해서 제어하는 것이 좋습니다.

env:
  REGISTRY: 172.25.46.10:32000

env에는 workflow에서 공통으로 사용할 환경변수를 선언했습니다. 여기서는 Docker 이미지를 push할 private registry 주소를 REGISTRY로 정의했습니다.

Job 설정

다음은 실제 배포 작업을 수행하는 job 설정입니다.

jobs:
  build-push-and-update-overlay:
    name: Build, push, and update local overlay
    if: github.actor != 'github-actions[bot]' && github.ref_name == 'main'
    permissions:
      contents: write
    runs-on: [self-hosted, Linux, X64]

build-push-and-update-overlay는 job의 식별자입니다. GitHub Actions 화면에서는 name에 지정한 Build, push, and update local overlay라는 이름으로 표시됩니다.

if: github.actor != 'github-actions[bot]' && github.ref_name == 'main'

이 조건은 workflow가 실행되더라도 실제 job이 실행될지 한 번 더 검사합니다.

여기서 중요한 부분은 다음 조건입니다.

github.actor != 'github-actions[bot]'

이 workflow는 마지막 단계에서 kustomization.yaml을 수정한 뒤 github-actions[bot] 계정으로 다시 commit/push합니다. 만약 이 조건이 없다면, bot이 push한 commit으로 인해 workflow가 다시 실행될 수 있습니다.

즉, 이 조건은 GitHub Actions가 만든 commit으로 인해 workflow가 반복 실행되는 상황을 막기 위한 장치입니다.

permissions:
  contents: write

이 job은 저장소의 파일을 수정하고 다시 push해야 하므로 contents: write 권한이 필요합니다.

runs-on: [self-hosted, Linux, X64]

runs-on은 job을 실행할 runner를 지정합니다. 현재는 로컬 환경의 Docker와 private registry를 사용해야 하므로 GitHub-hosted runner가 아니라 self-hosted runner를 사용하도록 설정했습니다.

이 runner에는 Docker 명령어를 실행할 수 있는 환경이 미리 준비되어 있어야 합니다.

Repository checkout

- name: Check out repository
  uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
  with:
    ref: ${{ github.ref_name }}
    persist-credentials: true

첫 번째 단계에서는 actions/checkout을 사용해 현재 브랜치의 코드를 runner로 가져옵니다.

ref: ${{ github.ref_name }}

현재 workflow가 실행된 브랜치를 checkout합니다.

persist-credentials: true

이후 단계에서 GitHub에 commit/push를 해야 하므로 인증 정보를 유지합니다.

Docker 사용 가능 여부 확인

- name: Check Docker access
  run: docker version

self-hosted runner에서 Docker 명령어를 정상적으로 사용할 수 있는지 확인합니다.

이 단계에서 실패한다면 runner 환경에서 Docker가 설치되어 있지 않거나, 현재 runner 사용자가 Docker에 접근할 권한이 없는 상태일 수 있습니다.

커밋 해시 기반 이미지 태그 생성

- name: Set image tag
  run: |
    echo "IMAGE_TAG=${GITHUB_SHA::12}" >> "$GITHUB_ENV"
    echo "TAG=${GITHUB_SHA::12}" >> "$GITHUB_ENV"

이 단계에서는 현재 commit hash의 앞 12자리를 이미지 태그로 사용합니다.

예를 들어 commit hash가 다음과 같다면,

a1b2c3d4e5f67890...

이미지 태그는 다음처럼 생성됩니다.

a1b2c3d4e5f6

latest 태그를 사용하면 실제 어떤 commit으로 빌드된 이미지인지 추적하기 어렵습니다. 반면 commit hash 기반 태그를 사용하면 특정 이미지가 어떤 코드 상태에서 만들어졌는지 추적하기 쉬워집니다.

echo "IMAGE_TAG=${GITHUB_SHA::12}" >> "$GITHUB_ENV"

$GITHUB_ENV에 값을 기록하면 이후 step에서도 해당 환경변수를 사용할 수 있습니다.

여기서는 IMAGE_TAG와 TAG를 모두 같은 값으로 설정했습니다. docker compose 파일에서 TAG 환경변수를 참조하고 있다면, 이 값이 이미지 태그로 사용됩니다.

Docker Compose용 env 파일 생성

- name: Create Compose env placeholders
  shell: bash
  run: |
    set -euo pipefail

    services=(
      api-gateway
      user-service
      product-service
      order-service
      payment-service
      notification-service
    )

    for service in "${services[@]}"; do
      env_file="services/${service}/.env"
      if [ ! -f "${env_file}" ]; then
        touch "${env_file}"
      fi
    done

현재 docker compose 설정에서는 각 서비스의 .env 파일을 참조하고 있습니다. 하지만 GitHub에 .env 파일을 올리지 않는 경우, runner 환경에서는 해당 파일이 존재하지 않아 compose 실행 중 오류가 발생할 수 있습니다.

이를 방지하기 위해 각 서비스 디렉터리에 .env 파일이 없으면 빈 파일을 생성하도록 했습니다.

set -euo pipefail

이 설정은 bash script를 더 안전하게 실행하기 위해 사용합니다.

-e: 명령어 실패 시 즉시 종료
-u: 선언되지 않은 변수를 사용하면 오류 처리
-o pipefail: pipe 중간에서 실패한 명령도 실패로 처리

Docker 이미지 빌드 및 Push

- name: Build and push service images
  shell: bash
  run: |
    set -euo pipefail

    docker compose -f docker/services.yaml build
    docker compose -f docker/services.yaml push

이 단계가 실제 Docker 이미지를 빌드하고 registry에 push하는 부분입니다.

docker compose -f docker/services.yaml build

docker/services.yaml에 정의된 서비스 이미지를 빌드합니다.

docker compose -f docker/services.yaml push

빌드된 이미지를 registry로 push합니다.

이 workflow에서는 직접 Docker 명령어를 실행하고 있지만, 상황에 따라 docker/build-push-action 같은 미리 만들어진 GitHub Action을 사용할 수도 있습니다.

다만 현재처럼 self-hosted runner에서 로컬 private registry를 사용하고, 여러 서비스를 compose 기반으로 한 번에 빌드하는 경우에는 직접 docker compose 명령어를 실행하는 방식도 단순하고 직관적입니다.

Kustomize 설치

- name: Set up Kustomize
  uses: imranismail/setup-kustomize@2ba527d4d055ab63514ba50a99456fc35684947f

이미지를 빌드하고 push한 뒤에는 Kubernetes manifest에서 사용하는 이미지 태그를 새 태그로 변경해야 합니다.

이 프로젝트에서는 Kustomize를 사용하고 있으므로, kustomize edit set image 명령어를 실행하기 위해 Kustomize를 설치합니다.

Kustomize overlay 이미지 태그 수정 및 commit

- name: Commit and push overlay update
  shell: bash
  run: |
    set -euo pipefail

    git fetch origin main
    git rebase origin/main

    services=(
      user-service
      product-service
      order-service
      payment-service
      notification-service
      api-gateway
    )

    pushd k8s/services/overlays/local
    for service in "${services[@]}"; do
      kustomize edit set image "${service}=${REGISTRY}/${service}:${IMAGE_TAG}"
    done
    popd

    if git diff --quiet -- k8s/services/overlays/local/kustomization.yaml; then
      echo "No overlay image tag changes to commit."
      exit 0
    fi

    git config user.name "github-actions[bot]"
    git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
    git add k8s/services/overlays/local/kustomization.yaml
    git commit -m "chore: update local image tags ${IMAGE_TAG}"
    git push

이 단계에서는 Kustomize overlay에 정의된 서비스 이미지 태그를 새로 빌드한 이미지 태그로 변경합니다.

먼저 원격 저장소의 최신 상태를 가져온 뒤 rebase합니다.

git fetch origin main
git rebase origin/main

이미 workflow가 실행되는 동안 다른 commit이 main에 추가되었을 수 있으므로, push 전에 최신 상태를 반영하기 위한 처리입니다.

이후 이미지 태그를 변경할 서비스 목록을 정의합니다.

services=(
  user-service
  product-service
  order-service
  payment-service
  notification-service
  api-gateway
)

그리고 Kustomize overlay 디렉터리로 이동합니다.

pushd k8s/services/overlays/local

각 서비스에 대해 kustomize edit set image를 실행합니다.

for service in "${services[@]}"; do
  kustomize edit set image "${service}=${REGISTRY}/${service}:${IMAGE_TAG}"
done

이 명령어를 실행하면 kustomization.yaml의 이미지 설정이 새 태그로 변경됩니다.

작업이 끝나면 다시 기존 working directory로 돌아옵니다.

popd

변경 사항이 없을 때는 commit하지 않기

if git diff --quiet -- k8s/services/overlays/local/kustomization.yaml; then
  echo "No overlay image tag changes to commit."
  exit 0
fi

이 부분은 kustomization.yaml에 실제 변경 사항이 있는지 확인합니다.

변경 사항이 없다면 굳이 commit을 만들 필요가 없으므로 workflow를 정상 종료합니다.

GitHub Actions Bot 계정으로 commit/push

git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add k8s/services/overlays/local/kustomization.yaml
git commit -m "chore: update local image tags ${IMAGE_TAG}"
git push

변경 사항이 있다면 GitHub Actions bot 계정으로 commit을 생성하고 push합니다.

이 commit이 Git 저장소에 반영되면, Argo CD는 변경된 kustomization.yaml을 기준으로 새로운 이미지 태그를 감지하고 Kubernetes 클러스터에 배포할 수 있습니다.

정리

이번 설정을 통해 main 브랜치에 push하거나 GitHub Actions 화면에서 workflow를 수동 실행했을 때 다음 작업을 자동화할 수 있었습니다.

repository checkout
commit hash 기반 이미지 태그 생성
Docker Compose 기반 이미지 빌드
private registry로 이미지 push
Kustomize overlay의 이미지 태그 수정
변경된 manifest 파일 commit/push
Argo CD를 통한 GitOps 배포 연계

특히 이미지 태그를 commit hash 기반으로 관리하면, 어떤 코드가 어떤 이미지로 빌드되었는지 추적하기 쉬워집니다. 또한 Kustomize overlay 파일까지 자동으로 수정하므로, 이미지 빌드 이후 Kubernetes 배포 manifest를 직접 수정하는 과정을 줄일 수 있습니다.

이 구조를 응용하면 로컬 Kubernetes 환경뿐만 아니라 개발, 스테이징, 운영 환경별 overlay를 분리해 더 체계적인 GitOps 배포 흐름으로 확장할 수 있습니다.

Reference

https://docs.github.com/ko/actions/get-started/quickstart

Kustomize secretGenerator와 Argo CD 동기화 오류 해결하기

hwara_ — Tue, 26 May 2026 11:32:05 +0900

개요

이번 글에서는 Kustomize의 secretGenerator를 사용해 Secret을 생성하던 중, Argo CD에서 동기화 오류가 발생한 문제를 정리합니다.

로컬에서는 .env 파일을 기준으로 Secret을 생성해 사용할 수 있었지만, 해당 .env 파일은 민감 정보이기 때문에 GitHub에 업로드하지 않았습니다. 그 결과 Argo CD가 Git 저장소를 기준으로 매니페스트를 생성하는 과정에서 .env 파일을 찾지 못해 에러가 발생했습니다.

문제 상황

Kustomize에서 다음과 같은 방식으로 Secret을 생성하고 있었습니다.

secretGenerator:
  - name: user-database-secret
    envs:
      - secrets/user-database-secret.env

그리고 Deployment에서는 해당 Secret을 참조해 환경 변수를 주입받는 구조였습니다.

로컬 환경에서는 secrets/user-database-secret.env 파일이 존재했기 때문에 정상적으로 동작했습니다. 하지만 이 파일은 데이터베이스 비밀번호 같은 민감 정보를 포함하고 있어 GitHub에는 업로드하지 않았습니다.

이후 Argo CD에서 Application을 동기화하려고 하자 다음과 같은 에러가 발생했습니다.

ComparisonError
Failed to load target state: failed to generate manifest for source 1 of 1: rpc error: code = Unknown desc = `kustomize build <path to cached source>/k8s/services/overlays/local` failed exit status 1: Error: loading KV pairs: env source files: [secrets/user-database-secret.env]: evalsymlink failure on '<path to cached source>/k8s/services/overlays/local/secrets/user-database-secret.env' : lstat <path to cached source>/k8s/services/overlays/local/secrets/user-database-secret.env: no such file or directory

원인 분석

에러의 핵심은 다음 부분입니다.

secrets/user-database-secret.env: no such file or directory

Argo CD는 Git 저장소에 있는 파일을 기준으로 매니페스트를 생성합니다. 즉, Argo CD가 kustomization.yaml을 읽고 kustomize build를 실행할 때, secretGenerator에 명시된 .env 파일도 함께 존재해야 합니다.

하지만 실제 구조는 다음과 같았습니다.

Kustomize의 secretGenerator는 .env 파일을 읽어 Kubernetes Secret을 생성한다.
Deployment는 생성된 Secret을 참조해 환경 변수를 사용한다.
민감 정보가 포함된 .env 파일은 GitHub에 업로드하지 않았다.
Argo CD는 Git 저장소를 기준으로 kustomize build를 실행한다.
Git 저장소에는 .env 파일이 없으므로 Secret 생성에 실패한다.
결과적으로 Argo CD의 비교 및 동기화 과정에서 ComparisonError가 발생한다.

정리하면, Kustomize가 필요로 하는 입력 파일은 Argo CD가 접근 가능한 Git 저장소 안에 있어야 하는데, Secret의 기반이 되는 .env 파일이 Git에 없어서 발생한 문제였습니다.

해결 방법

해결 방법은 크게 몇 가지가 있습니다.

1. Sealed Secrets 사용

Sealed Secrets를 사용하면 Secret 값을 암호화된 형태로 Git에 저장할 수 있습니다.

Git에는 일반 Secret이 아니라 암호화된 SealedSecret 리소스를 저장하고, 클러스터 내부의 컨트롤러가 이를 복호화해 실제 Kubernetes Secret을 생성합니다.

이 방식은 GitOps 흐름과 잘 맞지만, 별도의 Sealed Secrets 컨트롤러 설치와 키 관리가 필요합니다.

2. External Secrets Operator 사용

운영 환경에서는 External Secrets Operator, 즉 ESO를 사용하는 방법도 있습니다.

ESO는 AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager 같은 외부 Secret 저장소에서 값을 가져와 Kubernetes Secret으로 동기화할 수 있습니다.

이 방식은 민감 정보를 Git에 직접 저장하지 않으면서도 Argo CD 기반 배포 흐름을 유지할 수 있다는 장점이 있습니다.

운영 환경이라면 단순히 Secret을 수동 생성하는 방식보다는 ESO 같은 Secret 관리 도구를 도입하는 것이 더 적절해 보입니다.

3. Secret을 클러스터에 직접 생성

이번에는 로컬 테스트 환경이었기 때문에 가장 단순한 방식으로 해결했습니다.

kustomization.yaml에서 secretGenerator 설정을 제거하고, Secret을 미리 생성하는 스크립트를 별도로 작성했습니다.

흐름은 다음과 같습니다.

Secret 생성 스크립트를 실행한다.
Kubernetes 클러스터에 Secret을 먼저 생성한다.
Argo CD에서 Application을 Sync한다.
Deployment는 이미 생성된 Secret을 참조한다.

즉, Argo CD가 Kustomize를 실행할 때 더 이상 Git에 없는 .env 파일을 참조하지 않도록 변경했습니다.

예를 들어 다음과 같은 방식으로 Secret을 미리 생성할 수 있습니다.

kubectl create secret generic user-database-secret \
  --from-env-file=secrets/user-database-secret.env \
  -n <namespace>

이미 동일한 이름의 Secret이 존재할 수 있다면 다음처럼 dry-run과 apply를 조합해 사용할 수도 있습니다.

kubectl create secret generic user-database-secret \
  --from-env-file=secrets/user-database-secret.env \
  -n <namespace> \
  --dry-run=client -o yaml | kubectl apply -f -

위 명령어에서 <namespace>는 실제 Secret을 사용할 네임스페이스로 변경해야 합니다.

적용 결과

kustomization.yaml에서 secretGenerator를 제거한 뒤, Secret을 먼저 생성하고 Argo CD Sync를 다시 실행했습니다.

그 결과 Argo CD가 더 이상 Git에 없는 .env 파일을 찾지 않았고, Application이 정상적으로 배포되는 것을 확인했습니다.

이번 방식은 로컬 테스트 환경에서는 간단하게 적용할 수 있는 해결책이었습니다. 다만 운영 환경에서는 Secret을 수동으로 생성하는 방식이 관리 포인트를 늘릴 수 있습니다.

따라서 운영 환경에서는 다음과 같은 방식을 고려하는 것이 좋습니다.

Sealed Secrets를 사용해 암호화된 Secret을 Git에 저장
External Secrets Operator를 사용해 외부 Secret 저장소와 연동
Secret 생성 및 갱신 방식을 배포 프로세스 안에서 명확하게 관리

정리

이번 문제는 Kustomize의 secretGenerator 자체 문제라기보다는, Argo CD가 Git 저장소를 기준으로 매니페스트를 생성한다는 점을 고려하지 않아 발생한 문제였습니다.

로컬에는 .env 파일이 존재했지만, GitHub에는 해당 파일이 없었고 Argo CD는 GitHub에 있는 파일만 기준으로 kustomize build를 실행했습니다. 따라서 secretGenerator가 참조하는 .env 파일을 찾지 못해 배포가 실패했습니다.

로컬 테스트 환경에서는 Secret을 미리 생성하는 방식으로 해결할 수 있었습니다.

하지만 운영 환경에서는 Secret을 GitOps 흐름 안에서 안전하게 관리할 수 있도록 Sealed Secrets나 External Secrets Operator 같은 도구를 사용하는 것이 더 적절합니다.

Helm으로 Argo CD 설치 후 Gateway API와 TLS로 접속 구성하기

hwara_ — Tue, 26 May 2026 10:30:19 +0900

이번 글에서는 Kubernetes 클러스터에 Argo CD를 설치하고, Gateway API를 이용해 외부에서 접속할 수 있도록 구성하는 과정을 정리합니다.

설치는 Helm Chart를 사용했으며, 외부 노출은 Gateway API를 통해 처리했습니다. 로컬 테스트 환경에서는 Argo CD가 생성한 인증서를 별도의 TLS Secret으로 복사해 Gateway에서 사용하도록 구성했습니다.

구성 개요

전체 구성 흐름은 다음과 같습니다.

Helm으로 Argo CD 설치
Gateway에서 사용할 TLS Secret 준비
Gateway와 HTTPRoute를 적용해 Argo CD Server 외부 노출
초기 admin 계정으로 로그인
Argo CD Application 리소스 생성

이 글에서는 Gateway가 HTTPS를 종료하고, Argo CD Server에는 HTTP로 트래픽을 전달하는 방식을 사용합니다.

1. Argo CD 설치

먼저 Argo CD 설치에 사용할 argocd-values.yaml 파일을 작성합니다.

configs:
  params:
    server.insecure: true

여기서 중요한 설정은 다음 값입니다.

server.insecure: true

이 설정은 Argo CD Server가 자체적으로 HTTPS를 처리하지 않고 HTTP로 동작하도록 만드는 설정입니다.

이번 구성에서는 Gateway가 HTTPS TLS Termination을 담당하고, Argo CD Server에는 HTTP 포트인 80으로 요청을 전달합니다. 따라서 Argo CD Server 입장에서는 HTTPS가 아닌 HTTP 요청을 받도록 설정해야 합니다.

즉, 역할을 나누면 다음과 같습니다.

Gateway: 외부 HTTPS 요청 수신 및 TLS 종료
Argo CD Server: Gateway로부터 HTTP 요청 수신

이제 Helm으로 Argo CD를 설치합니다.

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

helm upgrade --install my-argo-cd argo/argo-cd \
  --version 9.5.15 \
  -n argocd \
  --create-namespace \
  -f argocd-values.yaml

설치가 끝나면 환경에 맞게 Argo CD Server를 외부에 노출해야 합니다.

간단한 테스트만 필요하다면 kubectl port-forward를 사용할 수도 있습니다. 이번 구성에서는 Gateway API를 사용해 외부에서 접근할 수 있도록 구성했습니다.

2. Gateway TLS Secret 준비

Gateway API에서 HTTPS Listener를 사용하려면 TLS 인증서 Secret이 필요합니다.

Argo CD Helm Chart는 기본적으로 argocd-secret을 생성하며, 이 Secret 안에는 tls.crt, tls.key 데이터가 포함될 수 있습니다. 하지만 argocd-secret의 타입은 일반적으로 Opaque입니다.

Gateway API의 certificateRefs에서 사용하는 인증서 Secret은 kubernetes.io/tls 타입이어야 하므로, argocd-secret을 그대로 Gateway의 인증서 Secret으로 사용할 수 없습니다.

따라서 로컬 테스트 환경에서는 argocd-secret에 들어 있는 인증서 데이터를 별도의 TLS Secret으로 복사했습니다.

kubectl get secret argocd-secret -n argocd \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > /tmp/argocd-tls.crt

kubectl get secret argocd-secret -n argocd \
  -o jsonpath='{.data.tls\.key}' | base64 -d > /tmp/argocd-tls.key

kubectl create secret tls argocd-gateway-tls \
  -n argocd \
  --cert=/tmp/argocd-tls.crt \
  --key=/tmp/argocd-tls.key \
  --dry-run=client -o yaml | kubectl apply -f -

위 명령어는 다음 순서로 동작합니다.

argocd-secret에서 tls.crt 값을 꺼내 인증서 파일로 저장
argocd-secret에서 tls.key 값을 꺼내 개인키 파일로 저장
두 파일을 사용해 kubernetes.io/tls 타입의 Secret 생성

생성되는 Secret 이름은 다음과 같습니다.

argocd-gateway-tls

이 Secret은 이후 Gateway의 certificateRefs에서 참조됩니다.

운영 환경에서는 이처럼 Argo CD 내부 Secret을 복사하기보다는, 일반적으로 cert-manager나 외부 인증서 관리 방식을 사용하는 것이 좋습니다.

3. Gateway와 HTTPRoute 적용

이제 Gateway API 리소스를 작성해 Argo CD Server를 외부에 노출합니다.

먼저 Gateway YAML을 작성합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: argocd-gateway
  namespace: argocd
spec:
  gatewayClassName: eg
  listeners:
    - protocol: HTTPS
      port: 443
      name: argocd-gateway
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
          - name: argocd-gateway-tls
            kind: Secret
            group: ""

이 Gateway는 443 포트에서 HTTPS 요청을 받습니다.

주요 설정은 다음과 같습니다.

gatewayClassName: eg

사용할 GatewayClass를 지정합니다. 이 값은 클러스터에 설치된 Gateway Controller에 따라 달라집니다. 예제에서는 eg를 사용했습니다.

tls:
  mode: Terminate

Gateway에서 TLS를 종료한다는 의미입니다. 즉, 외부 클라이언트는 HTTPS로 Gateway에 접근하지만, Gateway 뒤쪽의 Argo CD Server로는 HTTP 요청이 전달됩니다.

certificateRefs:
  - name: argocd-gateway-tls

앞에서 생성한 TLS Secret을 참조합니다.

다음으로 HTTPRoute YAML을 작성합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: argocd-http-route
  namespace: argocd
spec:
  parentRefs:
    - name: argocd-gateway
  rules:
    - backendRefs:
        - name: my-argo-cd-argocd-server
          port: 80

이 HTTPRoute는 argocd-gateway로 들어온 요청을 Argo CD Server Service로 전달합니다.

여기서 backendRefs.name에는 Argo CD Server Service 이름을 지정합니다.

backendRefs:
  - name: my-argo-cd-argocd-server
    port: 80

Helm 설치 시 release 이름을 my-argo-cd로 지정했기 때문에, Argo CD Server Service 이름은 다음과 같은 형태가 됩니다.

my-argo-cd-argocd-server

실제 Service 이름은 Helm release 이름이나 Chart 버전에 따라 달라질 수 있으므로,
적용 전에 kubectl get svc -n argocd로 확인하는 것이 좋습니다.

작성한 리소스를 적용합니다.

kubectl apply -f k8s/argocd/argocd-gateway.yaml
kubectl apply -f k8s/argocd/argocd-http-route.yaml

적용 후 Gateway와 HTTPRoute 상태를 확인합니다.

kubectl describe gateway argocd-gateway -n argocd
kubectl describe httproute argocd-http-route -n argocd

Gateway와 HTTPRoute가 정상적으로 연결되었다면, Gateway Controller가 할당한 주소를 통해 Argo CD UI에 접근할 수 있습니다.

4. 초기 로그인

Argo CD의 초기 admin 비밀번호는 argocd-initial-admin-secret Secret에 저장되어 있습니다.

다음 명령어로 초기 비밀번호를 확인합니다.

kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath='{.data.password}' | base64 -d

기본 계정 정보는 다음과 같습니다.

Username: admin
Password: 위 명령어로 확인한 값

초기 비밀번호로 로그인한 뒤에는 보안을 위해 비밀번호를 변경합니다.

Argo CD UI에서 다음 메뉴로 이동합니다.

User Info -> UPDATE PASSWORD

비밀번호를 변경한 뒤에는 기존 초기 비밀번호 Secret이 더 이상 필요하지 않은지 확인하고, 운영 환경에서는 적절히 정리하는 것이 좋습니다.

5. Application 적용

Argo CD는 Application이라는 Kubernetes CRD를 통해 Git Repository와 배포 대상을 정의합니다.

Application은 UI에서 생성할 수도 있고, YAML로 작성해 Kubernetes에 직접 적용할 수도 있습니다.

이번 구성에서는 Application YAML을 작성해 직접 적용했습니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: micro-mart-local
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/Hwara/micro-mart.git
    targetRevision: main
    path: k8s/services/overlays/local
  destination:
    server: https://kubernetes.default.svc
    namespace: micro-mart-local
  syncPolicy: {}

각 설정의 의미는 다음과 같습니다.

project: default

Application이 속할 Argo CD Project를 지정합니다. 별도로 Project를 생성하지 않았다면 기본값인 default를 사용할 수 있습니다.

source:
  repoURL: https://github.com/Hwara/micro-mart.git
  targetRevision: main
  path: k8s/services/overlays/local

source는 Argo CD가 추적할 Git 저장소와 배포 대상 매니페스트 위치를 정의합니다.

repoURL: Argo CD가 추적할 Git Repository URL
targetRevision: 추적할 브랜치, 태그 또는 커밋
path: Repository 내부에서 Kubernetes YAML 또는 Kustomize 설정이 위치한 경로

예제에서는 main 브랜치의 k8s/services/overlays/local 경로를 기준으로 배포 상태를 추적합니다.

destination:
  server: https://kubernetes.default.svc
  namespace: micro-mart-local

destination은 배포할 Kubernetes 클러스터와 네임스페이스를 지정합니다.

server: 배포 대상 클러스터 주소
namespace: 리소스를 배포할 네임스페이스

https://kubernetes.default.svc는 Argo CD가 설치된 현재 클러스터를 의미합니다.

syncPolicy: {}

예제에서는 자동 동기화를 설정하지 않았습니다. 따라서 Git Repository의 변경 사항이 감지되더라도 자동으로 배포되지는 않고, 사용자가 Argo CD UI나 CLI에서 수동으로 Sync를 실행해야 합니다.

자동 동기화를 사용하고 싶다면 syncPolicy.automated 설정을 추가할 수 있습니다. 다만 운영 환경에서는 자동 동기화 적용 여부를 신중히 결정하는 것이 좋습니다.

6. Argo CD UI에서 Application 상태 확인 및 수동 Sync

Application YAML을 Kubernetes에 적용했다면, 외부 노출한 Argo CD 주소로 접속합니다.

로그인 후 왼쪽 메뉴 또는 메인 화면의 Applications 탭으로 이동하면, 앞에서 생성한 Application을 확인할 수 있습니다.

Application 카드에서는 현재 배포 상태를 간단히 확인할 수 있습니다.

주로 확인할 값은 다음과 같습니다.

APP HEALTH
- 애플리케이션이 Kubernetes 클러스터에서 정상 동작 중인지 나타냅니다.
- 예를 들어 리소스가 정상적으로 실행 중이면 Healthy로 표시됩니다.
SYNC STATUS
- Git Repository에 정의된 상태와 실제 Kubernetes 클러스터 상태가 일치하는지 나타냅니다.
- Git의 매니페스트와 클러스터 상태가 일치하면 Synced, 차이가 있으면 OutOfSync로 표시됩니다.

생성된 Application을 클릭하면 더 자세한 리소스 상태를 확인할 수 있습니다.

상세 화면에서는 Application에 포함된 Kubernetes 리소스들이 어떤 상태인지 시각적으로 확인할 수 있습니다.

이를 통해 특정 리소스가 정상적으로 생성되었는지, Pod가 정상 실행 중인지, Service나 Deployment에 문제가 없는지 확인할 수 있습니다.

수동 Sync 실행

이번 예제에서는 Application YAML에 자동 동기화 설정을 추가하지 않았습니다.

syncPolicy: {}

따라서 Git Repository에 있는 매니페스트를 실제 클러스터에 반영하려면 Argo CD UI에서 수동으로 Sync를 실행해야 합니다.

수동 Sync는 다음 순서로 진행합니다.

Argo CD UI에서 Application을 클릭합니다.
상단의 SYNC 버튼을 클릭합니다.
Sync할 Revision과 옵션을 확인합니다.
SYNCHRONIZE 버튼을 클릭합니다.

SYNCHRONIZE를 실행하면 Argo CD가 Application에 등록된 GitHub Repository의 파일을 기준으로 Kubernetes 클러스터에 리소스를 배포합니다.

즉, 앞에서 작성한 Application의 다음 설정을 기준으로 동작합니다.

source:
  repoURL: https://github.com/Hwara/micro-mart.git
  targetRevision: main
  path: k8s/services/overlays/local
destination:
  server: https://kubernetes.default.svc
  namespace: micro-mart-local

Argo CD는 repoURL의 targetRevision 브랜치에서 path에 있는 Kubernetes 매니페스트를 읽고, destination에 지정된 클러스터와 네임스페이스에 적용합니다.

Sync가 완료되면 Application의 상태가 변경됩니다.

정상적으로 반영되었다면 다음과 같은 상태를 기대할 수 있습니다.

APP HEALTH: Healthy
SYNC STATUS: Synced

Sync 상태 확인과 롤백

Application 상세 화면에서는 단순히 현재 상태만 확인하는 것이 아니라, Sync 이력과 롤백 기능도 확인할 수 있습니다.

Argo CD UI에서는 다음 메뉴를 통해 배포 상태를 확인할 수 있습니다.

SYNC STATUS
- Git Repository와 실제 클러스터 상태가 일치하는지 확인
HISTORY AND ROLLBACK
- 이전 Sync 이력 확인
- 특정 Revision으로 롤백 가능

특히 GitOps 방식에서는 Git의 변경 이력이 곧 배포 이력이 되기 때문에, 어떤 Commit 또는 Revision이 클러스터에 반영되었는지 확인하는 것이 중요합니다.

문제가 발생했을 때는 HISTORY AND ROLLBACK 메뉴에서 이전에 정상 동작하던 Revision을 확인하고, 필요하다면 해당 Revision으로 롤백할 수 있습니다.

명령어로 Application 상태 확인하기

UI뿐만 아니라 kubectl 명령어로도 Application 상태를 확인할 수 있습니다.

kubectl get application -n argocd

특정 Application의 상세 상태를 확인하려면 다음 명령어를 사용할 수 있습니다.

kubectl describe application micro-mart-local -n argocd

배포 대상 네임스페이스에 실제 리소스가 생성되었는지도 함께 확인합니다.

kubectl get all -n micro-mart-local

Pod 상태를 조금 더 자세히 확인하려면 다음 명령어를 사용할 수 있습니다.

kubectl get pods -n micro-mart-local

특정 Pod에 문제가 있다면 describe 또는 logs 명령어로 원인을 확인합니다.

kubectl describe pod <pod-name> -n micro-mart-local
kubectl logs <pod-name> -n micro-mart-local

이를 통해 Argo CD UI에서 보이는 상태와 실제 Kubernetes 리소스 상태를 함께 비교할 수 있습니다.

정리

이번 글에서는 Helm으로 Argo CD를 설치하고, Gateway API를 통해 외부에서 접근할 수 있도록 구성했습니다.

핵심은 Argo CD Server를 server.insecure: true로 설정하고, HTTPS 처리는 Gateway에서 담당하도록 역할을 나누는 것입니다.

또한 Gateway API의 certificateRefs는 kubernetes.io/tls 타입 Secret을 요구하므로, 로컬 테스트 환경에서는 Argo CD가 생성한 인증서 데이터를 별도의 TLS Secret으로 복사해 사용했습니다.

Argo CD Application 리소스를 생성해 Git Repository의 특정 경로를 Kubernetes 배포 대상으로 등록했습니다.

이 구성을 통해 Git에 정의된 Kubernetes 매니페스트를 기준으로 실제 클러스터 상태를 추적하고, 필요할 때 수동으로 Sync할 수 있는 GitOps 기반 배포 환경을 만들 수 있었습니다.

application을 생성한 뒤에는 Argo CD UI에서 APP HEALTH와 SYNC STATUS를 통해 배포 상태를 확인할 수 있습니다. 자동 동기화를 설정하지 않은 경우에는 SYNC 버튼을 눌러 수동으로 Git Repository의 매니페스트를 클러스터에 반영해야 합니다.

또한 HISTORY AND ROLLBACK 메뉴를 통해 이전 Sync 이력을 확인할 수 있으며, 문제가 발생했을 때 특정 Revision으로 롤백할 수도 있습니다. 이를 통해 Git Repository를 기준으로 Kubernetes 리소스의 배포 상태를 추적하고 관리할 수 있습니다.

References

https://argo-cd.readthedocs.io/en/stable/operator-manual/ingress/

GitHub Actions Self-hosted Runner를 WSL 환경에 설치하고 서비스로 실행하기

hwara_ — Mon, 25 May 2026 14:33:08 +0900

개요

GitHub Actions는 기본적으로 GitHub에서 제공하는 hosted runner를 사용할 수 있습니다. 하지만 로컬 환경에서만 접근 가능한 리소스를 사용해야 하거나, 사설 레지스트리·로컬 Kubernetes 클러스터·내부 네트워크 환경에서 빌드와 배포를 수행해야 하는 경우에는 self-hosted runner를 구성하는 것이 유용합니다.

이번 글에서는 Windows 사용자 기준으로, Ubuntu WSL 개발 환경에 GitHub Actions self-hosted runner를 설치하고 서비스로 실행하는 과정을 정리합니다.

현재 개발 환경은 다음과 같습니다.

Windows에서 개발 진행
Ubuntu WSL을 주 개발 환경으로 사용
Docker는 Windows에 설치된 Docker Desktop 사용
GitHub Actions job은 Ubuntu WSL에 설치한 self-hosted runner에서 실행

이 구조에서는 Docker가 Windows Docker Desktop에서 실행되지만, 실제 빌드 명령은 Ubuntu WSL 환경에서 실행됩니다. 따라서 WSL 내부에서 docker 명령어를 사용할 수 있도록 Docker Desktop과 Ubuntu WSL을 연결하는 과정이 필요합니다.

Self-hosted runner 비용 관련 주의사항

Self-hosted runner를 사용할 때는 비용 정책도 함께 확인해야 합니다.

GitHub 공식 문서 기준으로 현재 GitHub Actions의 self-hosted runner 사용은 무료로 안내되어 있습니다. 또한 public repository에서 standard GitHub-hosted runner를 사용하는 경우도 무료로 제공됩니다. (GitHub Docs)

다만 GitHub는 한때 2026년 3월 1일부터 self-hosted runner 사용에 대해 분당 $0.002의 GitHub Actions cloud platform charge를 부과하겠다고 발표한 적이 있습니다. 이 발표에 따르면 public repository의 runner 사용은 계속 무료로 유지되지만, private repository에서 self-hosted runner를 사용하는 경우 과금 대상이 될 수 있었습니다. (The GitHub Blog)

이후 GitHub는 커뮤니티 피드백을 반영해 self-hosted GitHub Actions에 대한 과금 변경을 보류하고, 접근 방식을 재검토하겠다고 공지했습니다. 따라서 글을 작성하는 시점에는 “self-hosted runner는 무료”로 이해할 수 있지만, GitHub Actions 요금 정책은 변경될 수 있으므로 실제 운영 환경에서 사용하기 전에는 공식 billing 문서를 다시 확인하는 것이 좋습니다. (GitHub)

혹시 변동사항이 생긴다면 댓글로 알려주시면 감사하겠습니다.

정리하면 다음과 같습니다.

현재 기준 self-hosted runner 사용은 무료로 안내되어 있음
2026년 3월 1일부터 분당 $0.002 과금을 적용하겠다는 발표가 있었음
이후 GitHub가 해당 변경을 보류하고 재검토하겠다고 공지함
public repository와 private repository의 과금 정책은 다를 수 있으므로 운영 전 공식 문서 확인 필요

WSL에서 Docker 사용할 수 있도록 설정

Windows에서 Docker Desktop을 사용하고 Ubuntu WSL에서 개발하는 경우, WSL 내부에서 Docker 명령어를 실행하려면 Docker Desktop의 WSL Integration을 활성화해야 합니다.

Docker Desktop에서 다음 경로로 이동합니다.

Settings -> Resources -> WSL Integration

기존에 설치해 둔 Ubuntu 배포판을 활성화한 뒤 Apply를 클릭합니다.

이 설정을 적용하면 Ubuntu WSL 터미널에서 Windows Docker Desktop의 Docker Engine을 사용할 수 있습니다. 즉, WSL 내부에서 다음과 같은 Docker 명령어를 실행할 수 있게 됩니다.

docker version

정상적으로 연결되었다면 WSL 터미널에서도 docker build, docker push 같은 명령어를 사용할 수 있습니다.

이 과정이 필요한 이유는 self-hosted runner가 Ubuntu WSL에서 실행되기 때문입니다. GitHub Actions workflow 안에서 Docker build를 수행하려면, runner가 실행되는 WSL 환경에서도 Docker CLI를 사용할 수 있어야 합니다.

Self-hosted runner 다운로드 및 설정

GitHub 저장소에서 self-hosted runner를 등록합니다.

GitHub 저장소의 다음 경로로 이동합니다.

Repository -> Settings -> Actions -> Runners -> New self-hosted runner

이후 화면에 표시되는 안내에 따라 runner를 다운로드하고 설정합니다.

일반적인 흐름은 다음과 같습니다.

Runner 패키지 다운로드
압축 해제
config.sh 실행
GitHub에서 제공하는 URL과 token을 사용해 runner 등록

예시는 다음과 같습니다.

mkdir actions-runner
cd actions-runner

# GitHub 안내에 표시되는 명령어를 사용해 runner 다운로드
# 예: curl -o actions-runner-linux-x64-...tar.gz -L ...

tar xzf ./actions-runner-linux-x64-*.tar.gz

# GitHub 안내에 표시되는 URL과 token을 사용해 설정
./config.sh --url <repository-url> --token <runner-token>

실제 다운로드 URL과 token은 GitHub에서 runner를 생성할 때마다 달라질 수 있으므로, GitHub 화면에 표시되는 명령어를 그대로 사용하는 것이 좋습니다.

Self-hosted runner를 서비스로 설정하기

Self-hosted runner는 기본적으로 다음 명령어로 실행할 수 있습니다.

./run.sh

하지만 이 방식은 터미널을 열어둔 상태에서 직접 실행해야 하므로 번거롭습니다. 따라서 runner를 서비스로 등록해두면 백그라운드에서 실행할 수 있습니다.

먼저 runner를 다운로드하고 설정한 디렉터리로 이동합니다.

cd actions-runner

서비스를 설치합니다.

sudo ./svc.sh install

서비스를 시작합니다.

sudo ./svc.sh start

서비스 상태를 확인합니다.

sudo ./svc.sh status

정상적으로 실행 중이라면 runner가 GitHub Actions 작업을 받을 준비가 된 상태입니다.

Self-hosted runner 서비스 중지 및 제거

더 이상 runner를 사용하지 않거나 설정을 다시 구성해야 한다면 서비스를 중지하고 제거할 수 있습니다.

서비스를 중지합니다.

sudo ./svc.sh stop

서비스를 제거합니다.

sudo ./svc.sh uninstall

필요하다면 GitHub 저장소의 runner 목록에서도 해당 runner를 제거할 수 있습니다.

Repository -> Settings -> Actions -> Runners

Runner 등록 상태 확인

GitHub 저장소의 다음 경로로 이동합니다.

Repository -> Settings -> Actions -> Runners

새로 등록한 runner가 목록에 표시되는지 확인합니다.

Runner의 상태가 Idle 또는 Active로 표시된다면 정상적으로 등록된 것입니다. 반대로 Offline 상태라면 runner 서비스가 실행 중인지 확인해야 합니다.

sudo ./svc.sh status

GitHub Actions workflow에서 사용하기

Self-hosted runner를 사용하려면 workflow의 job에서 runs-on 값을 self-hosted runner 라벨에 맞게 지정해야 합니다.

예를 들어 다음과 같이 작성할 수 있습니다.

runs-on: [self-hosted, Linux, X64]

이 설정은 다음 조건을 만족하는 runner에서 해당 job을 실행하겠다는 의미입니다.

self-hosted 라벨을 가진 runner
Linux 환경의 runner
X64 아키텍처의 runner

예시는 다음과 같습니다.

jobs:
  build-push-and-update-overlay:
    name: Build, push, and update local overlay
    permissions:
      contents: write
    runs-on: [self-hosted, Linux, X64]
    steps:
      - name: Check out repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
        with:
          ref: ${{ github.ref_name }}
          persist-credentials: true

이렇게 설정하면 GitHub Actions가 해당 job을 실행할 때 GitHub-hosted runner가 아니라, 직접 등록한 self-hosted runner를 사용합니다.

정리

이번 글에서는 Windows 사용자가 Ubuntu WSL 개발 환경에서 GitHub Actions self-hosted runner를 설치하고 서비스로 실행하는 과정을 정리했습니다.

전체 흐름은 다음과 같습니다.

Windows Docker Desktop에서 WSL Integration 활성화
Ubuntu WSL에서 Docker 명령어가 동작하는지 확인
GitHub 저장소에서 self-hosted runner 생성
Ubuntu WSL에 runner 다운로드 및 설정
svc.sh를 이용해 runner를 서비스로 등록
GitHub Actions workflow의 runs-on에 self-hosted runner 라벨 지정

Self-hosted runner를 사용하면 로컬 네트워크, 사설 Docker Registry, 로컬 Kubernetes 클러스터처럼 GitHub-hosted runner에서 접근하기 어려운 리소스를 활용할 수 있습니다.

다만 self-hosted runner는 사용자의 로컬 머신 또는 서버에서 직접 명령을 실행하므로 보안에 주의해야 합니다. 특히 public repository에서 외부 PR이 self-hosted runner에서 실행되지 않도록 workflow trigger와 권한 설정을 신중하게 관리하는 것이 좋습니다.

Reference

GitHub Docs - Adding self-hosted runners
GitHub Docs - Configuring the self-hosted runner application as a service
GitHub Docs - GitHub Actions billing
GitHub Blog - GitHub Actions pricing changes

Kubernetes kubelet의 컨테이너 로그 로테이션 설정 정리

hwara_ — Mon, 25 May 2026 13:52:06 +0900

Kubernetes에서 컨테이너 로그는 노드에 계속 쌓일 수 있기 때문에, 별도의 관리가 없다면 디스크 사용량 문제가 발생할 수 있습니다.

다행히 kubelet은 기본적으로 컨테이너 로그에 대해 로테이션을 수행합니다. 즉, 로그 파일이 일정 크기를 넘으면 새 파일로 교체하고, 오래된 로그 파일은 일정 개수까지만 유지합니다.

이번 글에서는 kubelet의 컨테이너 로그 로테이션 기본 설정과, 로그 보관 시 주의할 점을 정리합니다.

kubelet의 기본 컨테이너 로그 로테이션 설정

Kubernetes 공식 문서에 따르면 kubelet은 컨테이너 로그 로테이션을 위해 다음 설정을 제공합니다.

containerLogMaxSize: 10Mi
containerLogMaxFiles: 5

각 설정의 의미는 다음과 같습니다.

containerLogMaxSize: 컨테이너 로그 파일 하나의 최대 크기
containerLogMaxFiles: 컨테이너 하나당 유지할 로그 파일 개수

기본값 기준으로 보면, 컨테이너 로그 파일 하나가 10Mi를 넘으면 로그 로테이션이 발생합니다. 그리고 컨테이너 하나당 최대 5개의 로그 파일만 유지됩니다.

따라서 단순 계산으로는 컨테이너 하나당 최대 약 50Mi 정도의 로그 파일이 노드에 저장될 수 있습니다.

10Mi × 5 files = 50Mi

다만 이는 컨테이너 하나를 기준으로 한 값입니다. 실제 노드 전체 로그 사용량은 실행 중인 Pod 수, 컨테이너 수, 로그 발생량에 따라 훨씬 커질 수 있습니다.

kubelet 로그 로테이션의 목적

kubelet의 로그 로테이션은 일반적인 logrotate처럼 로그를 압축해서 장기 보관하기 위한 기능은 아닙니다.

목적은 다음에 더 가깝습니다.

컨테이너 로그가 노드에 무한히 쌓여 디스크를 계속 사용하는 상황을 방지하는 것

즉, kubelet의 로그 로테이션은 노드 디스크 보호를 위한 최소한의 안전장치입니다. 로그를 장기간 보관하고 검색해야 한다면, Loki, Fluentd 같은 중앙 로그 저장소를 별도로 구성하는 것이 일반적입니다.

Kubernetes 자체는 클러스터 수준의 로그 저장소를 기본 제공하지 않으며, 로그를 저장하고 분석하기 위한 별도의 백엔드가 필요합니다.

`kubectl logs` 조회 시 주의할 점

로그 용량을 줄이기 위해 containerLogMaxSize 값을 작게 설정할 수도 있습니다. 하지만 이 경우 주의해야 할 점이 있습니다.

공식 문서에 따르면 kubectl logs는 최신 로그 파일의 내용만 제공합니다. 즉, 로그 로테이션으로 이전 파일로 넘어간 로그는 kubectl logs에서 직접 확인할 수 없습니다.

예를 들어 기본 설정인 10Mi를 사용 중이라면, 특정 컨테이너가 많은 로그를 출력해 로테이션이 발생했을 때 kubectl logs로 확인할 수 있는 범위는 최신 로그 파일에 남아 있는 내용으로 제한됩니다.

containerLogMaxSize: 10Mi

이 경우 kubectl logs로 볼 수 있는 로그는 최대 최신 10Mi 파일의 내용입니다.

따라서 containerLogMaxSize를 너무 작게 설정하면 문제가 발생했을 때 필요한 로그가 이미 로테이션되어 사라졌을 수 있습니다.

로그 용량을 줄이고 싶을 때 고려할 점

컨테이너 로그 용량을 줄이고 싶다면 kubelet 설정을 조정할 수 있습니다.

예를 들어 다음 값을 줄이면 컨테이너별 로그 저장량을 줄일 수 있습니다.

containerLogMaxSize: 5Mi
containerLogMaxFiles: 3

이 경우 컨테이너 하나당 대략 다음 정도의 로그만 유지됩니다.

5Mi × 3 files = 15Mi

하지만 단순히 값을 줄이기보다는 다음을 함께 고려하는 것이 좋습니다.

장애 분석에 필요한 최소 로그량은 어느 정도인지
애플리케이션이 과도하게 로그를 출력하고 있지는 않은지
로그 레벨이 운영 환경에 적절하게 설정되어 있는지
Loki 같은 중앙 로그 저장소에서 정상적으로 로그를 수집하고 있는지
노드 디스크 용량과 Pod 수를 고려했을 때 적절한 보관량인지

특히 중앙 로그 저장소를 사용하고 있다면, 노드에는 짧은 기간의 로그만 남기고 장기 보관과 검색은 중앙 로그 시스템에 맡기는 구조가 더 적절할 수 있습니다.

정리

kubelet은 기본적으로 컨테이너 로그 로테이션을 수행합니다.

기본 설정은 다음과 같습니다.

containerLogMaxSize: 10Mi
containerLogMaxFiles: 5

이 설정은 컨테이너 로그가 노드에 무한히 쌓이는 것을 방지하기 위한 장치입니다. 다만 장기 보관이나 검색 목적의 기능은 아니므로, 운영 환경에서 로그를 지속적으로 보관해야 한다면 Loki 같은 중앙 로그 저장소를 함께 구성해야 합니다.

또한 containerLogMaxSize를 너무 작게 설정하면 kubectl logs로 확인할 수 있는 최신 로그 범위가 줄어들 수 있습니다. 따라서 로그 용량 절감과 장애 분석 가능성 사이에서 적절한 균형을 잡는 것이 중요합니다.

Kubernetes 노드와 Docker 환경에서 디스크 용량 확인 및 정리하기

hwara_ — Mon, 25 May 2026 13:42:30 +0900

개발 환경이나 로컬 Kubernetes 클러스터를 오래 사용하다 보면 어느 순간 디스크 용량이 부족해지는 경우가 있습니다. 특히 컨테이너 이미지, 빌드 캐시, Pod 로그, 컨테이너 writable layer 등이 계속 쌓이면서 /var 디렉터리의 용량이 커질 수 있습니다.

이번 글에서는 Linux 환경에서 디스크 용량을 확인하는 방법과, Kubernetes에서 사용하는 containerd 및 Docker의 용량을 정리하는 방법을 정리합니다.

전체 디스크 용량 확인

먼저 루트 디렉터리 기준으로 어떤 디렉터리가 용량을 많이 사용하는지 확인합니다.

sudo du -xh / --max-depth=1 | sort -h

옵션의 의미는 다음과 같습니다.

du: 디렉터리별 디스크 사용량 확인
-x: 다른 파일 시스템은 제외
-h: 사람이 읽기 쉬운 단위로 출력
--max-depth=1: 바로 아래 단계의 디렉터리까지만 확인
sort -h: 용량 기준으로 정렬

일반적으로 서버나 Kubernetes 노드에서는 /var 디렉터리의 용량이 커지는 경우가 많습니다. /var이 크다면 다음과 같이 한 단계 더 좁혀서 확인합니다.

sudo du -xh /var --max-depth=1 | sort -h

이런 방식으로 /var/log, /var/lib, /var/lib/containerd처럼 용량이 큰 경로를 단계적으로 추적할 수 있습니다.

Pod 및 컨테이너 로그 용량 확인

Kubernetes 환경에서는 Pod 로그와 컨테이너 로그가 디스크를 많이 사용할 수 있습니다.

다음 명령어로 로그 디렉터리의 용량을 확인합니다.

sudo du -sh /var/log/pods
sudo du -sh /var/log/containers

/var/log/pods에는 Pod 단위의 로그가 저장되고, /var/log/containers에는 컨테이너 로그에 접근하기 위한 링크 형태의 파일들이 위치합니다.

로그 수집 도구로 Loki, Fluent Bit, Promtail 등을 사용하더라도 노드에 기록되는 컨테이너 로그 자체가 바로 사라지는 것은 아닙니다. 기본적으로 컨테이너 런타임과 kubelet은 로그 파일을 로컬 노드에 기록하고, 수집기는 해당 로그를 읽어서 외부 저장소로 전달하는 방식으로 동작합니다.

따라서 로그 수집 시스템을 사용하더라도 노드의 로그 로테이션 설정은 별도로 확인하는 것이 좋습니다.

containerd 용량 확인

Kubernetes 클러스터에서 containerd를 컨테이너 런타임으로 사용한다면, 이미지와 컨테이너 관련 데이터는 보통 다음 경로에 저장됩니다.

sudo du -sh /var/lib/containerd

이 경로에는 컨테이너 이미지 레이어, 스냅샷, 컨테이너 writable layer 등이 포함될 수 있습니다.

containerd에서 현재 저장된 이미지 목록은 crictl로 확인할 수 있습니다.

sudo crictl images

사용하지 않는 이미지를 정리하려면 다음 명령어를 사용할 수 있습니다.

sudo crictl rmi --prune

이 명령어는 현재 사용 중이지 않은 이미지를 정리합니다.

Kubernetes의 이미지 GC

Kubernetes 노드에서는 kubelet이 이미지 가비지 컬렉션을 자동으로 수행합니다.

기본적으로 kubelet에는 다음과 같은 이미지 GC 기준이 설정되어 있습니다.

imageGCHighThresholdPercent: 85
imageGCLowThresholdPercent: 80

의미는 다음과 같습니다.

파일 시스템 사용량이 85%를 넘으면 이미지 GC 시작
사용하지 않는 이미지를 정리
사용량이 80% 아래로 내려갈 때까지 정리

즉, Kubernetes 노드에서는 사용하지 않는 이미지가 무한히 쌓이지 않도록 kubelet이 일정 기준에 따라 정리합니다.

다만 이 설정은 kubelet 설정에 따라 달라질 수 있으므로, 실제 운영 환경에서는 노드의 kubelet 설정을 직접 확인하는 것이 좋습니다.

Docker 용량 확인

Docker를 사용하는 환경에서는 다음 명령어로 전체 디스크 사용량을 확인할 수 있습니다.

docker system df

예시는 다음과 같습니다.

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          6         0         5.308GB   2.472GB (46%)
Containers      0         0         0B        0B
Local Volumes   6         0         143.6MB   143.6MB (100%)
Build Cache     72        0         3.585GB   2.679GB

여기서 주요 항목은 다음과 같습니다.

Images: Docker 이미지가 사용하는 용량
Containers: 컨테이너 writable layer가 사용하는 용량
Local Volumes: Docker volume이 사용하는 용량
Build Cache: Docker 빌드 과정에서 생성된 캐시 용량
RECLAIMABLE: 정리 가능한 용량

Docker 이미지를 자주 빌드하는 개발 환경에서는 Build Cache가 생각보다 큰 용량을 차지할 수 있습니다.

사용하지 않는 Docker 이미지 정리

사용하지 않는 이미지를 정리하려면 다음 명령어를 사용합니다.

docker image prune -a

-a 옵션을 사용하면 사용 중이지 않은 모든 이미지를 정리합니다.

주의할 점은, 같은 이미지 ID를 가진 이미지가 여러 태그를 가지고 있더라도 실제 레이어는 중복 저장되지 않는다는 것입니다. 즉, 태그가 여러 개라고 해서 이미지 용량이 태그 개수만큼 늘어나는 것은 아닙니다.

이미지를 삭제해도 용량이 줄지 않는 경우

Docker 이미지를 모두 삭제했는데도 docker system df에서 Images의 SIZE가 크게 보이는 경우가 있습니다.

예를 들어 다음과 같은 상황입니다.

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          0         0         9.033GB   0B (0%)
Containers      0         0         0B        0B
Local Volumes   6         0         143.6MB   143.6MB (100%)
Build Cache     189       0         10.94GB   10.94GB

이 경우에는 이미지 자체는 삭제되었지만, 빌드 캐시에 이미지 레이어가 남아 있을 수 있습니다.

Docker는 빌드 속도를 높이기 위해 이전 빌드에서 사용한 레이어를 캐시로 보관합니다. 그래서 이미지를 삭제하더라도 빌드 캐시가 남아 있으면 실제 디스크 사용량이 크게 줄지 않을 수 있습니다.

Docker Build Cache 정리

빌드 캐시를 정리하려면 다음 명령어를 사용합니다.

docker builder prune

오래된 캐시만 삭제하고 싶다면 until 필터를 사용할 수 있습니다.

docker builder prune --filter until=24h

일정 용량만 남기고 정리하고 싶다면 --keep-storage 옵션을 사용할 수 있습니다.

docker builder prune --keep-storage 10GB

단, 빌드 캐시를 삭제하면 다음 빌드 시 기존 캐시를 사용할 수 없습니다. 따라서 다음 빌드 시간이 길어질 수 있습니다.

개발 환경에서 디스크 용량이 부족할 때는 유용하지만, 자주 빌드하는 프로젝트라면 필요한 캐시까지 모두 삭제하지 않도록 주의하는 것이 좋습니다.

Docker Desktop의 Build Cache GC

Docker Desktop에서 확인해보면 기본적으로 일정 용량 이상이 되었을 때 Build Cache를 정리하는 GC 설정이 존재하는 것으로 보입니다.

예를 들어 환경에 따라 20GB를 기준으로 빌더 캐시를 정리하도록 설정되어 있을 수 있습니다.

다만 이 값은 Docker Desktop 버전이나 설정에 따라 달라질 수 있으므로, 실제 값은 Docker Desktop 설정 또는 현재 사용 중인 Builder 설정을 확인하는 것이 좋습니다.

정리

디스크 용량이 부족할 때는 무작정 파일을 삭제하기보다, 먼저 어떤 경로가 용량을 많이 사용하는지 확인하는 것이 중요합니다.

Kubernetes 노드에서는 주로 다음 경로를 확인합니다.

sudo du -xh / --max-depth=1 | sort -h
sudo du -xh /var --max-depth=1 | sort -h
sudo du -sh /var/log/pods
sudo du -sh /var/log/containers
sudo du -sh /var/lib/containerd

containerd 환경에서는 다음 명령어로 이미지를 확인하고 정리할 수 있습니다.

sudo crictl images
sudo crictl rmi --prune

Docker 환경에서는 다음 명령어를 사용합니다.

docker system df
docker image prune -a
docker builder prune

정리하면, Kubernetes 노드에서는 kubelet이 기본적으로 이미지 GC를 수행하지만, 로그나 빌드 캐시, Docker Desktop의 가상 디스크 사용량 등은 별도로 확인이 필요합니다.

특히 Docker 이미지를 삭제했는데도 용량이 줄지 않는다면, 이미지가 아니라 Build Cache가 남아 있는 상황일 수 있으므로 docker builder prune을 함께 확인하는 것이 좋습니다.

Reference

https://kubernetes.io/ko/docs/concepts/architecture/garbage-collection/

머지된 Git 브랜치를 안전하게 정리하는 방법

hwara_ — Sun, 24 May 2026 10:39:16 +0900

Git 브랜치 삭제 명령어 정리

Git을 사용하다 보면 기능 개발이나 버그 수정을 위해 여러 브랜치를 만들게 됩니다.
작업이 끝난 브랜치를 계속 남겨두면 로컬과 원격 저장소의 브랜치 목록이 복잡해질 수 있으므로, 필요 없는 브랜치는 주기적으로 정리하는 것이 좋습니다.

이번 글에서는 로컬 브랜치, 원격 브랜치, 로컬에 남아 있는 원격 브랜치 정보를 삭제하는 방법을 정리합니다.

로컬 브랜치 삭제

로컬에 있는 브랜치는 다음 명령어로 삭제할 수 있습니다.

git branch -D <branch_name>

예를 들어 feature/login 브랜치를 삭제하려면 다음과 같이 실행합니다.

git branch -D feature/login

-D 옵션은 강제 삭제 옵션입니다.
해당 브랜치가 아직 merge되지 않았더라도 삭제할 수 있으므로, 정말 삭제해도 되는 브랜치인지 확인한 뒤 사용하는 것이 좋습니다.

보다 안전하게 삭제하려면 -d 옵션을 사용할 수 있습니다.

git branch -d <branch_name>

-d 옵션은 merge되지 않은 브랜치를 삭제하려고 할 때 경고를 표시합니다.

원격 브랜치 삭제

원격 저장소에 올라가 있는 브랜치는 다음 명령어로 삭제할 수 있습니다.

git push origin --delete <branch_name>

예를 들어 원격 저장소의 feature/login 브랜치를 삭제하려면 다음과 같이 실행합니다.

git push origin --delete feature/login

이 명령어는 origin 원격 저장소에 있는 브랜치를 삭제합니다.
협업 중인 브랜치라면 다른 사람이 사용하고 있지 않은지 확인한 뒤 삭제하는 것이 좋습니다.

로컬에 남아 있는 원격 브랜치 정보 정리

원격 브랜치를 삭제해도 로컬에는 origin/브랜치명 형태의 원격 추적 브랜치 정보가 남아 있을 수 있습니다.

이때는 다음 명령어로 정리할 수 있습니다.

git fetch --prune

이 명령어는 원격 저장소에서 이미 삭제된 브랜치 정보를 로컬에서도 정리합니다.

예를 들어 원격에서 feature/login 브랜치가 삭제되었는데 로컬에서 여전히 origin/feature/login이 보인다면, git fetch --prune을 실행해 정리할 수 있습니다.

머지된 로컬 브랜치 삭제

Git은 브랜치가 merge되었다고 해서 로컬 브랜치를 자동으로 삭제하지 않습니다.
따라서 작업이 끝난 브랜치는 직접 정리해야 합니다.

현재 main 브랜치에 merge된 로컬 브랜치는 다음 명령어로 확인할 수 있습니다.

git branch --merged main | grep -v main

이 명령어는 main 브랜치에 이미 merge된 브랜치 목록을 출력합니다.
삭제하기 전에 먼저 이 명령어로 어떤 브랜치가 대상인지 확인하는 것이 안전합니다.

확인 후 실제로 삭제하려면 다음 명령어를 실행합니다.

git branch --merged main | grep -v main | xargs -n 1 git branch -d

이 명령어는 main에 merge된 브랜치 중 main 브랜치를 제외한 나머지 브랜치를 하나씩 삭제합니다.

명령어별 정리

목적 명령어

로컬 브랜치 강제 삭제	git branch -D <branch_name>
로컬 브랜치 안전 삭제	git branch -d <branch_name>
원격 브랜치 삭제	git push origin --delete <branch_name>
삭제된 원격 브랜치 정보 정리	git fetch --prune
merge된 브랜치 확인	git branch --merged main \\| grep -v main
merge된 로컬 브랜치 삭제	git branch --merged main \\| grep -v main \\| xargs -n 1 git branch -d

정리

Git 브랜치는 작업 단위를 나누는 데 유용하지만, 사용하지 않는 브랜치를 계속 남겨두면 관리가 어려워질 수 있습니다.

브랜치를 정리할 때는 다음 순서로 진행하는 것이 좋습니다.

삭제할 브랜치가 merge되었는지 확인한다.
로컬 브랜치를 삭제한다.
필요하다면 원격 브랜치도 삭제한다.
git fetch --prune으로 로컬에 남은 원격 브랜치 정보를 정리한다.

특히 여러 사람이 함께 사용하는 저장소에서는 원격 브랜치를 삭제하기 전에 해당 브랜치를 다른 사람이 사용하고 있지 않은지 확인하는 것이 좋습니다.

Reference

https://dev-sihyun.tistory.com/2

Slack Incoming Webhook으로 채널에 메시지 보내기

hwara_ — Fri, 22 May 2026 11:15:01 +0900

Slack Incoming Webhook으로 채널에 메시지 보내기

이번 글에서는 Slack의 Incoming Webhook을 사용해 특정 채널로 메시지를 보내는 방법을 정리합니다.

Incoming Webhook은 외부 애플리케이션이나 스크립트에서 Slack 채널로 메시지를 전송할 수 있게 해주는 기능입니다. Slack 공식 문서에서도 Webhook URL에 JSON payload를 POST 요청으로 보내면 앱이 Slack에 메시지를 게시할 수 있다고 설명합니다.

예를 들어 배포 완료 알림, 에러 알림, 모니터링 알림 등을 Slack 채널로 보내고 싶을 때 사용할 수 있습니다.

1. Slack 채널 생성

먼저 Webhook 메시지를 받을 Slack 채널을 생성합니다.

Slack에서 다음 순서로 진행합니다.

Slack → 채널 → 채널 생성

테스트용 Webhook이라면 운영 채널보다는 별도의 테스트 채널을 만들어두는 것이 좋습니다.

예를 들어 다음과 같은 채널을 만들 수 있습니다.

#webhook-test

2. Slack 앱 생성

Slack Incoming Webhook은 Slack App을 통해 생성합니다.

먼저 Slack API 페이지로 이동합니다.

https://api.slack.com/apps

이후 다음 순서로 앱을 생성합니다.

Create New App → From scratch

앱 생성 화면에서 다음 정보를 입력합니다.

App Name: 사용할 Slack 앱 이름
Pick a workspace: 앱을 설치할 Slack 워크스페이스

입력 후 앱을 생성하면 Slack 앱 설정 화면으로 이동합니다.

3. Incoming Webhooks 활성화

Slack 앱 설정 화면의 좌측 메뉴에서 다음 항목으로 이동합니다.

Features → Incoming Webhooks

해당 페이지에서 Activate Incoming Webhooks 옵션을 활성화합니다.

Slack 공식 문서에서도 Incoming Webhooks 메뉴에서 기능을 활성화한 뒤, Workspace에 Webhook을 추가하는 흐름으로 안내하고 있습니다.

4. Webhook URL 생성

Incoming Webhooks를 활성화하면 아래쪽에 Webhook을 추가할 수 있는 버튼이 표시됩니다.

Add New Webhook to Workspace

버튼을 클릭하면 Webhook 메시지를 보낼 채널을 선택하는 화면이 나타납니다.

앞에서 만든 Slack 채널을 선택한 뒤 권한을 허용합니다.

채널 선택 → 허용

정상적으로 완료되면 Slack 앱 설정 화면에 새로운 Webhook URL이 생성됩니다.

이 URL을 복사해두면 외부에서 Slack 채널로 메시지를 보낼 때 사용할 수 있습니다.

Webhook URL은 외부에서 Slack 채널로 메시지를 보낼 수 있는 주소이므로, 코드에 직접 하드코딩하기보다는 환경 변수나 Secret으로 관리하는 것이 좋습니다.

5. curl로 Webhook 테스트

Webhook URL이 정상적으로 동작하는지 curl 명령어로 테스트할 수 있습니다.

curl -X POST \
  -H 'Content-type: application/json' \
  --data '{"text":"Hello, World!"}' \
  <Webhook URL>

각 옵션의 의미는 다음과 같습니다.

-X POST

Slack Webhook URL로 POST 요청을 보낸다는 의미입니다.

-H 'Content-type: application/json'

요청 본문이 JSON 형식임을 알립니다.

--data '{"text":"Hello, World!"}'

Slack 채널에 보낼 메시지 내용을 JSON 형식으로 전달합니다.

<Webhook URL>

Slack 앱 설정에서 복사한 Webhook URL을 넣습니다.

정상적으로 요청이 처리되면 선택한 Slack 채널에 다음 메시지가 표시됩니다.

Hello, World!

정리

Slack Incoming Webhook을 사용하면 외부 시스템에서 Slack 채널로 간단하게 메시지를 보낼 수 있습니다.

전체 흐름은 다음과 같습니다.

Slack 채널 생성
→ Slack App 생성
→ Incoming Webhooks 활성화
→ Webhook URL 생성
→ curl로 메시지 전송 테스트

이후 실제 프로젝트에서는 배포 스크립트, GitHub Actions, 모니터링 시스템, 백엔드 서버 등에서 이 Webhook URL을 호출해 Slack 알림을 보낼 수 있습니다.

Reference

https://blog.naver.com/segasas/223311008126
Slack 공식 문서: Incoming Webhooks - https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/?utm_source=chatgpt.com

Python 개발 환경 세팅하기: venv, Ruff, Black, Mypy, pre-commit 설정 정리

hwara_ — Wed, 20 May 2026 12:08:24 +0900

개요

Python 프로젝트를 시작할 때는 기능 구현에 바로 들어가기 전에 기본 개발 환경을 먼저 정리해두는 것이 좋습니다.

특히 여러 명이 함께 개발하거나, 여러 서비스로 나뉜 프로젝트를 관리하는 경우에는 코드 스타일과 검사 기준이 제각각이면 유지보수가 어려워집니다.

이번 글에서는 Python 프로젝트를 시작할 때 설정하면 좋은 기본 개발 환경을 정리합니다.

다루는 내용은 다음과 같습니다.

Python 가상환경 생성
공통 개발 도구 설치
pyproject.toml을 이용한 lint, formatter, type checker 설정
pre-commit을 이용한 커밋 전 자동 검사 설정

이 글은 Python 프로젝트에서 가상환경을 어떻게 구성해야 하는지, 그리고 ruff, black, mypy, pre-commit이 각각 어떤 역할을 하는지 궁금한 독자를 대상으로 합니다.

전체 구성

이번에 구성할 개발 도구는 다음과 같습니다.

도구 역할

venv	프로젝트별 Python 가상환경 생성
ruff	코드 품질 검사 및 import 정리
black	코드 포맷팅
mypy	타입 검사
pre-commit	커밋 전에 자동으로 검사 실행
pyproject.toml	Python 개발 도구 설정을 모아두는 설정 파일
.pre-commit-config.yaml	pre-commit 훅 설정 파일

Python 가상환경이 필요한 이유

Python 프로젝트에서는 보통 프로젝트마다 필요한 패키지 버전이 다릅니다.

예를 들어 A 프로젝트에서는 FastAPI 0.110 버전을 사용하고, B 프로젝트에서는 다른 버전의 FastAPI를 사용할 수 있습니다. 이때 전역 Python 환경에 모든 패키지를 설치하면 프로젝트 간 의존성이 섞이면서 문제가 발생할 수 있습니다.

이를 방지하기 위해 Python에서는 프로젝트별로 독립된 실행 환경을 만드는 가상환경을 사용합니다.

가상환경을 사용하면 다음과 같은 장점이 있습니다.

프로젝트별 패키지 버전을 분리할 수 있습니다.
전역 Python 환경이 지저분해지는 것을 막을 수 있습니다.
다른 개발자와 동일한 개발 환경을 맞추기 쉬워집니다.
프로젝트를 삭제할 때 가상환경도 함께 제거할 수 있습니다.

Python 가상환경 생성

프로젝트 루트에서 다음 명령어로 가상환경을 생성합니다.

python3.12 -m venv .venv

여기서 .venv는 가상환경 디렉터리 이름입니다. 꼭 .venv라는 이름을 써야 하는 것은 아니지만, Python 프로젝트에서는 관례적으로 많이 사용됩니다.

생성한 가상환경을 활성화합니다.

source .venv/bin/activate

Windows 환경에서는 다음 명령어를 사용합니다.

.venv\Scripts\activate

가상환경이 활성화되면 터미널 앞쪽에 (.venv)와 같은 표시가 붙습니다.

(.venv) $

이 상태에서 설치하는 Python 패키지는 전역 환경이 아니라 현재 프로젝트의 .venv 안에 설치됩니다.

공통 개발 도구 설치

가상환경을 활성화한 뒤, 개발 도구를 설치합니다.

pip install pre-commit ruff black mypy

이번 글에서 설치하는 도구들의 역할은 다음과 같습니다.

Ruff

ruff는 Python 코드의 문제를 빠르게 검사해주는 lint 도구입니다.

예를 들어 다음과 같은 문제를 찾아줍니다.

사용하지 않는 import
사용하지 않는 변수
잠재적인 버그 패턴
import 순서 문제
오래된 Python 문법 사용

또한 일부 문제는 --fix 옵션을 통해 자동으로 수정할 수 있습니다.

Black

black은 Python 코드 formatter입니다.

formatter는 코드의 의미를 바꾸지 않고, 들여쓰기나 줄바꿈 같은 스타일을 자동으로 통일해주는 도구입니다.

예를 들어 팀원마다 코드 스타일이 달라도 black을 적용하면 일정한 형식으로 정리됩니다.

Mypy

mypy는 Python 타입 힌트를 기반으로 타입 오류를 검사하는 도구입니다.

Python은 동적 타입 언어이기 때문에 실행 전에는 타입 오류를 발견하기 어려운 경우가 있습니다. mypy를 사용하면 타입 힌트를 기준으로 일부 오류를 미리 확인할 수 있습니다.

pre-commit

pre-commit은 Git 커밋 전에 특정 검사를 자동으로 실행해주는 도구입니다.

예를 들어 커밋하기 전에 ruff, black, mypy를 자동으로 실행하도록 설정할 수 있습니다.

이를 통해 문제가 있는 코드가 저장소에 들어가기 전에 한 번 더 검사할 수 있습니다.

pyproject.toml이란?

pyproject.toml은 Python 프로젝트의 설정을 한곳에서 관리하기 위한 설정 파일입니다.

과거에는 도구마다 설정 파일을 따로 두는 경우가 많았습니다.

예를 들어 다음과 같은 파일들이 각각 존재할 수 있었습니다.

.flake8
mypy.ini
setup.cfg
black 설정 파일
isort 설정 파일

하지만 최근 Python 프로젝트에서는 여러 개발 도구의 설정을 pyproject.toml에 모아서 관리하는 경우가 많습니다.

이 프로젝트에서는 pyproject.toml이 다음 도구들의 설정 파일 역할을 합니다.

ruff
black
mypy

즉, 개발자가 직접 ruff, black, mypy를 실행하거나, pre-commit이 커밋 전에 이 도구들을 실행할 때 모두 pyproject.toml에 작성된 설정을 기준으로 동작합니다.

기본 pyproject.toml 작성

프로젝트 루트에 pyproject.toml 파일을 생성합니다.

처음에는 아래와 같이 설정할 수 있습니다.

[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors
    "W",   # pycodestyle warnings
    "F",   # pyflakes (미사용 import 등)
    "I",   # isort (import 순서 정렬)
    "B",   # flake8-bugbear (잠재적 버그 패턴)
    "UP",  # pyupgrade (Python 최신 문법 권장)
]

[tool.black]
line-length = 100
target-version = ["py312"]

[tool.mypy]
python_version = "3.12"
strict = false
ignore_missing_imports = true

각 설정의 의미를 간단히 정리하면 다음과 같습니다.

Ruff 설정

[tool.ruff]
target-version = "py312"
line-length = 100

target-version은 프로젝트에서 사용하는 Python 버전을 의미합니다.

여기서는 Python 3.12를 기준으로 검사하도록 설정했습니다.

line-length는 한 줄의 최대 길이입니다. 이 값은 뒤에서 설정할 black과 동일하게 맞추는 것이 좋습니다.

[tool.ruff.lint]
select = [
    "E",
    "W",
    "F",
    "I",
    "B",
    "UP",
]

select는 어떤 종류의 규칙을 검사할지 지정합니다.

E, W: Python 스타일 관련 오류 및 경고
F: 미사용 import, 정의되지 않은 변수 등
I: import 순서 정리
B: 버그 가능성이 있는 코드 패턴
UP: 최신 Python 문법 사용 권장

Black 설정

[tool.black]
line-length = 100
target-version = ["py312"]

black은 코드 포맷팅을 담당합니다.

line-length를 ruff와 동일하게 100으로 맞춰두면 두 도구가 서로 다른 기준으로 동작하는 것을 줄일 수 있습니다.

Mypy 설정

[tool.mypy]
python_version = "3.12"
strict = false
ignore_missing_imports = true

mypy는 타입 검사를 담당합니다.

strict = false는 처음부터 너무 엄격한 타입 검사를 적용하지 않겠다는 의미입니다. 기존 코드가 많거나 타입 힌트가 아직 충분하지 않은 프로젝트라면, 처음에는 느슨하게 시작하고 점진적으로 강화하는 편이 좋습니다.

ignore_missing_imports = true는 타입 정보를 제공하지 않는 외부 라이브러리로 인해 발생하는 오류를 무시하도록 설정합니다.

프로젝트를 진행하며 설정 변경하기

개발 도구 설정은 처음부터 완벽하게 고정하기 어렵습니다.

프로젝트를 진행하다 보면 프레임워크 특성상 예외가 필요한 경우도 있고, 팀 규칙에 따라 특정 lint 규칙을 끄거나 추가해야 할 수도 있습니다.

예를 들어 제가 진행한 프로젝트에서는 다음과 같이 설정이 변경되었습니다.

[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors
    "W",   # pycodestyle warnings
    "F",   # pyflakes (미사용 import 등)
    "I",   # isort (import 순서 정렬)
    "B",   # flake8-bugbear (잠재적 버그 패턴)
    "UP",  # pyupgrade (Python 최신 문법 권장)
]
ignore = [
    "UP042",  # dev_convention.md 기준: 상태값 Enum은 str + enum.Enum 유지
]

[tool.ruff.lint.per-file-ignores]
# sys.path 조작 후 지연 임포트가 필요한 파일들 (E402)
"**/main.py" = ["E402"]           # 각 서비스 main.py
"**/tests/**/*.py" = ["E402"]     # 모든 서비스의 tests 디렉터리
"shared/**/*.py" = ["E402"]       # shared/telemetry 포함 shared 전체

[tool.ruff.lint.flake8-bugbear]
# B008 예외: FastAPI Depends, Query, Body 등은 기본 인자로 사용하는 것이 공식 패턴
extend-immutable-calls = [
    "fastapi.Depends",
    "fastapi.Query",
    "fastapi.Body",
    "fastapi.Header",
    "fastapi.Path",
    "fastapi.Cookie",
    "fastapi.File",
    "fastapi.Form",
    "fastapi.Security",
]

[tool.black]
line-length = 100
target-version = ["py312"]

[tool.mypy]
python_version = "3.12"
strict = false
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "redis.*"
ignore_missing_imports = true

여기서 중요한 점은 lint 도구의 경고를 무조건 코드 수정으로만 해결하지 않는다는 것입니다.

예를 들어 FastAPI에서는 Depends, Query, Body 등을 함수 기본 인자로 사용하는 패턴이 일반적입니다.

from fastapi import Depends

def get_user(user=Depends(get_current_user)):
    ...

일반 Python 코드에서는 함수 기본 인자에서 함수를 호출하는 패턴이 문제가 될 수 있습니다. 하지만 FastAPI에서는 의도된 사용 방식입니다.

따라서 이런 경우에는 코드를 억지로 바꾸기보다, 프로젝트에서 사용하는 프레임워크의 특성을 반영해 lint 예외를 설정하는 것이 더 적절합니다.

pre-commit이란?

pre-commit은 Git 커밋 전에 자동으로 검사를 실행해주는 도구입니다.

보통 개발자는 코드를 수정한 뒤 다음과 같은 흐름으로 커밋합니다.

git add .
git commit -m "add user api"

이때 pre-commit을 설정해두면 실제 커밋이 생성되기 전에 자동으로 여러 검사가 실행됩니다.

예를 들어 다음과 같은 작업을 커밋 전에 자동으로 실행할 수 있습니다.

ruff로 코드 검사
black으로 코드 포맷팅
mypy로 타입 검사
줄 끝 공백 제거
파일 끝 개행 확인
YAML 문법 검사
대용량 파일 커밋 방지
개인키 커밋 방지

즉, pre-commit은 문제가 있는 코드가 Git 저장소에 들어가기 전에 막아주는 안전장치입니다.

.pre-commit-config.yaml이란?

.pre-commit-config.yaml은 pre-commit이 어떤 검사를 실행할지 정의하는 설정 파일입니다.

이 파일도 보통 프로젝트 루트에 위치합니다.

pyproject.toml이 ruff, black, mypy의 세부 규칙을 정의한다면, .pre-commit-config.yaml은 커밋 전에 어떤 도구를 실행할지를 정의합니다.

두 파일의 역할을 비교하면 다음과 같습니다.

파일 역할

pyproject.toml	각 개발 도구의 세부 설정
.pre-commit-config.yaml	커밋 전에 실행할 훅 목록 설정

예를 들어 pyproject.toml에는 ruff가 어떤 규칙을 검사할지 작성합니다.

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "UP"]

반면 .pre-commit-config.yaml에는 커밋 전에 ruff를 실행하겠다고 작성합니다.

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.4
    hooks:
      - id: ruff
        args: [--fix]

즉, 관계를 정리하면 다음과 같습니다.

.pre-commit-config.yaml
  └─ 커밋 전에 ruff 실행

pyproject.toml
  └─ ruff가 실행될 때 어떤 규칙으로 검사할지 정의

.pre-commit-config.yaml 작성

프로젝트 루트에 .pre-commit-config.yaml 파일을 생성합니다.

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.4
    hooks:
      - id: ruff
        args: [--fix]   # 자동 수정 가능한 것은 자동으로 수정

  - repo: https://github.com/psf/black
    rev: 24.4.2
    hooks:
      - id: black

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy
        additional_dependencies: [pydantic, fastapi]

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace        # 줄 끝 공백 제거
      - id: end-of-file-fixer          # 파일 끝 개행 확인
      - id: check-yaml                 # YAML 문법 검사
      - id: check-added-large-files    # 대용량 파일 실수 커밋 방지
      - id: detect-private-key         # 개인키 커밋 방지

각 항목의 의미는 다음과 같습니다.

repo: 훅을 제공하는 Git 저장소 주소
rev: 사용할 훅의 버전
hooks: 실행할 훅 목록
id: 실행할 훅의 이름
args: 훅 실행 시 전달할 옵션

예를 들어 아래 설정은 ruff 훅을 사용하겠다는 의미입니다.

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.4.4
  hooks:
    - id: ruff
      args: [--fix]

args: [--fix]는 ruff가 자동 수정 가능한 문제를 발견하면 가능한 범위에서 자동으로 수정하라는 의미입니다.

pre-commit 훅 설치

설정 파일을 작성했다고 해서 바로 커밋 시점에 실행되는 것은 아닙니다.

처음 한 번은 다음 명령어로 Git 훅을 설치해야 합니다.

pre-commit install

이 명령을 실행하면 현재 Git 저장소의 .git/hooks/pre-commit 위치에 pre-commit 실행 스크립트가 설치됩니다.

이후부터는 git commit을 실행할 때마다 .pre-commit-config.yaml에 정의된 훅들이 자동으로 실행됩니다.

개발자
  └─ git commit 실행
      └─ Git pre-commit hook 실행
          └─ .pre-commit-config.yaml 읽기
              ├─ ruff 실행
              ├─ black 실행
              ├─ mypy 실행
              └─ 기타 검사 실행

전체 파일을 대상으로 pre-commit 실행하기

처음 pre-commit을 설정했다면 전체 파일을 대상으로 한 번 실행해보는 것이 좋습니다.

pre-commit run --all-files

이 명령어는 현재 변경된 파일뿐 아니라 프로젝트의 전체 파일을 대상으로 훅을 실행합니다.

기존 프로젝트에 pre-commit을 뒤늦게 도입하는 경우에는 많은 파일이 한 번에 수정될 수 있습니다. 이때는 변경 내용을 확인한 뒤 커밋하면 됩니다.

git status
git diff
git add .
git commit -m "chore: apply pre-commit formatting"

커밋 중 pre-commit이 실패했을 때

pre-commit 훅이 실패하면 커밋은 중단됩니다.

예를 들어 black이나 ruff가 파일을 자동 수정했다면, 수정된 파일을 다시 스테이징해야 합니다.

git status
git add .
git commit -m "add user api"

만약 자동 수정이 불가능한 문제가 있다면, 출력된 에러 메시지를 보고 직접 코드를 수정한 뒤 다시 커밋하면 됩니다.

이 흐름이 처음에는 번거롭게 느껴질 수 있지만, 결과적으로는 코드 리뷰 전에 기본적인 문제를 자동으로 걸러주기 때문에 유지보수에 도움이 됩니다.

detect-private-key 훅이 중요한 이유

detect-private-key 훅은 개인키가 Git 저장소에 커밋되는 것을 방지하기 위한 훅입니다.

예를 들어 JWT RS256 방식을 사용하면 .pem 형식의 개인키를 사용할 수 있습니다. 이런 파일이 실수로 Git에 올라가면 인증 토큰 서명에 사용되는 민감한 값이 외부에 노출될 수 있습니다.

- id: detect-private-key

이 훅을 추가해두면 개인키로 의심되는 내용이 커밋될 때 커밋을 중단시켜줍니다.

다만 이 훅만으로 모든 민감 정보 유출을 막을 수 있는 것은 아닙니다. .env, 인증서, 토큰, 비밀번호 파일 등은 .gitignore에도 함께 등록하는 것이 좋습니다.

예를 들어 다음과 같은 파일은 일반적으로 Git에 올리지 않습니다.

.env
*.pem
*.key
.venv/

최종 디렉터리 구조 예시

설정을 마치면 프로젝트 루트는 대략 다음과 같은 형태가 됩니다.

project-root/
├── .venv/
├── .gitignore
├── .pre-commit-config.yaml
├── pyproject.toml
├── services/
│   ├── user-service/
│   ├── product-service/
│   └── ...
└── shared/

여기서 .venv는 로컬 개발 환경용 디렉터리이므로 Git에 올리지 않습니다.

반면 pyproject.toml과 .pre-commit-config.yaml은 팀원들과 공유해야 하는 설정 파일이므로 Git에 포함합니다.

정리

이번 글에서는 Python 프로젝트를 시작할 때 설정하면 좋은 기본 개발 환경을 정리했습니다.

핵심은 다음과 같습니다.

Python 프로젝트에서는 가상환경을 사용해 프로젝트별 의존성을 분리하는 것이 좋습니다.
ruff는 코드 품질 검사와 import 정리를 담당합니다.
black은 코드 포맷팅을 담당합니다.
mypy는 타입 검사를 담당합니다.
pyproject.toml은 Python 개발 도구의 설정을 모아두는 파일입니다.
.pre-commit-config.yaml은 커밋 전에 실행할 검사 목록을 정의하는 파일입니다.
pre-commit install을 실행하면 이후 git commit마다 자동 검사가 실행됩니다.
민감 정보 유출을 막기 위해 detect-private-key 같은 훅과 .gitignore 설정을 함께 사용하는 것이 좋습니다.

처음부터 모든 규칙을 엄격하게 적용하기보다는, 프로젝트 상황에 맞게 점진적으로 규칙을 추가하고 예외를 정리하는 방식이 현실적입니다.

Ruff E712와 SQLAlchemy Boolean 조건식 처리하기

hwara_ — Wed, 20 May 2026 11:26:29 +0900

문제 상황

SQLAlchemy를 사용해 상품 목록을 조회하는 조건식을 작성하던 중, Ruff에서 다음과 같은 경고가 발생했습니다.

services\product-service\app\routes\products.py:94:27: E712 Avoid equality comparisons to `True`; use `if Product.is_active:` for truth checks

문제가 된 코드는 다음과 같습니다.

conditions.append(Product.is_active == True)

Ruff의 E712 규칙은 Python 코드에서 True, False와 직접 비교하는 패턴을 피하라는 경고입니다.

일반적인 Python 코드에서는 다음과 같은 비교를 권장하지 않습니다.

if value == True:
    ...

대신 아래처럼 truthy/falsy 평가를 사용하는 것이 더 자연스럽습니다.

if value:
    ...

일반 Python 코드에서 문제가 되는 이유

Python에서는 Boolean 값을 직접 == True, == False로 비교하지 않아도 조건문에서 참/거짓을 평가할 수 있습니다.

예를 들어 다음과 같은 코드는 불필요한 비교로 볼 수 있습니다.

if is_active == True:
    ...

보통은 다음과 같이 작성하는 것이 더 Pythonic합니다.

if is_active:
    ...

따라서 Ruff는 == True 같은 표현을 발견하면 E712 경고를 발생시킵니다.

SQLAlchemy에서는 상황이 다르다

하지만 SQLAlchemy의 where 조건식에서는 일반적인 Python Boolean 비교와 의미가 다릅니다.

conditions.append(Product.is_active == True)

위 코드는 Python의 Boolean 값을 단순 비교하는 코드가 아니라, SQLAlchemy가 SQL 조건식을 만들기 위한 표현식입니다.

즉, 의도는 다음과 같은 SQL 조건을 만드는 것입니다.

WHERE product.is_active = true

따라서 일반 Python 코드 기준으로는 E712 경고 대상이지만, SQLAlchemy 표현식에서는 의도된 사용일 수 있습니다.

이런 경우 Ruff 입장에서는 SQLAlchemy의 표현식 생성 의도를 정확히 구분하기 어렵기 때문에 오탐처럼 보일 수 있습니다.

해결 방법

SQLAlchemy에서는 Boolean 또는 NULL 비교를 위해 is_() 메서드를 사용할 수 있습니다.

변경 전 코드는 다음과 같습니다.

conditions.append(Product.is_active == True)

이를 아래와 같이 변경할 수 있습니다.

conditions.append(Product.is_active.is_(True))

이렇게 작성하면 Ruff의 E712 경고를 피하면서도, SQLAlchemy 표현식이라는 의도를 더 명확하게 드러낼 수 있습니다.

변경 전후 비교

변경 전

conditions.append(Product.is_active == True)

변경 후

conditions.append(Product.is_active.is_(True))

참고: None 비교도 같은 방식으로 처리 가능

SQLAlchemy 공식 문서에서도 None 비교에 대해 비슷한 예시를 제공합니다.

statement.where(users.c.name == None)

PEP8 또는 linter 경고가 신경 쓰이는 경우, 다음과 같이 is_()를 사용할 수 있습니다.

statement.where(users.c.name.is_(None))

Boolean 조건에서도 같은 방식으로 is_(True) 또는 is_(False)를 사용할 수 있습니다.

Product.is_active.is_(True)
Product.is_active.is_(False)

정리

Ruff의 E712는 일반 Python 코드에서 == True, == False 비교를 피하도록 안내하는 규칙입니다.

하지만 SQLAlchemy에서는 Product.is_active == True 같은 표현이 SQL 조건식을 만들기 위한 코드로 사용될 수 있습니다. 이 경우 일반적인 Python truth check와는 의미가 다르기 때문에 linter 경고가 오탐처럼 느껴질 수 있습니다.

이 문제는 SQLAlchemy의 is_() 메서드를 사용해 해결할 수 있습니다.

conditions.append(Product.is_active.is_(True))

결과적으로 linter 경고를 제거하면서도, SQLAlchemy 조건식의 의도를 더 명확하게 표현할 수 있었습니다.

Reference

SQLAlchemy 공식 문서: https://docs.sqlalchemy.org/en/14/core/tutorial.html

기록 저장소

GitHub Actions에서 커밋 해시 기반 Docker 이미지 태그로 배포 자동화하기

GitHub Actions에서 커밋 해시 기반 Docker 이미지 태그로 배포 자동화하기

현재 사용 중인 GitHub Actions 예시

Workflow 실행 조건 설정

Job 설정

Repository checkout

Docker 사용 가능 여부 확인

커밋 해시 기반 이미지 태그 생성

Docker Compose용 env 파일 생성

Docker 이미지 빌드 및 Push

Kustomize 설치

Kustomize overlay 이미지 태그 수정 및 commit

변경 사항이 없을 때는 commit하지 않기

GitHub Actions Bot 계정으로 commit/push

정리

Reference

Kustomize secretGenerator와 Argo CD 동기화 오류 해결하기

개요

문제 상황

원인 분석

해결 방법

1. Sealed Secrets 사용

2. External Secrets Operator 사용

3. Secret을 클러스터에 직접 생성

적용 결과

정리

Helm으로 Argo CD 설치 후 Gateway API와 TLS로 접속 구성하기

구성 개요

1. Argo CD 설치

2. Gateway TLS Secret 준비

3. Gateway와 HTTPRoute 적용

4. 초기 로그인

5. Application 적용

6. Argo CD UI에서 Application 상태 확인 및 수동 Sync

수동 Sync 실행

Sync 상태 확인과 롤백

명령어로 Application 상태 확인하기

정리

References

GitHub Actions Self-hosted Runner를 WSL 환경에 설치하고 서비스로 실행하기

개요

Self-hosted runner 비용 관련 주의사항

WSL에서 Docker 사용할 수 있도록 설정

Self-hosted runner 다운로드 및 설정

Self-hosted runner를 서비스로 설정하기

Self-hosted runner 서비스 중지 및 제거

Runner 등록 상태 확인

GitHub Actions workflow에서 사용하기

정리

Reference

Kubernetes kubelet의 컨테이너 로그 로테이션 설정 정리

kubelet의 기본 컨테이너 로그 로테이션 설정

kubelet 로그 로테이션의 목적

kubectl logs 조회 시 주의할 점

로그 용량을 줄이고 싶을 때 고려할 점

정리

Kubernetes 노드와 Docker 환경에서 디스크 용량 확인 및 정리하기

전체 디스크 용량 확인

Pod 및 컨테이너 로그 용량 확인

containerd 용량 확인

Kubernetes의 이미지 GC

Docker 용량 확인

사용하지 않는 Docker 이미지 정리

이미지를 삭제해도 용량이 줄지 않는 경우

Docker Build Cache 정리

Docker Desktop의 Build Cache GC

정리

Reference

머지된 Git 브랜치를 안전하게 정리하는 방법

Git 브랜치 삭제 명령어 정리

로컬 브랜치 삭제

원격 브랜치 삭제

로컬에 남아 있는 원격 브랜치 정보 정리

머지된 로컬 브랜치 삭제

명령어별 정리

정리

Reference

Slack Incoming Webhook으로 채널에 메시지 보내기

Slack Incoming Webhook으로 채널에 메시지 보내기

`kubectl logs` 조회 시 주의할 점