시작 시 Amazon EC2 인스턴스에서 명령 실행

Amazon EC2 인스턴스를 시작할 때 사용자 데이터를 인스턴스에 전달하여 자동화된 구성 태스크를 수행하는 데 사용할 수 있고, 인스턴스가 시작된 후에 스크립트를 실행하는 데 사용할 수도 있습니다.

더욱 복잡한 자동화 시나리오를 원하는 경우 AWS CloudFormation 또는 AWS OpsWorks를 고려할 수 있습니다. 자세한 내용은 다음 자료를 참조하십시오.

• AWS CloudFormation 사용 설명서의 AWS CloudFormation을 사용하여 Amazon EC2에 애플리케이션 배포.

• AWS OpsWorks 사용 설명서

Linux 인스턴스에서는 Amazon EC2에 쉘 스크립트 및 cloud-init 명령이라는 두 가지 유형의 사용자 데이터를 전달할 수 있습니다. 이 데이터를 인스턴스 시작 마법사에 일반 텍스트, 파일(명령줄 도구를 사용하여 인스턴스를 시작하는 데 유용) 또는 base64 인코딩 텍스트(API 호출용)로 전달할 수도 있습니다.

Windows 인스턴스에서는 시작 에이전트가 사용자 데이터 스크립트를 처리합니다. 다음 섹션에서는 각 운영 체제에서 사용자 데이터가 처리되는 방식의 차이점에 대해 설명합니다.

Amazon EC2가 Linux 인스턴스의 사용자 데이터를 처리하는 방법

다음 예제에서는 Amazon Linux 2에 LAMP 서버 설치의 명령을 인스턴스 시작 시 실행되는 shell 스크립트 및 cloud-init 명령 세트로 변환합니다. 각 예제에서는 사용자 데이터에 따라 다음 태스크를 수행합니다.

• 배포 소프트웨어 패키지를 업데이트합니다.

• 필요한 웹 서버, php 및 mariadb 패키지를 설치합니다.

• httpd 서비스를 시작하고 systemctl를 통해 활성화합니다.

• apache 그룹에 ec2-user 가 추가됩니다.

• 웹 디렉터리 및 해당 디렉터리에 들어 있는 파일에 적절한 소유권과 파일 권한을 설정합니다.

• 간단한 웹 페이지를 생성하여 웹 서버 및 PHP 엔진을 테스트합니다.

사전 조건 

이 주제의 예에서는 다음과 같이 가정합니다.

• 사용자 인스턴스에 인터넷에서 접속 가능한 퍼블릭 DNS 이름이 있습니다.

• 인스턴스와 연결된 보안 그룹은 SSH(포트 22) 트래픽을 허용하도록 구성되어 있으므로 인스턴스에 연결하여 출력 로그 파일을 볼 수 있습니다.

• 인스턴스는 Amazon Linux 2 AMI를 사용하여 시작됩니다. 이러한 명령은 Amazon Linux 2에서만 사용해야 합니다. 다른 Linux 배포에서는 명령이 작동하지 않을 수 있습니다. 다른 배포에 대한 cloud-init 지원 등의 자세한 내용은 해당 설명서를 참조하세요.

사용자 데이터 및 shell 스크립트

shell 스크립트에 익숙한 경우 이 방법은 인스턴스 시작 시 명령을 전송하는 가장 쉽고 완벽한 방법입니다. 부팅 시에 이러한 작업을 추가하면 인스턴스 부팅에 걸리는 시간이 그만큼 늘어납니다. 사용자 스크립트가 성공적으로 완료되었는지 테스트하려면 우선 작업이 완료될 수 있도록 몇 분의 여유 시간을 두어야 합니다.

중요

기본적으로 사용자 데이터 스크립트 및 cloud-init 명령은 최초로 인스턴스를 시작할 때만 실행됩니다. 인스턴스를 재시작할 때마다 사용자 데이터 스크립트 및 cloud-init 명령이 실행되도록 구성을 업데이트할 수 있습니다. 자세한 내용은 AWS 지식 센터에서 사용자 데이터를 활용하여 Amazon EC2 Linux 인스턴스를 다시 시작할 때마다 스크립트를 자동으로 실행하려면 어떻게 해야 하나요?를 참조하세요.

사용자 데이터 shell 스크립트는 #! 문자 및 스크립트를 읽을 인터프리터의 경로(일반적으로 /bin/bash))로 시작되어야 합니다. 쉘 스크립팅에 대한 소개는 GNU 운영 체제 웹 사이트의 Bash 참조 매뉴얼을 참조하세요.

사용자 데이터로 입력된 스크립트는 루트 사용자 권한으로 실행되므로 스크립트에 sudo 명령을 사용하지 마세요. 생성하는 모든 파일의 소유권은 루트 사용자에게 있습니다. 루트 이외의 사용자에게 파일 액세스를 허용하려면 스크립트에서 권한을 적절히 수정해야 합니다. 또한 스크립트는 대화형으로 실행되지 않으므로 사용자의 입력이 필요한 명령(예: yum update 플래그 없는 -y)은 포함할 수 없습니다.

