1# Gordon Version Deployment Workflow Example
2
3This document demonstrates how to use manifest annotations for simple version deployments and rollbacks in Gordon.
4
5## Prerequisites
6
7- Gordon server running with the registry and auto-route features enabled
8- Podman or Docker with OCI manifest support
9- A container image to deploy
10
11## Basic Versioned Deployment
12
13### 1. Build and Push Your Versioned Images
14
15```bash
16# Build and push your application images with versions
17export VERSION=v1.0.1
18podman build --tag myapp:$VERSION --tag registry.domain.com/myapp:$VERSION .
19podman push registry.domain.com/myapp:$VERSION
20
21export VERSION=v1.0.2
22podman build --tag myapp:$VERSION --tag registry.domain.com/myapp:$VERSION .
23podman push registry.domain.com/myapp:$VERSION
24```
25
26### 2. Create Manifest and Deploy
27
28```bash
29# Deploy v1.0.1 with version annotation
30export VERSION=v1.0.1
31podman manifest create myapp:latest
32podman manifest add myapp:latest registry.domain.com/myapp:$VERSION
33podman manifest annotate myapp:latest --annotation version=$VERSION registry.domain.com/myapp:$VERSION
34podman manifest push myapp:latest registry.domain.com/myapp:latest
35```
36
37### 3. Gordon Processing
38
39When Gordon receives the manifest, it will:
40
411. Parse the manifest annotations from the JSON structure:
42   ```json
43   {
44     "schemaVersion": 2,
45     "mediaType": "application/vnd.oci.image.manifest.v1+json",
46     "annotations": {
47       "version": "v1.0.1"
48     }
49   }
50   ```
51
522. Extract version information and deploy the specified version
533. Update routes to use the versioned image
54
55## Simple Version Deployment and Rollback
56
57### Deploying Different Versions
58
59```bash
60# Deploy v1.0.2
61export VERSION=v1.0.2
62podman manifest create myapp:latest --amend
63podman manifest add myapp:latest registry.domain.com/myapp:$VERSION
64podman manifest annotate myapp:latest --annotation version=$VERSION registry.domain.com/myapp:$VERSION
65podman manifest push myapp:latest registry.domain.com/myapp:latest
66
67# Rollback to v1.0.1 (just change the version)  
68export VERSION=v1.0.1
69podman manifest create myapp:latest --amend
70podman manifest add myapp:latest registry.domain.com/myapp:$VERSION
71podman manifest annotate myapp:latest --annotation version=$VERSION registry.domain.com/myapp:$VERSION
72podman manifest push myapp:latest registry.domain.com/myapp:latest
73
74# Deploy v1.0.3 (assuming you built and pushed it first)
75export VERSION=v1.0.3
76podman manifest create myapp:latest --amend
77podman manifest add myapp:latest registry.domain.com/myapp:$VERSION
78podman manifest annotate myapp:latest --annotation version=$VERSION registry.domain.com/myapp:$VERSION
79podman manifest push myapp:latest registry.domain.com/myapp:latest
80```
81
82### Gordon Version Processing
83
84When Gordon detects version annotations, it will:
85
861. **Parse version annotations**: Extract the version from the `version` annotation
872. **Execute deployment**: Deploy the specified version to all matching routes
883. **Log the deployment**
89
90**Example log output**:
91```
92INFO Processing versioned deployment image=myapp reference=latest version=v1.0.1
93INFO Performing version deployment route=myapp.domain.com versioned_image=myapp:v1.0.1
94INFO Version deployment completed successfully route=myapp.domain.com version=v1.0.1
95```
96
97## Supported Annotation Keys
98
99### Version Annotations
100- `version` - The version to deploy (required)
101
102## Real-World Example
103
104```bash
105# Deploy production v1.0.1
106export VERSION=v1.0.1
107podman manifest create myapp:latest --amend
108podman manifest add myapp:latest registry.domain.com/myapp:$VERSION
109podman manifest annotate myapp:latest --annotation version=$VERSION registry.domain.com/myapp:$VERSION
110podman manifest push myapp:latest registry.domain.com/myapp:latest
111
112# Deploy new version v1.0.2  
113export VERSION=v1.0.2
114podman manifest create myapp:latest --amend
115podman manifest add myapp:latest registry.domain.com/myapp:$VERSION
116podman manifest annotate myapp:latest --annotation version=$VERSION registry.domain.com/myapp:$VERSION
117podman manifest push myapp:latest registry.domain.com/myapp:latest
118
119# Oh no! Bug found - rollback to v1.0.1
120export VERSION=v1.0.1
121podman manifest create myapp:latest --amend
122podman manifest add myapp:latest registry.domain.com/myapp:$VERSION
123podman manifest annotate myapp:latest --annotation version=$VERSION registry.domain.com/myapp:$VERSION
124podman manifest push myapp:latest registry.domain.com/myapp:latest
125
126# Fix deployed - move forward to v1.0.3
127export VERSION=v1.0.3
128podman manifest create myapp:latest --amend
129podman manifest add myapp:latest registry.domain.com/myapp:$VERSION
130podman manifest annotate myapp:latest --annotation version=$VERSION registry.domain.com/myapp:$VERSION
131podman manifest push myapp:latest registry.domain.com/myapp:latest
132```
133
134## Configuration Requirements
135
136Ensure your Gordon configuration supports this workflow:
137
138```toml
139[auto_route]
140enabled = true
141
142[registry_auth]
143enabled = true
144username = "gordon"
145password = "your-password"
146
147[server]
148registry_domain = "registry.domain.com"
149```
150
151## Monitoring and Observability
152
153Gordon logs provide visibility into the version deployment process:
154
155- Manifest annotation parsing
156- Version detection and tracking
157- Deployment execution
158- Success/failure status
159
160Check Gordon logs for detailed version deployment information:
161
162```bash
163# View Gordon logs for version operations
164journalctl -u gordon -f | grep -i version
165
166# Or check Docker/Podman logs if running in container
167docker logs gordon-container | grep -i version
168```
169
170## Troubleshooting
171
172### Common Issues
173
1741. **Annotations not parsed**: Ensure you're using OCI manifest format, not Docker v2.2
1752. **Version target not found**: Verify the target version exists in your registry
1763. **Route not found**: Ensure the image has configured routes in Gordon
1774. **Permission errors**: Check registry authentication and permissions
178
179### Debugging Commands
180
181```bash
182# Inspect manifest annotations
183podman manifest inspect myapp:latest
184
185# Check Gordon configuration
186gordon config show
187
188# Verify image exists
189podman search registry.domain.com/myapp
190```
191
192This version deployment workflow provides a simple, declarative way to manage deployments and rollbacks using standard container registry operations and OCI manifest annotations.