Skip to content

Sync Traceable Images to Local Docker Registry

This guide covers how to synchronize Traceable Platform images to your local Docker registry for airgap deployments.

Overview

For airgap environments, you need to transfer all required container images to an internal registry. This guide provides multiple methods for syncing images based on your environment and requirements.

Prerequisites

  • Credentials for source registry: pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external
  • Credentials for destination registry (if required)
  • Docker or Podman installed
  • Skopeo installed (for Option 1)
  • Network access to both registries (for Option 1)

Setup

Export Environment Variables

export sourceHost=pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external
export destHost=mydocker.registry.com
export destPrefix=traceable-images
export traceableVersion=1.14.0

Parameters:

  • sourceHost: Traceable source registry
  • destHost: Your internal registry hostname
  • destPrefix: Path prefix in destination registry
  • traceableVersion: Target platform version

Download Workflow File

  1. Login to source registry:
docker login $sourceHost

Enter your username and token when prompted.

  1. Pull the airgap image:
docker pull \
  pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external/traceable/tiw-airgap:${traceableVersion}
  1. Create working directory:
mkdir traceable && cd traceable
  1. Extract workflow file:
docker run -ti -v $(pwd):/traceable --rm --entrypoint sh \
  pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external/traceable/tiw-airgap:${traceableVersion} \
  -c "cp -r /workflow/airgap/workflow-${traceableVersion}.tgz /traceable/"
  1. Extract the archive:
tar -xzf workflow-${traceableVersion}.tgz

Download ClusterMgr

curl -L \
  https://downloads.traceable.ai/platform/installer/clustermgr/linux-amd64/traceable-clustermgr-${traceableVersion}-linux-amd64.tgz \
  | tar -zxv

Skopeo compares source and destination images and pushes only the delta, making it efficient for incremental updates.

Requirement: Machine must have network access to both registries.

Generate Transfer Script

./traceable-clustermgr-${traceableVersion}/clustermgr image generate \
  -f airgap/image-mapping/custom/D3002.custom.ingress-install.yaml \
  --src-host $sourceHost \
  --dest-host $destHost \
  --dest-prefix $destPrefix \
  --skopeo > image-sync.sh

Generate Destination Image List

./traceable-clustermgr-${traceableVersion}/clustermgr image generate \
  -f airgap/image-mapping/custom/D3002.custom.ingress-install.yaml \
  --src-host $sourceHost \
  --dest-host $destHost \
  --dest-prefix $destPrefix \
  --list-dest > dest-images.txt

Use case: Create repositories in advance (e.g., for ECR):

for image in $(cat dest-images.txt); do
  repo=$(echo $image | cut -f1 -d":" | awk -F'/' '{print $2"/"$3}')
  echo "$destHost/$repo will be created"
  aws ecr create-repository --repository-name $repo
done

Sync Images

  1. Start Skopeo container:
docker run -ti -v $(pwd):/traceable --rm \
  -e destHost=${destHost} -e sourceHost=${sourceHost} \
  --entrypoint bash quay.io/skopeo/stable:latest
  1. Change to working directory:
cd /traceable
  1. Login to source registry:
skopeo login ${sourceHost}
  1. Login to destination registry:
skopeo login ${destHost}
  1. Execute sync script:
bash image-sync.sh

Option 2: Mirror Registry

Create a mirror of the Traceable registry at your location.

Generate Repository List

./traceable-clustermgr-${traceableVersion}/clustermgr image generate \
  -f airgap/image-mapping/custom/D3002.custom.ingress-install.yaml \
  --src-host $sourceHost \
  --list-src | \
  xargs -I{} echo {} | awk -F":" '{print $1}' > traceable-repo.txt

Use traceable-repo.txt as reference to configure your registry mirror.

Option 3: Airgap Bundle Transfer

For completely disconnected environments, use the pre-packaged airgap bundle.

Download Airgap Bundle

Contact Traceable team to obtain the airgap bundle:

traceable-platform-airgap-<version>.tgz

Sync Images from Bundle

  1. Export variables:
export version=<platform-version>
export destRegistry=<your-registry>
  1. Extract the bundle:
tar -xvzf traceable-platform-airgap-$version.tgz
  1. Navigate to images directory:
cd traceable-platform-$version/images/
  1. Generate sync script:
yq e '.[] | {"imageInfo": .fileName + " " + .tarTag}' index.yaml \
  | while IFS= read -r line; do 
    fileName=$(echo $line | cut -d" " -f2)
    imageTag=$(echo $line | cut -d" " -f3)
    echo "skopeo copy docker-archive:./${fileName} \
      docker://${destRegistry}/${imageTag} \
      --dest-tls-verify=false || exit -1" >> image-sync.sh
  done
  1. Execute sync:
bash image-sync.sh

Post-Sync Validation

After syncing images, validate that all images are present in your registry.

Reference: See Validate Images for detailed validation steps.

Quick Validation

# Generate image list
./clustermgr image generate \
  -f airgap/image-mapping/custom/D3002.custom.ingress-install.yaml \
  --dest-host $destHost \
  --dest-prefix $destPrefix \
  --list-dest > imageList.txt

# Validate each image
for image in $(cat imageList.txt); do
  skopeo inspect docker://$image --tls-verify=false > /dev/null 2>&1
  if [ $? -ne 0 ]; then
    echo "MISSING: $image"
  fi
done

Troubleshooting

Authentication Errors

Symptoms: unauthorized or authentication required

Solutions:

  1. Verify credentials are correct
  2. Re-login to registries:
skopeo login ${sourceHost}
skopeo login ${destHost}
  1. Check token expiration

Network Timeout

Symptoms: Connection timeout during transfer

Solutions:

  1. Check network connectivity
  2. Verify firewall rules
  3. Try transferring smaller batches
  4. Increase timeout settings

Disk Space Issues

Symptoms: no space left on device

Solutions:

  1. Check available disk space
  2. Clean up temporary files
  3. Use a larger disk or different location

TLS Certificate Errors

Symptoms: x509: certificate signed by unknown authority

Solutions:

  1. Add --src-tls-verify=false or --dest-tls-verify=false flags
  2. Add certificates to trust store
  3. Configure registry with valid certificates

Best Practices

  1. Validate After Sync: Always validate images after syncing
  2. Keep Logs: Save sync logs for troubleshooting
  3. Incremental Updates: Use Skopeo for efficient incremental syncs
  4. Automate: Script the sync process for repeatability
  5. Version Control: Track which versions have been synced
  6. Storage Planning: Ensure sufficient storage for all images

Support

For image sync assistance, contact: support@harness.io

Provide the following information:

  • Source and destination registries
  • Platform version
  • Sync method used
  • Error messages
  • Sync logs