서버 등록하기

Alpacon에 서버를 등록하여 브라우저에서 관리할 수 있습니다.

사용자 서버란?

사용자 서버는 개별 사용자 또는 사용자 그룹이 운영 중인 서버를 의미합니다. Alpacon은 다음 두 가지 유형의 서버를 모두 지원합니다:

• 클라우드 기반 서버 (예: AWS, GCP, Azure)
• 온프레미스 서버 (사용자가 직접 관리하는 서버)

클라우드 서버와 온프레미스 서버를 혼합 운영하는 하이브리드 환경에서도, Alpacon의 일관된 UI/UX를 통해 동일한 방식으로 모든 서버를 관리할 수 있습니다.

주요 이점:

• 모든 서버 유형에 대한 통합 관리 인터페이스
• 서버 위치와 무관한 일관된 경험
• 클라우드와 온프레미스 구분 불필요
• 중앙 집중식 제어 및 모니터링

등록 절차

서버 등록은 3단계로 진행됩니다:

1. 등록 방식 선택: 등록 방법 선택
2. 정보 입력: 서버 세부 정보 입력 (방식별 상이)
3. 설치 가이드: 생성된 설치 스크립트 또는 명령어 실행

등록 방식

토큰으로 등록

서버 등록 토큰과 생성된 CLI 명령어를 사용하여 서버를 등록합니다. 같은 토큰으로 서버를 한 대 또는 여러 대 등록할 수 있어, 단건과 대량 등록 모두에 적합한 방식입니다.

1단계: 등록 방식 선택

1. 좌측 사이드바에서 Servers 클릭
2. 우측 상단의 서버 등록 버튼 클릭
3. 토큰으로 등록 선택

2단계: 서버 정보 입력

• 플랫폼 (필수): 서버 OS 선택 (Debian 계열, Red Hat 계열, macOS, Windows)
• 서버 이름 (선택): 최대 20자. 서버 이름의 접두어로 사용됩니다. 지정하지 않으면 서버의 호스트 이름이 사용됩니다.
• 등록 토큰 (필수): 드롭다운에서 기존 토큰을 선택하거나 즉석에서 생성

참고: 등록된 서버에 어떤 사용자 그룹이 접근할 수 있는지는 이 폼이 아니라 등록 토큰이 결정합니다. 서버는 토큰의 허용 그룹(토큰 생성 시 설정)을 그대로 상속합니다. 서버 등록 토큰을 참고하세요.

3단계: 에이전트 설치

토큰 기반 CLI 설치 명령어가 생성되어 화면에 표시됩니다.

1. 생성된 명령어 복사
2. 대상 서버에서 실행
3. 설치 완료 대기
4. 서버 목록에서 상태가 온라인으로 표시되는지 확인

Ansible

alpacax.alpacon 컬렉션의 register 모듈을 사용해 Ansible playbook으로 여러 서버에 Alpamon 에이전트를 설치하고 등록합니다. 대량 등록이나 이미 Ansible로 서버를 관리하는 팀에 적합합니다. 모듈은 멱등성이 있어 playbook을 다시 실행해도 이미 등록된 호스트는 안전하게 건너뜁니다.

시작하기 전에

• 컨트롤 노드: Python 3.11+와 Ansible 2.15+(pip install ansible), 대상 서버에 대한 SSH 키 기반 접근.
• 서버 등록 토큰. 토큰이 등록된 서버에 접근할 수 있는 그룹을 결정합니다.
• 컬렉션 설치:

ansible-galaxy collection install alpacax.alpacon --upgrade

1단계: 등록 방식 선택

1. 좌측 사이드바에서 Servers 클릭
2. 우측 상단의 서버 등록 버튼 클릭
3. Ansible 선택 후 플랫폼(필요하면 서버 이름과 등록 토큰도) 선택

선택한 내용에 맞춰 Alpacon이 인벤토리와 실행 명령어가 포함된 가이드를 생성해 줍니다.

2단계: 인벤토리 구성

작업 디렉터리에 inventory.ini를 만듭니다.

[targets]
YOUR_IP ansible_user=YOUR_USER  # ansible_ssh_private_key_file=/path/to/YOUR_KEY.pem

YOUR_IP는 대상 서버의 IP나 호스트 이름으로, YOUR_USER는 SSH 사용자로 바꿉니다. Windows 대상은 ansible_connection=ssh ansible_shell_type=powershell을 추가하세요.

계속하기 전에 연결을 확인합니다. SUCCESS가 표시되어야 합니다.

ansible -i inventory.ini targets -m ping

Windows 대상에서는 ping이 동작하지 않습니다(대상에 Python이 필요). 대신 ansible.windows 컬렉션의 win_ping을 사용하세요: ansible -i inventory.ini targets -m ansible.windows.win_ping.

3단계: 등록

두 가지 방법 중 하나를 선택합니다.

옵션 A: 번들 playbook (단건 설치, 작성할 playbook 없음):

ansible-playbook -i inventory.ini alpacax.alpacon.register \
  -e alpacon_url=https://your-workspace.ap1.alpacon.io \
  -e registration_token=YOUR_REGISTRATION_TOKEN_KEY \
  -e platform=debian

