Posts on Riveroverflow

Building an AWS ALB-Based Gateway API

Mon, 11 May 2026 13:39:22 +0900

AWS Load Balancer Controller lets you manage Elastic Load Balancers in Kubernetes environments.
It supports resource types such as Ingress and LoadBalancer, and on AWS it can provision Application Load Balancers, Network Load Balancers, and Classic Load Balancers.

⚙️ How It Works

For Ingress

Reconciliation Flow

For a single Ingress resource, the controller behaves as follows:

The controller watches Ingress events from the API server.
If the conditions are met, it starts creating AWS resources.
An ALB is created for the new Ingress resource.
It can be either internet-facing or internal.
AWS creates target groups based on the Ingress resource.
Listeners are created for the configured ports. By default, ports 80 or 443 are used.
You can also attach certificates through annotations.
Rules are created from the Ingress definition.
Traffic is then routed to the appropriate Kubernetes Service.

The Load Balancer Controller also performs the following tasks:

Removes related AWS resources when an Ingress is deleted in Kubernetes
Updates AWS resources when an Ingress changes
Reconstructs and reconciles related AWS resources after the controller restarts

Traffic Handling

The Load Balancer Controller supports two traffic modes:

Instance mode (default): The ALB sends traffic to Kubernetes nodes, which then forward it through the Service’s NodePort.
IP mode: The ALB sends traffic directly to Kubernetes pods. Your CNI must support direct access to pod IPs.
- This reduces hops and generally provides better performance.
- Configure it with the alb.ingress.kubernetes.io/target-type: ip annotation.

For Gateway API

The controller follows a reconciliation loop like this:

API Monitoring: The controller continuously monitors Gateway API resources through the API server.
Queueing: Detected resources are added to an internal queue.
Processing: For each queued item:
- It checks whether the referenced GatewayClass is managed by its controller. In other words, it verifies that spec.controllerName in the GatewayClass is either gateway.k8s.aws/alb or gateway.k8s.aws/nlb.
- Gateway API definitions are mapped to AWS resources such as NLB/ALB listeners, rules, target groups, and add-ons.
- The mapped resources are compared against the actual AWS state.
  If the current state differs from the desired state, the controller calls the AWS API to synchronize it.
Status Updates: After reconciliation, the controller updates the status field of the Gateway resource.
This provides real-time feedback such as the load balancer DNS name, ARN, and whether the Gateway has been accepted and programmed.

NOTE: If this is Gateway API, why does it also support NLB?
Gateway API is not limited to L7 routing. It can also replace L4 routing scenarios.
In other words, it can serve as an alternative to type: LoadBalancer.
A single Gateway cannot mix route types from different layers.
For example, HTTPRoute and TCPRoute cannot be used on the same Gateway.

L7 Gateway: HTTPRoute, GRPCRoute

L4 Gateway: TCPRoute, UDPRoute, TLSRoute

Gateway API also supports both Instance mode and IP mode.

🚀 Installing AWS Load Balancer Controller

Installation with Helm

Add the Helm repository with the following command:

1

helm repo add eks https://aws.github.io/eks-charts

1
2
3
4
5
6
7
8
9


helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
 -n kube-system \
 --version 3.33.0 \
 --set clusterName = <cluster_name> \
 --set region = <aws_region> \
 --set vpcId = <vpc_id> \
 --set serviceAccount.create = true \
 --set serviceAccount.name = aws-load-balancer-controller \
 --set controllerConfig.featureGates.ALBGatewayAPI = true # Important: required for ALB Gateway API

Or you can define the Helm values in values.yaml and install from that:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# values.yaml
clusterName: <clutser_name>
region: <aws_region>
vpcId: <vpc_id>

serviceAccount:
 create: true
 name: aws-load-balancer-controller

controllerConfig:
 featureGates:
 ALBGatewayAPI: true

1
2
3
4


helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
 -n kube-system \
 --version 3.33.0 \
 -f values.yaml

Other useful values

In addition to the Helm values above, you may also want to consider the following:

autoscaling: Adds an HPA for the controller. It can be useful if changes happen frequently.
enableWafv2: Enables integration with AWS WAF v2.
enableCertManager: Lets cert-manager manage the TLS certificates used by the admission webhook.

For more details, refer to this README.

📝 Hands-on Example

We will create an ALB-based Gateway API setup to provide L7 rule-based routing.
We will attach ACM for TLS termination, apply WAF ACL rules, and enable S3 access logging.
We will also create a policy that blocks external access to the /metrics path.

Required components

An EKS cluster
AWS Load Balancer Controller (see the installation section above)
- The controller must assume a role through IRSA or Pod Identity with the IAM policy required to access AWS APIs
The installation manifest from the Gateway API CRD

Additional components

Route53 Hosted Zone, ACM Certificate, and External-DNS

These are listed as additional components, but in practice they are almost mandatory.
In real environments, you usually do not expose an ALB by itself. You attach a custom domain.

Below is an example Terraform configuration that creates a Route53 hosted zone and issues an ACM certificate.
If you purchased the domain in the AWS console, the hosted zone may already exist and should then be imported.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


resource "aws_route53_zone" "main" {
 name = var.root_domain_name
}

resource "aws_acm_certificate" "alb" {
 domain_name = var.root_domain_name
 subject_alternative_names = var.certificate_subject_alternative_names
 validation_method = "DNS"

 lifecycle {
 create_before_destroy = true
 }
}

resource "aws_route53_record" "alb_acm_validation" {
 for_each = {
 for dvo in aws_acm_certificate.alb.domain_validation_options :
 dvo.domain_name => {
 name = dvo.resource_record_name
 record = dvo.resource_record_value
 type = dvo.resource_record_type
 }
 }

 allow_overwrite = true
 zone_id = aws_route53_zone.main.zone_id
 name = each.value.name
 type = each.value.type
 ttl = 60
 records = [each.value.record]
}

resource "aws_acm_certificate_validation" "alb" {
 certificate_arn = aws_acm_certificate.alb.arn
 validation_record_fqdns = [for record in aws_route53_record.alb_acm_validation : record.fqdn]
}

## Variables
variable "root_domain_name" {
 description = "Primary public DNS zone managed in Route 53."
 type = string
 default = "example.com"
}

variable "certificate_subject_alternative_names" {
 description = "Additional DNS names to include in the shared ACM certificate."
 type = list(string)
 default = ["*.example.com"]

 validation {
 condition = length(var.certificate_subject_alternative_names) > 0
 error_message = "At least one subject alternative name must be provided."
 }
}

You can install External-DNS from here.

Below is an example Helm values file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


provider:
 name: aws

serviceAccount:
 create: true
 name: external-dns

# See the following for available source types:
# https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/about/
sources:
 - gateway-httproute

env:
 - name: AWS_DEFAULT_REGION
 value: ap-northeast-2

domainFilters:
 - example.com

policy: upsert-only

registry: txt
txtOwnerId: my-web

The required IAM policy is shown below.
Attach this policy through IRSA or Pod Identity.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Action": [
 "route53:ChangeResourceRecordSets",
 "route53:ListResourceRecordSets",
 "route53:ListTagsForResources"
 ],
 "Resource": [
 "arn:aws:route53:::hostedzone/*"
 ]
 },
 {
 "Effect": "Allow",
 "Action": [
 "route53:ListHostedZones"
 ],
 "Resource": [
 "*"
 ]
 }
 ]
}

External-DNS works with the following logic:

External-DNS extracts DNS name candidates from HTTPRoute and similar resources
- spec.hostname
- external-dns.alpha.kubernetes.io/hostname
It identifies the parent Gateway from the parents section in the HTTPRoute status
It checks whether the Gateway accepted the route
It matches Gateway listeners with the route information
It checks Gateway.status.addresses[].value to find the load balancer address
It creates the DNS records

WAFv2 regional ACL

You can create a WAFv2 ACL with regional scope and attach it to the ALB.
In this example, you create only the ACL itself, not the association.
The Load Balancer Controller will create the association for the ALB.

S3 for access logging

ALB access logs can be written directly to S3, not to a CloudWatch log group.
The following options are generally recommended:

Lifecycle policy
Block Public Access
KMS encryption when needed

For the ALB to write logs to S3, the following policy must be attached to the S3 bucket:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
 "Version":"2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Principal": {
 "Service": "logdelivery.elasticloadbalancing.amazonaws.com"
 },
 "Action": "s3:PutObject",
 "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/AWSLogs/123456789012/*"
 }
 ]
}

GatewayClass

You must select gateway.k8s.aws/alb in spec.controllerName.

1
2
3
4
5
6
7


# GatewayClass.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
 name: aws-alb-gateway-class
spec:
 controllerName: gateway.k8s.aws/alb

LoadBalancerConfiguration

LoadBalancerConfiguration is a CRD available after installing AWS Load Balancer Controller, and it lets you configure additional AWS ELB settings.
The Gateway resource contains options that fit the Gateway API specification, while this CRD holds the AWS-specific configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


apiVersion: gateway.k8s.aws/v1beta1
kind: LoadBalancerConfiguration
metadata:
 name: alb-config
 namespace: kube-system
spec:
 # Whether the load balancer should have a public or internal IP
 scheme: internet-facing
 ipAddressType: ipv4
 # Attach certificate information
 listenerConfigurations:
 - protocolPort: HTTPS:443
 defaultCertificate: <ARN of ACM Certificate>
 # For sslPolicy, see: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/describe-ssl-policies.html
 sslPolicy: ELBSecurityPolicy-TLS13-1-2-2021-06
 # Attach WAF (use the ARN of the regional WAFv2 ACL)
 wafV2:
 webACL: <ARN of wafv2 regional web acl)
 # Configure the load balancer to store access logs in S3
 loadBalancerAttributes:
 - key: access_logs.s3.enabled
 value: "true"
 - key: access_logs.s3.bucket
 value: <s3 bucket name>
 - key: access_logs.s3.prefix
 value: ""
 # Used to control which subnets the load balancer is attached to
 loadBalancerSubnets:
 - identifier: <subnet-id>

If loadBalancerSubnets is left empty, the AWS subnets must have the following tags:

For a public load balancer (internet-facing): "kubernetes.io/role/elb" = "1"
For a private load balancer (internal): "kubernetes.io/role/internal-elb" = "1"

Gateway

The Gateway must reference the name of the GatewayClass.
It can also reference the LoadBalancerConfiguration to use additional load balancer options.
Once the Gateway resource is created, the actual AWS ELB is provisioned and mapped to listeners.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
 name: aws-alb-gateway
 namespace: kube-system
spec:
 # Must reference the GatewayClass name
 gatewayClassName: aws-alb-gateway-class
 # Can reference additional ALB options
 infrastructure:
 parametersRef:
 kind: LoadBalancerConfiguration
 name: alb-config
 group: gateway.k8s.aws
 listeners:
 - name: http
 protocol: HTTP
 port: 80
 hostname: www.example.com
 allowedRoutes:
 namespaces:
 from: Selector
 selector:
 matchLabels:
 # The namespace name must be my-web
 kubernetes.io/metadata.name: my-web
 - name: https
 protocol: HTTPS
 port: 443
 hostname: www.example.com
 allowedRoutes:
 namespaces:
 from: Selector
 selector:
 matchLabels:
 kubernetes.io/metadata.name: my-web

HTTPRoute

HTTPRoute is mapped to actual rules and target groups.
In this example there are two rules. One blocks external requests to /metrics.
This is explained in more detail below.
The second rule forwards traffic for the root path (/) to the web server.
If multiple prefixes match, PathPrefix prefers the more specific path.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
 name: my-web
 namespace: my-web
 labels:
 app: my-web
 app.kubernetes.io/name: my-web
