Skip to main content
Type: rvn-eks-worker / Latest version: 1.0.0

​
Dependencies and consumers

Every dependency input can be specified manually to reference existing external infrastructure rather than a Ravion module. Set the dependency input to null and set its mapped inputs directly; see Use existing infrastructure instead of a module reference.

​
Readme

Background worker on EKS for running a long-lived private process with no exposed port, and no Kubernetes manifests or Helm charts to write.

​
Overview

EKS Worker runs queue consumers, event processors, and other long-lived background processes on an existing Ravion EKS cluster. Point it at a Git repository or an image you already have, set the start command, resources, and pod count in a form, and Ravion builds the image and keeps the process running on your cluster. There are no Kubernetes manifests to write and no Helm charts to maintain. Under the hood, each deploy installs a Helm chart that Ravion maintains - a packaged template of the Kubernetes resources a worker needs. The rvn-eks-worker chart renders the Deployment that runs your pods, a ServiceAccount, an optional HorizontalPodAutoscaler, and, when the module declares runtime secrets, an ExternalSecret. Each release runs helm upgrade --install --atomic, so a failed deploy rolls back to the previous revision on its own. The chart deliberately includes no Service, no container port, and no probes. A worker is reached by nothing; it reaches out. The Terraform stack creates the ECR repository that Dockerfile and Railpack builds push to and, when Fargate is selected, a workload-specific EKS Fargate profile and pod execution role. On the Pull from image registry path with automatic or EC2 compute, the stack creates no AWS resources. Everything else the module needs - cluster endpoint, certificate authority data, private subnet IDs, and the Ravion Runner role - comes from the selected EKS Cluster module. Chart source: ravionhq/modules/charts/rvn-eks-worker Terraform source: ravionhq/modules/compute/eks_service

​
Use cases

​
Prerequisites

  • An EKS Cluster module.
  • An EKS Add-ons module attached to that cluster with KEDA enabled, if using Spot burst.
  • The External Secrets Operator add-on on that cluster, if the worker uses Runtime secrets.

​
Build and image options

For Dockerfile and Railpack builds, provide Git repository and optionally Source base path. The stack creates an ECR repository named after the worker, Ravion pushes each build to it, and the chart deploys the resulting digest. Nodes pull from same-account ECR with their own credentials, so no pull secret is involved. A worker built with Railpack often shares a repository with the web service in front of it. Railpack’s detected start command is rarely the worker’s command, so set the worker’s entrypoint below rather than relying on the image default. Use Build environment variables for values the build itself needs - a private registry token, a NODE_ENV that changes what gets compiled. Values can be plain strings or references loaded from Parameter Store or Secrets Manager. For Dockerfile builds, turn on Inject environment variables in Dockerfile to pass them to the build as Docker build arguments; without it they are visible to the builder but not to docker build. These are separate from Runtime environment variables further down, and deliberately so: a credential needed to install dependencies has no business being in the running pod’s environment. Anything both halves need has to be set in both places. For Pull from image registry, provide the Image repository without a tag, and use Image pull secret names for a private registry - each entry names a Kubernetes Secret of type kubernetes.io/dockerconfigjson that already exists in the release namespace. Whichever source you choose, the deploy takes an Image tag or digest. A value beginning with sha256: is used as a digest and everything else as a tag. Workers usually need a command: use Start command to override the image entrypoint and Start command arguments to override its default arguments. For example, entrypoint bundle with arguments exec sidekiq.

​
Builder settings

Builder settings apply to Dockerfile and Railpack builds only. Scan images on push asks ECR to run its basic vulnerability scan on every pushed image. Force delete image repository lets the repository be destroyed while it still holds images; without it, destroying the module fails until the repository is emptied.

​
Resources and scaling

Kubernetes schedules on requests and enforces on limits. CPU is measured in cores or millicores: 1 is one vCPU and 100m is a tenth of one. Memory uses binary units: 256Mi, 1Gi (1024Mi). Fargate creates a dedicated profile matching this worker’s namespace and standard app instance label. Fargate pods launch only in the selected cluster’s private subnets and use on-demand capacity; EKS Fargate does not offer Spot pricing. Choose EC2 Spot instead when interruption tolerance and lower compute cost matter more than serverless pod placement. Autoscaling is off by default, unlike the web module. CPU utilization is a poor proxy for worker demand: a worker blocked on a queue poll uses almost no CPU no matter how deep the backlog. Enable it when the work is genuinely CPU-bound, and prefer a fixed pod count otherwise.

​
KEDA Spot burst

Spot burst is optional and off by default. Enable it only with Compute target set to EC2 on-demand; configure Baseline pods (default 2, minimum 1), Minimum Spot pods (default 0), Maximum Spot pods (default 8, minimum 1), Polling interval (secs) (default 30), Cooldown period (secs) (default 300), and the required KEDA triggers array. The On-Demand baseline remains fixed while a separate Spot Deployment starts at the configured minimum. If that minimum is zero, CPU- or memory-only triggers cannot wake the pool; choose a signal that reports demand with no Spot application pods running, and set thresholds with baseline capacity in mind. Select KEDA in the EKS add-ons module and apply the add-ons before enabling burst mode. Authentication resources and any referenced Kubernetes Secrets must be provisioned separately in the appropriate namespace or cluster scope. Put references, not credentials, in the trigger configuration; this module does not create trigger IAM permissions. KEDA 2.20.2’s published Kubernetes test matrix covers versions 1.33–1.35; verify compatibility with newer clusters, including 1.36, in staging. The Spot Deployment reuses the same image and pod configuration, so review duplicate job processing and idempotency before enabling it; no application code or configuration is migrated automatically. Each active Spot pod and the KEDA controllers add cost, and Spot capacity may be interrupted or unavailable. A new Spot Deployment starts at the configured minimum. On Helm upgrades, its live replica count is preserved unless below that minimum; counts above the maximum are left for KEDA to reconcile. Offline renders show the configured minimum, and the deployment identity needs permission to read Deployments in the namespace. When the minimum is zero, no Spot image is exercised until KEDA activates it; verify readiness separately in staging. Validate permissions, trigger behavior, and scaling before production. Stop timeout (secs) is the window a pod gets after SIGTERM to finish in-flight work before it is killed. The default of 30 seconds suits short tasks. Raise it to at least the length of your longest job, or a rollout will kill work mid-flight.

