Workloads

Workloads define how a container should run. They are versioned templates used to launch instances consistently across your infrastructure — whether you're deploying game servers, web applications, databases, or any other containerized service.

Workloads Page Overview

The Workloads page provides a comprehensive interface for managing your container templates:

View Modes

Toggle between Grid and Table views using the view mode buttons:

• Grid View: Card-based layout showing workload icon, name, description, Docker image, and resource configuration
• Table View: Compact list format ideal for managing many workloads

Search and Filter

Use the search bar to filter workloads by name or description. Filters help you quickly find specific templates in large collections.

Create a Workload

Click the Create Workload button to open the creation wizard:

1. Basic Info: Enter name, description, and optional labels
2. Container Configuration:
   • Docker image (e.g., itzg/minecraft-server:latest)
   • Command and arguments
   • Working directory
3. Ports: Define exposed ports with names, protocols, and container ports
4. Environment Variables: Set required and optional environment variables
5. Resources: Configure CPU and memory requests/limits
6. Volumes: Define persistent storage mounts
7. Health Checks: Configure liveness and readiness probes

Import Pterodactyl Egg

Shardlyn supports importing eggs from Pterodactyl Panel:

1. Click Import in the Workloads page
2. Paste the Pterodactyl egg JSON configuration
3. Review the converted workload spec
4. Save to create the workload

This enables easy migration from Pterodactyl to Shardlyn.

Workload Details

Each workload card displays:

• Icon: Automatically resolved based on container image or configurable
• Name and Description: Identifying information
• Docker Image: The container image and tag
• Active Instances: Count of running instances using this workload
• Resource Configuration: CPU and Memory limits

Actions

• Edit: Modify workload configuration
• Export: Download workload spec as YAML for backup or sharing
• Deploy: Launch a new instance from this workload
• Delete: Remove unused workloads

Private Images

If your workloads use images from a private container registry, you need to create a registry credential and reference it in your workload spec.

Creating a Registry Credential

1. Navigate to Settings > Credentials (or use the API)
2. Click Add Credential
3. Select provider: Registry
4. Fill in:
   • Name: A memorable name (e.g., docker-hub-private, ghcr-org)
   • Registry Server: The registry hostname (e.g., ghcr.io, registry.example.com)
   • Username: Your registry username or service account
   • Password: Your registry password, access token, or PAT

Using Private Images in Workloads

When creating or editing a workload, set the imagePullSecret field to the name of your registry credential:

spec:
  image: ghcr.io/my-org/custom-app:latest
  imagePullSecret: ghcr-org

The credential is securely stored and injected at deploy time — the agent receives the auth token only when it needs to pull the image.

Supported Registries

• Docker Hub (private repos) — use https://index.docker.io/v1/ as server
• GitHub Container Registry — use ghcr.io as server, a PAT as password
• AWS ECR — use your ECR endpoint, AWS as username, and an ECR auth token as password
• Google Artifact Registry — use us-docker.pkg.dev (or your region), _json_key as username, and your service account JSON as password
• Self-hosted registries — use your registry's hostname

Install Scripts

For workloads that require downloading files before running (especially game servers using tools like SteamCMD), Shardlyn supports a two-container pattern using spec.install:

1. An install container runs first, downloads game files to a shared volume
2. The main container starts with the downloaded files already in place

This pattern keeps your runtime images lightweight and reusable.

spec:
  image: cm2network/steamcmd:root
  install:
    container: cm2network/steamcmd:root
    entrypoint: /bin/bash
    script: |
      cd /mnt/server
      /home/steam/steamcmd/steamcmd.sh \
        +force_install_dir /mnt/server \
        +login anonymous \
        +app_update 258550 validate \
        +quit
  volumes:
    - name: server
      mountPath: /mnt/server
      sizeGb: 50

The install script:

• Runs once before the main container starts
• Has access to all volumes mounted at /mnt/server
• Has access to all environment variables from spec.env
• Can use a different container image than the main runtime
• Supports imagePullSecret for private install images too

See the Workload Specification for full details and SteamCMD examples.

Best Practices

• Use specific image tags instead of latest for reproducibility
• Set resource requests and limits to prevent resource contention
• Use labels to organize workloads by type, region, or tier
• Document environment variables with descriptions for operators

Next Steps

• Instances — Deploy and manage running containers from your workloads
• Git Deploy — Automate updates to instances from Git repositories
• File Management — Browse and edit files inside running instances
• Workload Specification — Full reference for the workload YAML format