spec:
 # Maps to Gateway listeners
 parentRefs:
 - name: my-alb-gateway # Gateway name
 namespace: kube-system
 sectionName: http # Listener name
 - name: my-alb-gateway
 namespace: kube-system
 sectionName: https
 # Hostname to receive. External-DNS creates records from this hostname.
 hostnames:
 - www.example.com
 rules:
 - matches:
 - path:
 type: PathPrefix
 value: /metrics
 filters:
 - type: ExtensionRef
 extensionRef:
 group: gateway.k8s.aws
 kind: ListenerRuleConfiguration
 name: deny-metrics
 - matches:
 - path:
 type: PathPrefix
 value: /
 # Target service name
 backendRefs:
 - name: my-web
 port: 80

ListenerRuleConfiguration

The following rule is attached to /metrics and returns a fixed 403 response.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: gateway.k8s.aws/v1beta1
kind: ListenerRuleConfiguration
metadata:
 name: deny-metrics
 namespace: my-web
spec:
 actions:
 - type: "fixed-response"
 fixedResponseConfig:
 statusCode: 403
 contentType: "text/plain"
 messageBody: "Forbidden for public access"

TargetGroupConfiguration

The ELB needs health checks for the target group.
So you need to define a health check endpoint.
Also, just as Ingress uses annotations to choose between IP and Instance targets, here you define that with targetType.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


apiVersion: gateway.k8s.aws/v1beta1
kind: TargetGroupConfiguration
metadata:
 name: my-web
 namespace: my-web
spec:
 targetReference:
 group: ""
 kind: Service
 name: my-web
 defaultConfiguration:
 # Route directly to pod IPs
 targetType: ip
 healthCheckConfig:
 healthCheckPath: /helathz/
 healthCheckProtocol: http
 matcher:
 httpCode: 200-399

🌐 Result Example

Below is an example resource map created by the Load Balancer Controller after applying the configuration.

The reason there were no healthy pods in the target group in the screenshot is that I had removed all worker nodes at that time.
When healthy targets do exist, you can see the pod IPs inside each target group.
For convenience during the project, I had also exposed Grafana and ArgoCD publicly.

You can also see that Route53 records were created.

The S3 access logs are also being stored correctly.

References

Karpenter Explained: Efficient Kubernetes Node Autoscaling on EKS

Fri, 01 May 2026 16:34:04 +0900

❓ What is Karpenter?

Karpenter is a Kubernetes node autoscaler designed for cloud-based Kubernetes environments.
It is most commonly used with Amazon EKS, which is the standard and recommended approach.
It can also work in non-EKS AWS environments, though this is not generally recommended.
In addition, Karpenter-style autoscaling is available or supported in other cloud environments such as AKS and Alibaba Cloud.

Karpenter provides several key advantages:

Automatic node scaling: When there are unscheduled pods, Karpenter provisions new worker nodes so that those pods can run.
It can also remove or replace nodes when they are no longer needed.
Cost efficiency: Karpenter optimizes worker node usage based on pod resource requests, using bin-packing to reduce waste.
Speed: Karpenter is generally faster than Cluster Autoscaler, the traditional node autoscaling approach for EKS.

When you run EKS with Auto Mode, AWS manages Karpenter automatically for you.
However, EKS Auto Mode can cost more than operating a self-managed EKS cluster.

🚀 How It Works

Provisioning

Karpenter provisions new nodes when Kubernetes cannot schedule pods due to insufficient cluster capacity.

The provisioning flow works as follows:

Karpenter continuously watches for pods that are pending or unschedulable.
Karpenter selects an appropriate NodePool and uses its associated NodeClass, such as EC2NodeClass, to determine how the node should be created.
Karpenter creates a NodeClaim and requests AWS to launch a new EC2 instance.
The new EC2 instance initializes as an EKS worker node.
The worker node joins the EKS cluster, allowing the pending pods to be scheduled.

Disruption

Karpenter also manages node disruption. It automatically detects nodes that can be disrupted and creates replacement nodes when needed.
Disruption may happen for several reasons:

Drift
- The node no longer matches the desired configuration defined in the NodePool or NodeClass.
Consolidation
- The node is empty.
- The node is underutilized.
- The workloads can be moved to fewer or cheaper nodes.
Expiration
- The node has reached its configured lifetime, such as expireAfter in the NodePool spec.
Interruption
- AWS sends an interruption or termination event for the underlying instance.

Among these, drift-based disruption is usually more important than consolidation because it ensures that nodes stay aligned with the desired cluster configuration.
The disruption flow is shown in the following diagram:

Disruption Controller

Checks whether the pods on the node can be evicted.
Checks the disruption budget.
Runs a scheduling simulation to verify that workloads can be rescheduled.
Adds the taint karpenter.sh/disrupted:NoSchedule to prevent new pods from being scheduled on the node.
Creates a new NodeClaim and waits for the replacement node to become ready.
Deletes the node.

Termination Controller

A DeletionTimestamp is set on the node, and the finalizer blocks immediate deletion.
The taint karpenter.sh/disrupted:NoSchedule is added.
Pods are evicted through the Kubernetes Eviction API while respecting PDBs.
Karpenter verifies that all VolumeAttachments have been deleted.
The related NodeClaim and EC2 instance are terminated.
The finalizer is removed.
Node deletion is completed.

Why is disruption divided into two phases?
A Karpenter-managed node can be deleted in different ways, such as by running kubectl delete node <node-name>.
Because of this, the termination process must be separated from the disruption decision-making process. The Termination Controller acts as a graceful node shutdown mechanism, regardless of how the node deletion was triggered.
This is also why the taint karpenter.sh/disrupted:NoSchedule is added during both processes.

Interruption

Interruption is a special type of disruption triggered by AWS events.
When an interruption event occurs, Karpenter starts the disruption process for the affected node.

The following events can trigger interruption handling:

Spot Interruption Warnings
Scheduled Change Health Events, such as maintenance events
Instance Terminating Events
Instance Stopping Events
Instance Status Check Failures

The interruption flow works as follows:

An EventBridge rule receives the AWS event.
The event message is sent to an SQS queue.
The Karpenter controller periodically polls the SQS queue.
When Karpenter detects an interruption event, it taints, drains, and terminates the affected node.

For Spot Interruption Warnings, Karpenter provisions a replacement node in parallel while terminating the interrupted node.
AWS also publishes Spot Rebalance Recommendation events. However, these events do not trigger Karpenter’s taint, drain, and terminate logic in the same way.
To enable interruption handling, Karpenter must be started with the following flag:

1

--interruption-queue=<queue-name>

🍪 Karpenter Prerequisites

Before installing Karpenter, you need to prepare several AWS resources and permissions.
The required prerequisites are:

IAM role for Karpenter
- Used by the Karpenter controller to call AWS APIs.
IAM role for Karpenter-provisioned nodes
- Attached to worker nodes launched by Karpenter.
Subnets for Karpenter-provisioned nodes
- Each subnet must have the karpenter.sh/discovery tag.
Security groups for Karpenter-provisioned nodes
- Each security group must have the karpenter.sh/discovery tag.
EKS access entry for Karpenter-provisioned nodes
- The access entry type should be EC2_LINUX or EC2_WINDOWS, depending on the node operating system.
Optional: SQS queue
- Required when using Karpenter’s interruption handling feature.
Optional: EventBridge rule and target
- Used to forward AWS interruption events to the SQS queue.

You can refer to the following IaC examples:

📊 Installing Karpenter with Helm

Karpenter can be installed easily using the official Helm chart.

1
2
3
4
5
6
7
8


helm upgrade --install karpenter oci://public.ecr.aws/karpenter/karpenter \
 --version <KARPENTER_VERSION> \
 --namespace <KARPENTER_NAMESPACE> \
 --create-namespace \
 --set "settings.clusterName=<CLUSTER_NAME>" \
 --set "settings.interruptionQueue=<INTERRUPTION_QUEUE_NAME>" \
 --set "settings.enableZonalShift=<ENABLE_ZONAL_SHIFT>" \
 --wait

The main values are:

settings.clusterName: The name of the EKS cluster.
settings.interruptionQueue: The SQS queue used for interruption handling.
settings.enableZonalShift: Enables zonal shift support, allowing Karpenter to avoid impaired Availability Zones when supported.

⚙️ Configuration Example

NodePool

Here is a simple NodePool example.

To use Karpenter, you need at least one NodePool and one corresponding NodeClass, such as EC2NodeClass.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
 name: default
spec:
 # Priority of this NodePool.
 # A higher weight gives the NodePool higher scheduling priority.
 weight: 10

 template:
 spec:
 # Node requirements
 requirements:
 - key: kubernetes.io/arch
 operator: In
 values: ["amd64"]

 - key: kubernetes.io/os
 operator: In
 values: ["linux"]

 - key: karpenter.sh/capacity-type
 operator: In
 values: ["spot", "on-demand", "reserved"]

 - key: karpenter.k8s.aws/instance-category
 operator: In
 values: ["c", "m", "r"]

 - key: karpenter.k8s.aws/instance-generation
 operator: Gt
 values: ["2"]

 # Reference to the EC2NodeClass
 nodeClassRef:
 group: karpenter.k8s.aws
 kind: EC2NodeClass
 name: default

 # Node expiration time
 expireAfter: "720h"

 limits:
 # Maximum CPU capacity that this NodePool can provision
 cpu: 64

 disruption:
 # If set to WhenEmptyOrUnderutilized, Karpenter may remove or replace
 # empty or underutilized nodes to reduce cost.
 #
 # If set to WhenEmpty, Karpenter only consolidates nodes that do not
 # have any workload pods.
 consolidationPolicy: WhenEmptyOrUnderutilized

 # The amount of time Karpenter waits before consolidating a node
 # after a pod has been added or removed.
 consolidateAfter: 1m

NodeClass

Here is an EC2NodeClass example.

EC2NodeClass defines AWS-specific node settings, such as the node IAM role, AMI selection, subnet selection, security group selection, and EC2 tags.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


apiVersion: karpenter.k8s.aws/v1
kind: EC2NodeClass
metadata:
 name: default
spec:
 # You must specify either `role` or `instanceProfile`.
 role: <NODE_ROLE_NAME>

 # AMI selection
 amiSelectorTerms:
 - alias: al2023@latest

 # Subnet discovery
 subnetSelectorTerms:
 - tags:
 karpenter.sh/discovery: <CLUSTER_NAME>

 # Security group discovery
 securityGroupSelectorTerms:
 - tags:
 karpenter.sh/discovery: <CLUSTER_NAME>

 # Tags added to EC2 instances created by Karpenter
 tags:
 ManagedBy: "Karpenter"

🧑‍🔬 Testing Node Autoscaling

Once your setup is complete, you can test whether Karpenter provisions nodes correctly.

Create a sample nginx deployment with enough replicas and CPU requests to trigger node autoscaling:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx
 labels:
 app: nginx
spec:
 replicas: 10
 selector:
 matchLabels:
 app: nginx
 template:
 metadata:
 labels:
 app: nginx
 spec:
 containers:
 - name: nginx
 image: nginx:latest
 resources:
 requests:
 cpu: "500m"
EOF

This deployment creates 10 pods, each requesting 500m CPU.
If your current cluster does not have enough available capacity, some pods will remain pending. Karpenter should detect those pending pods and provision new worker nodes automatically.
You can watch the pods and nodes with the following commands:

1
2


kubectl get pods -w
kubectl get nodes -w

You can also check whether the newly created EC2 instances have the tag defined in your EC2NodeClass:

1

ManagedBy: Karpenter

📚 References

Karpenter - documentations

CKA Review: Preparation Strategy, Exam Experience, and Takeaways (2026 Ver)

Sun, 19 Apr 2026 09:30:00 +0900

작년 말에 프로그래머스에서 얼리버드 할인으로 약 27~8만원에 바우처를 구매했는데, 올해 내로 모두 응시할 계획이고, 우선 CKA를 먼저 준비했다.

