Jenkins 통합

공식 Docker 컨테이너를 사용하여 Alpacon을 Jenkins 파이프라인에 통합합니다.

사전 요구사항

  • Docker Pipeline 플러그인이 설치된 Jenkins
  • Alpacon 워크스페이스와 파이프라인의 서비스 토큰이 속할 Application

Free 플랜 워크스페이스는 Application을 하나만 둘 수 있습니다. 파이프라인 전용으로 새로 만들지 말고 이미 있는 Application을 함께 사용하세요.

빠른 시작

1. 서비스 토큰 생성

CI와 자동화는 서비스 토큰으로 동작합니다. 서비스 토큰은 사람이 아니라 Application에 속하기 때문에 담당자가 바뀌어도 그대로 유지되며, 파이프라인이 무엇까지 할 수 있는지는 ACL이 정확히 정합니다.

토큰 발급 전에 애플리케이션에 서버 계정과 필요한 scope를 허용하는 전역 역할을 부여하세요. 예시의 ci-deploy는 애플리케이션이 소유한 계정으로 바꿔 사용합니다. 이 계정이 배포 디렉터리와 Docker에 접근할 수 있도록 권한을 설정하세요. 서비스 토큰은 root로 실행하거나 대화형 Websh 세션을 열 수 없습니다.

Alpacon Cloud에서는 서비스 토큰의 sudo 위험도가 심각(Critical)보다 낮거나 평가되지 않았으면 허용하고, 심각이면 거부합니다. 단, Advisory 워크스페이스에서는 위험도를 이유로 거부하지 않고 판단을 기록합니다. Advisory가 아니면 워크스페이스의 token_exec 규칙으로 위험도 기준을 더 엄격하게 정할 수 있습니다. 워크스페이스의 sudo 설정도 켜져 있어야 하며, 꺼져 있으면 workspace_sudo_with_mfa_disabled로 거부됩니다. 기본 설정의 자체 호스팅에서는 모든 서비스 토큰 sudo가 거부됩니다. 명령어 규칙은 sudo를 포함한 제출 문자열 전체와 일치해야 합니다. 서비스 토큰을 참고하세요.

  1. IAM → 애플리케이션에서 이 파이프라인이 속한 Application을 열거나 새로 생성
  2. 토큰 탭에서 새로 만들기 클릭
  3. 토큰 이름과 만료 시점 지정, 액세스 템플릿이나 직접 선택으로 권한 지정, 서버·명령어·경로 준비, 검토 단계에서 필요한 사유 작성
  4. 표시된 키 복사 또는 다운로드(alpst-로 시작하며 한 번만 표시)

명령어와 파일 전송 scope는 항상 웹 콘솔에서 승인을 기다립니다. ACL을 추가하거나 파이프라인을 시작하기 전에 슈퍼유저나 해당 요청의 승인자에게 승인을 받으세요.

2. ACL 규칙 추가

새 서비스 토큰은 ACL 규칙을 추가하기 전까지 아무 곳에도 닿지 못합니다. 서버, 명령, 파일 경로가 각각 기본 거부이므로 규칙이 하나도 없는 토큰은 어디서든 거부됩니다.

승인 후 토큰의 접근 규칙 탭에서 준비한 규칙을 적용하거나 서버와 파일 규칙을 추가하세요. Alpacon Cloud에서는 명령 ACL 관리자에 등록된 관리자가 같은 탭의 사전 승인된 명령에 명령어를 추가합니다. 이 권한은 워크스페이스 역할과 별개입니다. 자체 호스팅에서는 명령어 ACL을 사용합니다. 다음 접근 범위를 설정하세요.

규칙제한 대상
Server ACL파이프라인이 접근할 수 있는 서버
명령어 접근예제에서 제출하는 명령어 전체. 예: cd /opt/myapp && git pull && pm2 restart app, cd /opt/myapp && git pull origin main, cd /opt/myapp && npm ci --omit=dev, pm2 restart myapp
File ACL업로드하거나 내려받을 수 있는 경로

파일 전송은 서버 규칙을 먼저 확인한 다음 파일 규칙을 확인합니다. 접근 규칙 탭을 건너뛰면 파이프라인은 첫 명령에서 실패합니다.

3. Credentials 추가

Manage Jenkins → Credentials에서 다음을 추가하세요:

  • ALPACON_WORKSPACE: 워크스페이스 이름. 예: your-workspace (Secret text)
  • ALPACON_REGION: 워크스페이스 리전. us1 또는 ap1 (Secret text)
  • ALPACON_SERVICE_TOKEN: 1단계에서 복사한 alpst- 키 (Secret text)

4. 파이프라인 생성

groovy
pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE = credentials('ALPACON_WORKSPACE')
        ALPACON_REGION = credentials('ALPACON_REGION')
        ALPACON_SERVICE_TOKEN = credentials('ALPACON_SERVICE_TOKEN')
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN'
                sh 'alpacon exec ci-deploy@prod-server "cd /opt/myapp && git pull && pm2 restart app"'
            }
        }
    }
}

