Kubernetes

Search…
Kubernetes
Overview
Kubernetes isn't a CI per-se, but it can serve as the underpinning for many modern CI systems. As such, this example serves as a bare-bones example to base your implementations on.
Compatibility
earthly has been tested with the all-in-one earthly/earthly mode, and works as long as the pod runs in a privileged mode.
It has also been tested with a single remote earthly/buildkitd running in privileged mode, and an earthly/earthly pod running without any additional security concerns. This configuration is considered experimental. See these additional instructions.
Multi-node earthly/buildkitd configurations are currently unsupported.
Resources
​Kubernetes Documentation​
​Kubernetes Taints & Tolerations​
Setup (earthly/earthly Only)
This is the recommended approach when using Earthly within Kubernetes. Assuming you are following the steps outlined in the overview, here are the additional things you need to configure:
Dependencies
Your Kubernetes cluster needs to allow priveleged mode pods. It's possible to use a separate instance group, along with Taints and Tolerations to effectively segregate these pods.
Installation
The default image from earthly/earthly should be sufficient. If you need additional tools or configuration, you can create your own runner image.
Configuration
In some instances, notably when using Calico within your cluster, the MTU of the clusters network may end up mismatched with the internal CNI network, preventing external communication. You can set this through the CNI_MTU environment variable to force a match.
earthly/earthly currently requires the use of privileged mode. Use this in your container spec to enable it:
1
securityContext:
2
  privileged: true
Copied!
The earthly/earthly container will operate best when provided with decent storage for intermediate operations. Mount a volume like this:
1
volumeMounts:
2
  - mountPath: /tmp/earthly
3
    name: buildkitd-temp
4
...
5
volumes:
6
  - name: buildkitd-temp
7
    emptyDir: {} # Or other volume type
Copied!
The location within the container for this temporary folder is configurable with the EARTHLY_TMP_DIR environment variable.
The earthly/earthly image will expect to find the source code (with Earthfile) rooted in /workspace. To configure this, ensure that the SRC_DIR environment variable is set correctly. In the case of the example, we are building a remote target, so mounting a dummy volume is needed.
Setup (Remote earthly/buildkitd)
Note
This an experimental configuration.
It is possible to run multiple earthly/buildkitd instances in Kubernetes, for larger deployments. Follow the configuration instructions for using the earthly/earthly image above.
There are some caveats that come with this kind of a setup, though:
1.Some local cache is not available across instances, so it may take a while for the cache to become "warm".
2.Builds that occur across multiple instances simultaneously may fail in odd ways. This is not supported.
3.The TLS configuration needs to be shared across the entire fleet.
Configuration
To mitigate some of the issues, it is recommended to run in a "sticky" mode to keep builds pinned to a single instance for the duration. You can see how to do this in our example:
1
# Use session affinity to prevent "roaming" across multiple buildkit instances; if needed.
2
sessionAffinity: ClientIP
3
sessionAffinityConfig:
4
  clientIP:
5
    timeoutSeconds: 600 # This should be longer than your build.
Copied!
Example
Note
This example is not production ready, and is intended to showcase configuration needed to get Earthly off the ground. If you run into any issues, or need help, don't hesitate to reach out!
See our Kubernetes examples.
To run it yourself, first you will need to install some prerequisites on your machine. This example requires kind and kubectl to be installed on your system. Here are some links to installation instructions:
​kind Quick Start​
​Install kubectl​
When you are ready, clone the ci-examples repository, and then run (from the root of the repository):
1
earthly ./kubernetes+start
Copied!
Running this target will:
Create a kind cluster named earthlydemo-aio
Create & watch a job that runs an earthly build
When the example is complete, the cluster is left up and intact for exploration and experimentation. If you would like to clean up the cluster when complete, run (again from the root of the repository):
1
earthly ./kubernetes+clean
Copied!