ℹ️ Exam Information

CKA(Certified Kubernetes Administrator)

Provider: Linux Foundation
Exam format and scope: A performance-based exam focused on solving problems while working with Kubernetes
- Storage: 10%
- Troubleshooting: 30%
- Workloads & Scheduling: 15%
- Cluster Architecture, Installation & Configuration: 25%
- Services & Networking: 20%
Exam duration: 120 minutes
Kubernetes version: v1.35 (as of April 18, 2026; The exam version is usually updated 1-2 months after a new minor version is released)
Cost: $445
- After purchase, you can schedule the exam within one year
- One retake is included
- It is recommended not to but at full price and instread look for discounts through coupons
Exam environment: Online, using the PSI Secure Browser, with SSH access for each question on an Xfce-based Linux host
- Room and camera requirements:
  - You must take the exam alone in the room
  - No one, including children, adults, or animals, may enter
  - The environment must be quiet and free of disturbances
  - You may not cover your mouth during the exam
  - There must be no printed materials posted on the walls
  - Framed pictures and similar items are allowed
  - If a whiteboard is mounted on the wall, it must be completely blank
  - There must be nothing under the desk
  - Other than the computer required for the exam, all other items must be removed and kept out of reach during the exam
  - Earphones are not allowed
  - You may not wear anything on your wrists
  - Water is allowed only if it is in a transparent, unlabeled bottle
- Exam equipment requirements:
  - Supported operating systems: latest Windows 10 or 11 / macOS / Linux (Ubuntu only)
  - No other processes may be running besides the PSI browser (such as web browsers, note-taking apps, etc.)
  - A microphone and webcam must be available
  - A stable network connection is recommended
  - A personal PC or laptop is recommended rather than a company-issued device
  - A network without restrictions such as firewalls is recommended
  - A monitor of at least 15 inches is recommended
  - Additional monitors are not allowed
- There may be additional restrictions (for detauls, refer to the Linux Foundtation)
Identification:
- The ID must include a photo
- The English name on the ID must match the name used for exam registration
- Passport, international driver’s license, etc.

📖 Exam preparation

My total preparation period was three weeks. I think I spent about 1–2 hours per day on average.
For lectures, I used Udemy - Certified Kubernetes Administrator (CKA) with Practice Tests, and I also solved the KodeKloud practice problems provided alongside the course immediately after finishing each section.
Overall, I was satisfied with the course. The explanations were clear and beginner-friendly, and since it is usually difficult to recreate these environments on your own, it was very convenient to have problem scenarios provided right away for practice.
Also, the course did not only cover topics important for the CKA exam itself, but also explained related background knowledge. That made it a good review for topics I already knew, while helping me easily learn concepts I was unfamiliar with.

Two days before the exam, I worked through the Lightning Labs and Mock Exams provided on KodeKloud in connection with the course.
And the day before the exam, I completed the two mock exams on Killer.sh that were included when I registered for the test.

On the day of the exam, I reread the notes I had made from the questions I had gotten wrong while walking in the morning.

✏️ During the exam

Because the exam conditions are quite strict, I felt it would be realistically difficult to take it at home.
So, like many others in online reviews, I reserved a private room at a study café in advance and took the exam there.
I booked the room from 09:00 to 12:00 and scheduled the exam for 09:30 to 11:30, which turned out to be just right.

You can enter the exam environment 30 minutes before the start time, so if you go in early, you can complete the room check in advance and begin the exam right away.
Once the environment check started, they first verified my ID. In some other reviews, people said that if your photo had already been submitted during exam registration, they skipped the ID check, but in my case they checked it again.
After that, I had to show my surroundings, and I carefully used my laptop webcam to show even the area under the desk.
I also heard that by connecting through a QR code, you can briefly use your smartphone to help show the exam environment.
Finally, I showed myself putting my smartphone away, then showed my wrists and ears by turning them toward the camera, and then the exam began.
When I asked whether a laptop stand and a wireless mouse were allowed, I was told that both were permitted.

After that, I worked through the questions.
The difficulty level was a little harder than KodeKloud, but easier than Killer.sh.
People usually say that if you can pass Killer.sh, you are in a fairly safe range for the real exam.
From what I have seen in the community, quite a few people still pass the actual exam even if they fail Killer.sh.

You can move freely between questions, and if you place a flag on a question, it gets marked in the list so it is easier to review later.
At the top of each question, the system suggests relevant documentation links, and the SSH information you need to connect can be copied and pasted directly.
The body of each question is divided into a context section explaining the scenario and a task section describing what you need to do.
Some questions also include a test command to verify your work, though passing that check does not necessarily mean your answer is fully correct. For example, there could still be a namespace mismatch.

VSCodium is available, although you cannot install plugins.
I personally just used the terminal and Vim, but if you prefer a VS Code–style environment, it seems like a good option.

🚀 Result

24 hours later, the result came out!
I rememvered that I had used the wrong namespace on the exam, so I expected to lose a significant number of points because of it.
Still, since I had already scored above the passing mark on Killer.sh, I was not too worried about whether I would pass. I ended up with a score of 76%, which honestly did not quite meet my own expectations.
That said, what matters most is that I passed, so I decided to put my disappointment behind me.
(And anyway, I have to take it again in two years 😂)

The certificate can be downloaded as a PDF.
You can also claim an Open Badge on Credly.

🍕 Latest informations (April 2026) and tips

If you look at older reviews, many recommend setting up aliases and shell autocompletion yourself, but that is no longer necessary.
From the base host, you move into a different environment for each question via SSH, and alias k=“kubectl” as well as autocompletion are already configured.
Overly customized aliases are not very meaningful, since the environment changes from question to question. For example, something like kgpoy = kubectl get pod -o yaml is hardly useful.
It is best to just use the default setup as provided.

The following are relatively newer topics, so they are quite likely to appear on the exam:

Kustomize
Helm
Gateway API
CustomResourceDefinition (CRD)

There are also several other useful tips for the exam:

It is good to work imperatively when possible and make active use of --dry-run=client -o yaml.
Even when practicing in the KodeKloud environment, try not to rely on lecture materials, notes, or personal memos. Instead, practice using the official documentation just as you would in the real exam.
Since the exam is meant to test your Kubernetes knowledge, other details are usually explained kindly for you.
- For example, it may tell you how an nginx configuration should be modified, or what command should be used inside a sidecar container.
Still, the more commands you know, the better. For example:
- k get no <nodename> -o yaml | grep -A10 "taints": print the 10 lines after the taints section of a node
- journalctl -u kubelet: check kubelet logs
- openssl x509 -noout -text -in <cert-file>: inspect certificate information
- kubeadm token create --print-join-command: create a join token and print the worker node join command
It can also be helpful to become familiar with crictl, yq, and kubectl features such as jsonpath and custom headers.
Read each question carefully and avoid confusion over namespaces. Even a small phrase can be a subtask or an important condition.
Make full use of copy and paste. Copying resource names and similar values can help reduce typos.
- In the browser, use Ctrl + C / Ctrl + V, and in the terminal, use Ctrl + Shift + C / Ctrl + Shift + V.

🛏️ Conclusion

Although I earned the CKA, it is important to remember that this does not mean I have mastered Kubernetes.
I still have a lot of shortcomings, and there is still much more for me to learn.
At most, I have learned how to juggle the ball and dribble on the training ground; what really matters is performing well in an actual match.

Still, it is true that preparing for the exam helped me learn much more about Kubernetes, and significantly improved my fundamental hands-on ability to work with clusters.
I also still have vouchers for CKAD and CKS, so I am planning to take those later this year.

Building Amazon EKS with Custom Terraform Modules

Tue, 14 Apr 2026 23:43:27 +0900

🌯 Introduction

I had used Amazon EKS during the K-DT(Digital Training) program last summer, but I was not responsible for building or operating the cluster myself.
In my current project, I had full ownership of the AWS infrastructure, so I needed to design and provision the EKS cluster on my own.

At First, I considered using terraform-aws-modules/eks/aws module.
However, it felt too abstract for my use case, and the large number of input variables made it harder for me to understnad what was actually being created.
Instead of relying on a highly abstracted module, I decided to build the EKS cluster using my own smaller Terraform modules.
This approach helped me to understand each component more clearly and gave me more control over the infrastructure design.

The diagram below shows the dependencies of modules.

❓ What is Amazon EKS?

Amazon EKS(Elastic Kubernetes Service) is AWS’s managed Kubernetes service.
It allows you to run Kubernetes on AWS without having to manage the control plane yourself.

When running on Kubernetes in a public cloud environment, using a managed service is usually a better choice than building and operating a cluster directly on virtual machines.
A managed service reduces operational burden and provies tighter integration with the cloud platform.

Some of the main benefits are:

managed control plane operations
easier node scaling and lifecycle management
built-in networking integration with VPC, Load Balancer, and CNI
integration with AWS services such as IAM, CloudWatch, and EBS

EKS Standard vs Auto Mode

Amazon EKS has two main approaches:

EKS Standard
- AWS manages the control plane
- You manage more of the cluster components yourself
  - node groups, addons, and others
EKS Auto Mode
- AWS manages more of the operational details automatically
- it comes with additional fees

This post focuses on EKS Standard because I wanted to avoid the extra cost of Auto Mode and keep the infrastructure design explicit.
Since this project was also a learning opportunity, managing the building block myself helped me understand EKS more deeply.

🧀 EKS Cluster

This module creates the core EKS control plane.
It is responsible for provisioning the cluster itself, the IAM role used by EKS, and the network configuration for the cluster API endpoint.
I designed it to keep the cluster behavior explicit, especially around private access, control plane logging, and Auto Mode settings.

`main.tf`

The main part is aws_eks_cluster resource, which defines the EKS control plane.

One design choice here is support for private mode.
When enabled, the Kubernetes API endpoint is exposed privately instead of publicly.
In that case, I also create a dedicated security group and allow HTTPS access(Kubernetes API) from within the VPC so that internal resources, such as a bastion host, can reach the cluster API safely.

In access_config, I set authentication_mode = "API" so that cluster access can be managed through EKS access entries, instead of the legacy aws-auth ConfigMap.

The module also creates an IAM role for the EKS control plane and attaches the required AWS-managed policy.
This role allows EKS to interact with other AWS services as part of cluster operation.

By default, EKS cluster encrypts secrets at rest.
If you want to make secrets to be encrypted with CMK(Customer Managed Key) , you can use encryption_config block.
Visit here for more informations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


resource "aws_security_group" "eks_control_plane_access" {
 count = var.private_mode ? 1 : 0

 name = "${var.cluster_name}-eks-control-plane-access"
 description = "Allow bastion to reach EKS private API"
 vpc_id = var.vpc_id
}

resource "aws_vpc_security_group_ingress_rule" "eks_api_from_vpc" {
 count = var.private_mode ? 1 : 0

 security_group_id = aws_security_group.eks_control_plane_access[0].id
 cidr_ipv4 = var.vpc_cidr
 ip_protocol = "tcp"
 from_port = 443
 to_port = 443
}
resource "aws_eks_cluster" "eks" {
 name = var.cluster_name

 access_config {
 authentication_mode = "API"
 }

 role_arn = aws_iam_role.eks.arn
 version = var.kubernetes_version
 bootstrap_self_managed_addons = var.bootstrap_self_managed_addons
 enabled_cluster_log_types = var.enabled_cluster_log_types

 vpc_config {
 subnet_ids = var.subnet_ids
 endpoint_public_access = !var.private_mode
 endpoint_private_access = var.private_mode

 security_group_ids = aws_security_group.eks_control_plane_access[*].id
 }

 # Disable Auto-Mode
 compute_config {
 enabled = false
 }

 control_plane_scaling_config {
 tier = var.cp_scaling_tier
 }

 upgrade_policy {
 support_type = "STANDARD"
 }

 depends_on = [aws_iam_role_policy_attachment.cluster_AmazonEKSClusterPolicy]

}

