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?

Short Description

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.

Resolution

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==--

Docker Basics for Amazon ECS

Did this article help you?

Yes
No

Anything we could improve?

Let us know

Need more help?

Contact AWS Support