사용자 데이터 스크립트에서 AWS CLI를 포함한 AWS API를 사용하는 경우 인스턴스를 시작할 때 인스턴스 프로파일을 사용해야 합니다. 인스턴스 프로필은 사용자 데이터 스크립트에서 API 호출을 실행하는 데 필요한 적절한 AWS 자격 증명을 제공합니다. 자세한 내용은 IAM 사용 설명서의 인스턴스 프로파일 사용을 참조하세요. IAM 역할에 할당하는 권한은 API를 사용하여 호출하는 서비스에 따라 다릅니다. 자세한 내용은 Amazon EC2의 IAM 역할 단원을 참조하십시오.

cloud-init 출력 로그 파일이 콘솔 출력을 캡처하므로 시작 후 인스턴스가 의도한 대로 동작하지 않더라도 스크립트를 손쉽게 디버깅할 수 있습니다. 로그 파일을 보려면 인스턴스에 연결하여 /var/log/cloud-init-output.log를 엽니다.

사용자 데이터 스크립트는 처리 시 /var/lib/cloud/instances/instance-id/에서 복사 및 실행됩니다. 스크립트는 실행 후에는 삭제가 되지 않습니다. /var/lib/cloud/instances/instance-id/사용자 데이터를 파싱할 수 있는 스크립트가 AMI 인스턴스에 필요하다고 언급했습니다. 그렇지 않은 경우, 스크립트는 AMI에서 시작된 어떤 인스턴스에서든 이 디렉터리에 존재합니다.

사용자 데이터 및 콘솔

인스턴스를 시작할 때 인스턴스 사용자 데이터를 지정할 수 있습니다. 인스턴스의 루트 볼륨이 EBS 볼륨이면 인스턴스를 중지하고 사용자 데이터를 업데이트할 수도 있습니다.

시작 시 인스턴스 사용자 데이터 지정

인스턴스 시작 절차를 따릅니다. 사용자 데이터(User data) 필드는 인스턴스 시작 마법사의 고급 세부 정보 섹션에 있습니다. 사용자 데이터(User data) 필드에 쉘 스크립트를 입력한 다음 인스턴스 시작 절차를 완료합니다.

이 예제 스크립트는 웹 서버를 생성하고 구성합니다.

#!/bin/bash
yum update -y
amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2
yum install -y httpd mariadb-server
systemctl start httpd
systemctl enable httpd
usermod -a -G apache ec2-user
chown -R ec2-user:apache /var/www
chmod 2775 /var/www
find /var/www -type d -exec chmod 2775 {} \;
find /var/www -type f -exec chmod 0664 {} \;
echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php

인스턴스가 시작되고 스크립트의 명령이 실행되도록 충분한 시간을 허용한 후 스크립트에서 의도된 태스크를 완료했는지 확인합니다.

이 예제의 경우 스크립트가 생성한 PHP 테스트 파일의 URL을 웹 브라우저에 입력합니다. 이 URL은 인스턴스의 퍼블릭 DNS 주소에 슬래시(/)와 파일 이름이 추가된 형태입니다.

http://my.public.dns.amazonaws.com/phpinfo.php

PHP 정보 페이지가 표시되어야 합니다. PHP 정보 페이지가 표시되지 않는 경우 사용하고 있는 보안 그룹이 HTTP(포트 80) 트래픽을 허용하는 규칙을 포함하고 있는지 확인하세요. 자세한 내용은 보안 그룹에 규칙 추가 단원을 참조하십시오.

(선택 사항) 스크립트에서 의도한 작업을 완료하지 못했거나 스크립트가 오류 없이 완료되었는지 여부를 확인하려는 경우 인스턴스에 연결하여 cloud-init 출력 로그 파일(/var/log/cloud-init-output.log)을 조사하고 출력에서 오류 메시지를 찾아 봅니다.

다음 명령을 사용하여 cloud-init 데이터 섹션을 포함하는 Mime 멀티파트 아카이브를 생성하면 자세한 디버깅 정보를 확인할 수 있습니다.

output : { all : '| tee -a /var/log/cloud-init-output.log' }

이 명령은 스크립트의 명령 출력을 /var/log/cloud-init-output.log로 전송합니다. cloud-init 데이터 형식 및 Mime 멀티파트 아카이브를 생성하는 방법에 대한 자세한 내용은 cloud-init 형식을 참조하세요.

인스턴스 사용자 데이터 보기 및 업데이트

인스턴스 사용자 데이터를 업데이트하려면 먼저 인스턴스를 중단해야 합니다. 인스턴스가 실행 중인 경우 사용자 데이터를 볼 수 있지만 수정할 수는 없습니다.

주의

인스턴스를 중지하면 인스턴스 스토어 볼륨의 데이터가 삭제됩니다. 인스턴스 스토어 볼륨의 데이터를 유지하려면 영구 스토리지에 백업하세요.

인스턴스 사용자 데이터를 수정하려면

1. https://console.aws.amazon.com/ec2/에서 Amazon EC2 콘솔을 엽니다.

2. 탐색 창에서 Instances(인스턴스)를 선택합니다.

3. 인스턴스를 선택하고 인스턴스 상태, 인스턴스 중지를 차례로 선택합니다. 이 옵션이 비활성화되어 있으면 해당 인스턴스가 이미 중지되었거나 해당 루트 디바이스가 인스턴스 스토어 볼륨인 것입니다.

4. 확인 메시지가 표시되면 [Stop]을 선택합니다. 인스턴스가 중지하는 데 몇 분 정도 걸릴 수 있습니다.

5. 인스턴스가 선택된 상태에서 작업(Actions), 인스턴스 설정(Instance settings), 사용자 데이터 편집(Edit user data)을 차례로 선택합니다.