# IAM Role for Contorl Plane
resource "aws_iam_role" "eks" {
 name = "${var.cluster_name}-role"
 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Action = [
 "sts:AssumeRole",
 "sts:TagSession"
 ]
 Effect = "Allow"
 Principal = {
 Service = "eks.amazonaws.com"
 }
 },
 ]
 })
}

resource "aws_iam_role_policy_attachment" "cluster_AmazonEKSClusterPolicy" {
 policy_arn = "arn:aws:iam::aws:policy/AmazonEKSClusterPolicy"
 role = aws_iam_role.eks.name
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


variable "cluster_name" {
 description = "EKS cluster name"
 type = string
}

variable "kubernetes_version" {
 description = "EKS version"
 type = string
}

variable "bootstrap_self_managed_addons" {
 description = "Wheter to Enable VPC CNI and kube-proxy"
 type = bool
 default = true
}

variable "vpc_id" {
 description = "VPC ID"
 type = string
}

variable "vpc_cidr" {
 description = "VPC CIDR Block"
 type = string
}

variable "subnet_ids" {
 description = "Subnet IDs"
 type = list(string)
}

variable "private_mode" {
 description = "Enable EKS private access"
 type = string
}

variable "cp_scaling_tier" {
 description = "Scaling tier for Control Plane"
 type = string
 default = "standard"
}

variable "enabled_cluster_log_types" {
 type = set(string)
 default = []
 validation {
 condition = alltrue([
 for t in var.enabled_cluster_log_types :
 contains(["api", "audit", "authenticator", "controllerManager", "scheduler"], t)
 ])
 error_message = "enabled_cluster_log_types must contain only valid EKS control plane log types."
 }
}

`outputs.tf`

By default, Cluster security group is created by default.
For more informations, see here .

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


output "cluster_name" {
 value = aws_eks_cluster.eks.name
}

output "endpoint" {
 value = aws_eks_cluster.eks.endpoint
}

output "ca_certificate" {
 value = aws_eks_cluster.eks.certificate_authority[0].data
}

output "arn" {
 value = aws_eks_cluster.eks.arn
}

output "cluster_security_group_id" {
 value = aws_eks_cluster.eks.vpc_config[0].cluster_security_group_id
}

🔑 Access Entries

Since this cluster uses authentication_mode = "API", cluster access is managed through EKS access entries instead of the legacy aws-auth ConfigMap.

The difference is where access is managed. With aws-auth, IAM-to-Kubernetes mappings are stored inside the cluster as a Kubernetes ConfigMap.
With access entries, the same kind of access management is defined through AWS-managed EKS resources.
Newer model is preferred because it fits IaC-based infrastructure management much better and keeps cluster access configuration aligned with the AWS control plane.

Granting access through assumed IAM roles rather than IAM users is also recommended.
In practice, this means an engineer first assumes a role and then uses that role to access the cluster.
This is a better fit for operational environments because roles provide temporary credentials, while IAM users are usually tied to long-lived credentials.
From both a security and management perspective, using roles is the more natural approach.
For an IAM user to assume an IAM role, the user needs permission to call sts:AssumeRole on the role, and the role’s trust policy must allow that user.

Another important point is that EKS access scope in access policy association do not replace Kubernetes RBAC.
Access scope is just a simple access-control scope which is managed by AWS, while Kubernetes RBAC still works in cluster itself.
These two layers can work together.
In this module, I can optionally assign kubernetes_groups to the principal so that the access entry can integrate with native Kubernetes RBAC when more fine-grained authorization is needed.
For more information, visit here

This module is built around two main resources:

aws_eks_access_entry, which registers an IAM principal with the cluster
aws_eks_access_policy_association, which attaches one or more EKS access policies to that principal

`main.tf`

The aws_eks_access_entry resource creates the access entry for a single IAM principal.
After that, aws_eks_access_policy_association resources are created from a map variable, which makes it possible to attach multiple policies to the same principal. \

Each policy association also defines its access scope.
Depending on the configuration, access can be granted either at the cluster level or only for specific namespaces. \

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


resource "aws_eks_access_entry" "access" {
 cluster_name = var.cluster_name
 principal_arn = var.principal_arn
 kubernetes_groups = var.kubernetes_groups
}

resource "aws_eks_access_policy_association" "access" {
 for_each = var.eks_access_policy_association

 cluster_name = var.cluster_name
 principal_arn = var.principal_arn
 policy_arn = each.value.policy_arn

 access_scope {
 type = each.value.access_scope_type
 namespaces = each.value.namespaces
 }
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


variable "cluster_name" {
 description = "EKS cluster name"
 type = string
}

variable "principal_arn" {
 description = "IAM role ARN registering access policy"
 type = string
}

variable "kubernetes_groups" {
 description = "List of Kubernetes groups to assign to the principal"
 type = list(string)
 default = []
}

variable "eks_access_policy_association" {
 type = map(object({
 policy_arn = string
 access_scope_type = string
 namespaces = optional(list(string))
 }))
 default = {}
 validation {
 condition = alltrue([
 for t in var.eks_access_policy_association :
 contains(["namespace", "cluster"], t.access_scope_type)
 ])
 error_message = "eks_access_policy_association must contain only 'namespace' or 'cluster'"
 }
}

👪 Node Groups

EKS managed node groups automate the provisioning and lifecycle management of worker nodes.

This module has more input variables than some of the earlier modules because node groups tend to vary a lot depending on workload requirements.
Instance type, capacity model, scaling limits, labels, taints, and disk size can all change depending on how the cluster is intended to be used.

Worker nodes also need a role with the required AWS permissoins.
At minimum, the nodes need policies such as AmazonEKSWorkerNodePolicy and AmazonEC2ContainerRegistryPullOnly so that they can join the cluster and pull container images from Amazon ECR.

`main.tf`

The core resource in this module is aws_eks_node_group, which craetes a managed node group attached to the cluster.

I exposed Kubernetes-specific scheduling options through labels and taints.
These settings are important when different workloads need to be separated across different groups of nodes.
For example, some nodes may be dedicated to system workloads, while others may be reserved for specific applications or cost-optimized Spot workloads.

Another detail is the lifecycle block ignoring changes to desired_size.
I added this because the desired number of nodes may change dynamically during operation, and I did not want Terraform to constantly treat that runtime scaling state as drift.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


resource "aws_eks_node_group" "ng" {
 cluster_name = var.cluster_name
 node_group_name = var.node_group_name
 node_role_arn = aws_iam_role.ng.arn

 ami_type = var.ami_type
 instance_types = var.instance_types
 subnet_ids = var.subnet_ids
 capacity_type = var.capacity_type
 disk_size = var.disk_size

 scaling_config {
 desired_size = var.scaling.desired_size
 min_size = var.scaling.min_size
 max_size = var.scaling.max_size
 }

 labels = var.labels

 dynamic "taint" {
 for_each = var.taints
 content {
 key = taint.value.key
 value = taint.value.value
 effect = taint.value.effect
 }
 }

 lifecycle {
 ignore_changes = [scaling_config[0].desired_size]
 }

 depends_on = [aws_iam_role_policy_attachment.ng_attachment]
}

resource "aws_iam_role" "ng" {
 name = "${var.node_group_name}-role"

 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [{
 Action = "sts:AssumeRole"
 Effect = "Allow"
 Principal = {
 Service = "ec2.amazonaws.com"
 }
 }]
 })
}

resource "aws_iam_role_policy_attachment" "ng_attachment" {
 for_each = var.role_policy_attachment

 policy_arn = each.value
 role = aws_iam_role.ng.name
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91


variable "cluster_name" {
 description = "Name of EKS Cluster"
 type = string
}

variable "node_group_name" {
 description = "Name of node group"
 type = string
}

variable "subnet_ids" {
 description = "ID list of subnet"
 type = list(string)
}

variable "ami_type" {
 description = "Type of AMI"
 type = string
 validation {
 condition = contains([
 "AL2_x86_64", "AL2_x86_64_GPU", "AL2_ARM_64", "CUSTOM",
 "BOTTLEROCKET_ARM_64", "BOTTLEROCKET_x86_64",
 "BOTTLEROCKET_ARM_64_FIPS", "BOTTLEROCKET_x86_64_FIPS",
 "BOTTLEROCKET_ARM_64_NVIDIA", "BOTTLEROCKET_x86_64_NVIDIA",
 "BOTTLEROCKET_ARM_64_NVIDIA_FIPS", "BOTTLEROCKET_x86_64_NVIDIA_FIPS",
 "WINDOWS_CORE_2019_x86_64", "WINDOWS_FULL_2019_x86_64",
 "WINDOWS_CORE_2022_x86_64", "WINDOWS_FULL_2022_x86_64",
 "WINDOWS_CORE_2025_x86_64", "WINDOWS_FULL_2025_x86_64",
 "AL2023_x86_64_STANDARD", "AL2023_ARM_64_STANDARD",
 "AL2023_x86_64_NEURON", "AL2023_x86_64_NVIDIA", "AL2023_ARM_64_NVIDIA"
 ], var.ami_type)
 error_message = "amiType does not match. check: https://docs.aws.amazon.com/eks/latest/APIReference/API_Nodegroup.html#AmazonEKS-Type-Nodegroup-amiType"
 }
}

variable "instance_types" {
 description = "List of instance type"
 type = list(string)
}

variable "capacity_type" {
 description = "Node Capacity Type"
 type = string
 validation {
 condition = contains(["ON_DEMAND", "SPOT"], var.capacity_type)
 error_message = "Valid value: <ON_DEMAND | SPOT>"
 }
}

variable "disk_size" {
 description = "Disk size for each worker node"
 type = number
 default = 20
}

variable "scaling" {
 description = "Scaling Capacity"
 type = object({
 desired_size = number
 min_size = number
 max_size = number
 })
}

variable "labels" {
 description = "Node labels"
 type = map(string)
}

variable "taints" {
 description = "Taints for rule"
 type = map(object({
 key = string
 value = optional(string)
 effect = string
 }))

 validation {
 condition = alltrue([
 for _, v in var.taints :
 contains(["NO_SCHEDULE", "NO_EXECUTE", "PREFER_NO_SCHEDULE"], v.effect)
 ])
 error_message = "Valid effect: <NO_SCHEDULE | NO_EXECUTE | PREFER_NO_SCHEDULE>"
 }
}

variable "role_policy_attachment" {
 description = "Role policies to attach nodes"
 type = set(string)
 default = []
}

📲 Addons

Compared to the other parts of this EKS setup, add-ons are relatively simple.
In Terraform, an EKS add-on can be created with a single aws_eks_addon resource, so this is one of the few cases where creating a separate module is optional.

I still separated it into its own module for consistency. \ Since the rest of the cluster is also organized into small building blocks, keeping add-ons in a dedicated module made the overall structure easier to understand and extend later.

`main.tf`

1
2
3
4


resource "aws_eks_addon" "addon" {
 cluster_name = var.cluster_name
 addon_name = var.addon_name
}

`variables.tf`

1
2
3
4
5
6
7
8
9


variable "cluster_name" {
 description = "Name of EKS Cluster"
 type = string
}

variable "addon_name" {
 description = "Name of Addon"
 type = string
}

⛓️ Pod Identity Associations

EKS Pod Identity allows pods to access AWS services using IAM roles, without storing AWS credentials inside containers.
The idea is similar to how an EC2 instance profile provides credentials to an EC2 instance, but in this case the identity is assigned to a Kuberentes workload.

Instead of distributing static AWS credentials to applications or reusing the worker node’s IAM role, I associate a dedicated IAM role with a Kubernetes service account.
Pods that use that service account can then access AWS resources with only the permessions they actually need.

This is useful because it keeps AWS permission scoped at the workload level rather than the node level.
In other words, different applications in the same cluster can use different IAM roles depending on their responsiblities.

`main.tf`

First, this module creates IAM role that can be assumed by EKS pods.
Then it attaches the IAM policy that defines what the workload is allowed to do in AWS.
Finally, it creates the pod identity association that connects the IAM role to a specific Kubernetes service account in a specific namespace.
Pod identity agent is deployed by daemonset, providing pods to get its credentials from IAM role.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


resource "aws_iam_role" "pod" {
 name = var.role_name

 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Effect = "Allow"
 Principal = {
 Service = "pods.eks.amazonaws.com"
 }
 Action = [
 "sts:AssumeRole",
 "sts:TagSession"
 ]
 }
 ]
 })
}