중요: 컨테이너의 기본 entrypoint를 override하기 위해 args '--entrypoint=""'가 필요합니다.

CLI는 alpacon login으로만 토큰을 읽습니다. 환경 변수로 인증하는 경로는 없으므로 모든 파이프라인은 첫 Alpacon 명령 앞에 이 login 단계를 그대로 두어야 합니다.

사용 예시

애플리케이션 배포

groovy
pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE = credentials('ALPACON_WORKSPACE')
        ALPACON_REGION = credentials('ALPACON_REGION')
        ALPACON_SERVICE_TOKEN = credentials('ALPACON_SERVICE_TOKEN')
        TARGET_SERVER = 'prod-server'
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN'
                sh 'alpacon exec ci-deploy@$TARGET_SERVER "cd /opt/myapp && git pull origin main"'
                sh 'alpacon exec ci-deploy@$TARGET_SERVER "cd /opt/myapp && npm ci --omit=dev"'
                sh 'alpacon exec ci-deploy@$TARGET_SERVER "pm2 restart myapp"'
            }
        }
    }
}

sudo로 서비스 재시작

명령어 규칙은 sudo systemctl restart nginx 전체 문자열과 일치해야 합니다. Cloud에서는 워크스페이스에 더 엄격한 규칙이 없으면 심각 미만에서 허용하며, Advisory에서는 위험도를 이유로 거부하지 않고 판단을 기록합니다. 워크스페이스 sudo 설정이 켜져 있어야 합니다. 기본 설정의 자체 호스팅에서는 서비스 토큰 sudo를 거부합니다.

groovy
pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE = credentials('ALPACON_WORKSPACE')
        ALPACON_REGION = credentials('ALPACON_REGION')
        ALPACON_SERVICE_TOKEN = credentials('ALPACON_SERVICE_TOKEN')
    }
 
    stages {
        stage('Restart') {
            steps {
                sh 'alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN'
                sh 'alpacon exec ci-deploy@prod-server "sudo systemctl restart nginx"'
                sh 'alpacon exec ci-deploy@prod-server "systemctl status nginx"'
            }
        }
    }
}

Docker Compose로 배포

groovy
pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE = credentials('ALPACON_WORKSPACE')
        ALPACON_REGION = credentials('ALPACON_REGION')
        ALPACON_SERVICE_TOKEN = credentials('ALPACON_SERVICE_TOKEN')
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN'
                sh 'alpacon cp docker-compose.yml ci-deploy@prod-server:/opt/myapp/docker-compose.yml'
                sh 'alpacon cp .env ci-deploy@prod-server:/opt/myapp/.env'
                sh 'alpacon exec ci-deploy@prod-server "docker compose -f /opt/myapp/docker-compose.yml pull"'
                sh 'alpacon exec ci-deploy@prod-server "docker compose -f /opt/myapp/docker-compose.yml up -d"'
                sh 'alpacon exec ci-deploy@prod-server "docker compose -f /opt/myapp/docker-compose.yml ps"'
            }
        }
    }
}

alpacon cp 두 줄에는 Server ACL 항목에 더해 /opt/myapp/ 경로를 여는 File ACL 항목이 필요하고, docker compose 줄에는 Cloud의 사전 승인 명령어 또는 자체 호스팅의 명령어 ACL 항목이 필요합니다.

보안

Alpacon을 통해 실행된 모든 명령은 워크스페이스 감사 로그에 기록되며, 사람이 아니라 토큰을 소유한 Application 이름으로 남습니다. 환경 변수를 통해 전달된 민감한 값(비밀번호, 토큰 등)은 명령 기록에서 자동으로 마스킹됩니다.

문제 해결

Entrypoint 오류

증상: 컨테이너가 예상한 명령을 실행하지 않음

해결 방법: docker agent 설정에 args '--entrypoint=""'를 반드시 포함해야 합니다.

정상적인 서비스 토큰으로 로그인 실패

증상: alpst- 키를 정확히 복사했는데도 alpacon login이 failed to verify user profile을 출력함

해결 방법: 서비스 토큰은 Alpacon CLI v1.7.4 이상이 필요합니다. 그 이전 버전은 alpst- 키를 알아보지 못하고 이처럼 오해하기 쉬운 메시지를 대신 출력합니다. 에이전트가 실제로 실행하는 버전을 확인하고 올리세요. 자체 호스팅 에이전트이거나 alpacax/alpacon-cli 이미지 태그를 고정한 경우가 대부분입니다.

명령이나 파일이 거부됨

증상: 내 터미널에서는 되는 명령이나 alpacon cp가 파이프라인에서는 거부됨

해결 방법: 토큰의 서버·파일 ACL과 실행 계정을 확인하세요. Cloud에서는 Command ACL 관리자에게 토큰의 사전 승인 명령어 검토를 요청하고, 자체 호스팅에서는 명령어 ACL을 확인하세요. 자동화 오류 해결을 참고하세요.

다음 단계

최종 수정: