EKS Helm Chart

Type: rvn-eks-chart / 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

Install any Helm chart onto an EKS cluster: NATS, Redis, Grafana, cert-manager, or anything else published to a Helm repository or an OCI registry, and charts you keep in a Git repository.

Overview

EKS Helm Chart deploys a chart onto an existing Ravion EKS cluster: one someone else publishes, or one you keep in a Git repository. Point it at a chart and a version, write the values you want in JSON, and Ravion installs the release. Each deploy runs helm upgrade --install --atomic, so a failed deploy rolls back to the previous revision automatically. Unlike EKS Web Service and EKS Worker, this module has no build and no image. The chart decides which Kubernetes resources to create, and your values configure them. Terraform source: ravionhq/modules/compute/eks_service

Use cases

Scenario	EKS Helm Chart helps by…
Messaging and streaming	Running NATS, RabbitMQ or Kafka inside the cluster
Caches and datastores	Installing Redis, Valkey or other stateful charts
Cluster tooling	Adding operators and controllers that are not EKS add-ons
Vendor agents	Installing an agent chart that a vendor publishes
Your own manifests	Shipping ConfigMaps, dashboards or policies you keep in a repository as a chart

Prerequisites

An EKS Cluster module.
For charts with persistent volumes, a storage driver such as the EBS CSI add-on on the EKS Add-ons module.
For Create IAM role, the eks-pod-identity-agent add-on on the cluster.

Chart source

Chart source	Fields	Example
Helm repository	Repository URL and Chart name	`https://nats-io.github.io/k8s/helm/charts/` and `nats`
OCI registry	Chart URL	`oci://registry-1.docker.io/bitnamicharts/redis`
Git repository	Git repository URL, Branch and Chart path	`https://github.com/acme/platform`, `main` and `charts/dashboards`

Chart version is the chart’s own version from its Chart.yaml. It is not the version of the app the chart installs (appVersion), though some charts, such as NATS, keep the two in step. To find the available versions:

Chart source	How to list versions
Helm repository	`helm repo add <repo> <repository URL>`, then `helm search repo <repo>/<chart> --versions`. The repository’s `index.yaml` lists the same versions.
OCI registry	`helm show chart <chart URL>` for the latest version, or the registry’s tag list for every version
Either	Search for the chart on Artifact Hub, which shows its versions, release notes and default values

Chart version pins the release to one chart version. If you leave it blank, each deploy installs whatever the repository marks as latest, so a redeploy can upgrade the chart without warning. Pin a version for anything you run in production. You can also override the version for a single deploy. For a private HTTPS repository or OCI registry, set Registry credentials to a username and password pair. Each one is a reference to Parameter Store (from_parameter_store) or Secrets Manager (from_secrets_manager), never the value itself. Ravion resolves them on the deploy runner. A Git repository source installs the chart directory as it is on the branch when the deploy runs. Everyone who can push to that branch decides what the next deploy installs. Protect the branch, or set Commit or tag to pin deploys to one commit. Ravion installs the regular files inside the chart directory, up to 64 MiB in total. Symbolic links and the .git directory are left out. Ravion clones a private repository with your organization’s connected code source, so there are no credentials to set. Chart version and Registry credentials apply to the other two sources only.

Chart values

Values is the JSON form of a Helm values file. Ravion passes it to Helm as --values, and Helm merges it over the chart’s defaults. Any value the chart supports can be set this way, including nested objects and lists. To find the available values, see the chart’s values.yaml or run helm show values <chart>. For example, a three-node NATS cluster with JetStream enabled:

{
  "config": {
    "cluster": { "enabled": true, "replicas": 3 },
    "jetstream": {
      "enabled": true,
      "fileStore": { "pvc": { "size": "20Gi", "storageClassName": "gp3" } }
    }
  },
  "podDisruptionBudget": { "enabled": true }
}

The top-level key ravion is reserved, and a deploy whose values set it fails.

Values from Parameter Store or Secrets Manager

To keep a value out of your configuration, put a reference in its place, written as in a stack’s environment variables. A reference is an object with a single key, from_parameter_store or from_secrets_manager, holding the parameter or secret’s ARN or name. To read one key of a JSON secret, give from_secrets_manager an object with key and json_key, and optionally version.