resource "aws_iam_role_policy_attachment" "pod" {
 role = aws_iam_role.pod.name
 policy_arn = var.policy_arn
}

resource "aws_eks_pod_identity_association" "association" {
 cluster_name = var.cluster_name
 namespace = var.namespace
 service_account = var.service_account
 role_arn = aws_iam_role.pod.arn
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


variable "cluster_name" {
 description = "Name of EKS Cluster"
 type = string
}

variable "role_name" {
 description = "IAM role name to assign pod"
 type = string
}

variable "policy_arn" {
 description = "IAM policy arn"
 type = string
}

variable "namespace" {
 description = "Kubernetes namespace"
 type = string
}

variable "service_account" {
 description = "Name of serviceAccount"
 type = string
}

🚪 (Optional) Bastion Host

When the EKS cluster runs in private API mode, the Kubernetes API endpoint is not exposed to the public internet.
That means cluster administration has to be performed from somewhere inside the VPC or from a connected network.

A bastion host is one way to solve that problem, but it is not the only option.
Other approaches, such as Client VPC or Site-to-Site VPN, can also provide private connectivity to the cluster.
In this project, however, I chose a bastino host combined with AWS Systems Manager Session Manager.
Because VPN services are too expensive and increase operational overheads.

`main.tf`

This module creates a small EC2 instance that acts as an administrative entry point into the private network.
The instance itself is intentionally simple: it uses a minimal security group, an IAM instance profile for Systems Manager access, and a small amount of bootstrap configuration through user_data.

One design choice I like here is avoiding traditional SSH-based bastion access.
Instead of opening inbound SSH, the instance is managed through SSM Session Manager.
This keeps inbound access closed while still allowing interactive administration when needed.
In practice, that reduces operational overhead compared to managing SSH keys and security group ingress rules.

I also attached a small custom IAM policy that allows the bastion to call eks:DescribeCluster.
This is useful because tools such as aws eks update-kubeconfig rely on EKS cluster metadata in order to build client configuration for kubectl.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114


data "aws_ami" "ubuntu" {
 most_recent = true

 filter {
 name = "name"
 values = ["ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-arm64-server-*"]
 }

 filter {
 name = "virtualization-type"
 values = ["hvm"]
 }

 owners = ["099720109477"] # Canonical
}

resource "aws_security_group" "bastion" {
 name = "bastion_ssm"
 description = "Deny inbound traffic and allow outbound traffic"
 vpc_id = var.vpc_id
}

resource "aws_vpc_security_group_egress_rule" "bastion_internet" {
 security_group_id = aws_security_group.bastion.id

 cidr_ipv4 = "0.0.0.0/0"
 from_port = 443
 ip_protocol = "tcp"
 to_port = 443
}

resource "aws_iam_instance_profile" "ssm" {
 name = "${var.name}-profile"
 role = aws_iam_role.bastion.id
}

resource "aws_instance" "bastion" {
 ami = data.aws_ami.ubuntu.id
 instance_type = var.instance_type

 subnet_id = var.subnet_id
 vpc_security_group_ids = [aws_security_group.bastion.id]
 associate_public_ip_address = var.associate_public_ip_address

 iam_instance_profile = aws_iam_instance_profile.ssm.name

 metadata_options {
 http_tokens = "required"
 }

 root_block_device {
 encrypted = true
 volume_type = "gp3"
 }

 user_data = file("${path.module}/user_data.sh")
 user_data_replace_on_change = true

 tags = {
 Name = var.name
 }
}

resource "aws_iam_role" "bastion" {
 name = var.name
 path = "/"
 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Sid = "AllowEC2SSM"
 Effect = "Allow"
 Action = [
 "sts:AssumeRole"
 ]
 Principal = {
 Service = "ec2.amazonaws.com"
 }
 }
 ]
 })

 tags = {
 Purpose = "Bastion"
 }
}

resource "aws_iam_role_policy_attachment" "bastion_ssm" {
 role = aws_iam_role.bastion.name
 policy_arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
}

data "aws_iam_policy_document" "bastion_access_eks" {
 statement {
 sid = "AllowEKStoBastion"
 actions = [
 "eks:DescribeCluster"
 ]
 resources = [
 var.eks_arn
 ]
 }
}

resource "aws_iam_policy" "bastion_access_eks" {
 name = "${var.name}-access-eks"
 path = "/"
 policy = data.aws_iam_policy_document.bastion_access_eks.json
}

resource "aws_iam_role_policy_attachment" "bastion_access_eks" {
 role = aws_iam_role.bastion.name
 policy_arn = aws_iam_policy.bastion_access_eks.arn
}

`user_data.sh`

It installs useful infra tools, and adds small shell configurations.
This script makes the bastion host to prepared workstation inside the VPC.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66


#!/usr/bin/env bash
set -euo pipefail

export DEBIAN_FRONTEND=noninteractive

apt-get update
apt-get upgrade -y

apt-get install -y apt-transport-https ca-certificates curl gnupg unzip

# kubectl
mkdir -p /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.35/deb/Release.key |
 gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.35/deb/ /' \
 >/etc/apt/sources.list.d/kubernetes.list
apt-get update
apt-get install -y kubectl

# OpenTofu
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://get.opentofu.org/opentofu.gpg | tee /etc/apt/keyrings/opentofu.gpg >/dev/null
curl -fsSL https://packages.opentofu.org/opentofu/tofu/gpgkey | gpg --dearmor -o /etc/apt/keyrings/opentofu-repo.gpg
chmod a+r /etc/apt/keyrings/opentofu.gpg /etc/apt/keyrings/opentofu-repo.gpg

cat >/etc/apt/sources.list.d/opentofu.list <<'EOF'
deb [signed-by=/etc/apt/keyrings/opentofu.gpg,/etc/apt/keyrings/opentofu-repo.gpg] https://packages.opentofu.org/opentofu/tofu/any/ any main
deb-src [signed-by=/etc/apt/keyrings/opentofu.gpg,/etc/apt/keyrings/opentofu-repo.gpg] https://packages.opentofu.org/opentofu/tofu/any/ any main
EOF

apt-get update
apt-get install -y tofu

ARCH="$(uname -m)"

case "$ARCH" in
x86_64)
 AWSCLI_URL="https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip"
 ;;
aarch64 | arm64)
 AWSCLI_URL="https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip"
 ;;
*)
 echo "Unsupported architecture: $ARCH"
 exit 1
 ;;
esac

curl -fsSL "$AWSCLI_URL" -o "awscliv2.zip"
unzip -o awscliv2.zip
./aws/install

# SSM Agent
snap install amazon-ssm-agent --classic || true
systemctl enable snap.amazon-ssm-agent.amazon-ssm-agent.service || true
systemctl restart snap.amazon-ssm-agent.amazon-ssm-agent.service || true

# Shell
curl -fsSL https://starship.rs/install.sh | sh -s -- -y

cat <<'EOF' >>/home/ubuntu/.bashrc
eval "$(starship init bash)"
alias k='kubectl'
EOF

chown ubuntu:ubuntu /home/ubuntu/.bashrc

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


variable "name" {
 description = "Name of the instance"
 type = string
}

variable "vpc_id" {
 description = "VPC ID"
 type = string
}

variable "subnet_id" {
 description = "Subnet ID"
 type = string
}

variable "instance_type" {
 description = "EC2 Instance Type"
 type = string
 default = "t4g.nano"
}

variable "eks_arn" {
 description = "EKS Arn"
 type = string
}

variable "associate_public_ip_address" {
 description = "Associate public IP address"
 type = bool
}

`outputs.tf`

1
2
3
4
5
6
7


output "bastion_id" {
 value = aws_instance.bastion.id
}

output "bastion_role_arn" {
 value = aws_iam_role.bastion.arn
}

🚀 Using Modules

This is the example of using modules.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167


##########
# locals #
##########
locals {
 vpc_cidr = "10.0.0.0/16"

 # Enable/disable EKS private access
 eks_private_mode = true

 # EKS Addon list
 eks_addons = toset([
 "coredns",
 "kube-proxy",
 "vpc-cni",
 "aws-ebs-csi-driver",
 "eks-pod-identity-agent",
 ])

 # Pod identity associations
 pod_identity_associations = {
 vpc_cni = {
 role_name = "${var.cluster_name}-vpc-cni"
 policy_arn = "arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy"
 namespace = "kube-system"
 service_account = "aws-node"
 }
 ebs_csi = {
 role_name = "${var.cluster_name}-ebs-sci"
 policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy"
 namespace = "kube-system"
 service_account = "ebs-csi-controller-sa"
 }
 }
}

########################################################
# EKS - Cluster #
# #
# NOTE: #
# By default, EKS secrets are protected with enveloped #
# encryption in EKS version 1.28 or higher #
########################################################
module "eks_cluster" {
 source = "../../../modules/eks-cluster"

 cluster_name = var.cluster_name
 kubernetes_version = "1.35"
 vpc_id = module.vpc.vpc_id
 vpc_cidr = local.vpc_cidr
 subnet_ids = module.vpc.private_subnet_ids
 private_mode = local.eks_private_mode

 enabled_cluster_log_types = []
 cp_scaling_tier = "standard"
}

######################
# EKS - Access Entry #
######################
module "eks_access_entry_private" {
 count = local.eks_private_mode ? 1 : 0
 source = "../../../modules/eks-access-entry"

 # Use module output instead of var.cluter_name because of the dependency implication.
 cluster_name = module.eks_cluster.cluster_name
 principal_arn = module.bastion[0].bastion_role_arn

 eks_access_policy_association = {
 clusteradmin = {
 policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
 access_scope_type = "cluster"
 }
 }
}

module "eks_access_entry_public" {
 count = local.eks_private_mode ? 0 : 1
 source = "../../../modules/eks-access-entry"

 cluster_name = module.eks_cluster.cluster_name
 principal_arn = data.terraform_remote_state.shared.outputs.eks_fullaccess_role_arn

 eks_access_policy_association = {
 clusteradmin = {
 policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
 access_scope_type = "cluster"
 }
 }
}

#####################################
# EKS - Node Group #
# Desired Node group size is ignored #
# when comparing the state #
#####################################
module "eks_node_group" {
 source = "../../../modules/eks-node-group"

 cluster_name = module.eks_cluster.cluster_name
 node_group_name = "${var.cluster_name}-ng"

 ami_type = "AL2023_ARM_64_STANDARD"
 subnet_ids = module.vpc.private_subnet_ids
 instance_types = ["t4g.large"]

 capacity_type = "ON_DEMAND"
 disk_size = 20

 scaling = {
 desired_size = 2
 min_size = 2
 max_size = 4
 }

 labels = {
 NodeGroupName = "default"
 }

 taints = {}

 # Role policy Attachment
 role_policy_attachment = [
 "arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy",
 "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly"
 ]
}

################
# EKS - Addons #
################
module "eks-addons" {
 source = "../../../modules/eks-addons"
 for_each = local.eks_addons