​
Zone placement

Worker pods are spread across the cluster’s availability zones with a soft topology.kubernetes.io/zone spread constraint, so a small cluster never leaves pods pending. Combined with the zone-local routing the EKS Web Service and EKS Cluster modules apply, a worker’s calls to other services and to DNS stay inside its own zone whenever a destination pod exists there, which keeps AWS cross-AZ data transfer charges off that traffic.

​
Application configuration

Use Runtime environment variables for plain values, as an array of {name, value} objects. Use Deploy-provided environment variables to allow a pipeline deploy step to set selected plain values. They cannot replace a Runtime environment variable or Runtime secret. Use Runtime secrets for sensitive values, as an array of {name, value_from} objects - the same shape as ECS. value_from must be a full Secrets Manager or SSM Parameter Store ARN, including the JSON-key extraction suffix when you want a single key out of a JSON secret. Ravion never reads these values. The ARNs travel to the chart as references, the chart renders an ExternalSecret, and the External Secrets Operator materializes the Kubernetes Secret in the cluster. No secret value reaches Ravion, the Helm values document, or the Helm release history.

​
Deployment

Every deploy runs helm upgrade --install --atomic, so a release either lands completely or leaves the cluster on the previous revision. Pods roll with zero unavailable. Maximum rollout surge (%) defaults to 100%, allowing a full replacement set to start together when enough matching capacity is already available. Lower this advanced setting to limit temporary capacity. The disruption budget controls voluntary evictions such as node drains, not Deployment rolling updates; shutdown grace still allows old workers to finish in-flight work. Deployments collapse: if several are queued, only the newest runs.

​
Metrics and logs

The Metrics and Logs tabs follow the providers selected on the EKS add-ons module referenced above. You configure observability once, on that module, and every workload attached to it follows; there is nothing to set here. Without an add-ons reference both tabs stay empty. Where several providers can serve the same signal they form a fallback chain, not a merge. The tab reads the first store that can answer right now and moves to the next when it cannot, saying which store it ended up using. Reading two stores at once would draw every line twice. The practical effect is that the in-cluster store’s one weakness stops being fatal. Loki is reached through the Ravion Operator, so with the agent offline those logs are unavailable - but if CloudWatch Logs is also selected, the tab shows CloudWatch and says so, then switches back when the agent returns. Charts are the same five golden signals whichever store answers: CPU, memory working set, container restarts, network in, and network out. Two things differ on the CloudWatch link of the chain, and are worth knowing before you read a number off it:
  • CPU uses different units by provider. Prometheus shows usage as a percentage of the running pods’ CPU requests, matching the autoscaler’s CPU target; CloudWatch reports cores. Other Prometheus charts sum across pods; CloudWatch averages across them.
  • It needs enhanced observability, which the add-ons module turns on with CloudWatch by default. Without it, CPU and memory come back empty.
Replicas available and desired have no CloudWatch equivalent. Container Insights’ nearest metric counts pods behind a Kubernetes Service, and a worker renders no Service, so with CloudWatch as the only metrics provider those two charts are empty while the pod charts still work. A provider that ships to a vendor rather than rendering in Ravion - Datadog, Grafana Cloud, New Relic, OpenSearch, Splunk, or a custom OTLP endpoint - adds an Open in … action to the tab, pointing at this worker rather than at the vendor’s front page. Turning a signal off on the add-ons module empties the matching tab here.

​
Configuration

​
Design decisions

  • Terraform owns AWS-side workload infrastructure. The worker itself is Helm-owned; the stack creates an ECR repository when Ravion builds the image and a dedicated EKS Fargate profile when Fargate is selected. With a pulled image and automatic or EC2 compute, it creates nothing.
  • No Nixpacks. ECS still carries a Nixpacks build source for services created before Railpack existed. EKS has no such history, so Dockerfile and Railpack are the only builders.
  • No Service and no probes. A worker exposes no port, so there is nothing to route to and no HTTP endpoint to check. Liveness for a worker is better expressed by letting the process exit on a fatal error and letting Kubernetes restart it.
  • Autoscaling defaults off. CPU utilization rarely tracks worker demand. Turning it on by default would produce autoscaling that looks configured but never fires.
  • Name and namespace are fixed after creation. Together they identify the Helm release that rollback and history target.
  • Pod Identity, not IRSA. The chart emits a stable ServiceAccount name and no role annotation. With Create IAM role on, the stack creates the role and an aws_eks_pod_identity_association binding it to that ServiceAccount by namespace and name; the trust policy is pinned to this cluster and account. No IAM OIDC provider is involved.

​
Learn more

​
Inputs reference

All inputs for rvn-eks-worker version 1.0.0. Use the name shown for each field as the input key in module config.
  • Inputs — EKS cluster, Worker service, Build config, Dockerfile, Railpack, Image, Container resources, Autoscaling, Environment variables, IAM roles and policies, Networking and deployment, Builder config, Image registry lifecycle, Misc, Terraform settings