6. 필요에 따라 사용자 데이터를 수정한 다음 저장(Save)을 선택합니다.

7. 인스턴스를 시작합니다. 새 사용자 데이터는 인스턴스를 시작한 후에 인스턴스에 표시되지만 사용자 데이터 스크립트가 실행되지는 않습니다.

사용자 데이터 및 cloud-init 명령

cloud-init 패키지는 새 Amazon Linux 인스턴스가 시작될 때의 특정 측면을 구성합니다. 가장 널리 사용되는 기능은 사용자가 자신의 프라이빗 키로 로그인할 수 있도록 ec2-user의 .ssh/authorized_keys 파일을 구성하는 것입니다. cloud-init 패키지가 Amazon Linux 인스턴스에 대해 수행하는 구성 태스크에 대한 자세한 내용은 Amazon Linux 2 사용 설명서의 Amazon Linux 2에서 cloud-init 사용하기를 참조하세요.

cloud-init 사용자 명령을 인스턴스 시작 시에 전달하는 방법은 스크립트를 전달하는 방법과 동일하지만 구문은 서로 다릅니다. cloud-init에 대한 자세한 내용은 http://cloudinit.readthedocs.org/en/latest/index.html을 참조하세요.

중요

기본적으로 사용자 데이터 스크립트 및 cloud-init 명령은 최초로 인스턴스를 시작할 때만 실행됩니다. 인스턴스를 재시작할 때마다 사용자 데이터 스크립트 및 cloud-init 명령이 실행되도록 구성을 업데이트할 수 있습니다. 자세한 내용은 AWS 지식 센터에서 사용자 데이터를 활용하여 Amazon EC2 Linux 인스턴스를 다시 시작할 때마다 스크립트를 자동으로 실행하려면 어떻게 해야 하나요?를 참조하세요.

부팅 시에 이러한 작업을 추가하면 인스턴스 부팅에 걸리는 시간이 그만큼 늘어납니다. 사용자 데이터 명령이 완료되었는지 테스트하려면 우선 작업이 완료될 수 있도록 몇 분의 여유 시간을 두어야 합니다.

인스턴스에 사용자 데이터로 cloud-init 명령을 전달하려면 다음을 수행합니다.

1. 인스턴스 시작 절차를 따릅니다. 사용자 데이터(User data) 필드는 인스턴스 시작 마법사의 고급 세부 정보 섹션에 있습니다. 사용자 데이터(User data) 필드에 cloud-init 지시문 텍스트를 입력한 다음 인스턴스 시작 절차를 완료합니다.

   아래 예제에서는 명령을 통해 Amazon Linux 2에서 웹 서버를 생성하고 구성합니다. 명령을 cloud-init 명령으로 식별하려면 상단에 #cloud-config 행을 추가해야 합니다.

   #cloud-config
   repo_update: true
   repo_upgrade: all
   	
   packages:
   - httpd
   - mariadb-server
   	
   runcmd:
   - [ sh, -c, "amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2" ]
   - systemctl start httpd
   - sudo systemctl enable httpd
   - [ sh, -c, "usermod -a -G apache ec2-user" ]
   - [ sh, -c, "chown -R ec2-user:apache /var/www" ]
   - chmod 2775 /var/www
   - [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ]
   - [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ]
   - [ sh, -c, 'echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php' ]

2. 인스턴스가 시작되고 사용자 데이터의 명령이 실행되도록 충분한 시간을 허용한 후 명령에서 의도된 태스크를 완료했는지 확인합니다.

   이 예제의 경우 명령에서 생성한 PHP 테스트 파일의 URL을 웹 브라우저에 입력합니다. 이 URL은 인스턴스의 퍼블릭 DNS 주소에 슬래시(/)와 파일 이름이 추가된 형태입니다.

   http://my.public.dns.amazonaws.com/phpinfo.php

   PHP 정보 페이지가 표시되어야 합니다. PHP 정보 페이지가 표시되지 않는 경우 사용하고 있는 보안 그룹이 HTTP(포트 80) 트래픽을 허용하는 규칙을 포함하고 있는지 확인하세요. 자세한 내용은 보안 그룹에 규칙 추가 단원을 참조하십시오.

3. (선택 사항) 명령에서 의도한 작업을 완료하지 못했거나 명령이 오류 없이 완료되었는지 여부를 확인하려는 경우 인스턴스에 연결하여 출력 로그 파일(/var/log/cloud-init-output.log)을 조사하고 출력에서 오류 메시지를 찾아 봅니다. 명령에 다음 줄을 추가하면 자세한 디버깅 정보를 확인할 수 있습니다.

   output : { all : '| tee -a /var/log/cloud-init-output.log' }

   이 명령은 runcmd 출력을 /var/log/cloud-init-output.log로 전송합니다.

사용자 데이터 및 AWS CLI

AWS CLI를 사용하여 인스턴스의 사용자 데이터를 지정, 수정 및 확인할 수 있습니다. 인스턴스 메타데이터를 사용하여 인스턴스의 사용자 데이터를 보는 방법에 대한 자세한 내용은 인스턴스에서 인스턴스 사용자 데이터 검색 섹션을 참조하세요.

Windows에서 AWS Tools for Windows PowerShell를 사용하는 대신 AWS CLI을 사용할 수 있습니다. 자세한 정보는 사용자 데이터 및 Tools for Windows PowerShell을 참조하십시오.