{
  "oauth": {
    "clientId": {
      "from_secrets_manager": {
        "key": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/app-AbCdEf",
        "json_key": "CLIENT_ID"
      }
    },
    "audience": { "from_parameter_store": "/tailscale/audience" }
  }
}

The deploy runner reads each reference and passes the value to Helm as a string with --set-string. A name resolves in the cluster’s account and region. References work in objects at any depth, and a list holding a reference fails the deploy. A deploy with references always runs on the deploy runner. Helm stores every value in the release, including the values read this way, and helm get values shows them. Use references for settings kept out of your repository, such as an OAuth client ID. For a credential the workload uses, reference a Kubernetes Secret that the chart can read, for example one created by the External Secrets Operator.

IAM roles and policies

Create IAM role creates an IAM role and binds it through EKS Pod Identity to a ServiceAccount in the release namespace. Set ServiceAccount name to the ServiceAccount the chart creates. This is usually the release name, but check the chart’s serviceAccount.name value. The role’s trust policy only accepts pods in this cluster and account.

Deployment

Every deploy runs helm upgrade --install --atomic, so a release either lands completely or the cluster stays on the previous revision. Deploys collapse: if several are queued, only the newest runs. Destroying the module’s stack runs helm uninstall on the release. The namespace is never deleted, because other releases may share it. Some charts leave PersistentVolumeClaims behind on uninstall. Delete them yourself if you no longer need the data.

Configuration

Field	Required	Default	Description
Cluster	Yes	-	Existing rvn-eks-cluster module instance
Service name	Yes	{project}-{env}-{module}	Helm release name
Namespace	Yes	{project}-{env}	Kubernetes namespace the release installs into
Create namespace	No	true	Create the namespace if it does not exist
Chart source	Yes	Helm repository	Helm repository, OCI registry or Git repository
Repository URL	Yes*	-	HTTPS Helm repository URL, for Helm repository sources
Chart name	Yes*	-	Chart name within the repository, for Helm repository sources
Chart URL	Yes*	-	`oci://` chart reference, for OCI registry sources
Git repository URL	Yes*	-	HTTPS URL of the repository, for Git repository sources
Branch	Yes*	-	Branch each deploy installs from, for Git repository sources
Chart path	Yes*	-	Directory holding `Chart.yaml`, for Git repository sources
Commit or tag	No	Branch’s latest commit	Commit or tag to pin deploys to, for Git repository sources
Chart version	No	Latest	Chart version to install
Registry credentials	No	-	Username and password references for a private source
Values	No	{}	Helm values as JSON, merged over the chart’s defaults
Create IAM role	No	false	Create an IAM role bound to the chart’s ServiceAccount through EKS Pod Identity
ServiceAccount name	No	Release name	ServiceAccount the role is bound to
IAM role name	No	{release}-task	Explicit role name
IAM policy ARNs	No	[]	Managed policy ARNs attached to the role
IAM inline policies	No	-	Inline policy documents keyed by name
Tags	No	Standard Ravion tags	Additional tags applied to AWS resources
Advanced Terraform variables	No	{}	Raw lower-level overrides for exceptional cases
OpenTofu version override	No	Ravion default	Override the OpenTofu version for the stack
Ravion Terraform workspace name	No	{project}-{env}-{module}	Override the state backend workspace name

Design decisions

Values are a single JSON document. A chart’s values can be any shape. A single document covers all of them, and it maps directly onto the values file that the chart’s own documentation describes.
A Git chart source has no build. The chart is installed as it is in the repository. For a service you build into an image, use EKS Web Service, EKS Worker or EKS Cron.
No Ravion secret injection. EKS Web Service and EKS Worker render an ExternalSecret from secret references. A chart this module installs does not know about that mechanism, so this module does not offer it.
Name and namespace are fixed after creation. Together they identify the Helm release that rollback, history and uninstall target.

Learn more

Inputs reference

All inputs for rvn-eks-chart version 1.0.0. Use the name shown for each field as the input key in module config.

EKS cluster

$ref:rvn-eks-cluster

