Deploy on AWS

Run Koldan on Amazon EKS with the standard Koldan Helm chart. This page is an AWS addendum: prepare the AWS infrastructure here, then follow Install with Helm for rendering, installation, verification, and rollback.

Before you begin

Obtain the chart, container images, and license through the distribution channel associated with your Koldan subscription. Confirm that the Koldan release supports the Kubernetes version used by the target EKS cluster.

Prepare or select:

• an EKS cluster with private worker networking and sufficient CPU, memory, and ephemeral storage;
• a dedicated namespace and a deployment identity with least-privilege access;
• node access or image-pull credentials for every required container registry;
• an HTTP ingress controller and a load-balancer design that support the required request sizes, timeouts, WebSocket behavior where used, and gRPC over HTTP/2;
• Route 53 records and either ACM-managed certificates at the AWS load balancer or Kubernetes TLS Secrets at the ingress layer;
• EBS CSI-backed storage classes for in-cluster stateful workloads; and
• reachable PostgreSQL, Temporal, S3-compatible storage, and OIDC services.

Keep worker nodes and private dependencies in private subnets. Use public load balancers only for interfaces that clients must reach, and keep management endpoints and dependency consoles private.

Plan AWS networking

Place load balancers in the subnets appropriate to their scheme and make subnet selection explicit in the controller configuration. Restrict security groups and network policies to the required paths:

Prefer VPC endpoints or private service endpoints where they meet your operating model. Verify DNS resolution from pods, not only from an administrator workstation. Ensure network timeouts exceed the longest supported upload and gRPC session without leaving unlimited idle connections.

Configure AWS exposure

The chart creates an HTTP Ingress through web.ingress.* and a gRPC LoadBalancer Service through grpc.service.* by default. Select the actual controller and load-balancer behavior with web.ingress.className, web.ingress.annotations, and grpc.service.annotations.

Use annotations documented for the installed AWS load-balancer controller version. At minimum, make the following choices explicit:

• public or internal scheme;
• target type and health-check behavior;
• IPv4 or dual-stack addressing;
• selected subnets and security groups;
• deletion protection and access logging where required;
• certificate ARN and TLS policy when TLS terminates at the AWS load balancer; and
• connection idle timeout long enough for supported Koldan HTTP and gRPC operations.

Do not combine controller-managed ACM termination with an unrelated web.ingress.tls Secret. If TLS passes through to Koldan, configure the serving certificate through the supported chart values and ensure its subject alternative names match the Route 53 record.

After installation, wait for the controller to assign load-balancer addresses before creating or updating Route 53 aliases. Avoid using a load-balancer hostname as the permanent Koldan advertised address; publish the stable application DNS name and configure Koldan to advertise that name.

Configure identity and secrets

Grant the deployment pipeline only the EKS, registry, secret, DNS, and load-balancer permissions required for the release. Separate infrastructure provisioning permissions from Helm deployment permissions when practical.

For AWS API access from pods, use EKS Pod Identity or IAM Roles for Service Accounts only when the selected Koldan integration supports the AWS default credential chain. The chart exposes serviceAccount.annotations for service-account configuration, but the account is shared by Koldan workloads unless you supply a separately managed account. Scope its IAM policy to the exact bucket, actions, and encryption keys required; do not grant account-wide S3 access.

When a Koldan configuration field requires an explicit access key, database password, OIDC client secret, or provider token, deliver it through the protected Helm workflow described in Install with Helm. Do not assume that attaching an IAM role replaces a credential field unless the release documentation explicitly supports that mode.

Use AWS Secrets Manager or another approved secret manager as the source for deployment credentials. The pipeline must still pass values in the format supported by the chart. Restrict access to Helm release metadata because it can contain rendered secret values.

Configure managed dependencies

Managed AWS services reduce the number of stateful components operated inside EKS, but they remain external dependencies that must satisfy the Koldan service contracts.

PostgreSQL

For Amazon RDS for PostgreSQL or Aurora PostgreSQL, create the required databases and users, enable backups and point-in-time recovery, and size connections, storage, IOPS, and failover capacity. Add the AWS database CA chain through customCA when it is not already trusted by the Koldan image. Do not enable IAM database authentication unless the Koldan release explicitly supports its token lifecycle.

Object storage

For Amazon S3, create a dedicated bucket, block public access, enable encryption, and define lifecycle, versioning, replication, and recovery controls appropriate to the stored data. Limit the workload identity or access key to the required bucket and prefix. Validate multipart upload, download, delete, and list behavior from a Koldan pod through the selected endpoint.

Temporal and identity

Keep Temporal and OIDC endpoints reachable through approved private connectivity or controlled egress. Configure high availability, persistence, backups, and certificate trust independently. Do not expose Temporal administration or identity-provider administration interfaces through the Koldan load balancers.

Disable each corresponding bundled dependency with its chart install value only after its external replacement is fully configured.

Configure persistent storage

For any bundled stateful dependency, use an EBS CSI storage class with encryption, expansion, and a reclaim policy that matches the recovery plan. EBS volumes are tied to an Availability Zone; use topology-aware binding and placement so a pod and its volume remain schedulable together.

Increasing replicas does not by itself make a stateful subchart highly available or multi-AZ. Validate the dependency chart's replication and failover model, and test loss of a node and an Availability Zone. Prefer an independently operated or managed service when the bundled topology cannot meet the required recovery objectives.

Do not use EBS for a workload that requires simultaneous ReadWriteMany access. Confirm the access mode of every rendered PVC before installation.

Install and verify

Run the standard Helm preflight and installation procedure. In addition to the Kubernetes checks, verify:

1. all images pull without cross-account or registry authorization failures;
2. load balancers are active in the intended subnets and use the intended scheme;
3. target groups report the expected pods or nodes healthy;
4. security-group rules and network policies expose only required ports;
5. Route 53 records resolve to the correct load balancers;
6. ACM or Kubernetes certificate chains validate for the published names;
7. EBS claims bind in a failure domain where their pods can schedule;
8. PostgreSQL, Temporal, S3, OIDC, logging, and metrics endpoints are reachable from pods; and
9. an authenticated HTTP request, a gRPC call, and representative licensed operations complete successfully.

Record the AWS resource identifiers and configuration revisions with the Helm release record so an operator can correlate a Koldan incident with load balancer, security group, DNS, database, bucket, and volume changes.

Troubleshoot and recover

For pending load balancers, inspect the controller events and logs, subnet discovery or selection, IAM permissions, service annotations, quota, and security groups. For unhealthy targets, verify readiness, target type, service port mapping, protocol, health-check path, and network reachability.

For an unbound EBS claim, check the CSI controller, StorageClass binding mode, allowed topology, encryption-key access, quota, and pod scheduling constraints. For dependency timeouts, test DNS and TCP/TLS connectivity from a pod in the Koldan namespace and inspect VPC routes, endpoints, security groups, and network ACLs.

Helm rollback changes Kubernetes resources only. It does not reverse Route 53, ACM, IAM, security-group, load-balancer-controller, RDS, S3, EBS snapshot, or VPC changes. Restore or reverse those resources through the infrastructure change that created them, and follow the backup and restore procedure for persistent data.