예: 시작 시 사용자 데이터 지정

인스턴스를 시작할 때 사용자 데이터를 지정하려면 run-instances 명령을 --user-data 파라미터와 함께 사용합니다. run-instances를 사용하면 AWS CLI에서는 사용자 데이터의 base64 인코딩을 수행합니다.

다음 예에서는 스크립트를 명령줄에서 문자열로 지정하는 방법을 보여줍니다.

aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \
    --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \
    --user-data echo user data

다음 예에서는 텍스트 파일을 사용하여 스크립트를 지정하는 방법을 보여줍니다. file:// 접두사를 사용하여 파일을 지정해야 합니다.

aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \
    --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \
    --user-data file://my_script.txt

다음은 shell 스크립트가 포함된 텍스트 파일의 예입니다.

#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

예: 중지된 인스턴스의 사용자 데이터 수정

modify-instance-attribute 명령을 사용하여 중지된 인스턴스의 사용자 데이터를 수정할 수 있습니다. modify-instance-attribute를 사용하여 AWS CLI는 사용자 데이터의 base64 인코딩을 수행하지 않습니다.

• Linux 컴퓨터에서 base64 명령을 사용하여 사용자 데이터를 인코딩합니다.

  base64 my_script.txt >my_script_base64.txt

• Windows 컴퓨터에서 certutil 명령을 사용하여 사용자 데이터를 인코딩합니다. AWS CLI에서 이 파일을 사용하기 전에 첫 번째(인증서 시작) 줄과 마지막(인증서 종료) 줄을 제거해야 합니다.

  certutil -encode my_script.txt my_script_base64.txt
  notepad my_script_base64.txt

--attribute 및 --value 파라미터를 사용하여 인코딩된 텍스트 파일로 사용자 데이터를 지정합니다. file:// 접두사를 사용하여 파일을 지정해야 합니다.

aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --value file://my_script_base64.txt

예: 중지된 인스턴스의 사용자 데이터 삭제

기존 사용자 데이터를 삭제하려면 다음과 같이 modify-instance-attribute 명령을 사용합니다.

aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --user-data Value=

예: 사용자 데이터 보기

인스턴스의 사용자 데이터를 가져오려면 describe-instance-attribute 명령을 사용합니다. describe-instance-attribute를 사용하여 AWS CLI는 사용자 데이터의 base64 디코딩을 수행하지 않습니다.

aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData

다음은 사용자 데이터 base64가 인코딩된 출력의 예입니다.

{
    "UserData": {
        "Value": "IyEvYmluL2Jhc2gKeXVtIHVwZGF0ZSAteQpzZXJ2aWNlIGh0dHBkIHN0YXJ0CmNoa2NvbmZpZyBodHRwZCBvbg=="
    },
    "InstanceId": "i-1234567890abcdef0"
}

• Linux 컴퓨터에서 --query 옵션을 사용하여 인코딩된 사용자 데이터를 가져오고, base64 명령을 사용하여 이를 디코딩합니다.

  aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" | base64 --decode

• Windows 컴퓨터에서 --query 옵션을 사용하여 코딩된 사용자 데이터를 가져오고, certutil 명령을 사용하여 이를 디코딩합니다. 인코딩된 출력과 디코딩된 출력은 각각 다른 파일에 저장됩니다.

  aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" >my_output.txt
  certutil -decode my_output.txt my_output_decoded.txt
  type my_output_decoded.txt

출력의 예제는 다음과 같습니다.

#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

셸 스크립트와 cloud-init 지시문 결합

기본적으로 사용자 데이터에는 한 번에 하나의 콘텐츠 유형만 포함할 수 있습니다. 그러나 MIME 멀티 파트 파일에서 text/cloud-config 및 text/x-shellscript 콘텐츠 유형을 사용하여 사용자 데이터에 셸 스크립트와 cloud-init 지시문을 모두 포함할 수 있습니다.

다음은 MIME 멀티 파트 형식을 보여줍니다.

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
	
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
	
#cloud-config
cloud-init directives
	
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
	
#!/bin/bash
shell script commands
--//--

예를 들어, 다음 사용자 데이터에는 cloud-init 지시문과 bash 셸 스크립트가 포함됩니다. cloud-init 지시문은 파일(/test-cloudinit/cloud-init.txt)을 생성하고 해당 파일에 Created by cloud-init를 씁니다. bash 셸 스크립트는 파일(/test-userscript/userscript.txt)을 생성하고 해당 파일에 Created by bash shell script를 씁니다.

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
	
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
	
#cloud-config
runcmd:
- [ mkdir, /test-cloudinit ]
write_files:
- path: /test-cloudinit/cloud-init.txt
content: Created by cloud-init
	
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
	
#!/bin/bash
mkdir test-userscript
touch /test-userscript/userscript.txt
echo "Created by bash shell script" >> /test-userscript/userscript.txt
--//--

Amazon EC2가 Windows 인스턴스의 사용자 데이터를 처리하는 방법

Windows 인스턴스에서 운영 체제 버전에 대한 기본 실행 에이전트는 다음과 같이 사용자 데이터를 처리합니다.

• EC2Launch v2는 Windows Server 2022에서 사용자 데이터 스크립트 실행

• EC2Launch는 Windows Server 2016 및 2019에서 사용자 데이터 스크립트 실행

