Skip to content

Download Workflow File

This guide explains how to download the workflow file required for platform upgrades.

What is a Workflow File?

The workflow file serves as a comprehensive package that includes all the essential resources required to install and upgrade the platform successfully. Specifically, it encompasses several key elements:

  1. Helm Charts: Pre-configured templates that define the Traceable applications needed for the installation of the platform
  2. Install Workflow: Outlines the sequence of steps and tasks necessary for a smooth installation process
  3. Image List: Contains details about the container images required by the platform

Prerequisites

Before downloading the workflow file, ensure you have:

  • Docker or Podman installed on your local machine
  • Access credentials (username and token) for the Traceable registry
  • Sufficient disk space (workflow files can be several GB)
  • Network access to pkg.harness.io

Download Steps

1. Docker Login to Traceable Registry

Login to the Traceable registry:

docker login pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external

When prompted:

  • Username: Enter your Traceable registry username
  • Password: Enter your access token (not your regular password)

Expected Output:

Login Succeeded

2. Pull the Workflow Image

Pull the tiw-airgap image for your target version:

docker pull pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external/traceable/tiw-airgap:${traceableVersion}

Example:

# For version 1.40.0
docker pull pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external/traceable/tiw-airgap:1.40.0

Note: Replace ${traceableVersion} with your actual target version (e.g., 1.40.0, 1.41.2)

3. Create Working Directory

Create a directory to store the workflow file:

mkdir traceable && cd traceable

4. Extract Workflow File from Image

Copy the workflow file from the Docker image to your local directory:

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/"

Example:

# For version 1.40.0
docker run -ti -v $(pwd):/traceable --rm --entrypoint sh \
  pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external/traceable/tiw-airgap:1.40.0 \
  -c "cp -r /workflow/airgap/workflow-1.40.0.tgz /traceable/"

After successful execution, you will see the file workflow-${traceableVersion}.tgz in your current directory.

5. Extract the Workflow Archive

Extract the workflow tarball:

tar -xzf workflow-${traceableVersion}.tgz

Example:

tar -xzf workflow-1.40.0.tgz

This will create a directory structure containing:

  • Helm charts
  • Workflow definitions
  • Image lists
  • Configuration files

Verification

After extraction, verify the contents:

ls -lh

You should see:

  • workflow-${traceableVersion}.tgz - The original archive
  • Extracted directories containing helm charts and workflow files

Check Workflow Contents

# List extracted contents
find . -type f -name "*.yaml" | head -10

You should see various YAML files for helm charts and workflows.

Using Podman Instead of Docker

If you're using Podman instead of Docker, replace docker with podman in all commands:

Login with Podman

podman login pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external

Pull Image with Podman

podman pull pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external/traceable/tiw-airgap:${traceableVersion}

Extract with Podman

podman 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/"

Troubleshooting

Issue 1: Authentication Failed

Symptoms: Error response from daemon: Get "https://pkg.harness.io/...": unauthorized

Solutions:

  1. Verify your username and token are correct
  2. Ensure the token hasn't expired
  3. Contact Traceable support for new credentials
  4. Check if you have access to the specific registry

Issue 2: Image Not Found

Symptoms: Error response from daemon: manifest for ... not found

Solutions:

  1. Verify the version number is correct
  2. Check if the version is available in the registry
  3. Contact Traceable support to confirm version availability
  4. List available tags:
# This may not work without API access, contact support for available versions

Issue 3: Network Timeout

Symptoms: error pulling image configuration: download failed after attempts

Solutions:

  1. Check your internet connection
  2. Verify firewall rules allow access to pkg.harness.io
  3. Try using a different network
  4. Increase Docker timeout settings:
# Edit /etc/docker/daemon.json
{
  "max-concurrent-downloads": 3,
  "max-download-attempts": 5
}

Issue 4: Insufficient Disk Space

Symptoms: no space left on device

Solutions:

  1. Check available disk space:
df -h
  1. Clean up Docker images and containers:
docker system prune -a
  1. Free up disk space or use a different directory with more space

Issue 5: Permission Denied

Symptoms: permission denied while trying to connect to the Docker daemon socket

Solutions:

  1. Run with sudo:
sudo docker pull ...
  1. Add your user to the docker group:
sudo usermod -aG docker $USER
newgrp docker
  1. Restart Docker service:
sudo systemctl restart docker

Airgap Environment

For airgap (offline) environments:

1. Download on Connected Machine

Follow all the steps above on a machine with internet access.

2. Save Docker Image

Save the image to a tar file:

docker save pkg.harness.io/ieq3j_9otlwbpfz-uryoda/docker-external/traceable/tiw-airgap:${traceableVersion} \
  -o tiw-airgap-${traceableVersion}.tar

3. Transfer Files

Transfer both files to the airgap environment:

  • tiw-airgap-${traceableVersion}.tar (Docker image)
  • workflow-${traceableVersion}.tgz (Workflow file)

4. Load Image in Airgap Environment

On the airgap machine:

docker load -i tiw-airgap-${traceableVersion}.tar

5. Extract Workflow

Extract the workflow file as described in step 5 above.

Next Steps

After successfully downloading and extracting the workflow file:

  1. For UI-based upgrades: Upload the workflow file through the Traceable Operator UI

  2. For ClusterMgr upgrades: The workflow file is automatically used by ClusterMgr

  3. Verify workflow contents: Ensure all required files are present before proceeding with upgrade

Best Practices

  1. Version Matching: Always download the workflow file that matches your target platform version
  2. Backup: Keep a copy of the workflow file for rollback purposes
  3. Verification: Verify the integrity of downloaded files before using them
  4. Documentation: Document which workflow version was used for each upgrade
  5. Storage: Store workflow files in a secure, backed-up location
  6. Cleanup: Remove old workflow files after successful upgrades to save space

Security Considerations

  1. Credentials: Never commit registry credentials to version control
  2. Access Control: Limit access to workflow files to authorized personnel only
  3. Secure Transfer: Use secure methods (SCP, SFTP) when transferring files
  4. Verification: Verify file checksums if provided by Traceable support
  5. Audit: Log all workflow file downloads for audit purposes

File Structure

After extraction, the typical workflow directory structure:

workflow-2.5.0/
├── charts/
│   ├── api-server/
│   ├── platform-agent/
│   ├── hypertrace/
│   └── ...
├── workflow.yaml
├── images.txt
└── metadata.json

Support

For issues downloading workflow files or questions about specific versions, contact: support@harness.io

Provide the following information when requesting support:

  • Target platform version
  • Error messages encountered
  • Network environment (online/airgap)
  • Docker/Podman version
  • Operating system