Skip to main content

Deploying on Amazon EKS

This guide will help prepare you for some of the specific configurations for the Ignition Helm Chart when used with AWS Elastic Kubernetes Service (EKS). It is expected that you've reviewed other areas of the documentation including the Installation and Preparation sections.

Additionally, consider reviewing the Amazon EKS Best Practices Guide for additional general information on configuring your EKS deployment.

Prerequisites​

Review the prerequisites in this section. There may additional installation steps required to prepare your EKS cluster for running Ignition and other typical workloads.

EKS Cluster Requirements​

  • EKS Cluster running Kubernetes v1.29+
  • kubectl configured to access your EKS cluster.
  • Helm 3+ installed locally.

Required AWS Components​

  • AWS EBS CSI Driver - AWS Elastic Block Storage (EBS) is required for persisting the Ignition data volume. The guide will show how to configure an associated StorageClass, but the EBS CSI Driver must be installed in your cluster first, typically as an add-on.
  • AWS Load Balancer Controller - We'll use the AWS EC2 Application Load Balancer (ALB) to make Ignition available outside of the cluster. The AWS Load Balancer Controller must be installed in order to automatically translate Ingress resources into EC2 ALBs.
  • IAM Role for Service Accounts (IRSA) - If you need Ignition to access other AWS services, we'll use IRSA to map IAM roles to the Ignition service account.

Other Requirements​

  • cert-manager installed in the cluster - We'll use cert-manager to automatically provision TLS certificates for the Ignition Gateway Web Server behind the ALB. For more information on cert-manager integration with the Ignition Helm Chart, see the cert-manager Preparation page.
  • Certificate loaded into AWS Certificate Manager (ACM) - In order to use TLS with the ALB, you'll need to load a certificate into ACM and reference the ARN in the Ingress annotations.

Setup​

With prerequisites established, we'll begin to create resources in our cluster to house and support our Ignition deployment.

Namespace Setup​

Let's create a namespace in our cluster for Ignition. We'll configure the ignition namespace with a Restricted Pod Security Standards profile.

namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  labels:
    pod-security.kubernetes.io/enforce: restricted
  name: ignition

Apply the namespace.yaml to your cluster:

kubectl apply -f namespace.yaml

ServiceAccount Setup​

This step is optional, but may be required if you need Ignition to access other AWS services.

tip

If you're deploying Ignition Cloud Edition, you'll need a service account that can communicate with AWS Marketplace Metering services. See the Ignition Cloud Edition - Licensing section for more details.

See our Creating an Ignition Service account on EKS using IRSA guide for detailed steps on creating an IAM role and associating it with the Ignition service account using IRSA.

IngressClass Setup​

There are several ways to configure Ingress for allowing external users to access your Ignition Gateway running on EKS. We'll be setting up a dedicated ALB Controller IngressClass for Ignition.

ingressclass.yaml
apiVersion: elbv2.k8s.aws/v1beta1
kind: IngressClassParams
metadata:
  name: ignition-alb
spec:
  scheme: internet-facing
  group:
    name: ignition
  targetType: ip
---
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: ignition-alb
spec:
  controller: ingress.k8s.aws/alb
  parameters:
    apiGroup: elbv2.k8s.aws
    kind: IngressClassParams
    name: ignition-alb

There are additional customizations that you can bake in via IngressClassParams specifications. We'll also apply individual customizations to Ingress resources via annotations with our Ignition Helm Chart values.

Once your ingressclass.yaml (example above) is set up, apply it to your cluster:

kubectl apply -f ingressclass.yaml

We now have an ignition-alb IngressClass created in the cluster that we can reference in our Helm Chart ingress configuration.

StorageClass Setup​

To provision EBS volumes for Ignition, we'll need to make sure there is a storage class configured. We recommend a minimum of General Purpose SSD volume type. Refer to AWS EBS Volume Types documentation for more specifics on the various EBS volume types and their capabilities.

Below are example StorageClass definitions for gp3 EBS volume types.

storageclass.yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  # Uncomment to make this storage class the default for the cluster
  # annotations:
  #   storageclass.kubernetes.io/is-default-class: "true"
  name: gp3
parameters:
  fsType: ext4
  type: gp3
  encrypted: "true"
provisioner: kubernetes.io/aws-ebs
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer

For more information on available parameters for the storage class, inspect the StorageClass Parameters section of the AWS EBS CSI Driver documentation.

Once your storageclass.yaml (example above) is set up, apply it to your cluster:

kubectl apply -f storageclass.yaml

We now have a gp3 StorageClass created that we can reference in our Helm Chart gateway.dataVolumeStorageClass configuration.

Installation​

With prerequisites and setup completed, we're ready to start building up the Helm Chart values that we'll use to deploy Ignition. There is a full example of the Helm Chart values at the end in the Full Example section that will include the various snippets from this setup guide.

Redundancy​