• EC2Config 서비스는 Windows Server 2016 이전 버전에서 사용자 데이터 스크립트를 실행

UserData 템플릿의 AWS CloudFormation 속성 어셈블리 예제는 Base64 인코딩 UserData 속성 및 AccessKey 및 SecretKey를 사용하는 Base64 인코딩 UserData 속성을 참조하세요.

수명 주기 후크와 함께 작동하는 Auto Scaling 그룹 내의 인스턴스에서 명령을 실행하는 예제는 Amazon EC2 Auto Scaling 사용 설명서에서 자습서: 인스턴스 메타데이터를 통해 대상 수명 주기 상태를 검색하도록 사용자 데이터 구성을 참조하세요.

내용

• 사용자 데이터 스크립트
• 사용자 데이터 실행
• 사용자 데이터 및 콘솔
• 사용자 데이터 및 Tools for Windows PowerShell

사용자 데이터 스크립트

EC2Config 또는 EC2Launch에서 스크립트를 실행하려면 사용자 데이터에 추가할 때 해당 스크립트를 특수 태그 안에 포함해야 합니다. 사용하는 태그는 명령 프롬프트 창에서 명령이 실행되는지(배치 명령) 아니면 Windows PowerShell을 사용하는지에 따라 달라집니다.

배치 스크립트와 Windows PowerShell 스크립트를 둘 다 지정할 경우, 인스턴스 사용자 데이터에 나타나는 순서와 관계 없이, 배치 스크립트가 먼저 실행되고 Windows PowerShell 스크립트가 다음에 실행됩니다.

사용자 데이터 스크립트에서 AWS을(를) 포함한 AWS CLI API를 사용하는 경우 인스턴스를 시작할 때 인스턴스 프로파일을 사용해야 합니다. 인스턴스 프로필은 사용자 데이터 스크립트에서 API 호출을 실행하는 데 필요한 적절한 AWS 자격 증명을 제공합니다. 자세한 내용은 인스턴스 프로파일 섹션을 참조하세요. IAM 역할에 할당하는 권한은 API를 사용하여 호출하는 서비스에 따라 다릅니다. 자세한 내용은 Amazon EC2의 IAM 역할 단원을 참조하십시오.

스크립트 유형

• 배치 스크립트 구문
• Windows PowerShell 스크립트 구문
• YAML 구성 스크립트 구문
• Base64 인코딩

배치 스크립트 구문

script 태그를 사용하여 배치 스크립트를 지정합니다. 다음 예제와 같이 줄 바꿈을 사용하여 명령을 구분합니다.

<script>
    echo Current date and time >> %SystemRoot%\Temp\test.log
    echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>

기본적으로 사용자 데이터 스크립트는 인스턴스를 시작할 때 한 번만 실행됩니다. 인스턴스를 재부팅하거나 시작할 때마다 사용자 데이터 스크립트를 실행하려면 <persist>true</persist>를 사용자 데이터에 추가합니다.

<script>
    echo Current date and time >> %SystemRoot%\Temp\test.log
    echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>
<persist>true</persist>

EC2Launch v2 에이전트

UserData 단계에서 EC2Launch v2 executeScript 태스크와 함께 XML 사용자 데이터 스크립트를 분리된 프로세스로 실행하려면 사용자 데이터에 <detach>true</detach>를 추가하세요.

참고

detach 태그는 이전 시작 에이전트에서 지원되지 않습니다.

<script>
    echo Current date and time >> %SystemRoot%\Temp\test.log
    echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>
<detach>true</detach>

Windows PowerShell 스크립트 구문

AWS Windows AMI에는 AWS Tools for Windows PowerShell이(가) 포함되어 있으므로 사용자 데이터에서 이러한 cmdlet을 지정할 수 있습니다. IAM 역할을 인스턴스와 연결하는 경우, 인스턴스에서 실행되는 애플리케이션이 역할의 자격 증명을 사용하여 AWS 리소스(예: Amazon S3 버킷 등)에 액세스할 수 있기 때문에 cmdlet에 대한 자격 증명을 지정할 필요가 없습니다.

<powershell> 태그를 사용하여 Windows PowerShell 스크립트를 지정합니다. 줄 바꿈을 사용하여 명령을 구분합니다. <powershell> 태그는 대/소문자를 구분합니다.

예:

<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>

기본적으로 사용자 데이터 스크립트는 인스턴스를 시작할 때 한 번만 실행됩니다. 인스턴스를 재부팅하거나 시작할 때마다 사용자 데이터 스크립트를 실행하려면 <persist>true</persist>를 사용자 데이터에 추가합니다.

<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<persist>true</persist>

<powershellArguments> 태그를 사용하여 하나 이상의 PowerShell 인수를 지정할 수 있습니다. 인수가 전달되지 않는 경우 EC2Launch 및 EC2Launch v2는 기본적으로 -ExecutionPolicy Unrestricted 인수를 추가합니다.

예:

<powershell>
    $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<powershellArguments>-ExecutionPolicy Unrestricted -NoProfile -NonInteractive</powershellArguments>

EC2Launch v2 에이전트

UserData 단계에서 EC2Launch v2 executeScript 태스크와 함께 XML 사용자 데이터 스크립트를 분리된 프로세스로 실행하려면 사용자 데이터에 <detach>true</detach>를 추가하세요.

참고

