cocos/hal/cloud/README.md

Agent Cloud Init Setup

Overview

The hal/cloud directory contains essential files required for setting up a virtual machine (VM) with cloud-init. This setup ensures the automated installation of dependencies, configuration of the environment, and deployment of the Cocos agent as a systemd service.

Directory Contents

• config.yaml: This YAML file provides configuration instructions for the cloud image.
• meta-data: Contains VM metadata, such as instance-specific details and identifiers.
• qemu.sh: A Bash script for downloading and configuring a cloud image, running QEMU to simulate a VM with the cloud-init configuration.
• .env: Contains environment variables for starting the VM in different modes, configuring disk space, memory allocation, and other parameters.

Configuration

Preparing the Cloud-Config File

The config.yaml file defines system configurations, including user creation, package installations, file management, and command execution. Ensure that the cloud-config file is set up with the following configurations:

• User Credentials: Specify the default username and password.
• Certificates and Keys: Certificate files for agent for secure communication.
• Environment Variables: Configuration parameters required by the system.

The config.yaml file is divided into multiple sections, each addressing a specific aspect of the setup process.

1. User Configuration

This section creates a default user with specific permissions and configurations:

• Creates a user named cocos_user.
• Adds cocos_user to the sudo and docker groups.
• Sets a default password (should be changed for production use).
• Configures the user’s shell as /bin/bash.

2. Package Installation

Installs essential system packages required for various operations:

• curl: For downloading files from the web.
• make: A utility for building software.
• git: Version control system for managing code repositories.
• python3 and python3-dev: Required for running Python-based tools.
• net-tools: Provides networking utilities such as ifconfig and route.

3. File Management (write_files)

Creates and configures critical files required for the setup:

• Certificates: Cert files (cert.pem, ca.pem, key.pem) located at /etc/cocos/certs/.
• Environment Variables: An env file stored at /etc/cocos/environment.
• Systemd Service File: Cocos agent service configuration file at /etc/systemd/system/cocos-agent.service for managing the Cocos agent.
• Agent Scripts:
  • agent_setup.sh: Configures network interfaces and resizes the root filesystem.
  • agent_start_script.sh: Sets up Docker and starts the Cocos agent.

4. Execution of Commands (runcmd)

A sequence of commands is executed to finalize the setup:

• Creates necessary directories: /cocos, /cocos_init, /var/log/cocos, /etc/cocos.
• Downloads and installs the Cocos agent binary.
• Installs Wasmtime and configures its environment variables.
• Installs Docker and adds cocos_user to the Docker group.
• Reloads systemd and enables the Cocos agent service.

Running the Agent

To test the cloud-init configuration, execute the qemu.sh script to bring up a VM using QEMU:

sudo ./qemu.sh

Important: The script must be executed as root.

Once the QEMU boots the VM, the Cocos agent will run as a systemd service. The service is configured to start automatically on boot and restart in case of failure.

Debugging and Monitoring

For troubleshooting and monitoring the Cocos agent service, use the following commands within the VM:

Manually Start the Service

To manually start the agent service, execute:

sudo systemctl start cocos-agent.service

Verify Service Status

To check if the service is running properly, use:

sudo systemctl status cocos-agent.service

View Service Logs

To inspect logs generated by the agent service, execute:

journalctl -u cocos-agent.service

Check Standard Output and Error Logs

To check logs stored in the system, use:

cat /var/log/cocos/agent.stdout.log
cat /var/log/cocos/agent.stderr.log