If you're deploying Ignition with redundancy enabled, make sure to review the Redundancy preparation guide for general considerations. We'll ensure that the primary and backup Ignition gateways are deployed to different availability zones.

affinity: |
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchLabels:
          {{- include "ignition.selectorLabels" . | nindent 10 }}
      topologyKey: topology.kubernetes.io/zone

Ingress​

We'll use cert-manager to automatically provision self-signed TLS certificates for the Ignition Gateway Web Server. Ensure that you've got a self-signed ClusterIssuer configured in your cluster as described in the cert-manager Setup. This configuration will enable encryption between the ALB and the Ignition Gateway.

certManager:
  enabled: true

gateway:
  tls:
    enabled: true

For Ingress, we'll need to direct the chart to use the IngressClass we created above. Additionally, we'll configure our ingress.hostOverride to match the DNS name that we will use to access Ignition. Finally, we'll tie in a certificate that we create in AWS Certificate Manager (ACM) to use for TLS termination at the ALB. This certificate will be what users will see when they connect to the Ignition Gateway.

ingress:
  className: ignition-alb
  tls:
    enabled: true
  # Set these to your desired domain values
  domainSuffix: example.com
  hostOverride: my-ignition-gateway.example.com
  annotations:
    # Configure ALB healthchecks which have to use a simple GET and 200 response
    alb.ingress.kubernetes.io/healthcheck-path: /StatusPing
    alb.ingress.kubernetes.io/healthcheck-protocol: HTTPS
    # Specify backend protocol as HTTPS since we're using TLS to the gateway
    alb.ingress.kubernetes.io/backend-protocol: HTTPS
    # Listen on 80/443 and configure redirect to HTTPS
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
    alb.ingress.kubernetes.io/ssl-redirect: '443'
    # Use updated security policy to drop support for TLS 1.0/1.1 and allow TLS 1.3
    alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-Res-2021-06
    # Set the AWS Certificate Manager certificate ARN to use
    alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:<region>:<acct>:certificate/<id>

Storage​

By default, the Ignition Helm Chart only provisions 3Gi of persistent storage for the data volume. You can configure the data volume size to be larger and also select the gp3 storage class (if it isn't marked default like the example above).

gateway:
  dataVolumeStorageSize: 50Gi
  dataVolumeStorageClass: gp3

Full Example​

Below is a complete example of the Helm Chart values that we've accumulated through the various sections above. Feel free to use this as a baseline for your own deployments. Pay special mind to the highlighted sections that will definitely require your configuration.

base-values.yaml
# Use of YAML extension field and anchors to reduce duplication
x-securitycontext: &securitycontext
  securityContext:
    allowPrivilegeEscalation: false
    capabilities:
      drop:
      - ALL
    seccompProfile:
      type: RuntimeDefault

certManager:
  enabled: true

gateway:
  extraSpec: 
    <<: *securitycontext
  preconfigure:
    extraSpec:
      <<: *securitycontext
  dataVolumeStorageSize: 50Gi
  dataVolumeStorageClass: gp3
  tls:
    enabled: true

ingress:
  className: ignition-alb
  tls:
    enabled: true
  # Set these to your desired domain values
  domainSuffix: example.com
  hostOverride: my-ignition-gateway.example.com
  # Customizations for ALB
  annotations:
    # Configure ALB healthchecks which have to use a simple GET and 200 response
    alb.ingress.kubernetes.io/healthcheck-path: /StatusPing
    alb.ingress.kubernetes.io/healthcheck-protocol: HTTPS
    # Specify backend protocol as HTTPS since we're using TLS to the gateway
    alb.ingress.kubernetes.io/backend-protocol: HTTPS
    # Listen on 80/443 and configure redirect to HTTPS
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
    alb.ingress.kubernetes.io/ssl-redirect: '443'
    # Use updated security policy to drop support for TLS 1.0/1.1 and allow TLS 1.3
    alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-Res-2021-06
    # Set the AWS Certificate Manager certificate ARN to use
    alb.ingress.kubernetes.io/certificate-arn: 'arn:aws:acm:<region>:<acct>:certificate/<id>'

Finally, we can install the chart with these values (omit the redundancy-values.yaml for a standalone Gateway):

helm install ignition inductiveautomation/ignition \
  --namespace ignition \
  --create-namespace \
  --values base-values.yaml \
  --values redundancy-values.yaml

Other Considerations​

This guide covers the very basics for deploying Ignition on AWS EKS. Within the K8s ecosystem, there are many other tools (some of which are even bundled as EKS add-ons) that can help enhance your deployment. Here are some additional tools to help complement your EKS deployment:

  • external-dns - Automate the management of CNAME DNS records that resolve to the dynamic ALB hostnames.
  • External Secrets Operator (ESO) - Synchronize secrets defined and managed in AWS Secrets Manager into your EKS cluster automatically.
  • Mountpoint for Amazon S3 CSI Driver - Tie-in S3 buckets as volume mounts in your Ignition deployment for external modules integration or scheduled backups.