detach 태그는 이전 시작 에이전트에서 지원되지 않습니다.

<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<detach>true</detach>

YAML 구성 스크립트 구문

EC2Launch v2를 사용하여 스크립트를 실행하는 경우 YAML 형식을 사용할 수 있습니다. EC2Launch v2에 대한 구성 작업, 세부 정보 및 예제를 보려면 EC2Launch v2 태스크 구성 섹션을 참조하세요.

executeScript 작업을 통해 YAML 스크립트를 지정합니다.

PowerShell 스크립트를 실행하는 YAML 구문 예제

version: 1.0
    tasks:
    - task: executeScript
      inputs:
      - frequency: always
        type: powershell
        runAs: localSystem
        content: |-
          $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
          New-Item $file -ItemType file

배치 스크립트를 실행하는 YAML 구문 예제

version: 1.1
    tasks:
    - task: executeScript
      inputs:
      - frequency: always
        type: batch
        runAs: localSystem
        content: |-
          echo Current date and time >> %SystemRoot%\Temp\test.log
          echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log

Base64 인코딩

Amazon EC2 API 또는 사용자 데이터의 base64 인코딩을 수행하지 않는 도구를 사용하는 경우, 직접 사용자 데이터를 인코딩해야 합니다. 그렇지 않을 경우, 실행할 script 또는 powershell 태그를 찾을 수 없다는 오류가 기록됩니다. 다음은 Windows PowerShell을 사용하여 인코딩하는 예제입니다.

$UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

다음은 PowerShell을 사용하여 디코딩하는 예제입니다.

$Script = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData))

base64 인코딩에 대한 자세한 내용은 https://www.ietf.org/rfc/rfc4648.txt을 참조하세요.

사용자 데이터 실행

기본적으로 모든 AWS Windows AMI는 초기 실행에 대해 활성화되는 사용자 데이터 실행 기능을 포함하고 있습니다. 다음 번에 인스턴스가 재부팅하거나 재시작할 때 사용자 데이터 스크립트가 실행되도록 지정할 수 있습니다. 또는 인스턴스가 재부팅하거나 재시작할 때마다 사용자 데이터 스크립트가 실행되도록 지정할 수도 있습니다.

참고

초기 실행 후에는 사용자 데이터가 기본적으로 실행되도록 설정되어 있지 않습니다. 인스턴스를 재부팅하거나 시작할 때 사용자 데이터가 실행되도록 설정하려면 이후 재부팅 또는 시작 섹션을 참조하세요.

사용자 데이터 스크립트는 임의 암호가 생성될 때 로컬 관리자 계정에서 실행됩니다. 그렇지 않으면 사용자 데이터 스크립트가 시스템 계정에서 실행됩니다.

인스턴스 시작

인스턴스 사용자 데이터의 스크립트는 인스턴스 초기 시작 중에 실행됩니다. persist 태그가 있는 경우 사용자 데이터 실행이 후속 재부팅이나 시작에 대해 활성화됩니다. EC2Launch v2, EC2Launch 및 EC2Config용 로그 파일에는 표준 출력 및 표준 오류 스트림의 출력이 들어 있습니다.

EC2Launch v2

EC2Launch v2의 로그 파일은 C:\ProgramData\Amazon\EC2Launch\log\agent.log입니다.

참고

C:\ProgramData 폴더를 숨길 수 있습니다. 폴더를 보려면 숨겨진 파일과 폴더를 표시해야 합니다.

다음 정보는 사용자 데이터가 실행될 때 로깅됩니다.

• Info: Converting user-data to yaml format - 사용자 데이터가 XML 형식으로 제공된 경우

• Info: Initialize user-data state - 사용자 데이터 실행의 시작

• Info: Frequency is: always - 부팅할 때마다 사용자 데이터 태스크가 실행되는 경우

• Info: Frequency is: once - 사용자 데이터 태스크가 한 번만 실행되는 경우

• Stage: postReadyUserData execution completed - 사용자 데이터 실행의 끝

EC2Launch

EC2Launch에 대한 로그 파일은 C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log입니다.

C:\ProgramData 폴더를 숨길 수 있습니다. 폴더를 보려면 숨겨진 파일과 폴더를 표시해야 합니다.

다음 정보는 사용자 데이터가 실행될 때 로깅됩니다.

• Userdata execution begins - 사용자 데이터 실행의 시작

• <persist> tag was provided: true - persist 태그가 있는 경우

• Running userdata on every boot - persist 태그가 있는 경우

• <powershell> tag was provided.. running powershell content - powershell 태그가 있는 경우

• <script> tag was provided.. running script content - script 태그가 있는 경우

• Message: The output from user scripts - 사용자 데이터 스크립트가 실행되는 경우 해당 출력이 로깅됨

EC2Config

EC2Config의 로그 파일은 C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log입니다. 다음 정보는 사용자 데이터가 실행될 때 로깅됩니다.

• Ec2HandleUserData: Message: Start running user scripts - 사용자 데이터 실행의 시작

• Ec2HandleUserData: Message: Re-enabled userdata execution - persist 태그가 있는 경우

• Ec2HandleUserData: Message: Could not find <persist> and </persist> - persist 태그가 없는 경우

• Ec2HandleUserData: Message: The output from user scripts - 사용자 데이터 스크립트가 실행되는 경우 해당 출력이 로깅됨

이후 재부팅 또는 시작

