Configuring Container Resource Limits and Reserves
Managing container CPU and memory (RAM) resources is critical to running reliable, performant applications. Cycle's container resources model exposes flexible controls that help users achieve this.
This guide covers:
- Why resource configuration matters
- What the defaults are for containers on Cycle
- How to set RAM and CPU reserves & limits
- Reviewing different telemetry and metrics reporting
Why Resource Configuration Matters
When working with a single server or even just a few, it might not seem like setting resource configurations is paramount… and in those scenarios, it might not be. But, as a product scales, container resource configuration plays a vital role in maintaining both application and infrastructure stability, performance, and utilization. Without clearly defined CPU and memory boundaries, either or both layers may experience unpredictable behavior.
Here are just a few ways configuring container resources can help:
- Reliability and Stability
- Performance Consistency
- Better Utilization and Density
- Operational Visibility for Later Decisions
Resource Configuration and Cycle Stacks
Configuring individual containers through the portal or API is a great way to manage:
- Stateful workloads
- Containers with infrequent image changes
- Containers with infrequent code changes
For these types of workloads, it's fine to use the portal or API to configure and manage. For workloads that teams deploy often, we generally will recommend using stacks. Stacks provide an as-code representation of configurations that teams can version control and are very useful with other automation pieces like pipelines.
For those who have never worked with stacks before, there is an in-depth primer on this page.
The rest of this guide will focus on individual container level settings. If there are questions on whether to use a stack for a given workload(s), ping the community or the Cycle team directly through Slack , we love to chat about these things.
Limits and Reserves
A limit is the maximum amount a container instance can use of a resource.
A reserve is how much of the underlying resource that the platform sets aside for each instance of the container being configured.
Finding Container Resource Configuration in Portal
The best way to get familiar with these settings and to follow along with the guide is to use the Cycle portal and interact with a container directly via container configurations.
If the hub has no servers, environments, containers online, or a starting point is just needed - check out this guide for getting started.
Navigating to the container configuration:
- Starting from the main dashboard, click on Environments
- Select the dropdown from the top of the page and select the environment to work from.
- Click Containers from the horizontal navigation.
- Select the container to work with from the list.
- In the container modal, there is a nav option for Config on the left hand side.
- Once on the config page, either scroll down to Resources or select it from the mini-nav.
- Enable the Resources section.
Saving Configuration Changes
The Save Container button at the bottom right corner of the config page will need to be used to save the configuration changes each time the container is changed.
This will restart the container.
Resource Defaults
Any container that does not have a resource configuration will be set to the default. The default configuration for limits on CPU are:
Cycle uses the following rules to calculate CPU max usage:
| Deployment Scenario | Core Count | Default CPU Usage Limit |
|---|---|---|
| Default Deployment Strategy | ≤ 2 cores | Max 10 shares (1 vCPU or thread) |
| Default Deployment Strategy | > 2 cores | Max 50% of available shares (half of available cores) |
| Deployment Scenario | Core Count | Default CPU Usage Limit |
|---|---|---|
| High Availability or Manual Strategy | ≤ 4 cores | Max 20 shares (2 Cores) |
| High Availability or Manual Strategy | > 4 cores | Max 50% of available shares (half of available cores) |
For servers that have 2 threads or less, a maximum of 10 shares is given by default as a limit. There is more information in the platform documentation for container resources.
The total number of shares available for a given server is shown on that server's dashboard. To learn more about shares, check out this specific section on container resources.
Setting RAM
Setting the RAM limits and reserves is very straightforward.
The configuration allows for setting in units of megabytes, gigabytes, and terabytes.
This is the easy part because RAM limits and reserves are enforceable and can be set reliably.
Stateful Container Priority
If a server runs out of RAM, the platform will terminate stateless instances before stateful ones. Stateful containers are prioritized because they are typically more critical than stateless workloads.
Setting CPU
Setting CPU limits and reserves requires a bit more nuance than RAM. CPU is a shared resource, meaning enforcement works differently from memory allocation.
For example, 2 containers can process tasks on the same underlying thread, while the same 2 containers cannot store data to the same underlying memory space.
CPUs rely on shares - this is a Cycle specific abstraction on reserving CPU clock. Each share represents 10% of the clock time on an underlying thread. So 10 shares represents 100% of the clock on that thread.
If the container expects access to a minimum of 2 threads, but the desired upper limit is 4 threads, the following would be set for CPU:
- limit - 40
- reserve - 20
For a limit that represents unlimited CPU usage on the server, use the value 0 for the limit.
The word reserve and allocation is at times used interchangeably. This is especially true for CPU reserves being referred to as CPU Allocations on the server dashboard.
The reserve values are also reflected on the server dashboard as CPU Allocations.
Threads and Cores
Cycle supports a very wide range of server types. Virtual machines will generally have a virtualized CPU (vCPU) where each vCPU is 1 thread. Most modern bare metal servers have hyperthreading, which is 2 threads per core.
To determine any server's CPU type and threading, check out the server's dashboard, where the portal displays any data we have on CPU's in the summary on the far right of the page.
Overcommitting Resources
RAM is a fixed amount of physical memory on the underlying server, so RAM reserves cannot be overcommitted.
CPU works differently. On Cycle, CPU resources are configured using shares, which represent a portion of available CPU time rather than a fixed physical quantity. Because CPU is a shared resource, it can be overcommitted.
In practice, overcommitting CPU means allowing the total configured CPU shares on a server to exceed the server's directly available capacity. This works when workloads are unlikely to demand their full configured CPU at the same time.
If CPU overcommit will be used, [the server settings for overcommit must be enabled])(/portal/server-settings#advanced-updates).
Troubleshooting Using Server Dashboard
Server dashboards show usage as a total across all container instances for that server. If testing is being done on a single server and it's showing different values for the container instance telemetry than the server itself, there are a few things that can cause this.
Graph Axis Distinctions
A common hang up is based on server vs instance axis differences. The upper limit of the container instance CPU configuration is generally not 100% of the server's available CPU. In this case, it is common to observe an instance telemetry graph showing 80% usage while the server chart shows only 20 or 40%.
The thing to pay attention to here is the instance axis shows the percentage usage based on what it has access to, while the server shows the usage as a whole.
Codifying Resource Constraints
Once the settings have been tested and are in line with expectations, it is common practice to codify them in a stack, or to deploy custom configurations using the API.
If you have more questions about resource limits/allocations, reach out via our community , or through the community Slack