Skip to content

Commit 1523990

Browse files
j143j143
committed
docs: add adr for image pull implementation
1 parent ceeffce commit 1523990

File tree

1 file changed

+127
-0
lines changed

1 file changed

+127
-0
lines changed

‎adr-003-docker-image-download.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# ADR-003: Support Real Docker Image Downloads
2+
3+
## Status
4+
Proposed
5+
6+
## Context
7+
The current implementation of the basic Docker engine supports a simplified mechanism for handling container images. This includes listing images and simulating image fetching. However, it does not support real Docker image downloads from container registries, which limits its functionality and compatibility with standard Docker workflows.
8+
9+
## Decision
10+
We will implement support for real Docker image downloads. This will involve integrating with container registries to fetch image manifests and layers, and extracting these layers to create a functional root filesystem for containers.
11+
12+
### Key Differences Between Current Implementation and Real Docker Image Downloads
13+
14+
| Feature | Current Implementation | Real Docker Implementation |
15+
|----------------------------------|------------------------------------------------|---------------------------------------------|
16+
| **Image Fetching** | Simulated fetching with placeholder logic | Fetches images from real container registries (e.g., Docker Hub) |
17+
| **Manifest Handling** | Not implemented | Parses and processes image manifests |
18+
| **Layer Downloading** | Not implemented | Downloads and verifies image layers |
19+
| **Layer Extraction** | Basic tar extraction | Handles complex layer structures and metadata |
20+
| **Registry Authentication** | Not supported | Supports authentication for private registries |
21+
22+
## Consequences
23+
1. **Benefits**:
24+
- Aligns the basic Docker engine with real-world Docker workflows.
25+
- Enables compatibility with existing container images and registries.
26+
- Provides a more realistic environment for learning and experimentation.
27+
28+
2. **Challenges**:
29+
- Increased complexity in implementation.
30+
- Requires handling of network operations, authentication, and error cases.
31+
- May introduce dependencies on external libraries or tools for registry interaction.
32+
33+
## Implementation Plan
34+
1. **Registry Integration**:
35+
- Implement a `Registry` interface to abstract interactions with container registries.
36+
- Provide a default implementation for Docker Hub.
37+
38+
2. **Manifest Handling**:
39+
- Fetch and parse image manifests to determine required layers.
40+
41+
3. **Layer Downloading and Verification**:
42+
- Download image layers using the digests specified in the manifest.
43+
- Verify layer integrity using checksums.
44+
45+
4. **Layer Extraction**:
46+
- Extract layers to create a root filesystem for containers.
47+
48+
5. **Authentication**:
49+
- Add support for registry authentication to handle private images.
50+
51+
6. **Testing**:
52+
- Add unit and integration tests to ensure correctness and reliability.
53+
54+
## Implementation Diagram
55+
56+
The following diagram illustrates the current stage of implementation and the end goal for supporting real Docker image downloads:
57+
58+
```mermaid
59+
graph TD
60+
A[Current Stage: Simulated Image Fetching] --> B[Intermediate Stage: Registry Integration]
61+
B --> C[End Goal: Full Docker Image Support]
62+
63+
%% Current Stage
64+
subgraph Current
65+
A1[Simulated Fetching Logic]
66+
A2[Basic Image Listing]
67+
A3[Placeholder Pull Function]
68+
end
69+
70+
%% Intermediate Stage
71+
subgraph Intermediate
72+
B1[Registry Interface Implementation]
73+
B2[Manifest Parsing]
74+
B3[Layer Downloading]
75+
end
76+
77+
%% End Goal
78+
subgraph EndGoal
79+
C1[Full Registry Authentication]
80+
C2[Layer Verification]
81+
C3[Layer Extraction]
82+
C4[Root Filesystem Creation]
83+
end
84+
85+
%% Connections
86+
A --> B1
87+
B1 --> B2
88+
B2 --> B3
89+
B3 --> C1
90+
C1 --> C2
91+
C2 --> C3
92+
C3 --> C4
93+
```
94+
95+
### Explanation of Stages
96+
97+
1. **Current Stage**:
98+
- Simulated fetching logic is used to mimic image downloads.
99+
- Basic image listing functionality is implemented.
100+
- The `Pull` function exists as a placeholder without real registry interaction.
101+
102+
2. **Intermediate Stage**:
103+
- Introduce a `Registry` interface to abstract interactions with container registries.
104+
- Implement manifest parsing to identify required layers.
105+
- Add functionality for downloading image layers from registries.
106+
107+
3. **End Goal**:
108+
- Support full registry authentication, including private registries.
109+
- Verify the integrity of downloaded layers using checksums.
110+
- Extract layers to create a functional root filesystem for containers.
111+
- Achieve compatibility with real Docker workflows.
112+
113+
## Alternatives Considered
114+
1. **Continue with Simulated Fetching**:
115+
- Simpler to implement but limits functionality.
116+
117+
2. **Use a Third-Party Library**:
118+
- Reduces development effort but may introduce external dependencies.
119+
120+
## Decision Drivers
121+
- Need for realistic Docker functionality.
122+
- Compatibility with existing container images and workflows.
123+
- Balance between implementation complexity and feature completeness.
124+
125+
## References
126+
- [Docker Image Specification](https://github.com/moby/moby/blob/master/image/spec/v1.2.md)
127+
- [OCI Image Format Specification](https://github.com/opencontainers/image-spec)

0 commit comments

Comments
 (0)