인스턴스 사용자 데이터를 업데이트하는 경우 인스턴스를 재부팅하거나 시작할 때 사용자 데이터 스크립트가 자동으로 실행되지 않습니다. 하지만 인스턴스를 재부팅하거나 시작할 때 한 번만 또는 인스턴스를 재부팅하거나 시작할 때마다 사용자 데이터 스크립트가 실행되도록 사용자 데이터 실행을 활성화할 수 있습니다.

[Sysprep으로 종료(Shutdown with Sysprep)] 옵션을 선택하는 경우 이후 재부팅이나 시작에 대해 사용자 데이터 실행을 활성화하지 않았더라도 다음에 인스턴스가 재부팅되거나 시작될 때 사용자 데이터 스크립트가 실행됩니다. 사용자 데이터 스크립트는 이후 재부팅 또는 시작 시 실행되지 않습니다.

EC2Launch v2를 사용하여 사용자 데이터 실행을 활성화하려면(미리 보기 AMI)

• 처음 부팅할 때 사용자 데이터에서 작업을 실행하려면 frequency를 once로 설정합니다.

• 부팅할 때마다 사용자 데이터에서 작업을 실행하려면 frequency를 always로 설정합니다.

EC2Launch를 사용하여 사용자 데이터 실행을 활성화하려면(Windows Server 2016 이상)

1. Windows 인스턴스에 연결합니다.

2. PowerShell 명령 창을 열고 다음 명령을 실행합니다.

   C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -Schedule

3. Windows 인스턴스에서 연결을 해제합니다. 다음 번에 인스턴스가 시작될 때 업데이트된 스크립트를 실행하려면 인스턴스를 중지하고 사용자 데이터를 업데이트합니다.

EC2Config를 사용하여 사용자 데이터 실행을 활성화하려면(Windows Server 2012 R2 이하)

1. Windows 인스턴스에 연결합니다.

2. Open C:\Program Files\Amazon\Ec2ConfigService\Ec2ConfigServiceSetting.exe.

3. 사용자 데이터에서 Enable UserData execution for next service start(다음 서비스 시작 시 사용자 데이터 실행 활성화)를 선택합니다.

4. Windows 인스턴스에서 연결을 해제합니다. 다음 번에 인스턴스가 시작될 때 업데이트된 스크립트를 실행하려면 인스턴스를 중지하고 사용자 데이터를 업데이트합니다.

사용자 데이터 및 콘솔

인스턴스를 시작할 때 인스턴스 사용자 데이터를 지정할 수 있습니다. 인스턴스의 루트 볼륨이 EBS 볼륨이면 인스턴스를 중지하고 사용자 데이터를 업데이트할 수도 있습니다.

시작 시 인스턴스 사용자 데이터 지정

인스턴스 시작 절차를 따릅니다. 사용자 데이터(User data) 필드는 인스턴스 시작 마법사의 고급 세부 정보 섹션에 있습니다. 사용자 데이터 필드에 PowerShell 스크립트를 입력한 다음 인스턴스 시작 절차를 완료합니다.

다음 사용자 데이터 필드 스크린샷의 예제 스크립트는 파일 이름에 현재 날짜 및 시간을 사용하여 Windows 임시 폴더에 파일을 생성합니다. <persist>true</persist>를 포함할 경우 인스턴스를 재부팅하거나 시작할 때마다 스크립트가 실행됩니다. 사용자 데이터가 이미 base64로 인코딩됨 확인란을 비워 두면 Amazon EC2 콘솔이 base64 인코딩을 수행합니다.

인스턴스 사용자 데이터 보기 및 업데이트

모든 인스턴스의 인스턴스 사용자 데이터를 볼 수 있으며, 중지된 인스턴스의 인스턴스 사용자 데이터를 업데이트할 수 있습니다.

콘솔을 사용하여 인스턴스의 사용자 데이터를 업데이트하려면

1. https://console.aws.amazon.com/ec2/에서 Amazon EC2 콘솔을 엽니다.

2. 탐색 창에서 Instances(인스턴스)를 선택합니다.

3. 인스턴스를 선택하고 작업, 인스턴스 상태, 인스턴스 중지를 차례로 선택합니다.

   주의

   인스턴스를 중지하면 인스턴스 스토어 볼륨의 데이터가 삭제됩니다. 인스턴스 스토어 볼륨의 데이터를 유지하려면 영구 스토리지에 백업하세요.

4. 확인 메시지가 표시되면 [Stop]을 선택합니다. 인스턴스가 중지하는 데 몇 분 정도 걸릴 수 있습니다.

5. 인스턴스가 선택된 상태에서 작업(Actions), 인스턴스 설정(Instance settings), 사용자 데이터 편집(Edit user data)을 차례로 선택합니다. 인스턴스가 실행 중일 때는 사용자 데이터를 변경할 수 없습니다. 하지만 볼 수는 있습니다.

6. [사용자 데이터 편집(Edit user data)] 대화 상자에서 사용자 데이터를 업데이트하고 [저장(Save)]을 선택합니다. 매번 인스턴스를 재부팅하거나 시작할 때마다 사용자 데이터 스크립트를 실행하려면 다음 예제와 같이 <persist>true</persist>를 추가합니다.

   

7. 인스턴스를 시작합니다. 이후의 재부팅 또는 시작에 대해 사용자 데이터 실행을 활성화한 경우 인스턴스 시작 프로세스의 일부로서 업데이트된 사용자 데이터 스크립트가 실행됩니다.