required

Cluster.

Immutable after creation

Set cluster to null. Mapped inputs for cluster: set these keys alongside cluster, not inside it, when supplying existing infrastructure instead of a module reference.

section

AWS account & region.

string

AWS account.

Default: << ref.input.aws_account_id >>
Immutable after creation

string

Region. Region of the selected cluster. Must match the region in the cluster ARN, which Ravion cross-checks on every deploy.

Default: << ref.input.aws_region >>
Immutable after creation

string

Terraform execution environment.

Default: << ref.input.execution_environment_id >>

section

Cluster connection.

string

required

EKS cluster name.

Default: <<ref.stack.output.cluster_name>>
Immutable after creation

string

required

Cluster ARN. Ravion resolves the owning AWS account and region from this ARN, and rejects a deploy whose cluster name or region disagrees with it.

Default: <<ref.stack.output.cluster_arn>>
Immutable after creation

string

required

Cluster API endpoint. HTTPS endpoint of the Kubernetes API server. May be private-only; the deploy runner executes inside the cluster VPC.

Default: <<ref.stack.output.cluster_endpoint>>
Immutable after creation

string

required

Cluster certificate authority data. Base64-encoded CA bundle used to verify the API server’s TLS certificate. Public key material, not a credential.

Default: <<ref.stack.output.cluster_certificate_authority_data>>
Immutable after creation

string

required

Ravion Runner role ARN. Stable IAM role the deploy runner assumes to obtain a cluster token. Registered as an EKS access entry by the cluster module.

Default: <<ref.stack.output.ravion_runner_role_arn>>
Immutable after creation

string

Ravion Runner security group ID. Security group the deploy runner’s network interface joins so it can reach the cluster API endpoint. Null when the cluster module did not create one, which is only workable if the endpoint is public or the execution environment supplies its own group.

Default: <<ref.stack.output.ravion_runner_security_group_id>>
Immutable after creation

string

required

VPC ID. VPC the cluster runs in. Load balancer target groups must live in the same VPC as the pods they register.

Default: <<ref.input.vpc_id>>
Immutable after creation

string_array

required

Cluster private subnet IDs. Private subnets from the selected EKS cluster. A workload targeting Fargate launches pod network interfaces in these subnets; EKS Fargate does not support public subnets.

Default: <<ref.input.subnet_ids>>
Immutable after creation
Shown when: {"compute_target":"fargate"}

Helm release

string

required

Release name. Charts usually prefix the Kubernetes objects they create with this name.

Default: <<project.given_id>>-<<environment.given_id>>-<<module.given_id>>
Immutable after creation
Pattern: ^[a-z0-9]([a-z0-9-]{0,51}[a-z0-9])?$ — 1-53 lowercase letters, numbers, and hyphens. Start and end with a letter or number.

string

required

Namespace.

Default: <<project.given_id>>-<<environment.given_id>>
Immutable after creation
Pattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ — 1-63 lowercase letters, numbers, and hyphens. Start and end with a letter or number.

boolean

Create namespace. Turn off when the namespace is managed elsewhere.

Default: true

Chart

string

required

Chart source.

Default: http
Allowed values: http (Helm repository), oci (OCI registry), git (Git repository)

string

required

Repository URL. HTTPS protects private repository credentials in transit.

Pattern: ^https://\S+$ — An https:// URL.
Shown when: {"chart_source_type":"http"}

string

required

Chart name. Omit the repository prefix (nats, not nats/nats).

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$ — A chart name without the repository prefix, such as nats rather than nats/nats.
Shown when: {"chart_source_type":"http"}

string

required

Chart URL. Include the oci:// prefix; omit the version tag.

Pattern: ^oci://[^\s:]+(:[0-9]+)?/[^\s:@]+$ — An oci:// reference without a tag, such as oci://registry-1.docker.io/bitnamicharts/redis.
Shown when: {"chart_source_type":"oci"}

string

required

Git repository URL. A private repository must be connected to Ravion as a code source.

Pattern: ^https://\S+$ — An https:// URL.
Shown when: {"chart_source_type":"git"}

string

required

Branch. Each deploy installs the chart as it is on this branch.