 cluster_name = module.eks_cluster.cluster_name
 addon_name = each.value
}


###################################
# EKS - Pod identity associations #
###################################
module "pod_identity_association" {
 source = "../../../modules/eks-pod-identity-association"
 for_each = local.pod_identity_associations

 cluster_name = module.eks_cluster.cluster_name
 role_name = each.value.role_name
 policy_arn = each.value.policy_arn
 namespace = each.value.namespace
 service_account = each.value.service_account
}

################
# Bastion Host #
################
module "bastion" {
 count = local.eks_private_mode ? 1 : 0
 source = "../../../modules/ec2-ssm-bastion"

 name = "bastion-prod"
 vpc_id = module.vpc.vpc_id
 subnet_id = module.vpc.private_subnet_ids[0]
 instance_type = "t4g.nano"
 eks_arn = module.eks_cluster.arn
 associate_public_ip_address = false
}

🪪 Accessing EKS Cluster

If the EKS cluster exposes a public API endpoint, you can access it directly from your local environment by updating your kubeconfig.

1
2


# Add --role-arn <role-arn> if you need to assume a role
aws eks update-kubeconfig --region <region> --name <cluster-name>

If the cluster runs in private mode, you need to access it from inside the VPC or through a connected private network first.
In my setup, that means starting a session on the bastion host through AWS Systems Manager Session Manager.

1

aws ssm start-session --target <instance-id>

From there, you can run aws eks update-kubeconfig and use kubectl against the private cluster endpoint.

➡️ What Comes Next

Provisioning the EKS cluster itself is only the beginning.
In the standard EKS model, there are still several operational components that often need to be installed separately depending on the environment and workload requirements.

Some common examples are:

ArgoCD for GitOps-based deployment
cert-manager for TLS certificate management
AWS Load Balancer Controller for integrating Kubernetes services with AWS load balancers
Karpenter for node autoscaling
Gateway API CRD for newer north-south traffic control management
Observability Stack
and so on

You can also consider AWS EKS Capabilities.

📚 References

Replacing Obsidian Sync with a Self-Hosted LiveSync Stack

Sat, 11 Apr 2026 02:26:09 +0900

🧋 Introduction

My Journey with Note-Taking Apps

I use Obsidian as my persoanl knoweldge base instead of Notion. The reason is simple:

Notion feels too heavy
It comes with too many features I do not really need
The loading speed can feel slow at times

Obsidian, on the other hand, feels lightweight, fast, and much closer to the kind of workflow I want for managing my notes

Sync options for Obsidian

There are many possible options, and I spend quite a bit of time looking through them.

Official options
- Obsidian Sync
  - It’s polished and reliable, but it is a paid service.
- iCloud
  - This can be a solid choice if you are fully in the Apple ecosystem.
  - However, it becomes less practical when you also use non-Apple devices. (I use NixOS btw)
Unofficial options
- Git & GitHub
  - I tried this before, but the mobile experience was not great, expecially when the repository became larger.
  - On iPhone, using apps like Working Copy for pull and push operations did not feel very reliable.
- Syncthing
  - Peer-to-peer sync is a very practical approach, expecially when combined with a WireGuard-based VPN like Tailscale.
  - The main problem for me was the lack of official support on iPhone.
- ⭐ Self-hosted livesync(with CouchDB)
  - The option stood out the most to me.

Why I Chose Self-Hosted LiveSync

In the end, I decided to go with self-hosted LiveSync, backed by CouchDB, for a few reasons:

I already have my own home server running on Proxmox
The LiveSync plugin has a strong community and over 10k GitHub start
It looked fun to build and self-host

In this post, I will walk through how I set up my Obsidian sync stack using CouchDB + Caddy + Tailscale inside a Proxmox LXC container.

🏗️ Provisioning an LXC Container

First, We will provision an LXC Container in a Proxmox Cluster.
I use the Terraform provider bgp/proxmox, to manage resources declaratively.

Downloading Debian 13 LXC Image

Although we are using Terraform, the proxmox_download_file resource currently downloads the LXC image repeatedly, because of a checksum verification issue.
So for now, I will download manually instead.

First, connect to your proxmox cluster:

1

ssh <your-proxmox-cluster>

Then, list officially supported LXC images:

1

pveam available

Download the Debian13 image:

1

pveam download local debian-13-standard_13.1-2_amd64.tar.zst

Terraform Module

We will create a module to make the code reusable.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111


# ./modules/lxc_container/main.tf
terraform {
 required_providers {
 proxmox = {
 source = "bpg/proxmox"
 version = "0.101.0"
 }
 }
}

resource "proxmox_virtual_environment_container" "container" {
 description = var.description

 node_name = var.node_name
 vm_id = var.vm_id

 unprivileged = true
 # If true, it cannot be destoryed.
 protection = var.protection

 features {
 nesting = true
 }

 # Required to turn on tailscaled on LXC container.
 device_passthrough {
 path = "/dev/net/tun"
 }

 # If you want you can make resource quotas to variables.
 cpu {
 cores = 2
 limit = 2
 units = 1024
 }

 memory {
 dedicated = 2048
 swap = 512
 }

 initialization {
 hostname = var.hostname

 ip_config {
 ipv4 {
 address = "dhcp"
 }
 }

 user_account {
 keys = var.ssh_keys
 password = random_password.container.result
 }
 }

 wait_for_ip {
 ipv4 = true
 }

 network_interface {
 name = var.network_interface
 }

 disk {
 datastore_id = var.datastore_id
 size = var.disk_size
 }

 operating_system {
 template_file_id = var.template_file_id
 type = var.os_type
 }

 startup {
 order = "3"
 up_delay = "60"
 down_delay = "60"
 }

 dynamic "mount_point" {
 for_each = var.mount_points

 content {
 path = mount_point.value.path
 volume = mount_point.value.volume

 size = try(mount_point.value.size, null)
 read_only = try(mount_point.value.read_only, null)
 backup = try(mount_point.value.backup, null)
 replicate = try(mount_point.value.replicate, null)
 shared = try(mount_point.value.shared, null)
 quota = try(mount_point.value.quota, null)
 acl = try(mount_point.value.acl, null)
 mount_options = try(mount_point.value.mount_options, null)
 }
 }

 tags = var.tags
}

resource "random_password" "container" {
 length = 16
 override_special = "_%@"
 special = true
}

output "container_password" {
 value = random_password.container.result
 sensitive = true
}

Here’s the module’s variables.tf.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91


# ./module/lxc_container/variables.tf

variable "description" {
 type = string
 description = "LXC description"
}

variable "node_name" {
 type = string
 description = "Proxmox node name"
}

variable "vm_id" {
 type = number
 description = "LXC VM ID"
}

variable "protection" {
 type = bool
 description = "Whether to prevent data"
}

variable "hostname" {
 type = string
 description = "Container hostname"
}

variable "ssh_keys" {
 type = list(string)
 description = "SSH public keys for root account"
 default = []
}

variable "network_interface" {
 type = string
 description = "Container network interface name"
}

variable "datastore_id" {
 type = string
 description = "Datastore ID for root disk"
}

variable "disk_size" {
 type = number
 description = "Root disk size in GB"
}

variable "template_file_id" {
 type = string
 description = "OS template file ID"
}

variable "os_type" {
 type = string
 description = "Container OS type"

 validation {
 condition = contains([
 "alpine",
 "centos",
 "debian",
 "fedora",
 "ubuntu",
 "unmanaged"
 ], var.os_type)
 error_message = "os_type must be one of the supported Proxmox LXC OS types."
 }
}

variable "mount_points" {
 description = "Additional mount points for the container"
 type = list(object({
 path = string
 volume = string
 size = optional(string)
 read_only = optional(bool)
 backup = optional(bool)
 replicate = optional(bool)
 shared = optional(bool)
 quota = optional(bool)
 acl = optional(bool)
 mount_options = optional(list(string))
 }))
 default = []
}

variable "tags" {
 description = "Tags"
 type = list(string)
}

If we expose the IPv4 address as an output, we can connect to the LXC container more easily:

1
2
3
4


# ./modules/lxc_container/outputs.tf
output "ipv4" {
 value = proxmox_virtual_environment_container.container.ipv4
}

`provider.tf`

To passthrough a device, you need to access Proxmox using an administrator account (root@pam) with a password:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


terraform {
 required_providers {
 proxmox = {
 source = "bpg/proxmox"
 version = "0.101.0"
 }
 }
}

provider "proxmox" {
 endpoint = <your_endpoint>
 username = var.proxmox_username
 password = var.proxmox_password
 insecure = true

 ssh {
 agent = true
 username = "root"
 }
}