사용자 데이터 및 Tools for Windows PowerShell

Tools for Windows PowerShell을 사용하여 인스턴스의 사용자 데이터를 지정, 수정 및 확인할 수 있습니다. 인스턴스 메타데이터를 사용하여 인스턴스의 사용자 데이터를 보는 방법에 대한 자세한 내용은 인스턴스에서 인스턴스 사용자 데이터 검색 섹션을 참조하세요. 사용자 데이터 및 AWS CLI에 대한 자세한 내용은 사용자 데이터 및 AWS CLI 섹션을 참조하세요.

예시: 시작 시 인스턴스 사용자 데이터 지정

인스턴스 사용자 데이터를 포함하는 텍스트 파일을 생성합니다. 매번 인스턴스를 재부팅하거나 시작할 때마다 사용자 데이터 스크립트를 실행하려면 다음 예제와 같이 <persist>true</persist>를 추가합니다.

<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<persist>true</persist>

인스턴스를 시작할 때 인스턴스 사용자 데이터를 지정하려면 New-EC2Instance 명령을 사용합니다. 이 명령은 사용자 데이터의 base64 인코딩을 수행하지 않습니다. 다음 명령을 사용하여 사용자 데이터를 script.txt 이름의 텍스트 파일로 인코딩합니다.

PS C:\> $Script = Get-Content -Raw script.txt
PS C:\> $UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

-UserData 파라미터를 사용하여 사용자 데이터를 New-EC2Instance 명령으로 전달합니다.

PS C:\> New-EC2Instance -ImageId ami-abcd1234 -MinCount 1 -MaxCount 1 -InstanceType m3.medium \
    -KeyName my-key-pair -SubnetId subnet-12345678 -SecurityGroupIds sg-1a2b3c4d \
    -UserData $UserData

예시: 중지된 인스턴스에 대한 인스턴스 사용자 데이터 업데이트

Edit-EC2InstanceAttribute 명령을 사용하여 중지된 인스턴스의 사용자 데이터를 수정할 수 있습니다.

새 스크립트를 포함하는 텍스트 파일을 생성합니다. 다음 명령을 사용하여 사용자 데이터를 new-script.txt 이름의 텍스트 파일로 인코딩합니다.

PS C:\> $NewScript = Get-Content -Raw new-script.txt
PS C:\> $NewUserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($NewScript))

-UserData 및 -Value 파라미터를 사용하여 사용자 데이터를 지정합니다.

PS C:\> Edit-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData -Value $NewUserData

예시: 인스턴스 사용자 데이터 보기

인스턴스의 사용자 데이터를 가져오려면 Get-EC2InstanceAttribute 명령을 사용합니다.

PS C:\> (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData

다음은 예시 출력입니다. 사용자 데이터가 인코딩됩니다.

PHBvd2Vyc2hlbGw+DQpSZW5hbWUtQ29tcHV0ZXIgLU5ld05hbWUgdXNlci1kYXRhLXRlc3QNCjwvcG93ZXJzaGVsbD4=

다음 명령을 사용하여 인코딩된 사용자 데이터를 변수에 저장한 다음 디코딩합니다.

PS C:\> $UserData_encoded = (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData
PS C:\> [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData_encoded))

다음은 예시 출력입니다.

<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<persist>true</persist>

예시: 태그 값과 일치하도록 인스턴스의 이름 바꾸기

Get-EC2Tag 명령을 사용하여 태그 값을 읽고 처음 부팅할 때 태그 값과 일치하도록 인스턴스 이름을 바꾼 다음 재부팅할 수 있습니다. 이 명령을 성공적으로 실행하려면 API 호출로 태그 정보를 가져오기 때문에 인스턴스에 ec2:DescribeTags 권한이 연결된 역할이 있어야 합니다. IAM 역할을 사용하여 권한을 설정하는 방법에 대한 자세한 내용은 IAM 역할을 인스턴스에 연결 섹션을 참조하세요.

<powershell>
	$instanceId = (invoke-webrequest http://169.254.169.254/latest/meta-data/instance-id -UseBasicParsing).content
	$nameValue = (get-ec2tag -filter @{Name="resource-id";Value=$instanceid},@{Name="key";Value="Name"}).Value
	$pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$"
	#Verify Name Value satisfies best practices for Windows hostnames
	If ($nameValue -match $pattern) 
	    {Try
	        {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} 
	    Catch
	        {$ErrorMessage = $_.Exception.Message
	        Write-Output "Rename failed: $ErrorMessage"}}
	Else
	    {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"}
</powershell>

인스턴스가 인스턴스 메타데이터의 태그에 액세스하도록 구성된 경우 인스턴스 메타데이터의 태그를 사용하여 인스턴스 이름을 바꿀 수도 있습니다. 자세한 내용은 인스턴스 메타데이터의 인스턴스 태그 작업 단원을 참조하십시오.

<powershell>
	$nameValue = Get-EC2InstanceMetadata -Path /tags/instance/Name
	$pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$"
	#Verify Name Value satisfies best practices for Windows hostnames
	If ($nameValue -match $pattern) 
	    {Try
	        {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} 
	    Catch
	        {$ErrorMessage = $_.Exception.Message
	        Write-Output "Rename failed: $ErrorMessage"}}
	Else
	    {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"}
</powershell>