GitLab CI 통합

공식 Docker 컨테이너를 사용하여 GitLab CI/CD 파이프라인에서 Alpacon으로 배포와 서버 관리를 자동화하세요.

빠른 시작

1. 서비스 토큰 생성

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

  1. IAM → Applications에서 이 파이프라인이 속한 Application을 열거나 새로 생성
  2. 자격 증명 탭에서 추가 클릭
  3. 토큰 이름과 접근 범위 지정, 필요한 사유 작성
  4. 표시된 키 복사(alpst-로 시작하며 한 번만 표시)

CI 범위로 만든 토큰은 검토를 거쳐야 동작합니다. 요청은 대기중(pending) 상태로 생성되고 승인 권한이 있는 사람이 활성화하기 전까지는 어디에도 인증되지 않습니다. 파이프라인 도중에 발견하지 않도록 이 단계를 미리 감안하세요.

2. ACL 규칙 추가

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

토큰을 열고 ACL 탭에서 다음을 추가하세요.

규칙제한 대상
Server ACL파이프라인이 접근할 수 있는 서버
Command ACL실행할 수 있는 명령. 예: docker compose ... up -d
File ACL업로드하거나 내려받을 수 있는 경로

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

3. CI/CD 변수 추가

GitLab 프로젝트에 다음 변수를 추가하세요 (Settings → CI/CD → Variables):

  • ALPACON_WORKSPACE: 워크스페이스 이름 (예: your-workspace)
  • ALPACON_REGION: 워크스페이스 리전 (us1 또는 ap1)
  • ALPACON_SERVICE_TOKEN: 1단계에서 복사한 alpst- 키 (Masked와 Protected로 표시)

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

4. .gitlab-ci.yml 생성

중요: alpacax/alpacon-cli 이미지는 ENTRYPOINT ["alpacon"]으로 설정되어 있으므로, GitLab CI에서 entrypoint: [""]로 오버라이드해야 합니다.

stages:
  - deploy
 
deploy:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN
    - alpacon websh root@prod-server "docker ps"
  only:
    - main

사용 예제

docker-compose.yml로 배포

deploy-compose:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN
    - alpacon cp docker-compose.yml prod-server:/opt/myapp/docker-compose.yml
    - alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml up -d"
    - alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml ps"
  only:
    - main

환경 변수 파일과 함께 배포

참고: 디렉터리에 여러 파일을 업로드할 때는 먼저 디렉터리를 생성하고 적절한 권한을 설정해야 합니다:

deploy-with-env:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN
    # Create directory with proper permissions
    - alpacon websh root@prod-server "mkdir -p /opt/myapp && chown ubuntu:ubuntu /opt/myapp"
    # Upload files
    - alpacon cp docker-compose.yml prod-server:/opt/myapp/
    - alpacon cp .env prod-server:/opt/myapp/
    # Deploy
    - alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml up -d"
    - alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml ps"
  only:
    - main

이미지 태그와 함께 배포

deploy-tagged:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN
    - alpacon websh --env="DOCKER_USERNAME=$DOCKER_USERNAME" --env="DOCKER_PASSWORD=$DOCKER_PASSWORD" root@prod-server "docker login -u \$DOCKER_USERNAME -p \$DOCKER_PASSWORD"
    - alpacon cp docker-compose.yml prod-server:/opt/myapp/docker-compose.yml
    - alpacon websh --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" --env="DOCKER_USERNAME=$DOCKER_USERNAME" root@prod-server "docker compose -f /opt/myapp/docker-compose.yml pull"
    - alpacon websh --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" root@prod-server "docker compose -f /opt/myapp/docker-compose.yml up -d"
    - alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml ps"
  only:
    - main

다중 환경 배포

아래 두 job은 같은 토큰을 사용하므로 토큰의 Server ACL에 prod-server뿐 아니라 staging-server도 들어가야 합니다. 환경마다 토큰을 따로 발급해 각자의 서버로만 범위를 좁히면 staging 파이프라인이 프로덕션에 아예 닿지 못합니다.

deploy-staging:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN
    - alpacon cp docker-compose.yml staging-server:/opt/myapp/docker-compose.yml
    - alpacon websh root@staging-server "docker compose -f /opt/myapp/docker-compose.yml up -d"
  only:
    - develop
  environment:
    name: staging
 
deploy-production:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN
    - alpacon cp docker-compose.yml prod-server:/opt/myapp/docker-compose.yml
    - alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml up -d"
  only:
    - main
  environment:
    name: production
  when: manual

완전한 CI/CD 파이프라인

stages:
  - build
  - deploy
 
build-image:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
    - docker build -t $DOCKER_USERNAME/myapp:$CI_COMMIT_SHORT_SHA .
    - docker push $DOCKER_USERNAME/myapp:$CI_COMMIT_SHORT_SHA
  only:
    - main
 
deploy:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_TOKEN
    - alpacon websh --env="DOCKER_USERNAME=$DOCKER_USERNAME" --env="DOCKER_PASSWORD=$DOCKER_PASSWORD" root@prod-server "docker login -u \$DOCKER_USERNAME -p \$DOCKER_PASSWORD"
    - alpacon cp docker-compose.yml prod-server:/opt/myapp/docker-compose.yml
    - alpacon websh --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" --env="DOCKER_USERNAME=$DOCKER_USERNAME" root@prod-server "docker compose -f /opt/myapp/docker-compose.yml pull"
    - alpacon websh --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" --env="DOCKER_USERNAME=$DOCKER_USERNAME" root@prod-server "docker compose -f /opt/myapp/docker-compose.yml up -d"
    - alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml ps"
  only:
    - main
  needs:
    - build-image

보안

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

문제 해결

Entrypoint 오류

증상: Error: unknown command "sh" for "alpacon"

해결 방법: 이미지 구성에 entrypoint: [""]를 추가하는 것을 잊었습니다. 다음과 같이 사용하세요:

image:
  name: alpacax/alpacon-cli:latest
  entrypoint: [""]

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

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

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

명령이나 파일이 거부됨

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

해결 방법: 토큰의 ACL이 그 작업을 포함하지 않습니다. 토큰의 ACL 탭에서 빠진 Server ACL, Command ACL, File ACL 항목을 추가하세요. 세 가지가 각각 기본 거부라서 추가하지 않은 종류는 전부 막힙니다.

권한 거부

증상: Docker 명령 실행 시 permission denied

해결 방법: root@ 문법을 사용하여 root로 실행하세요: alpacon websh root@server-name "docker ps"

업로드 후 파일을 찾을 수 없음

증상: 파일이 성공적으로 업로드되었지만 명령 실행 시 찾을 수 없음

해결 방법: 디렉터리가 존재하지 않거나 권한이 없을 수 있습니다. 적절한 소유권으로 디렉터리를 생성하세요:

- alpacon websh root@server "mkdir -p /path/to/dir && chown username:username /path/to/dir"
- alpacon cp file.txt server:/path/to/dir/

리소스

다음 단계

최종 수정: