|
| 1 | +--- |
| 2 | +title: Build autoscaling |
| 3 | +description: How to enable and configure container build autoscaling to parallelize builds across multiple builders |
| 4 | +--- |
| 5 | + |
| 6 | +import {ImageWithCaption} from '~/components/Image' |
| 7 | + |
| 8 | +Container build autoscaling allows you to automatically scale out your builds to multiple BuildKit builders based on the number of concurrent builds you want to process on a single builder. This feature is available on all Depot plans and can significantly speed up your container builds when you have multiple concurrent builds or resource-intensive builds. |
| 9 | + |
| 10 | +## How build autoscaling works |
| 11 | + |
| 12 | +By default, all builds for a project are routed to a single BuildKit host per architecture you're building. Each BuildKit builder can process multiple jobs concurrently on the same host, which enables deduplication of work across builds that share similar steps and layers. |
| 13 | + |
| 14 | +With build autoscaling enabled, Depot will automatically spin up additional BuildKit builders when the concurrent build limit is reached. Here's how the process works: |
| 15 | + |
| 16 | +1. You run `depot build`, which informs our control plane that you'd like to run a container build |
| 17 | +2. The control plane checks your autoscaling configuration to determine the maximum concurrent builds per builder |
| 18 | +3. If the current builder is at capacity, the provisioning system spins up additional BuildKit builders |
| 19 | +4. Each additional builder operates on a clone of the main builder's layer cache |
| 20 | +5. The `depot build` command connects directly to an available builder to run the build |
| 21 | + |
| 22 | +<ImageWithCaption |
| 23 | + src="/images/depot-container-build-architecture-autoscaling.webp" |
| 24 | + alt="Depot container build architecture with autoscaling" |
| 25 | + title="Depot container build architecture with autoscaling" |
| 26 | + className="mx-auto" |
| 27 | +/> |
| 28 | + |
| 29 | +## When to use build autoscaling |
| 30 | + |
| 31 | +Build autoscaling is particularly useful in these scenarios: |
| 32 | + |
| 33 | +- **High concurrent build volume**: When you have many builds running simultaneously that consume all resources of a single builder |
| 34 | +- **Resource-intensive builds**: When individual builds require significant CPU, memory, or I/O resources |
| 35 | +- **Time-sensitive builds**: When you need to reduce build queue times during peak periods |
| 36 | +- **CI/CD pipelines with parallel jobs**: When your pipeline triggers multiple builds at once |
| 37 | + |
| 38 | +### When NOT to use build autoscaling |
| 39 | + |
| 40 | +Consider these tradeoffs before enabling autoscaling: |
| 41 | + |
| 42 | +- **Cache efficiency**: Additional builders operate on cache clones that are not written back to the main cache, reducing cache hit rates |
| 43 | +- **Deduplication loss**: Builds on different builders cannot share work, even if they have similar layers |
| 44 | +- **Small, infrequent builds**: If your builds are small and run infrequently, the overhead may not be worth it |
| 45 | + |
| 46 | +**Recommendation**: Before enabling autoscaling, first try sizing up your container builder. You can select larger builder sizes on our [pricing page](/pricing), which allows you to run larger builds on a single builder without needing to scale out. |
| 47 | + |
| 48 | +## How to enable build autoscaling |
| 49 | + |
| 50 | +To enable container build autoscaling: |
| 51 | + |
| 52 | +1. Navigate to your Depot project settings |
| 53 | +2. Go to the **Settings** tab |
| 54 | +3. Find the **Build autoscaling** section |
| 55 | +4. Toggle **Enable horizontal autoscaling** |
| 56 | +5. Set the **Maximum concurrent builds per builder** (default is 1) |
| 57 | +6. Click **Save changes** |
| 58 | + |
| 59 | +<ImageWithCaption |
| 60 | + src="/images/depot-enable-horizontal-autoscaling.webp" |
| 61 | + alt="Enabled horizontal autoscaling on a Depot project" |
| 62 | + title="Enabled horizontal autoscaling on a Depot project" |
| 63 | + className="mx-auto" |
| 64 | +/> |
| 65 | + |
| 66 | +The concurrent builds setting determines how many builds can run on a single builder before triggering a scale-out event. For example: |
| 67 | + |
| 68 | +- Setting it to `1` means each build gets its own dedicated builder |
| 69 | +- Setting it to `3` means up to 3 builds can share a builder before a new one is launched |
| 70 | + |
| 71 | +## Cache behavior with autoscaling |
| 72 | + |
| 73 | +Understanding cache behavior is crucial when using autoscaling: |
| 74 | + |
| 75 | +### Cache cloning |
| 76 | + |
| 77 | +When additional builders are launched due to autoscaling: |
| 78 | + |
| 79 | +1. They receive a **read-only clone** of the main builder's layer cache |
| 80 | +2. New layers built on scaled builders are stored locally but **not persisted** back to the main cache |
| 81 | +3. When the scaled builder terminates, its local cache changes are lost |
| 82 | + |
| 83 | +### Cache implications |
| 84 | + |
| 85 | +This means: |
| 86 | + |
| 87 | +- Builds on scaled builders can read from the main cache |
| 88 | +- They cannot contribute new layers back to the main cache |
| 89 | +- Subsequent builds may need to rebuild layers that were already built on scaled builders |
| 90 | +- Cache efficiency may decrease with heavy autoscaling usage |
| 91 | + |
| 92 | +## Billing and costs |
| 93 | + |
| 94 | +Build autoscaling is available on **all Depot plans** at no additional cost: |
| 95 | + |
| 96 | +- **No extra charges**: Autoscaling itself doesn't incur additional fees |
| 97 | +- **Standard compute rates**: You pay the same per-minute rate for scaled builders as regular builders |
| 98 | +- **No cache storage charges**: Cache clones are temporary and don't count toward your storage quota |
| 99 | +- **Pay for what you use**: Scaled builders are terminated when not in use |
| 100 | + |
| 101 | +## Best practices |
| 102 | + |
| 103 | +1. **Monitor your builds**: Use Depot's build insights to understand your build patterns before enabling autoscaling |
| 104 | +2. **Start conservative**: Begin with a higher concurrent build limit and decrease if needed |
| 105 | +3. **Size up first**: Consider using larger builder sizes before enabling autoscaling |
| 106 | +4. **Review cache hit rates**: Monitor if autoscaling significantly impacts your cache efficiency |
| 107 | +5. **Adjust during peak times**: You can dynamically adjust settings based on your build patterns |
| 108 | + |
| 109 | +## Example configuration |
| 110 | + |
| 111 | +Here's an example of when autoscaling might be beneficial: |
| 112 | + |
| 113 | +**Scenario**: Your team has resource-intensive builds that compile large applications with heavy dependencies. Each build requires significant CPU and memory resources, and you frequently have multiple builds running concurrently due to: |
| 114 | + |
| 115 | +- Multiple developers pushing code simultaneously |
| 116 | +- CI pipelines that build multiple variants of your application (different environments, architectures, or configurations) |
| 117 | +- Monorepo setups where changes trigger builds for multiple services |
| 118 | + |
| 119 | +**Without autoscaling**: |
| 120 | + |
| 121 | +- Multiple resource-intensive builds compete for CPU and memory on a single builder |
| 122 | +- Builds experience CPU throttling and memory pressure |
| 123 | +- Build times increase dramatically when multiple builds run concurrently |
| 124 | +- Builds may fail due to out-of-memory errors when too many run simultaneously |
| 125 | + |
| 126 | +**With autoscaling** (max 1 concurrent build per builder): |
| 127 | + |
| 128 | +- Each resource-intensive build gets its own dedicated builder with full access to 16 CPUs and 32GB RAM |
| 129 | +- No resource contention between builds |
| 130 | +- Consistent, predictable build times regardless of concurrent load |
| 131 | +- Builds can fully utilize available compute resources without interference |
| 132 | + |
| 133 | +**Example build characteristics that benefit from this configuration**: |
| 134 | + |
| 135 | +- Large Docker images with many layers (>50 layers) |
| 136 | +- Compilation of languages like Rust, C++, or Go with extensive dependencies |
| 137 | +- Machine learning model training or data processing during build |
| 138 | +- Multi-stage builds with resource-intensive compilation steps |
| 139 | +- Builds that require significant disk I/O for dependency installation |
| 140 | + |
| 141 | +Result: Each build runs with dedicated resources, preventing resource contention and ensuring optimal performance even during peak usage. |
| 142 | + |
| 143 | +## Troubleshooting |
| 144 | + |
| 145 | +If you're experiencing issues with autoscaling: |
| 146 | + |
| 147 | +1. **Builds still queueing**: Verify autoscaling is enabled and check your concurrent build limit |
| 148 | +2. **Increased cache misses**: This is expected behavior with cache clones - consider if the speed benefit outweighs cache efficiency |
| 149 | +3. **Costs increasing**: Monitor your usage in the Depot dashboard and adjust concurrent limits if needed |
| 150 | + |
| 151 | +For additional help, reach out on [Discord](https://depot.dev/discord) or contact support. |
0 commit comments