> 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/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md).
# Use Harness Cloud build infrastructure
You can use Harness-managed build infrastructure for your Harness CI pipelines.
With Harness Cloud, you can run builds in isolation on Harness-managed VMs that are preconfigured with tools, packages, and settings commonly used in CI pipelines. Harness hosts, maintains, and upgrades these machines so that you can focus on building software instead of maintaining build infrastructure.
Harness Cloud provides the following advantages:
* Use Cloud credits to run builds on Harness-managed infrastructure. No need to set-up and maintain the infrastructure yourself
* Starter pipelines for different programming languages.
* Blazing fast builds on Linux, macOS, and Windows.
* Get the latest features first. Harness may enable features for Harness Cloud before rolling them out to other build infrastructure options.
Go to [Which build infrastructure is right for me](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/which-build-infrastructure-is-right-for-me.md) for a comparison of build infrastructure options.
{% hint style="info" %}
**WHAT HAPPENS WHEN PIPELINES RUN ON HARNESS CLOUD?**
When a build runs on Harness Cloud, Harness runs each CI stage in a new, ephemeral VM.
The steps in each stage execute on the stage's dedicated VM. This allows the stage's steps to share information through the underlying filesystem. You can run CI steps directly on the VM or in a Docker container. When the stage is complete, the VM automatically terminates.
{% endhint %}
### What you will learn from this topic
By the end of this topic, you will understand:
* Platforms, VM images, and machine sizes available on Harness Cloud.
* How to configure a pipeline stage to run on Harness Cloud.
* The connector and secret manager requirements for Harness Cloud.
* How to access privately hosted resources and apply Harness Cloud best practices.
### Before you begin
Before you use Harness Cloud build infrastructure, ensure you have the following:
* Harness CI project and the required connector and secret manager configuration. Go to [Requirements for connectors and secrets](#requirements-for-connectors-and-secrets) to review access requirements.
### Billing and Cloud credits
Free plans get 2000 free Harness Cloud credits each month. If you are using a paid CI plan, you can purchase build credit packages. Free plans require credit card validation to use Harness Cloud. If you do not want to provide a credit card, consider using [local runner build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/define-a-docker-build-infrastructure.md).
Harness can invoice in arrears for overages. Go to [Subscriptions and licenses](/continuous-integration/troubleshooting-and-resources/ci-subscription-mgmt.md#harness-cloud-billing-and-cloud-credits) for Harness Cloud billing and build credit consumption.
### Platforms and image specifications
Harness Cloud supports **Linux**, **macOS**, and **Windows** platforms. Each CI stage that runs on Harness Cloud is executed on a **Harness-managed VM image**.
The VM image defines:
1. The **operating system** (for example, Ubuntu 22.04, Ubuntu 24.04, macOS, or Windows)
2. A **curated set of pre-installed tools** maintained and updated by Harness
Go to [Harness Cloud VM Images](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-vm-images) to review image components and preinstalled software.
After selecting a base VM image, you can **customize the build environment at pipeline execution time** by:
1. Locking specific tool versions
2. Installing additional tools that are not pre-installed
3. Running steps directly on the host VM or inside Docker containers
These customizations are applied **on top of the selected VM image**, are re-applied on each run, and **do not modify the underlying image**. [Learn more](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-vm-images#pre-installed-software-version-management)
You can also use **Bring Your Own Image (BYOI)** to create fully custom VM images with your tools and dependencies pre-installed, eliminating the need to install them at pipeline runtime. Go to [Harness Cloud BYOI](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-byoi) and [BYOI on Harness Cloud VM Images](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-vm-images#bring-your-own-image-byoi) to build custom VM images.
{% hint style="info" %}
To enable Windows and macOS for Harness Cloud, contact [Harness Support](mailto:support@harness.io).
{% endhint %}
### Requirements for connectors and secrets
Harness Cloud resolves connectors and secrets through the Harness Platform, not through a delegate. This determines which authentication methods and secret managers you can use.
#### Connectors
* All connectors must connect through the Harness Platform, not a delegate.
* AWS connectors cannot use IRSA or AssumeRole.
* GCP and Azure connectors cannot use authentication that inherits credentials from the delegate.
#### Secret managers
{% hint style="info" %}
On Harness Cloud, the Harness Built-in Secret Manager is supported. HashiCorp Vault is supported using OIDC, and AWS Secrets Manager and Google Cloud Secret Manager are supported using OIDC or static credentials. Go to [Secret resolution on Harness Cloud build infrastructure](https://developer.harness.io/harness-platform/use-harness-platform/secrets/secrets-management/harness-secret-manager-overview#secret-resolution-on-harness-cloud-build-infrastructure) to review the supported secret managers.
{% endhint %}
### Use Harness Cloud
You can configure your pipelines to use Harness Cloud in minutes.
{% tabs %}
{% tab title="Visual editor" %}
1. Go to the pipeline where you want to use Harness Cloud build infrastructure.
2. Select the **Build** stage, and then select the **Infrastructure** tab.
3. Select **Harness Cloud** and the desired **Platform**.
4. Save and run your pipeline.
{% endtab %}
{% tab title="YAML editor" %}
To enable Harness Cloud build infrastructure in your pipeline YAML, specify the `platform` and `runtime` in the `stage.spec`. For example:
```yaml
platform:
os: Linux
arch: Amd64
runtime:
type: Cloud
spec: {}
```
* In `runtime`, you must include `type: Cloud`.
* In `platform`, specify the `os` and `arch`. Go to [Platforms and image specifications](#platforms-and-image-specifications) for a list of supported operating systems and architectures.
Pipeline YAML example
The following YAML example describes a basic CI pipeline that uses Harness Cloud build infrastructure:
```yaml
pipeline:
name: Build sample-app
identifier: Build_sample_app_1677210779657
projectIdentifier: my-app-project
orgIdentifier: default
properties:
ci:
codebase:
connectorRef: account.GitHub_example
repoName: my-gh-account/example-repo
build: <+input>
stages:
- stage:
name: Build
identifier: Build
type: CI
spec:
cloneCodebase: true
execution:
steps:
- step:
type: Run
name: Echo Welcome Message
identifier: Echo_Welcome_Message
spec:
shell: Sh
command: echo "Welcome to Harness CI"
platform:
os: Linux
arch: Amd64
runtime:
type: Cloud
spec: {}
```
{% endtab %}
{% endtabs %}
#### Use resource classes
You can use the YAML editor to change the cloud machine size.
{% hint style="info" %}
Resource class support is now Generally Available (GA). If this feature is not yet enabled in your account, reach out to [Harness Support](mailto:support@harness.io) for assistance.
{% endhint %}
To select a resource class size, set the desired size as the value for the `size` property in the CI stage cloud infrastructure runtime configuration. For example:
```yaml
platform:
os: Linux
arch: Amd64
runtime:
type: Cloud
spec:
size: xlarge # optional
```
Go to [Harness Cloud billing and cloud credits](/continuous-integration/troubleshooting-and-resources/ci-subscription-mgmt.md#harness-cloud-billing-and-cloud-credits) to review all available resource classes in Harness Cloud.
#### Hardware acceleration
Harness supports hardware acceleration using nested virtualization on Linux/AMD Cloud machines.
By enabling this feature, Android SDK tools and emulators can run more efficiently within virtualized environments, making Android test execution faster and optimizing build time.
To enable this feature, set the `nestedVirtualization` property to `true` as shown below.
{% hint style="info" %}
* To enable `nestedVirtualization` use the YAML editor, as this option is currently unavailable in the visual editor.
* When using hardware acceleration, run your steps directly on the VM, rather than inside a container. Running inside a container is currently not supported with hardware acceleration.
* Hardware acceleration is available for all machine sizes, when using Linux with AMD architecture on Harness Cloud.
{% endhint %}
```yaml
- stage:
name: build
identifier: build
type: CI
spec:
platform:
os: Linux
arch: Amd64
runtime:
type: Cloud
spec:
nestedVirtualization: true
size: xlarge # optional
```
### Access privately hosted resources
When running builds on Harness Cloud, you may need to access internal resources that are not publicly accessible, such as:
* Internal artifact repositories
* Private source code management systems (SCMs)
* Internal APIs and services
* On-premises databases
Harness supports multiple approaches to enable secure communication between Harness Cloud infrastructure and your private network:
1. **Cloud Private Connectivity** - Use Tailscale networking and customer subnet routers or App Connectors to reach private services from supported hosted builds and Platform connector operations. Go to [Cloud Private Connectivity](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/cloud-private-connectivity) for account availability, supported images, prerequisites, and configuration.
2. **IP allowlisting** - Allow Harness Cloud IP ranges through your firewall
3. **Private network connectivity** - Use cloud provider solutions like AWS PrivateLink or GCP Private Service Connect (Enterprise)
#### IP allowlisting
Your networking or security team can allowlist the IP ranges used by Harness Cloud to permit traffic from Harness-managed build infrastructure to your private resources.
Go to [Retrieve allowlisted IPs for Harness Cloud](https://developer.harness.io/harness-platform/use-harness-platform/references/allowlist-harness-domains-and-ips#retrieve-allowlisted-ips-for-hosted-ci-via-api) to retrieve allowlisted IPs via API.
Go to [Allowlist Harness domains and IPs](https://developer.harness.io/harness-platform/use-harness-platform/references/allowlist-harness-domains-and-ips) to review IP allowlisting in detail, or [contact Harness Support](https://support.harness.io/).
#### Private network connectivity (Enterprise)
For enterprise customers with strict compliance and security requirements, you can use cloud provider private networking solutions for enhanced security without exposing traffic to the public internet.
Go to [Harness Cloud Network and Security](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security) to review private network connectivity, including AWS PrivateLink and GCP Private Service Connect. Go to [IP allowlisting](https://developer.harness.io/harness-platform/use-harness-platform/references/network-and-security/ip-allowlisting) to allowlist Harness Cloud IP ranges.
### Queue Intelligence
With Queue Intelligence, Harness CI can queue and run build jobs in sequence when the build infrastructure receives more jobs than it can run concurrently.
The Queue Intelligence feature introduces a `queued` state for individual builds. Builds progress through the following states:
* `pending`: Build request created and waiting for a delegate. The maximum timeout for this state is 12 hours.
* `queued`: Build request queued by a delegate. The maximum timeout for this state is 12 hours. When viewing the build in the UI, this state is indicated by a **Queued license limit reached** message.
* `running`: The delegate runs a build for each build stage in the pipeline. The maximum timeout for this state is one hour.
### Harness Cloud best practices
Use these practices when you configure and run builds on Harness Cloud:
* Do not hardcode system environment variables. Use references such as `$HOME` or `$USER`.
* Do not hardcode the number of processors or threads. Use commands such as `nproc` to specify threads or jobs in build and test commands.
* Do not use tools that run only in a specific cloud environment, such as `gcloud`. Harness Cloud sources build VMs from different cloud providers. You cannot predict the cloud provider that hosts a VM during an execution. Avoid tools, such as `gsutil` or `gcloud`, that require a specific cloud provider environment.
* Review the [requirements for connectors and secrets](#requirements-for-connectors-and-secrets).
* Harness Cloud machine images can change. If your pipeline requires a specific software, tool, or environment version, [lock versions](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-vm-images#lock-versions-or-install-additional-tools) to prevent failures when the image changes.
* Add pipeline steps to [specify tool versions](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-vm-images#specify-versions), [lock versions, configure environments, or install additional tools](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-vm-images#lock-versions-or-install-additional-tools).
* Run `apt-get update` before [installing additional software](https://developer.harness.io/harness-platform/use-harness-platform/references/harness-cloud-vm-images#lock-versions-or-install-additional-tools) that might not be in the image package list.
### Troubleshoot Harness Cloud build infrastructure
Account verification error with Harness Cloud on a Free plan
Recently Harness has been the victim of several Crypto attacks that use our Harness-managed build infrastructure (Harness Cloud) to mine cryptocurrencies. Harness Cloud is available to accounts on the Free tier of Harness CI. Unfortunately, to protect our infrastructure, Harness now limits the use of the Harness Cloud build infrastructure to business domains and block general-use domains, like Gmail, Hotmail, Yahoo, and other unverified domains.
To address these issues, you can do one of the following:
* Use the local runner build infrastructure option, or upgrade to a paid plan to use the self-managed VM or Kubernetes cluster build infrastructure options. There are no limitations on builds using your own infrastructure.
* Create a Harness account with your work email and not a generic email address, like a Gmail address.
Cannot use STO steps with Harness Cloud macOS runners
Currently, [STO scan steps](https://developer.harness.io/security-testing-orchestration/use-sto/sto-scanner-configuration/security-step-settings-reference) aren't compatible with Harness Cloud macOS runners, because Apple's M1 CPU doesn't support nested virtualization. You can use STO scan steps with Harness Cloud Linux and Windows runners.
Harness Cloud compatibility with gsutil or gcloud
No, gsutil is deprecated. You should use gcloud-equivalent commands instead, such as `gcloud storage cp` instead of `gsutil cp`.
However, neither gsutil nor gcloud are recommended with Harness Cloud build infrastructure. Harness Cloud sources build VMs from a variety of cloud providers, and it is impossible to predict which specific cloud provider hosts the Harness Cloud VM that your build uses for any single execution. Therefore, avoid using tools (such as gsutil or gcloud) that require a specific cloud provider's environment.
Connector or delegate errors when using Harness Cloud
To use Harness Cloud build infrastructure, all connectors used in the stage must connect through the Harness Platform. This means that:
* GCP connectors can't inherit credentials from the delegate. They must be configured to connect through the Harness Platform.
* Azure connectors can't inherit credentials from the delegate. They must be configured to connect through the Harness Platform.
* AWS connectors can't use IRSA, AssumeRole, or delegate connectivity mode. They must connect through the Harness Platform with access key authentication.
For more information, go to [Use Harness Cloud build infrastructure - Requirements for connectors and secrets](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure#requirements-for-connectors-and-secrets).
To change the connector's connectivity mode:
1. Go to the **Connectors** page at the account, organization, or project scope. For example, to edit account-level connectors, go to **Account Settings**, select **Account Resources**, and then select **Connectors**.
2. Select the connector that you want to edit.
3. Select **Edit Details**.
4. Select **Continue** until you reach **Select Connectivity Mode**.
5. Select **Change** and select **Connect through Harness Platform**.
6. Select **Save and Continue** and select **Finish**.
Built-in Harness Docker Connector does not work with Harness Cloud
Depending on when your account was created, the built-in **Harness Docker Connector** (`account.harnessImage`) might be configured to connect through a Harness Delegate instead of the Harness Platform. In this case, attempting to use this connector with Harness Cloud build infrastructure generates the following error:
```
While using hosted infrastructure, all connectors should be configured to go via the Harness platform instead of via the delegate. \
Please update the connectors: [harnessImage] to connect via the Harness platform instead. \
This can be done by editing the connector and updating the connectivity to go via the Harness platform.
```
To resolve this error, you can either modify the **Harness Docker Connector** or use another Docker connector that you have already configured to connect through the Harness Platform.
To change the connector's connectivity settings:
1. Go to **Account Settings** and select **Account Resources**.
2. Select **Connectors** and select the **Harness Docker Connector** (ID: `harnessImage`).
3. Select **Edit Details**.
4. Select **Continue** until you reach **Select Connectivity Mode**.
5. Select **Change** and select **Connect through Harness Platform**.
6. Select **Save and Continue** and select **Finish**.
Use Xcode for a macOS build with Harness Cloud
Yes. Harness Cloud macOS runners include several versions of xcode as well as homebrew. For details, go to [Harness Cloud image specifications](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure#platforms-and-image-specifications). You can also [install additional tools at runtime](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure#lock-versions-or-install-additional-tools).
Get logs from a service during a Run step
Yes. To do this, you can add a step that runs in parallel to the Run step, and have that parallel step get the service's logs while the build runs. For an example, go to [Use a parallel step to monitor failures](https://developer.harness.io/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/articles/parallel-step-for-logging).
Use a Plugin step on hosted macOS runners
Hosted macOS runners cannot run Docker containers, which means you cannot use a containerized Plugin step. Download and run the plugin binary directly in a Run step instead. Go to [Using the plugin binary on hosted macOS runners](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/build-and-upload-artifacts/artifacts-tab#using-the-plugin-binary-on-hosted-macos-runners) for an example.
Harness Cloud macOS platform .netrc file has incorrect permissions
There is a known issue impacting macOS machines on [Harness Cloud build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md) due to incorrect permissions for the `.netrc` file at `/Users/anka/.netrc`. The permissions are set to `644` when they should be `600`.
This can cause errors when installing Cocoapods. If your build installs Cocoapods, uses a macOS platform on Harness Cloud build infrastructure, and fails due to an error like `Couldn't determine repo type for URL` when installing Cocoapods, then, until this issue is fixed, make sure the pipeline edits the permissions on the `.netrc` file before attempting to install Cocoapods.
Harness Cloud Windows platforms cannot clone BitBucket Cloud repositories
Due to a [BitBucket Cloud issue](https://jira.atlassian.com/browse/BCLOUD-23158), specific versions of BitBucket Cloud could fail to clone repos on Windows platforms running Git version 2.44.
Atlassian released a fix for this issue; however, if you use a Harness Cloud Windows platform and your build is unable to clone your BitBucket Cloud repo, do the following:
1. [Disable Clone Codebase](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md#disable-clone-codebase-for-specific-stages).
2. At the beginning of your build stage, add a [Run step](/continuous-integration/use-harness-ci/use-harness-ci/run-step-settings.md) that uses the `harness/drone-git` image and Git commands to clone your BitBucket cloud repo.
### Next steps
* [Set up Kubernetes cluster build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure.md): Set up, secure, and customize Kubernetes cluster build infrastructure to run Harness CI builds
* [Set up VM build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/vm-build-infrastructure.md): Set up VM build infrastructures on AWS, Azure, GCP, or macOS to run Harness CI builds and configure high availability
* [Set up local runner build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/define-a-docker-build-infrastructure.md): Define a CI build infrastructure on any Linux or macOS host
{% @harness-feedback/feedback %}