|
| 1 | +--- |
| 2 | +title:"How to: Upgrade Deprecated Docker Images in Classic Pipelines" |
| 3 | +description:"Find and upgrade deprecated Docker v1 and schema 1 images to support docker-27 runner in Classic Pipelines." |
| 4 | +group:kb |
| 5 | +sub-group:articles |
| 6 | +toc:true |
| 7 | +kb:false |
| 8 | +ht:true |
| 9 | +common:false |
| 10 | +categories:[Pipelines] |
| 11 | +support-reviewed:2025-07-14 AA |
| 12 | +--- |
| 13 | + |
| 14 | +As part of our ongoing platform upgrades, Codefresh is moving to a newer Classic Runner version based on Docker 27. This change deprecates older Docker image formats such as Docker Image Format v1 and Docker manifest version 2, schema 1. |
| 15 | + |
| 16 | +This guide walks you through: |
| 17 | +- Identifying deprecated Docker images in your Classic Pipelines. |
| 18 | +- Upgrading those images to a modern supported format (OCI or Docker manifest v2, schema 2). |
| 19 | + |
| 20 | +##Step 1: Find Deprecated Docker Images |
| 21 | + |
| 22 | +You can identify deprecated images using one of the following methods: |
| 23 | + |
| 24 | +###Option A: Analyze Build Logs (Manual Method) |
| 25 | + |
| 26 | +The latest`dind` versions output a deprecation warning in the build log each time a deprecated image is pulled. |
| 27 | + |
| 28 | +**Pros** |
| 29 | +- No setup required |
| 30 | +- Works retroactively on historical builds |
| 31 | + |
| 32 | +**Cons** |
| 33 | +- Time-consuming for large accounts |
| 34 | +- Requires script execution and manual review |
| 35 | + |
| 36 | +Example warning in logs: |
| 37 | +``` |
| 38 | +[DEPRECATION NOTICE] Docker Image Format v1 and Docker Image manifest version 2, schema 1 support is disabled by default... |
| 39 | +``` |
| 40 | + |
| 41 | +Use the following script to scan your build logs and extract deprecated images: |
| 42 | +👉[Find deprecated images used in previous builds](https://gist.github.com/francisco-cocozza/6046028184cc12b5ee4513bdcb4217c5) |
| 43 | + |
| 44 | +>💡 For large-scale environments, see[Appendix I](#appendix-i-monitor-engine-metrics) for a metrics-based approach. |
| 45 | +
|
| 46 | +--- |
| 47 | + |
| 48 | +##Step 2: Upgrade Deprecated Docker Images |
| 49 | + |
| 50 | +Once you've identified deprecated images, re-push them using a modern Docker client to convert the manifest format. |
| 51 | + |
| 52 | +###Sample Codefresh Pipeline |
| 53 | + |
| 54 | +```yaml |
| 55 | +version:"1.0" |
| 56 | + |
| 57 | +steps: |
| 58 | +push: |
| 59 | +title:"Re-pushing deprecated image" |
| 60 | +type:push |
| 61 | +candidate:<source-image-name> |
| 62 | +registry:<target-registry> |
| 63 | +tag:<target-tag> |
| 64 | +image_name:<target-image-name> |
| 65 | +``` |
| 66 | +
|
| 67 | +**Example:** |
| 68 | +```yaml |
| 69 | +push: |
| 70 | +title:"Re-pushing deprecated image" |
| 71 | +type:push |
| 72 | +candidate:docker/whalesay:latest |
| 73 | +registry:docker |
| 74 | +tag:new-manifest |
| 75 | +image_name:codefresh/whalesay |
| 76 | +``` |
| 77 | +
|
| 78 | +This pipeline step pulls the original image and re-pushes it with a compatible manifest. |
| 79 | +
|
| 80 | +> 🔁 Repeat this for each deprecated image. |
| 81 | +
|
| 82 | +--- |
| 83 | +
|
| 84 | +## Appendix I: Monitor Engine Metrics |
| 85 | +
|
| 86 | +A scalable way to detect deprecated image pulls using Prometheus engine metrics. Requires Codefresh Runtime version`v7.5.0` or later. |
| 87 | + |
| 88 | +### Metric Details |
| 89 | + |
| 90 | +Metric name:`codefresh_engine_deprecated_images_pulled_total` |
| 91 | + |
| 92 | +Labels include: |
| 93 | +-`account_name` |
| 94 | +-`pipeline_id` |
| 95 | +-`workflow` |
| 96 | +-`image_name` |
| 97 | + |
| 98 | +This metric increments each time a deprecated image is pulled. |
| 99 | + |
| 100 | +### How to Enable |
| 101 | + |
| 102 | +In your Hybrid Runtime Helm values: |
| 103 | + |
| 104 | +```yaml |
| 105 | +runtime: |
| 106 | + engine: |
| 107 | + env: |
| 108 | + METRICS_PROMETHEUS_ENABLED: true |
| 109 | + podMonitor: |
| 110 | + main: |
| 111 | + enabled: true |
| 112 | +``` |
| 113 | + |
| 114 | +To ensure metric collection on shutdown, configure a scrape timeout: |
| 115 | + |
| 116 | +```yaml |
| 117 | +runtime: |
| 118 | + engine: |
| 119 | + env: |
| 120 | + METRICS_PROMETHEUS_SCRAPE_TIMEOUT: '120000' # 120s |
| 121 | +``` |
| 122 | + |
| 123 | +### Monitoring Stack Setup |
| 124 | + |
| 125 | +You can install the [kube-prometheus-stack Helm chart](https://artifacthub.io/packages/helm/prometheus-community/kube-prometheus-stack): |
| 126 | + |
| 127 | +```bash |
| 128 | +helm repo add prometheus-community https://prometheus-community.github.io/helm-charts |
| 129 | +helm repo update |
| 130 | +helm install kube-prom prometheus-community/kube-prometheus-stack --create-namespace --namespace kube-prom -f ./kube-prom-values.yaml |
| 131 | +``` |
| 132 | + |
| 133 | +#### Example Storage Class (AWS EBS) |
| 134 | + |
| 135 | +```yaml |
| 136 | +# kube-prom-storage-class.yaml |
| 137 | +apiVersion: storage.k8s.io/v1 |
| 138 | +kind: StorageClass |
| 139 | +metadata: |
| 140 | + name: kube-prom |
| 141 | +provisioner: kubernetes.io/aws-ebs |
| 142 | +parameters: |
| 143 | + type: gp3 |
| 144 | +``` |
| 145 | + |
| 146 | +#### Example Helm Values |
| 147 | + |
| 148 | +```yaml |
| 149 | +# kube-prom-values.yaml |
| 150 | +prometheus: |
| 151 | + prometheusSpec: |
| 152 | + podMonitorSelectorNilUsesHelmValues: false |
| 153 | + serviceMonitorSelectorNilUsesHelmValues: false |
| 154 | + storageSpec: |
| 155 | + volumeClaimTemplate: |
| 156 | + spec: |
| 157 | + storageClassName: kube-prom |
| 158 | + accessModes: ["ReadWriteOnce"] |
| 159 | + resources: |
| 160 | + requests: |
| 161 | + storage: 20Gi |
| 162 | +
|
| 163 | +grafana: |
| 164 | + persistence: |
| 165 | + storageClassName: kube-prom |
| 166 | + enabled: true |
| 167 | +``` |
| 168 | + |
| 169 | +> 📝 Please consult the [official Helm docs](https://artifacthub.io/packages/helm/prometheus-community/kube-prometheus-stack?modal=values&path=prometheus.prometheusSpec.storageSpec) for additional configuration. |
| 170 | + |
| 171 | +### Verifying Metrics in Grafana |
| 172 | + |
| 173 | +After a build completes: |
| 174 | +1. Log into Grafana (port-forward to localhost:3000 if needed). |
| 175 | +2. Navigate to **Explore → Metrics**. |
| 176 | +3. Search for `codefresh_engine_deprecated_images_pulled_total`. |
| 177 | + |
| 178 | +You should see metrics if deprecated images were pulled. |
| 179 | + |
| 180 | +--- |
| 181 | + |
| 182 | +## Appendix II: Grafana Dashboard |
| 183 | + |
| 184 | +You can visualize deprecated image pulls using a prebuilt Grafana dashboard: |
| 185 | + |
| 186 | +1. Download the dashboard JSON from [this gist](https://gist.github.com/francisco-cocozza/6046028184cc12b5ee4513bdcb4217c5). |
| 187 | +2. In Grafana, go to **Dashboards → New → Import**. |
| 188 | +3. Upload the JSON and select `Mimir API` as the data source. |
| 189 | +4. Click **Import**. |
| 190 | + |
| 191 | +### Dashboard View |
| 192 | + |
| 193 | +You’ll be able to: |
| 194 | +-Filter by account name |
| 195 | +-View time-based pull counts |
| 196 | +-Identify pipelines and image names involved |
| 197 | + |
| 198 | +--- |
| 199 | + |
| 200 | +## Related Links |
| 201 | + |
| 202 | +-[Upgrade Docker images pipeline example](https://gist.github.com/francisco-cocozza/6046028184cc12b5ee4513bdcb4217c5) |
| 203 | +-[kube-prometheus-stack on ArtifactHub](https://artifacthub.io/packages/helm/prometheus-community/kube-prometheus-stack) |