How do I enable Docker debug mode with user data when I boot AMIs optimized for Amazon ECS?
Last updated: 2019-04-26
I need to troubleshoot an issue with an Amazon Elastic Container Service (Amazon ECS) container instance right after it boots. How do I enable Docker debug mode with user data when I boot Amazon Machine Images (AMIs) optimized for Amazon ECS?
Configuring an Amazon Elastic Compute Cloud (Amazon EC2) instance at instance boot is typically performed with a script in Amazon EC2 user data. This script is executed by cloud-init concurrently with other services launching. For more information, see User-Data Formats in the cloud-init documentation. Cloud-init provides a mechanism called "cloud boothooks" to run scripts that must complete before the execution of user data and the launch of services. For more information, see Cloud Boothook in the cloud-init documentation. You can use this mechanism to ensure that the Docker daemon configuration is in place before the Docker daemon service starts.
Before you begin, consider the following:
- Start troubleshooting immediately after your container instance boots.
- Don't add a script to modify the OPTIONS variable because restarting the Docker daemon can interfere with the startup, registration, or storage setup process of the instance or create a race condition.
Enable Docker debug mode
1. Update your Docker daemon configuration file at /etc/sysconfig/docker using a cloud boothook. For more information, see Cloud Boothook in the cloud-init documentation.
2. To enable Docker debug mode before the Docker daemon starts, add the -D flag to the OPTIONS variable in /etc/sysconfig/docker. Use the cloud-init-per utility to get the cloud boothook to run only once. See the following example:
#cloud-boothook #!/bin/bash cloud-init-per once docker_debug echo 'OPTIONS="-D"' >> /etc/sysconfig/docker
Pass existing user data with a cloud boothook
1. Encapsulate both the boothook and user data using a MIME multi-part file.
2. Concatenate the encapsulated data.
3. Pass the concatenated data to the Amazon EC2 instance.
Note: To create mime-multipart files, use the write-mime-multipart utility. This utility is not installed by default, but it is included as part of the cloud-utils package on distributions based on Debian and RHEL. For more information, see the write-mime-multipart entry in the Ubuntu documentation.
See the following example:
Content-Type: multipart/mixed; boundary="==BOUNDARY==" MIME-Version: 1.0 --==BOUNDARY== Content-Type: text/cloud-boothook; charset="us-ascii" #!/bin/bash # Set Docker daemon options cloud-init-per once docker_debug echo 'OPTIONS="-D"' >> /etc/sysconfig/docker --==BOUNDARY== Content-Type: text/x-shellscript; charset="us-ascii" #!/bin/bash # Set any ECS agent configuration options cat >> /etc/ecs/ecs.config <<EOF ECS_CLUSTER=my-ecs-cluster ECS_LOGLEVEL=debug EOF --==BOUNDARY==--