Shown when: {"chart_source_type":"git"}

string

required

Chart path. Directory holding Chart.yaml, from the repository root. Enter . for a chart at the root.

Pattern: ^(\.|\.*[A-Za-z0-9_-][A-Za-z0-9._-]*(/\.*[A-Za-z0-9_-][A-Za-z0-9._-]*)*)$ — A path inside the repository, or . for its root, with no leading slash and no .. segment.
Shown when: {"chart_source_type":"git"}

string

Commit or tag. Pin deploys to one commit or tag of the branch. Blank uses the branch’s latest commit.

Shown when: {"chart_source_type":"git"}

string

Chart version. Pin the chart version (not appVersion) for repeatable deploys. Blank uses the latest version on each deploy.

Shown when: {"chart_source_type":["http","oci"]}

object

Registry credentials. Username and password references in Parameter Store or Secrets Manager, resolved on the deploy runner. Leave blank for public sources.

Shown when: {"chart_source_type":["http","oci"]}

Chart values

object

Values. JSON merged over the chart’s defaults. from_secrets_manager and from_parameter_store references resolve at deploy time, but the result is stored in the Helm release, so prefer charts that read an existing Secret. The ravion key is reserved.

Default: {}

IAM roles and policies

boolean

Create IAM role. Gives chart pods short-lived AWS credentials through EKS Pod Identity. Leave off if the chart calls no AWS APIs.

Default: false

string

ServiceAccount name. Must match the chart’s ServiceAccount (often serviceAccount.name). Blank uses the release name.

Pattern: ^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$ — 1-253 lowercase letters, numbers, dots and hyphens. Start and end with a letter or number.
Shown when: {"pod_identity_role_creation_enabled":true}

string

IAM role name. Blank uses <release name>-task. Must be unique within the AWS account.

Pattern: ^[\w+=,.@-]{1,64}$ — 1-64 characters of letters, digits and + = , . @ _ -
Shown when: {"pod_identity_role_creation_enabled":true}

string_array

IAM policy ARNs.

Default: []
Shown when: {"pod_identity_role_creation_enabled":true}

object

IAM inline policies. Keyed by policy name and attached to the generated role.

Shown when: {"pod_identity_role_creation_enabled":true}

Misc

keyvalue

Tags. A map of tags to assign to all resources. Default tags are Owner, ProjectGivenId, EnvironmentGivenId, ModuleGivenId, ModuleId

Terraform settings

string

OpenTofu version override. Override the environment’s default version for this module

string

Ravion Terraform workspace name. Override Terraform state backend workspace name. Defaults to project + environment + module given ids.

Immutable after creation

boolean

Include default plan policies. Turn off to plan with only the policies below instead of the default read-only policies. Requires at least one policy below.

Default: true

string_array

Terraform plan IAM policies. IAM managed policy ARNs for the Terraform plan runner role. Without default policies, allow s3:CreateBucket, s3:PutObject, s3:GetObject, and s3:ListBucket on the ravion-terraform-plans-<AWS account number> bucket in this account.

Default: []

boolean

Include default apply policies. Turn off to apply and destroy with only the policies below instead of AdministratorAccess. Requires at least one policy below.

Default: true

string_array

Terraform apply IAM policies. IAM managed policy ARNs for the Terraform apply runner role. Without default policies, allow s3:CreateBucket, s3:PutObject, s3:GetObject, and s3:ListBucket on the ravion-terraform-plans-<AWS account number> bucket in this account.

Default: []

object

Advanced Terraform variables. Optional raw Terraform variable overrides for advanced module inputs or one-off overrides. Values here override the generated variables above.

Default: {}

Introduction

Concepts

Config as code

Access control

Migrate

GitHub Actions

Modules

Pipelines

Guides

Troubleshooting

Agent setup

Module definitions

Dependencies and consumers

Readme

Overview

Use cases

Prerequisites

Chart source

Chart values

Values from Parameter Store or Secrets Manager

IAM roles and policies

Deployment

Configuration

Design decisions

Learn more

Inputs reference

EKS cluster

Helm release

Chart

Chart values

IAM roles and policies

Misc

Terraform settings