Skip to content

Commit 21b2f3b

Browse files
josecelanojosecelano
committed
docs: complete phase B.1 docker container research
- Add comprehensive research document at docs/research/e2e-docker-config-testing.md - Document Docker container approach for E2E configuration testing - Analyze Ubuntu 24.04 base image strategy with SSH and systemd setup - Research testcontainers-rs integration vs direct Docker CLI approach - Document network configuration requirements for Ansible connectivity - Include references to Docker-in-VM testing research repository - Update split-e2e-tests plan to mark B.1 as completed with results summary The research establishes foundation for implementing Docker-based configuration testing to replace LXD VMs and resolve network connectivity issues in GitHub Actions.
1 parent 4a691e2 commit 21b2f3b

File tree

2 files changed

+225
-2
lines changed

2 files changed

+225
-2
lines changed

‎docs/refactors/split-e2e-tests-provision-vs-configuration.md‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ Split the E2E testing into two independent test suites:
105105

106106
#### Phase A Results Summary
107107

108-
✅ **Successfully Completed** (December 2024)
108+
✅ **Successfully Completed** (September 2025)
109109

110110
**Implementation Details:**
111111

@@ -132,14 +132,42 @@ Split the E2E testing into two independent test suites:
132132

133133
#### B.1: Research Docker container approach
134134