`main.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# main.tf
locals {
 # Import your SSH public keys here
 ssh_keys = [
 ]
}

module "couchdb" {
 source = "./modules/lxc_container"
 node_name = <your-node-name>
 description = "CouchDB LXC"
 datastore_id = <your-datastore-id>
 protection = true # Recommended

 vm_id = 500 # You can change if you want
 network_interface = <your-network-interface>
 disk_size = 32 # You can change if you want
 hostname = "couchdb" # You can change if you want

 # File ID format: `datasotre_id:type/<image>`
 template_file_id = "local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst"
 os_type = "debian"
 ssh_keys = local.ssh_keys

 # Example tags
 tags = ["debian", "couchdb", "obsidian"]
}

output "couchdb_ipv4" {
 value = module.couchdb.ipv4
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# varialbes.tf
# `terraform.tfvars` should be ignored by Git.
# or, you can use environment variable: `export TF_VAR_<variable_name>`
variable "proxmox_username" {
 type = string
 default = "root@pam"
}

variable "proxmox_password" {
 type = string
 sensitive = true
}

Applying & Accessing

Now, you can create the LXC Container!

1
2
3
4
5


terraform init

terraform plan

terraform apply -auto-approve

After applying, You can access container now:

1

ssh root@<your-container-ip>

🪏 Settingup CouchDB + LiveSync

Install CouchDB

First, update the package manager and upgrade installed packages.
Then, install the dependencies required to follow the CouchDB installation instructions:

1
2
3


apt update
apt upgrade -y
apt install -y gpg curl sudo

Next, follow the official CouchDB installation guide here.

During installation, a TUI prompt will appear to configure CouchDB.
You can use the following options:

type: standalone
bind address: 127.0.0.1
Erlang magic cookie: <your-random-long-string>
admin password: <your-admin-password>

Store the informations somewhere private and secure.

To verify that CouchDB is running, check its service status:

1

systemctl status couchdb

Install Obsidian LiveSync

Replace the placeholders and run the script below:

1

curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | hostname=http://<YOUR SERVER IP>:5984 username=<INSERT USERNAME HERE> password=<INSERT PASSWORD HERE> bash

You can also refer to the latest instructions here.

If the output looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


-- Configuring CouchDB by REST APIs... -->
{"ok":true}
""
""
""
""
""
""
""
""
""
<-- Configuring CouchDB by REST APIs Done!

then the database has been initialized successfully.

🔒 Setting up Tailscale

Tailscale is a peer-to-peer VPN built on the top of WireGuard, so it lets you securely connect you devices from anywhere.

Install Tailscale on Your devices

The dashboard already provides clear installation instructions for each platform, so you can simply follow them.
You have to install Tailscale in all the devices you want to use Obsidian.

Once Tailscale is installed and connected, you can also verify it from inside your LXC container.
A new network interface should appear:

Set Up MagicDNS

Tailscale also supports internal DNS and HTTPS certificates support issued by Let’s Encrypt. \

In Dashboard -> DNS, enable MagicDNS and HTTPS Certificates.

👮 Setup Caddy

Caddy is a simple web server that can also act as a reverse-proxy.
It integrates especially well with Tailscale, which makes it a great fit fot this setup

You can install Caddy here.

In /etc/caddy/Caddyfile, configure the reverse proxy:

1
2
3
4
5
6
7
8
9


# /etc/caddy/Caddyfile
# Match your tailnet MagicDNS FQDN
https://<hostname>.<your-tailnet>.ts.net {
 reverse_proxy 127.0.0.1:5984 {
 header_up Host {host}
 header_up X-Forwarded-For {remote_host}
 header_up X-Forwarded-Proto {scheme}
 }
}

In /opt/couchdb/etc/local.ini, configure the CORS options.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


[chttpd]
bind_address = 127.0.0.1
port = 5984
enable_cors = true

[cors]
credentials = true
origins = app://obsidian.md, capacitor://localhost, http://localhost
headers = accept, authorization, content-type, origin, referer
methods = GET, PUT, POST, HEAD, DELETE, OPTIONS
max_age = 3600

In /etc/default/tailscaled, make sure the caddy user can access Tailscale in order to manage HTTPS certificates.

1

TS_PERMIT_CERT_UID=caddy

Then, restart the services

1
2
3


systemctl restart tailscaled
systemctl restart caddy
systemctl restart couchdb

🍰 Client usage

Almost done!
The only things left are migrating your existing vault and connecting your client devices.

Generate a Setup URI

The commands below do not need to be run inside the LXC container.
You can run them on your own laptop instead.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


export hostname=<your-hostname>
export database=obsidiannotes # Change this if you want
export passphrase=<random-passphrase>
export username=<username>
export password=<password>

deno run -A https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/flyio/generate_setupuri.ts

# Generated Passphrase & Link:
Your passphrase of Setup-URI is: <passphrase>
This passphrase is never shown again, so please note it in a safe place.
obsidian://setuplivesync?settings=....

Migrate Your Existing Vault

Follow these steps:

Install the Self-hosted LiveSync plugin in Obsidian.
Enable the plugin
For Device Setup Method, select Use a Setup URI.
- Enter your passphrase and URI(obsidian://setuplivesync?settings=...)
Select “I am setting up a new server for the first time / I want to reset my existing server.”
Follow the remaining steps.
Reload the app once without saving.

Register your other devices

I created a new valut in my phone, and followed these steps:

Install the Self-hosted LiveSync plugin in Obsidian.
Enable the Plugin
For Device Setup Method, select a Setup URI. (QR code didn’t work for me)
- Enter with your passphrase and URI(obsidian://setuplivesync?settings=...)
Select “My remote server is already set up. I want to join this device”
Select “This Vault is empty, or contains only new files that are not on the server”
Follow the remaining setup steps.
Reload the app once without saving.

Settings

I am using LiveSync presets, for immediate syncing.
In most case, the sync latency is under one second.

☁️ Off-Site Backup

Because the database can become a single point of failure, you should be prepared for outages or storage failures.
With an off-site backup, you can restore your data more safely.

Git & GitHub

It may feel a little awkward to keep using Git here, but it is still a practical option for a secondary backup because it is lightweight enough for frequent pushes.
You don’t need to install it on every device.
Instead, you can install a Git plugin on your main desktop or laptop and push changes continuously.
Auto-push is also supported by Git plugins.
In this setup, the .git folder is automatically ignored when syncing via LiveSync, so you don’t need to worry about sync conflicts or Git history growth affecting LiveSync.

Cloud Object Storage

Object storage services such as Cloudflare R2 or AWS S3 are highly reliable, and their lifecycle policies are very useful.
Periodically backing up your data to object storage can be a good option.
You can also automate backups using cron and the AWS CLI.

📚 References

Terraform-Based Cost Optimization for NAT Gateway in the Development Environment

Fri, 10 Apr 2026 16:17:01 +0900

💰 Introduction

In our college capstone design project, our budget is too limited to keep paying ongoing AWS cloud costs.
However, our infrastructrue does not need to run 24/7.
Since the NAT Gateway incurs relatively high costs simply by begin provisioned, we decided to remove it during non-working hours.
This allows us to reduce unncessary expenses while keeping the envionment available when the team is actively working.

💡 Strategy

The strategy is to control NAT Gateway provisioning through the natgw_azs variable.
If natgw_azs, which is of type list(string), is empty, Terraform will not create any NAT Gateway or related route table entries.
If those resources already exist, Terraform will remove them during apply.
Based on this behavior, we can build a module that conditionally manages NAT Gateways and routing rules, then integrate it with automation tools to enable costs optimization during non-working hours.

🖥️ Terraform Code

Module

This module creates Regional NAT Gateway when variable natgw_azs has any elements(availability zones).
If natgw_azs is empty, NAT Gateway is desired to be destroyed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166


# main.tf
locals {
 nat_enabled = length(var.natgw_azs) > 0
}

#########
## VPC ##
#########
resource "aws_vpc" "vpc" {
 cidr_block = var.cidr_block
 enable_dns_support = true
 enable_dns_hostnames = true

 tags = {
 Name = "${var.cluster_name}-vpc"
 }
}

#############
## Subnets ##
#############
resource "aws_subnet" "public" {
 for_each = var.public_subnets

 vpc_id = aws_vpc.vpc.id
 cidr_block = each.value.cidr
 availability_zone = var.azs[each.value.az]
 map_public_ip_on_launch = false

 tags = {
 Name = "${var.cluster_name}-public-subnet-${each.key}"
 "kubernetes.io/role/elb" = "1"
 }
}

resource "aws_subnet" "private" {
 for_each = var.private_subnets

 vpc_id = aws_vpc.vpc.id
 cidr_block = each.value.cidr
 availability_zone = var.azs[each.value.az]
 map_public_ip_on_launch = false

 tags = {
 Name = "${var.cluster_name}-private-subnet-${each.key}"
 "kubernetes.io/role/internal-elb" = "1"
 }
}

resource "aws_subnet" "db" {
 for_each = var.db_subnets

 vpc_id = aws_vpc.vpc.id
 cidr_block = each.value.cidr
 availability_zone = var.azs[each.value.az]
 map_public_ip_on_launch = false

 tags = {
 Name = "${var.cluster_name}-db-subnet-${each.key}"
 }
}

#################
## IGW & NATGW ##
#################
resource "aws_internet_gateway" "igw" {
 vpc_id = aws_vpc.vpc.id

 tags = {
 Name = "${var.cluster_name}-igw"
 }
}

# Create EIPs for each azs
resource "aws_eip" "regional_nat" {
 for_each = local.nat_enabled ? toset([
 for az in var.natgw_azs : var.azs[az]
 ]) : []

 domain = "vpc"

 tags = {
 Name = "${var.cluster_name}-regional-nat-${each.key}"
 }
}

# NAT Gateway: created when len(natgw_azs) > 0
resource "aws_nat_gateway" "regional_natgw" {
 count = local.nat_enabled ? 1 : 0

 vpc_id = aws_vpc.vpc.id
 availability_mode = "regional"

 # Associate EIP alloc & NATGW
 dynamic "availability_zone_address" {
 for_each = aws_eip.regional_nat

 content {
 availability_zone = availability_zone_address.key
 allocation_ids = [availability_zone_address.value.id]
 }
 }

 tags = {
 Name = "${var.cluster_name}-regional-natgw"
 }
}

###############################
## Route Table & Association ##
###############################
resource "aws_route_table" "public_rtb" {
 vpc_id = aws_vpc.vpc.id
 route {
 cidr_block = "0.0.0.0/0"
 gateway_id = aws_internet_gateway.igw.id
 }
 tags = {
 Name = "${var.cluster_name}-public-rtb"
 }
}

resource "aws_route_table" "private_rtb" {
 vpc_id = aws_vpc.vpc.id

 # Create route entry for NATGW if presents
 # aws_nat_gateway.regional_nat returns array, because of `count`
 dynamic "route" {
 for_each = local.nat_enabled ? [1] : []

 content {
 cidr_block = "0.0.0.0/0"
 nat_gateway_id = aws_nat_gateway.regional_natgw[0].id
 }
 }

 tags = {
 Name = "${var.cluster_name}-private-rtb"
 }
}

resource "aws_route_table" "db_rtb" {
 vpc_id = aws_vpc.vpc.id

 tags = {
 Name = "${var.cluster_name}-db-rtb"
 }
}

resource "aws_route_table_association" "public_rtb" {
 for_each = aws_subnet.public
 subnet_id = each.value.id
 route_table_id = aws_route_table.public_rtb.id
}

resource "aws_route_table_association" "private_rtb" {
 for_each = aws_subnet.private
 subnet_id = each.value.id
 route_table_id = aws_route_table.private_rtb.id
}

resource "aws_route_table_association" "db_rtb" {
 for_each = aws_subnet.db
 subnet_id = each.value.id
 route_table_id = aws_route_table.db_rtb.id
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


# variables.tf
variable "cluster_name" {
 description = "Kubernetes cluster name for prefix"
 type = string
}

variable "azs" {
 description = "Availability zone aliases"
 type = map(string)
}

variable "cidr_block" {
 description = "CIDR block for vpc."
 type = string
}

variable "public_subnets" {
 description = "Public subnets"
 type = map(object({
 cidr = string
 az = string
 }))
}

variable "private_subnets" {
 description = "Private subnets"
 type = map(object({
 cidr = string
 az = string
 }))
}

variable "db_subnets" {
 description = "DB subnets"
 type = map(object({
 cidr = string
 az = string
 }))
}

variable "natgw_azs" {
 description = "EIP alloc az for NATGW"
 type = list(string)
}

Usage

Here’s the example for using modules.
You can simply toggle NAT Gateway by changing the argument: natgw_azs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


# main.tf

#######
# VPC #
#######
module "vpc" {
 source = "../../../modules/vpc"
 cluster_name = var.cluster_name
 cidr_block = local.vpc_cidr
 azs = {
 a = "ap-northeast-2a"
 c = "ap-northeast-2c"
 }
 public_subnets = {
 a = {
 cidr = "10.1.0.0/24"
 az = "a"
 }
 c = {
 cidr = "10.1.1.0/24"
 az = "c"
 }
 }
 private_subnets = {
 a = {
 cidr = "10.1.100.0/24"
 az = "a"
 }
 c = {
 cidr = "10.1.101.0/24"
 az = "c"
 }
 }
 db_subnets = {
 a = {
 cidr = "10.1.200.0/24"
 az = "a"
 }
 c = {
 cidr = "10.1.201.0/24"
 az = "c"
 }
 }
 # When reducing the number of NAT gateway AZs,
 # it is safer to first set `natgw_azs` to an empty list and apply,
 # then recreate the NAT gateway with the desired AZs.
 natgw_azs = ["a", "c"]
}

📚 References

AWS STS: AssumeRole - How AWS Resources assume IAM Role

Fri, 10 Apr 2026 13:49:23 +0900

🔑 What is AWS Security Token Service (STS)?

AWS Security Token Service (STS) is an AWS service that issues temporary secuirty credentials for IAM users or roles.
These credentials help reduce reliance on long-lived access keys and can be configured to follow the principle of least privilege. \

❓ Why use AWS STS?

With AssumeRole, You can avoid distributing long-lived access keys to users, applications, or AWS services.
Temporary credentials are safer because they expire automatically.
STS supports cross-account access without sharing permanent credentials.
It helps enforce least privilege by allowing you to assume only the permissions needed for a specific task.
Supports federation (SSO, OAuth)

⚙️ How AssumeRole works

A user, application, or AWS service requests to assume an IAM role.
AWS checks the role’s trust policy to determine whether the requester is allowed.
If allowed, STS returns temporary credentials:
- Access key ID
- Secret access key
- Session token
The requester uses those temporary credentials to access AWS resources.
The credentials expire after the session duration.

🚀 Use Cases

Cross-account access
CI/CD Pipelines
AWS workloads: EKS, EC2, .. etc
Temporary elevated access

💻 Terraform Example

This example demonstrates a common STS-based access pattern: an EC2 instance receives temporary role credentials and uses them to access S3 securely without embedded access keys.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142


provider "aws" {
 region = "ap-northeast-2"
}

# --------------------------------------------------
# S3 bucket
# --------------------------------------------------
resource "aws_s3_bucket" "app_bucket" {
 # bucket name must be unique
 bucket = "my-sts-demo-bucket-1234567890"
}

resource "aws_s3_bucket_public_access_block" "app_bucket" {
 bucket = aws_s3_bucket.app_bucket.id

 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}

# --------------------------------------------------
# IAM role for EC2
# EC2 can assume this role
# --------------------------------------------------
data "aws_iam_policy_document" "ec2_assume_role" {
 statement {
 effect = "Allow"

 actions = ["sts:AssumeRole"]

 principals {
 type = "Service"
 identifiers = ["ec2.amazonaws.com"]
 }
 }
}

resource "aws_iam_role" "ec2_s3_role" {
 name = "ec2-s3-access-role"
 # Trust Policy
 assume_role_policy = data.aws_iam_policy_document.ec2_assume_role.json
}

# --------------------------------------------------
# Policy: allow EC2 role to read objects from S3
# --------------------------------------------------
data "aws_iam_policy_document" "s3_read_policy" {
 statement {
 effect = "Allow"

 actions = [
 "s3:ListBucket"
 ]

 resources = [
 aws_s3_bucket.app_bucket.arn
 ]
 }

 statement {
 effect = "Allow"

 actions = [
 "s3:GetObject"
 ]

 resources = [
 "${aws_s3_bucket.app_bucket.arn}/*"
 ]
 }
}

resource "aws_iam_policy" "s3_read_policy" {
 name = "ec2-s3-read-policy"
 policy = data.aws_iam_policy_document.s3_read_policy.json
}

resource "aws_iam_role_policy_attachment" "attach_s3_read" {
 role = aws_iam_role.ec2_s3_role.name
 policy_arn = aws_iam_policy.s3_read_policy.arn
}

# --------------------------------------------------
# Instance profile for EC2
# --------------------------------------------------
resource "aws_iam_instance_profile" "ec2_profile" {
 name = "ec2-s3-instance-profile"
 role = aws_iam_role.ec2_s3_role.name
}

# --------------------------------------------------
# Networking (simple example)
# Replace with your existing VPC/subnet/security group if needed
# --------------------------------------------------
data "aws_vpc" "default" {
 default = true
}

data "aws_subnets" "default" {
 filter {
 name = "vpc-id"
 values = [data.aws_vpc.default.id]
 }
}

resource "aws_security_group" "ec2_sg" {
 name = "ec2-s3-demo-sg"
 description = "Security group for EC2 S3 demo"
 vpc_id = data.aws_vpc.default.id

 ingress {
 description = "SSH"
 from_port = 22
 to_port = 22
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }

 egress {
 from_port = 0
 to_port = 0
 protocol = "-1"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

# --------------------------------------------------
# EC2 instance
# Replace ami with one valid in your region
# --------------------------------------------------
resource "aws_instance" "app" {
 ami = var.ami
 instance_type = "t3.micro"
 subnet_id = data.aws_subnets.default.ids[0]
 vpc_security_group_ids = [aws_security_group.ec2_sg.id]
 iam_instance_profile = aws_iam_instance_profile.ec2_profile.name

 tags = {
 Name = "sts-demo-ec2"
 }
}

👍 Best Practices

Prefer temporary credentials over long-lived access keys
Follow least privilege when defining role permissions
Use clear trust policies and avoid overly broad principals
Set appropriate session durations
Use external IDs when granting third-party cross-account access
Monitor role usage with CloudTrail

📚 References

Hugo Theme Stack - Basic Configuration (2025 Guide)

Sun, 06 Jul 2025 23:13:21 +0900

Now we got Deploy pipeline and multilingual setup, The next thing to do is configuring the basic setups.

⚙️ Configuring params.toml

This is the example for: config/_default/params.toml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# Pages placed under these sections will be shown on homepage and archive page.
mainSections = ["post"]
# Output page's full content in RSS.
rssFullContent = true
favicon = "/favicon.ico"

[footer]
since = 2025
customText = ""

[dateFormat]
published = "Jan 02, 2006"
lastUpdated = "Jan 02, 2006 15:04 MST"

[sidebar]
emoji = "🤯"
subtitle = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."

[sidebar.avatar]
enabled = true
local = true
src = "/img/avatar.png"

[article]
headingAnchor = false
math = true
readingTime = true

[article.license]
enabled = true
default = "Licensed under CC BY-NC-SA 4.0"

If you want to fix more in this file, You can see the official document for it.

favicon

The path of the favicon file.
The favicon is the icon of the webpage in the tab view.
In this example, the path of the file is: /static/favicon.ico.

emoji: The emoji of the sidebar profile.
subtitle: The default subtitle of your blog. If translated subtitle exists, it will be ignored.
avatar: Your Avatar in your profile.
In this example, the avatar image file should be located in /assets/img/avatar.png, since static files in Hugo are served directly at root.
The size of Avatar image is: 150 x 150.

article

math = true allows us to write KaTeX mathematics formula.
You can now write math formulas like this:

Inline: $E=mc^2$
Block:

$$ \int_{a}^{b} x^2 dx $$

since indicates the year of the blog created.

In Custom Menu, you can add external link with icons.
The config below is my example.
I added my LeetCode bio link instead of the twitter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


# Configure main menu and social menu
#[[main]]
#identifier = "home"
#name = "Home"
#url = "/"
#[main.params]
#icon = "home"
#newtab = true

[[social]]
identifier = "github"
name = "GitHub"
url = "https://github.com/fudoge"
weight = 1

[social.params]
icon = "brand-github"

[[social]]
identifier = "leetcode"
name = "LeetCode"
url = "https://leetcode.com/u/fudoge/"
weight = 2

[social.params]
icon = "brand-leetcode"

identifier is the identifier of the custom menu option.
name is the name of the option. If you hover your mouse on the menu, this name will be appeared.
url is the URL that links to the site.
weight is the ordering factor of the menu items.
The less number it has, The earlier the item appears.

social.params

icon indicates the icon.
Icons in Tabler fits well in this theme.
This theme has already used the icons in Tabler.
You can download the icon, and apply them by saving the file like assets/icons/example.svg.

You can see the Page has been fixed!

📚 References

Stack Theme - site config
Stack Theme - menu config
Stack Theme - sidebar config

How to setup multilingual hugo blog and manage them with Stack Theme(2025 Guide)

Tue, 01 Jul 2025 22:01:36 +0900

🧩 Config file setup

Even if you’re not planning to support multiple languages right now, setting up your blog for multilingual support in advance will make future expansions much easier.

This post uses (Hugo-Theme-Stack by Jimmy).

This post sets up Korean as a main language, English as a secondary language.
Edit config/_default/config.toml like :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# Change baseurl before deploy
baseurl = "https://riveroverflow.pages.dev"
title = "Chaewoon's Blog"

# Theme i18n support
# Available values: en, fr, id, ja, ko, pt-br, zh-cn, zh-tw, es, de, nl, it, th, el, uk, ar
defaultContentLanguage = "ko"

# Set hasCJKLanguage to true if DefaultContentLanguage is in [zh-cn ja ko]
# This will make .Summary and .WordCount behave correctly for CJK languages.
hasCJKLanguage = true

[languages]
 [languages.en]
 languageCode = 'en-US'
 languageName = 'English'
 weight = 1
 [languages.en.params.sidebar]
 subtitle = 'Not just filling - overflowing'

 [languages.ko]
 languageCode = 'ko-KR'
 languageName = '한국어'
 weight = 2
 [languages.ko.params.sidebar]
 subtitle = '넘치게 채우기'


[pagination]
pagerSize = 5

defaultContentLanguage = "ko" declares default content language to Korean.
If your default content Language is Chinese, Japanese, or Korean, you have to set: hasCJKLanguage = true.
weight is the index number of the language list.
languageName is the name of the language in the list.
subtitle is the profile message of you.
If you want to change page’s title for each language, you can set for each of them with languages.ko.title.
This is Korean example:

1
2
3
4
5
6
7


 [languages.ko]
 languageCode = 'ko-KR'
 languageName = '한국어'
 weight = 2
 title = 'Chaewoon의 블로그'
 [languages.ko.params.sidebar]
 subtitle = '넘치게 채우기'

📝 How to write multilingual posts and bind them

If you want to write some posts, you have to follow this structure:

1
2
3
4
5


content/
├── post/
│ └── multilingual-test/
│ ├── index.en.md
│ └── index.ko.md

Location of Post file must be content/post/<title>/index.<language-code>.md

Posts that share their slug are binded. You can write your multilingual test post like this: /content/post/multilingual-test/index.en/md:

1
2
3
4
5
6
7


---
title: Multilingual Test
slug: "Multilingual Test"
date: 2025-06-03
---

## This is English Article!

content/post/multilingual-test/index.ko.md would be:

1
2
3
4
5
6
7


---
title: 다국어 테스트
slug: "Multilingual Test"
date: 2025-06-03
---

## 한국어 게시글입니다!

Now, turn test server on.

1

hugo server -D

You can go to the translated post!

🎭 Multilingual Setup for sidebars, pages, etc

In English page, you can see that the sidebar is empty. It is because other content has no translated component.
So, you have to make your translated version of other components(page, content, categories, etc).

Make your translated markdown files in content/. You can make markdown files like this:

Moreover, if you want to change some built-in translations in this theme, you can make i18n/<lang>.toml and override.
You can check the stack theme’s i18n setup here.

📚 References

Stack by Jimmicai - config/i18n
Hugo Documnet - content management/multilingual
Hugo Document - configuration/languages

How to deploy Hugo Blog Using Cloudflare Pages(2025 Guide)

Wed, 25 Jun 2025 22:22:24 +0900

Hugo is a high-performance static site generator written in go. With Hugo, you can create static site and manage them efficiently. You can easily deploy it with GitHub Pages and Cloudflare Pages.

🚀 Install Hugo

Install GoHugo

🎨 Install Theme

I used hugo-theme-stack, If you want another one, you can browse in here

Start with Hugo-theme-stack-starter template.
Fork it to your repository using Use This Template.
While the original author uses GitHub Pages, I preferred Cloudflare Pages for better performance and access control.

Then, clone it to local.

1
2


git clone https://github.com/fudoge/hugo-blog.git
cd hugo-blog

Change branch master to main.
Change our local branch to main, and Change GitHub’s default branch to main.

1
2


git branch -m main
git push -u origin main

Delete master branch.

1

git push origin --delete master

Now, let’s see the first blog page. Execute this command below and open localhost:1313 in your web browser.

1

hugo server -D

You can also view this example site here,

Remove GitHub Pages related files, and push your changes.
Also, add .vscode and some unimportant files in .gitignore.

1
2
3
4
5
6


rm -rf .devcontainer .github .vscode
echo ".vscode" >> .gitignore
echo ".DS_Store" >> .gitignore
git add .
git commit -m "First commit"
git push origin main

☁️ Deploy to Cloudflare Pages

First, we have to change baseURL. If you don’t change baseURL, your deployed blog might have broken links. Fix it in config/_default/config.toml.

In Cloudflare Dashboard, Choose Compute(Workers)/Workers & Pages -> Pages.

Set your blog’s repository, Project name, branch and build setups.
And Follow the Hugo Template.

First build would be fail. Cloudflare Pages may default to older Hugo versions, causing build errors when using newer theme features.

In Settings -> Variables and Secrets, change HUGO_VERSION to your local Hugo version. You can easily see them in hugo version.

Deploy again. Now, You have your own Hugo blog now! Feel free to customize your content, update the theme, and start writing awesome posts!