> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/pipelines/infrastructure.md).

# Infrastructure & Runtimes

Infrastructure defines the compute resources where pipeline stages execute. Harness 3.0 supports multiple runtime types; Cloud (Harness-hosted), Kubernetes, Shell (bare-metal or VM), and VM runtimes. The runtime determines how steps are isolated, what resources are available, and how networking is configured.

```typescript
interface Runtime {
  // Runtime type
  type: "cloud" | "kubernetes" | "shell" | "vm"

  // Runtime-specific configuration
  spec: RuntimeCloud | RuntimeKubernetes | RuntimeShell | RuntimeVM
}

interface Platform {
  // Operating system
  os: "linux" | "macos" | "windows"

  // CPU architecture
  arch: "amd64" | "arm64"

  // OS variant (e.g., alpine, debian)
  variant: string

  // OS version
  version: string

  // Feature flags
  features: string[]
}
```

### Cloud runtime <a href="#cloud-runtime" id="cloud-runtime"></a>

The Cloud runtime uses Harness-hosted infrastructure. No delegate or cluster configuration is required; Harness manages compute, scaling, and cleanup automatically.

#### Short configuration <a href="#short-configuration" id="short-configuration"></a>

```yaml
stages:
  - name: build
    runtime: cloud
    steps:
      - run: npm ci
      - run: npm run build
```

#### Full configuration <a href="#full-configuration" id="full-configuration"></a>

```yaml
stages:
  - name: build
    runtime:
      type: cloud
      spec:
        size: large
        platform:
          os: linux
          arch: amd64
    steps:
      - run: npm ci
      - run: npm run build
      - run: npm test
```

{% hint style="info" %}
**CLOUD RUNTIME DEFAULT**

When no runtime is specified, Harness defaults to Cloud runtime with `size: flex` and Linux AMD64 platform. This is sufficient for most CI workloads.
{% endhint %}

***

### Kubernetes runtime <a href="#kubernetes-runtime" id="kubernetes-runtime"></a>

The Kubernetes runtime executes pipeline stages as pods in your own Kubernetes cluster. This provides full control over the execution environment, network access, and resource allocation.

```yaml
stages:
  - name: build
    runtime:
      type: kubernetes
      spec:
        connector: k8s-build-cluster
        namespace: harness-builds
        service_account: harness-builder
        resources:
          requests:
            cpu: "2"
            memory: 4Gi
          limits:
            cpu: "4"
            memory: 8Gi
        node_selector:
          workload: ci
        tolerations:
          - key: dedicated
            operator: Equal
            value: ci
            effect: NoSchedule
    steps:
      - run: npm ci
      - run: npm run build
```

{% hint style="warning" %}
**RESOURCE MANAGEMENT**

Set resource requests and limits to ensure consistent performance and prevent noisy-neighbor issues in shared clusters. Without limits, pods may be evicted by the Kubernetes scheduler during memory pressure.
{% endhint %}

***

### Shell runtime <a href="#shell-runtime" id="shell-runtime"></a>

The Shell runtime executes steps directly on the host machine where the Harness delegate is running. No containerization is involved. This is useful for on-premise environments, legacy systems, or workloads that require direct access to host resources.

```yaml
stages:
  - name: deploy-on-prem
    runtime:
      type: shell
    delegate:
      tags:
        - on-prem
        - linux
    steps:
      - run: |
          echo "Running directly on host"
          whoami
          uname -a
          ./deploy-local.sh
```

{% hint style="warning" %}
**SECURITY CONSIDERATION**

Shell runtime steps execute with the same permissions as the Harness delegate process. Ensure proper access controls and isolation are in place, especially when running untrusted code or on shared hosts.
{% endhint %}

***

### VM runtime <a href="#vm-runtime" id="vm-runtime"></a>

The VM runtime provisions a dedicated virtual machine for each stage execution. This provides full machine isolation, root access, and the ability to install arbitrary software. VMs are provisioned on demand and destroyed after the stage completes.

```yaml
stages:
  - name: build
    runtime:
      type: vm
      spec:
        image: ubuntu-22.04
        size: large
        pool: build-pool
        disk:
          size: 100Gi
          type: ssd
    steps:
      - run: |
          sudo apt-get update
          sudo apt-get install -y build-essential
          make all
```

***

### Platform configuration <a href="#platform-configuration" id="platform-configuration"></a>

The platform configuration specifies the operating system, CPU architecture, variant, version, and feature requirements for the runtime environment.

| Property   | Type       | Description                                                    |
| ---------- | ---------- | -------------------------------------------------------------- |
| `os`       | `string`   | Operating system: `linux`, `macos`, `windows`                  |
| `arch`     | `string`   | CPU architecture: `amd64`, `arm64`                             |
| `variant`  | `string`   | OS variant, e.g., `alpine`, `debian`, `ubuntu-22.04`           |
| `version`  | `string`   | Specific OS version string                                     |
| `features` | `string[]` | Feature flags such as `docker`, `gpu`, `nested-virtualization` |

```yaml
stages:
  - name: build-linux
    runtime:
      type: cloud
      spec:
        size: medium
        platform:
          os: linux
          arch: amd64
          features:
            - docker
    steps:
      - run: docker build -t my-app .

  - name: build-macos
    runtime:
      type: cloud
      spec:
        size: large
        platform:
          os: macos
          arch: arm64
    steps:
      - run: xcodebuild -scheme MyApp
```

***

### Machine sizes <a href="#machine-sizes" id="machine-sizes"></a>

Machine sizes control the CPU and memory allocated to Cloud and VM runtimes.

| Size      | vCPU | Memory | Typical Use Case                                                           |
| --------- | ---- | ------ | -------------------------------------------------------------------------- |
| `flex`    | Auto | Auto   | Default. Harness auto-scales based on workload. Best for most CI tasks.    |
| `small`   | 1    | 2 GB   | Lightweight scripts, linting, notifications.                               |
| `medium`  | 2    | 4 GB   | Standard builds, unit tests, moderate compilation.                         |
| `large`   | 4    | 8 GB   | Large builds, integration tests, Docker image builds.                      |
| `xlarge`  | 8    | 16 GB  | Heavy compilation (C++, Rust), large monorepos, ML workloads.              |
| `xxlarge` | 16   | 32 GB  | Enterprise-scale builds, large test suites, resource-intensive operations. |

### Multi-platform build example <a href="#multi-platform-build-example" id="multi-platform-build-example"></a>

Build the same application on multiple platforms simultaneously using matrix strategy with platform configuration.

```yaml
pipeline:
  stages:
    - name: build
      strategy:
        matrix:
          platform:
            - os: linux
              arch: amd64
            - os: linux
              arch: arm64
            - os: macos
              arch: arm64
            - os: windows
              arch: amd64
      runtime:
        type: cloud
        spec:
          size: large
          platform:
            os: ${{ matrix.platform.os }}
            arch: ${{ matrix.platform.arch }}
      steps:
        - run: |
            echo "Building on ${{ matrix.platform.os }}/${{ matrix.platform.arch }}"
            make build GOOS=${{ matrix.platform.os }} GOARCH=${{ matrix.platform.arch }}
```

{% hint style="info" %}
**COST OPTIMIZATION**

Use `flex` size for most workloads. Harness Cloud automatically scales resources to match demand, so you only pay for what you use. Reserve fixed sizes for workloads with specific resource requirements.
{% endhint %}