옵션 B: 커스텀 playbook (재사용 가능, 기존 자동화에 통합). playbook.yml로 저장하세요.

- hosts: targets
  become: true
  tasks:
    - alpacax.alpacon.register:
        alpacon_url: "https://your-workspace.ap1.alpacon.io"
        registration_token: "{{ registration_token }}"
        platform: "debian"
      no_log: true

ansible-playbook -i inventory.ini playbook.yml \
  -e registration_token=YOUR_REGISTRATION_TOKEN_KEY

보안: 위 예시는 간결함을 위해 토큰을 -e registration_token=...로 전달하는데, 이렇게 하면 셸 히스토리와 프로세스 목록에 토큰이 노출될 수 있습니다. 단건 실행이 아니라면 토큰을 Ansible Vault에 보관하고 명령줄 대신 변수로 참조하세요.

모듈 파라미터

• alpacon_url(필수): Alpacon 워크스페이스 URL.
• registration_token(필수): 등록 토큰 키. 평문 대신 Ansible Vault에 보관하세요.
• platform(필수): debian, rhel, darwin, windows.
• server_name(선택): 지정하지 않으면 대상의 호스트 이름을 사용합니다.
• package_proxy(선택): 패키지 설치에 사용할 HTTP 프록시 URL.
• allow_sudo_with_mfa(선택, Linux 전용): sudo with MFA를 위해 alpamon-pam 패키지도 설치합니다.

플랫폼별 참고

• Linux(debian = Debian/Ubuntu, rhel = RHEL/CentOS/Fedora): become: true로 실행합니다. 대상 사용자에게 root 또는 비밀번호 없는 sudo 권한이 필요합니다.
• macOS(darwin): become: true를 설정하지 마세요. Homebrew는 root 실행을 거부합니다. 대상에 Homebrew가 설치돼 있어야 하며(Alpamon은 alpacax/alpacon tap으로 배포), package_proxy와 allow_sudo_with_mfa는 적용되지 않습니다. 컨트롤 노드가 macOS면 ansible-playbook 실행 전에 OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES를 export하세요.
• Windows: become: true를 설정하지 마세요. 접속 사용자가 이미 Administrator여야 합니다. PowerShell 5.1+, TLS 1.2, github.com으로의 아웃바운드 HTTPS가 필요합니다.

AWS Cloud-Init (곧 제공 예정)

AWS Cloud-Init user data를 사용하여 EC2 인스턴스 프로비저닝 시 서버를 자동으로 등록합니다.

Terraform (곧 제공 예정)

Terraform provider를 사용하여 Infrastructure as Code 워크플로우의 일부로 서버 프로비저닝과 등록을 동시에 수행합니다.

지원 플랫폼

전체 Linux 배포판 목록은 설치 가이드를 참고하세요.

플랫폼별 기능 범위

Linux와 macOS는 사용자/그룹 관리, Unix 권한 변경(chmod / chown)을 포함한 Alpacon의 모든 기능을 사용할 수 있습니다. Windows 서버는 **터미널 세션(Websh)**과 **파일 전송(WebFTP)**을 지원하며, 사용자/그룹 관리와 Unix 권한 제어는 적용되지 않으므로 해당 UI가 비활성화됩니다.

필수 요구사항

서버:

• 지원되는 운영체제 및 아키텍처 (지원 플랫폼 참고)
• 설치를 위한 관리자 권한 (Linux/macOS는 root/sudo, Windows는 관리자 권한 PowerShell)
• 인터넷 연결

네트워크:

• 아웃바운드 HTTPS 연결 가능 (포트 443)
• Alpacon API 서버 접근 가능

문제 해결

연결 상태가 “오프라인”으로 표시되는 경우: 플랫폼에 맞는 명령으로 에이전트 상태 확인, 재시작, 로그 점검을 수행하세요.

Linux (systemd)

sudo systemctl status alpamon
sudo systemctl restart alpamon
sudo journalctl -u alpamon -n 50

macOS (launchd)

sudo launchctl print system/com.alpacax.alpamon
sudo launchctl kickstart -k system/com.alpacax.alpamon
tail -n 50 /var/log/alpamon/alpamon.log

Windows (Service Control Manager)

관리자 권한 PowerShell에서:

sc.exe query alpamon
Restart-Service alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 50

참고: Windows에서 alpamon register는 다시 실행해도 안전합니다. 필요한 경우 에이전트를 %ProgramFiles%\alpamon\에 설치하고, 서비스 구성을 갱신한 뒤 서비스를 시작합니다.

설치 실패 시:

• 관리자 권한 확인 (Linux/macOS는 sudo, Windows는 관리자 권한 PowerShell)
• 인터넷 연결 확인
• 지원 플랫폼인지 확인

보안 고려사항

에이전트 통신:

• 모든 통신은 TLS 암호화
• 서버에서 Alpacon으로의 아웃바운드 연결만 필요
• 인바운드 포트 오픈 불필요

인증:

• 각 서버는 고유한 토큰으로 인증
• 토큰은 설치 시에만 사용되며 서버에 안전하게 저장

다음 단계

서버 등록 후:

• 서버 접속하기
• 서버 접근 제어하기
• 서버 모니터링