135-
- [ ] **Task**: Design Docker-based test environment
135+
- [x] **Task**: Design Docker-based test environment
136136
- **Reference**: Use proven approach from [virtualization support research](https://github.com/josecelano/github-actions-virtualization-support)
137+
- **Additional Reference**: [Docker-in-VM testing](https://github.com/josecelano/test-docker-install-inside-vm-in-runner) - Research on Docker installation within VMs documenting network connectivity issues
137138
- Create Ubuntu 24.04 base container configuration
138139
- Investigate cloud-init support in Docker (or alternative initialization)
139140
- Research testcontainers integration for Rust
140141
- Document container networking requirements for Ansible
142+
- **Research Documentation**: See `docs/research/e2e-docker-config-testing.md` for detailed analysis
141143
- **Advantage**: Docker is well-established and reliable on GitHub Actions
142144

145+
#### B.1 Results Summary
146+
147+
✅ **Successfully Completed** (September 2025)
148+
149+
**Implementation Details:**
150+
151+
- Created comprehensive research document at `docs/research/e2e-docker-config-testing.md`
152+
- Documented Docker container requirements for Ansible testing
153+
- Analyzed Ubuntu 24.04 base image strategy with SSH server and systemd configuration
154+
- Researched cloud-init alternatives for container initialization
155+
- Evaluated testcontainers-rs integration options vs direct Docker CLI approach
156+
- Documented network configuration requirements for Ansible connectivity
157+
158+
**Key Findings:**
159+
160+
- Docker containers are well-established and reliable on GitHub Actions (no nested virtualization issues)
161+
- Need systemd-in-Docker configuration for service management (Docker daemon, etc.)
162+
- SSH server setup required for Ansible connectivity with proper user/sudo access
163+
- Testcontainers-rs provides good integration options but direct Docker CLI is simpler for initial implementation
164+
- Container networking provides consistent internet access for package downloads
165+
166+
**Research References:**
167+
168+
- [Virtualization Support Research](https://github.com/josecelano/github-actions-virtualization-support) - Comprehensive virtualization tools testing
169+
- [Docker-in-VM Testing](https://github.com/josecelano/test-docker-install-inside-vm-in-runner) - Specific network connectivity issue documentation
170+
143171
#### B.2: Create Docker configuration
144172

145173
- [ ] **Task**: Create `docker/test-ubuntu/Dockerfile`

‎docs/research/e2e-docker-config-testing.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# E2E Configuration Testing with Docker Containers
2+
3+
## Executive Summary
4+
5+
For Phase B.1 of the E2E test split, this document outlines the research findings and approach for implementing Docker container-based configuration testing to replace LXD VM-based testing for the configuration, release, and run phases.
6+
7+
## Background & Problem Statement
8+
9+
- **Current Issue**: LXD VMs work for provisioning but fail during configuration phase due to network connectivity issues within VMs on GitHub Actions runners
10+
- **Root Cause**: GitHub Actions runners are themselves VMs, creating nested virtualization issues that prevent network connectivity required for software installation
11+
- **Solution**: Split testing into provision (LXD VMs) and configuration (Docker containers) phases
12+
13+
## Configuration Testing Requirements
14+
15+
Based on analysis of the current E2E workflow, the configuration tests need to validate:
16+
17+
### 1. Software Installation (Configure Phase)
18+
19+
- **Docker Installation**: Via Ansible playbook `install-docker.yml`
20+
- **Docker Compose Installation**: Via Ansible playbook `install-docker-compose.yml`
21+
- **APT Cache Updates**: Via `update-apt-cache.yml`
22+
- **Network connectivity**: For package downloads
23+
24+
### 2. Infrastructure Validation (Test Phase)
25+
26+
- **Cloud-init completion**: Verify initialization completed
27+
- **Docker service**: Verify Docker daemon is running
28+
- **Docker Compose**: Verify Docker Compose binary is functional
29+
- **SSH connectivity**: Ensure Ansible can connect and execute commands
30+
31+
### 3. Current Ansible Workflow Integration
32+
33+
- **Inventory management**: Dynamic inventory generation with container IP
34+
- **SSH-based execution**: Ansible connects via SSH to execute playbooks
35+
- **Privilege escalation**: Requires `sudo` access within container
36+
- **Ubuntu 24.04 target**: Current templates target Ubuntu 24.04 LTS
37+
38+
## Docker Container Approach
39+
40+
### Container Requirements
41+
42+
1. **Base Image**: Ubuntu 24.04 LTS (to match current VM environment)
43+
2. **SSH Server**: OpenSSH server for Ansible connectivity
44+
3. **Systemd**: For service management (Docker daemon, etc.)
45+
4. **Sudo Access**: For privilege escalation during software installation
46+
5. **Network Access**: For package downloads and installations
47+
6. **Init System**: Alternative to cloud-init for container initialization
48+
49+
### Container Configuration Strategy
50+
51+
#### Option 1: Custom Dockerfile (Recommended)
52+
53+
- **Base**: `ubuntu:24.04`
54+
- **SSH Setup**: Install and configure OpenSSH server
55+
- **Systemd**: Enable systemd for service management
56+
- **User Setup**: Create user with sudo access
57+
- **Network**: Default Docker networking (sufficient for GitHub Actions)
58+
59+
#### Option 2: Pre-built Image with SSH
60+
61+
- **Base**: Existing Ubuntu images with SSH enabled
62+
- **Pros**: Faster setup, less maintenance
63+
- **Cons**: Less control, may not match exact VM environment
64+
65+
### Cloud-init Alternative
66+
67+
Since cloud-init is VM-specific, containers need alternative initialization:
68+
69+
1. **Container Init Scripts**: Custom initialization via entrypoint script
70+
2. **SSH Key Injection**: Mount SSH keys via Docker volumes or copy
71+
3. **User Provisioning**: Direct user/key setup instead of cloud-init
72+
4. **Service Initialization**: Direct systemd service management
73+
74+
## Research References
75+
76+
### Docker-in-VM Testing Research
77+
78+
- **[Virtualization Support Research](https://github.com/josecelano/github-actions-virtualization-support)**: Comprehensive testing of virtualization tools on GitHub Actions, demonstrating Docker feasibility
79+
- **[Docker-in-VM Test Repository](https://github.com/josecelano/test-docker-install-inside-vm-in-runner)**: Specific research on Docker installation within VMs on GitHub Actions runners, documenting the network connectivity issues
80+
81+
### Related Issues
82+
83+
- **[GitHub Actions Runner Images Issue #13003](https://github.com/actions/runner-images/issues/13003)**: Network connectivity issues with LXD VMs on GitHub runners
84+
- **[Original Virtualization Investigation](https://github.com/actions/runner-images/issues/12933)**: Background context on GitHub Actions virtualization support
85+
86+
## Testcontainers Integration Analysis
87+
88+
### Benefits of testcontainers-rs
89+
90+
- **Container Lifecycle Management**: Automatic startup/cleanup
91+
- **Network Management**: Automatic port mapping and network configuration
92+
- **Integration**: Well-integrated with Rust testing ecosystem
93+
- **Parallel Testing**: Multiple containers can run in parallel
94+
95+
### Implementation Approach
96+
97+
- **Generic Image**: Use `testcontainers::GenericImage` for Ubuntu container
98+
- **Custom Configuration**: Configure SSH, systemd, and networking
99+
- **Volume Mounting**: SSH keys and test artifacts
100+
- **Port Mapping**: SSH port (22) mapping for Ansible connectivity
101+
102+
### Alternative: Direct Docker CLI
103+
104+
- **Simpler Setup**: Direct `docker run` commands
105+
- **Less Dependencies**: No additional crates required
106+
- **Manual Management**: Explicit container lifecycle management
107+
- **More Control**: Direct control over Docker operations
108+
109+
## Network Configuration
110+
111+
### Ansible Connectivity Requirements
112+
113+
1. **SSH Access**: Container must accept SSH connections
114+
2. **Port Mapping**: Map container SSH port to host
115+
3. **IP Address**: Deterministic container IP for Ansible inventory
116+
4. **DNS Resolution**: Container must resolve package repositories
117+
118+
### GitHub Actions Networking
119+
120+
- **Docker Networking**: Works reliably on GitHub Actions
121+
- **Port Mapping**: Standard Docker port mapping supported
122+
- **Internet Access**: Containers have internet access for package downloads
123+
- **No Nested Virtualization**: Avoids the LXD VM networking issues
124+
125+
## Implementation Plan Summary
126+
127+
### Phase B.1 Deliverables
128+
129+
1. **Docker Configuration**: Create `docker/test-ubuntu/Dockerfile`
130+
2. **Container Setup**: Ubuntu 24.04 with SSH, systemd, sudo user
131+
3. **Integration Strategy**: Document testcontainers vs direct Docker approach
132+
4. **Network Requirements**: Document Ansible connectivity requirements
133+
5. **Cloud-init Alternative**: Design container initialization approach
134+
135+
### Next Steps (B.2+)
136+
137+
1. **Docker Implementation**: Build and test Docker configuration
138+
2. **Binary Creation**: Implement `e2e-config-tests` binary
139+
3. **Container Management**: Integrate container lifecycle with tests
140+
4. **Local Testing**: Validate complete workflow locally
141+
5. **CI Integration**: Create GitHub Actions workflow
142+
143+
## Technical Architecture
144+
145+
```text
146+
┌─────────────────────────────────────────────────────────┐
147+
│ GitHub Actions Runner │
148+
│ ┌─────────────────────────────────────────────────────┐│
149+
│ │ e2e-config-tests binary ││
150+
│ │ ┌─────────────────────────────────────────────────┐ ││
151+
│ │ │ Docker Container │ ││
152+
│ │ │ ┌─────────────────────────────────────────────┐ │ ││
153+
│ │ │ │ Ubuntu 24.04 LTS │ │ ││
154+
│ │ │ │ - SSH Server (port 22) │ │ ││
155+
│ │ │ │ - Systemd (service management) │ │ ││
156+
│ │ │ │ - Sudo user (ansible connectivity) │ │ ││
157+
│ │ │ │ - Package management (apt) │ │ ││
158+
│ │ │ └─────────────────────────────────────────────┘ │ ││
159+
│ │ └─────────────────────────────────────────────────┘ ││
160+
│ │ ▲ ││
161+
│ │ │ SSH Connection ││
162+
│ │ ▼ ││
163+
│ │ ┌─────────────────────────────────────────────────┐ ││
164+
│ │ │ Ansible Client │ ││
165+
│ │ │ - install-docker.yml │ ││
166+
│ │ │ - install-docker-compose.yml │ ││
167+
│ │ │ - inventory generation │ ││
168+
│ │ └─────────────────────────────────────────────────┘ ││
169+
│ └─────────────────────────────────────────────────────┘│
170+
└─────────────────────────────────────────────────────────┘
171+
```
172+
173+
## Risk Assessment
174+
175+
### Low Risk
176+
177+
- **Docker Support**: Well-established and reliable on GitHub Actions
178+
- **Network Connectivity**: Docker containers have consistent internet access
179+
- **Package Installation**: No nested virtualization issues
180+
181+
### Medium Risk
182+
183+
- **Systemd in Containers**: May require special configuration
184+
- **SSH Setup**: Need to ensure SSH server starts correctly
185+
- **Performance**: Container overhead vs VM performance
186+
187+
### Mitigation Strategies
188+
189+
- **Systemd**: Use proven systemd-in-Docker patterns
190+
- **SSH Testing**: Validate SSH connectivity in local testing phase
191+
- **Documentation**: Comprehensive troubleshooting documentation
192+
193+
## Conclusion
194+
195+
Docker containers provide a viable and reliable alternative to LXD VMs for configuration testing. The approach addresses the core network connectivity issues while maintaining compatibility with the existing Ansible-based configuration workflow. The implementation should start with a custom Ubuntu 24.04 Dockerfile and consider testcontainers-rs integration for better test lifecycle management.

0 commit comments

Comments
 (0)