Constraining Memory in Acorn

In our most recent update of Acorn, v0.5.0, we added the ability to constrain memory. This is a great way of defining how much memory you would like allocated to your application. Constraining the amount of resources is an important concept for administrators of an Acorn installation and thus users of that installation.

In this post we will go over how you can integrate this into your current acorns to ensure resource preservation.

Ways to set the memory constraints

There are several ways of constraining memory for your application and all come with an order of precedence. To generalize, Acorn will take the most specific to the least specific memory definitions.

1. acorn run --memory foo=512Mi example (where bar is a workload in the example acorn)
2. Via the memory (or mem) property for workloads in the Acornfile.
3. acorn install --workload-memory-default=512Mi

Another section of the memory feature worth noting is the install flag --workload-memory-maximum. This flag sets a maximum that when exceeded prevents the offending acorn from being installed. This is useful if you are an administrator for your Acorn installation and do not want users of your installation to use too much memory for their applications.

Let’s walk through a couple of examples to understand setting memory in Acorn better.

Acceptable memory values

Memory in Acorn is defined by the binary representations of bytes. These include:

• Ki
• Mi
• Gi
• Ti
• Pi
• Etc.

The Acornfile and CLI flags will recognize these and validate them for you in a standard way. As a result, 1Gi will be valid anywhere memory is referenced. Under-the-hood, these values are getting translated directly to bytes so you can also pass the raw amount of bytes without any prefixes.

Lastly, 0 is a special value that denotes the memory should not have a limit. This too is applicable for all place memory is reference.

Setting memory in action

For administrators of an Acorn installation, there is the ability to set a maximum and default amount of memory for the users of the Acorn installation. This allows us to ensure that current and future acorns that are deployed will not exceed our resources limits. Let’s say that we want a default memory of 512Mi and a maximum memory of 1Gi, we would run the following command to install or update our Acorn installation.

$ acorn install —-workload-memory-default=512Mi --workload-memory-maximum=1Gi

Any acorns that are installed but do not have memory defined will now use the default memory. Let’s define an acorn that will utilize the default memory.

containers: {
    foo: {
        image: “fooimage”
    }
}

jobs: {
    bar: {
        image: “barimage”
    }
}

If we run this acorn, each workload will get a memory of 512Mi as was defined by the default. However, what if we want to define a non default value? Well, we can do so with the new memory property for workloads (a new concept that aggregates both containers and jobs together conceptually).

containers: {
    foo : {
        image: “fooimage”
        memory: 123Mi // mem is also valid
    }
}

jobs: {
    bar: {
        image: “barimage”
    }
}

Running this acorn will define a memory of 123Mi for the foo workload while setting the default memory for the bar workload. What if we define an acorn that exceeds the maximum memory that we defined?

containers: {
    foo: {
        image: “fooimage”
        memory: 2Gi // exceeds the maximum
    }
}

jobs: {
    bar: {
        image: “barimage”
    }
}

And then try to run it…

$ acorn run -n example .
✗  ERROR:  App.api.acorn.io "example" is invalid: spec.image: Invalid value: "2Gi": invalid memory from Acornfile: workload “foo” with memory of 2Gi exceeds the workload-memory-maximum of 1Gi

As expected, this message tells us that we have defined a memory of 2Gi in the Acornfile which exceeds the maximum of 1Gi.

Say that we do not have access to edit the Acornfile but still want to run this Acorn. We can successfully deploy acorn this by increasing the maximum or by overwriting the workload’s define memory at runtime.

For the sake of tutorial, let’s say that we’re not an administrator and cannot update Acorn. Then our only option is to override the value at runtime.

$ acorn run -n example memory exampleContainer=1Gi . # success!

What if all of the workloads in the acorn exceed the maximum memory? We are able to override all workloads in an acorn by just not defining a workload for the --memory run flag.

$ acorn run -n example memory 1Gi . # success!

You can also do a combination of the two.

$ acorn run -n example --memory 1Gi --memory bar=512Mi . # success!

Lastly, we are also able to define memory with no limit by setting its value to 0. By default, every Acorn installation comes with a default and maximum memory of 0. However, in our current example, we set the maximum to be a non-default value of 1Gi. If we run an acorn where the memory is set to be 0 but the maximum is not 0, then that acorn will instead get the maximum amount of memory.

$ acorn run -n example --memory 0 . # all workloads will get the maximum memory (1Gi)

This works the same way if the default is 0 but the maximum is not.

$ acorn install --workload-memory-default 0 # maximum is still 1Gi
$ acorn run . # all workloads using the default memory will get the maximum memory (1Gi)

This is useful if you want your workloads to use the maximum amount that they are allowed.

Wrapping up

In this post we went over the memory feature added to Acorn in v0.5.0. We talked about why you would want to constrain memory and the flexibility you have in setting its constraint. If you have more questions, or just want to read up on Acorn in general, check our documentation around memory here.