IAM on HabibiOps

AWS IAM Roles Anywhere Using Sidecar Kubernetes Containers

Fri, 13 Feb 2026 00:00:00 +0000

Introduction

Accessing AWS resources from outside AWS using only temporary credentials and without creating an IAM user with an access key is a problem that everyone who frequently works with AWS faces at one point. AWS IAM Roles Anywhere helps to solve this issue by enabling applications running on servers on premises to access AWS resources with AWS temporary credentials. It relies on public key infrastructure (PKI) for establishing trust between AWS and the workloads having certificates issued by your own private certificate authority (CA). You create a trust anchor by referencing your own certificate authority (CA) and then configure a role to trust IAM Roles Anywhere by mentioning the trust anchor in the trust policy. In addition, you place a condition in the trust policy to restrict the access to only a specific common name (CN) of a certificate.

I recently had a use case where an application running inside a pod on an external Kubernetes cluster needed to access AWS resources. Something similar to IAM roles for service accounts (IRSA) would have been ideal, but IRSA cannot work on pods running on external Kubernetes clusters. A very straightforward solution to this problem is to use an IAM user with an access key, but this is not ideal and the security department will not be happy having static credentials being used by the application. Let’s see how we to set up IAM Roles Anywhere to be used from the application running inside a Kubernetes pod.

IAM Roles Anywhere Setup inside AWS

We have to do two steps inside AWS to configure IAM Roles Anywhere:

Establish trust: create a trust anchor.
Configure IAM roles properly: properly adjust the trust policy and permissions.

In order to establish trust, we can set up a Certificate Authority (CA) using AWS Certificate Manager Private Certificate Authority or use an existing company CA to create a trust anchor. We had an existing CA, so we will be using it in the following steps.

First step: create a trust anchor, choose external certificate bundle, and paste the PEM-encoded certificate bundle in the field.

The second step is to configure the IAM role properly. You can attach the necessary permissions to the role directly. The trust policy will dictate the conditions under which the role can be assumed. Here is an example trust policy that can be used for our use case:

 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


{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Principal": {
 "Service": "rolesanywhere.amazonaws.com"
 },
 "Action": [
 "sts:AssumeRole",
 "sts:TagSession",
 "sts:SetSourceIdentity"
 ],
 "Condition": {
 "StringEquals": {
 "aws:PrincipalTag/x509Subject/CN": "myAwesomePodApp",
 "aws:PrincipalTag/x509Issuer/O": "My Awesome Org",
 "aws:PrincipalTag/x509SAN/DNS": "myAwesomePodApp.com",
 "aws:PrincipalTag/x509Subject/O": "My Awesome Org",
 "aws:PrincipalTag/x509Subject/ST": "AwesomeState",
 "aws:PrincipalTag/x509Subject/C": "AwesomeCountry",
 "aws:PrincipalTag/x509Issuer/ST": "AwesomeState",
 "aws:PrincipalTag/x509Issuer/C": "AwesomeCountry",
 "aws:PrincipalTag/x509Issuer/CN": "awesome-internal-ca"
 },
 "ArnEquals": {
 "aws:SourceArn": "arn:aws:rolesanywhere:eu-central-1:123456789012:trust-anchor/c3281693-76c9-48ea-8162-8d48d22c203f"
 }
 }
 }
 ]
}

Notice that the Condition part can list all the details of the certificate that the pod is using such as the common name (CN), the organization (O), the DNS name (DNS), etc. You can decide which parts of the certificate are important for your use case but as a minimum include the CN and DNS details.

After setting up the trust anchor and the IAM role properly, the application holding a valid certificate signed by the CA can assume the role to access AWS resources if the certificate matches the conditions in the trust policy. For example, if the certificate has the common name myAwesomePodApp, and the DNS name myAwesomePodApp.com, is signed by the CA awesome-internal-ca, and all the other specified conitions inside the trust policy, the application can assume the role.

IAM Roles Anywhere Setup on Kubernetes Pods

To use IAM Roles Anywhere and get temporary credentials, we need to install the official credential helper tool. The helper tool manages the process of calling the endpoint to get session credentials and automatically refreshing them before they expire by using the certificate and associated private key. The helper tool has three commands that are interesting for us:

1
2
3


credential-process Retrieve AWS credentials in the appropriate format for external credential processes
serve Serve AWS credentials through a local endpoint
update Updates a profile in the AWS credentials file with new AWS credentials

The first command credential-process would retrieve the credentials by providing the certificate and private key. The trust anchor arn along the profile arn can be fetched by clicking on the respective details in the IAM Roles Anywhere console. For example, the below command would retrieve the temporary credentials when run from the terminal:

1
2
3
4
5
6


./aws_signing_helper credential-process \
 --certificate ./myAwesomePodApp.crt \
 --private-key ./myAwesomePodApp.key \
 --trust-anchor-arn arn:aws:rolesanywhere:eu-central-1:123456789012:trust-anchor/c3281693-76c9-48ea-8162-8d48d22c203f \
 --profile-arn arn:aws:rolesanywhere:eu-central-1:123456789012:profile/0b3ced02-1f68-4b63-892d-f9ab0117cbfd \
 --role-arn arn:aws:iam::123456789012:role/myAwesomePodAppIAMRole

The update command would obtain the temporary credentials and write them directly to the AWS credentials file. The serve command is a very interesting option for us because it allows us to run a local endpoint that vends temporary security credentials from IAM Roles Anywhere acting like a local token vending machine endpoint. This endpoint can be used by applications running inside the Kubernetes cluster or other VMs to obtain temporary credentials. Our legacy application can benefit from the serve command by consuming the temporary credentials using that endpoint.

Here is an example of the serve command with identical parameters to the command above:

1
2
3
4
5
6


./aws_signing_helper serve \
 --certificate ./myAwesomePodApp.crt \
 --private-key ./myAwesomePodApp.key \
 --trust-anchor-arn arn:aws:rolesanywhere:eu-central-1:123456789012:trust-anchor/c3281693-76c9-48ea-8162-8d48d22c203f \
 --profile-arn arn:aws:rolesanywhere:eu-central-1:123456789012:profile/0b3ced02-1f68-4b63-892d-f9ab0117cbfd \
 --role-arn arn:aws:iam::123456789012:role/myAwesomePodAppIAMRole

The serve command starts a local server that listens on 127.0.0.1 at the default port 9911. We can then use the local endpoint as follows with the aws cli:

1

export AWS_EC2_METADATA_SERVICE_ENDPOINT=http://127.0.0.1:9911

After that, you can run the aws cli commands as usual. This is an example if the aws cli is not available and the aws sdk cannot be used by the application for some reason:

1
2
3
4


export AWS_EC2_METADATA_SERVICE_ENDPOINT=http://127.0.0.1:9911
export IAM_ROLE=myAwesomePodAppIAMRole
TOKEN=$(curl -X PUT "$AWS_EC2_METADATA_SERVICE_ENDPOINT/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
curl -H "X-aws-ec2-metadata-token: $TOKEN" $AWS_EC2_METADATA_SERVICE_ENDPOINT/latest/meta-data/iam/security-credentials/$IAM_ROLE

Notice that it implements the same URIs and request headers as IMDSv2. The command will also automatically refresh the credentials five minutes before the previous ones expire.

Architecture Diagram

Here is the architecture diagram of the entire solution:

We have two pods running in the external Kubernetes cluster outside AWS:

The application pod.
- It uses the temporary credentials that are fetched by the sidecar container.
The AWS Signing Helper Pod running as a sidecar container.
- It uses the certificate and private key mounted as a secret.
- It uses the parameters needed to call the credential helper tool mounted as a config map.

We discuss the Kubernetes manifest files below.

AWS Signing Helper Pod

The sidecar container for the credential helper tool is a simple container image that uses the official AWS CLI image as the base image:

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


FROM public.ecr.aws/aws-cli/aws-cli:2.11.18

ARG IAMRA_VERSION="1.7.3"
ENV IAMRA_VERSION=$IAMRA_VERSION

WORKDIR /usr/local/bin

RUN curl -O "https://rolesanywhere.amazonaws.com/releases/${IAMRA_VERSION}/X86_64/Linux/aws_signing_helper"

RUN chmod a+x aws_signing_helper

USER 1000

For convenience, we will store the built image in ECR and call it iamra_aws_signing_helper.

Certificate Secret Manifest File

Here is the manifest file that stores the certificate and private key:

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


---
apiVersion: v1
kind: Secret
metadata:
 name: iamra-myapp-cert
 namespace: myapp
type: kubernetes.io/tls
data:
 tls.crt: |
 LS0tLS1...
 tls.key: |
 LS0tLS1...

Config Map Manifest File

Here is the manifest file that stores the parameters needed to call the credential helper tool:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


---
apiVersion: v1
kind: ConfigMap
metadata:
 name: iamra-myapp-conf
 namespace: myapp
data:
 IAMRA_ROLE_ARN: "arn:aws:iam::123456789012:role/myAwesomePodAppIAMRole"
 IAMRA_TRUST_ANCHOR_ARN: "arn:aws:rolesanywhere:eu-central-1:123456789012:trust-anchor/c3281693-76c9-48ea-8162-8d48d22c203f"
 IAMRA_PROFILE_ARN: "arn:aws:rolesanywhere:eu-central-1:123456789012:profile/0b3ced02-1f68-4b63-892d-f9ab0117cbfd"

Application Pod Manifest File

Here is the manifest file that runs the application pod and the sidecar container:

 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


---
apiVersion: v1
kind: Pod
metadata:
 name: iamra-myapp-pod
 namespace: myapp
spec:
 containers:
 - name: myAwesomeApp
 image: 123456789012.dkr.ecr.eu-central-1.amazonaws.com/my_awesome_legacy_app:2.1.34
 command: [ 'sh', '-c' ]
 args:
 - aws sts get-caller-identity;
 aws s3 ls; # access whatever you want here
 ./my_app do_something_with_s3_data; # process the data
 aws s3 cp app_data s3://my-bucket/app_data; # upload to S3
 imagePullPolicy: Always
 env:
 - name: AWS_EC2_METADATA_SERVICE_ENDPOINT
 value: "http://127.0.0.1:9911/"
 - name: AWS_REGION
 value: "eu-central-1"
 - name: iamra-aws-signing-helper
 image: 123456789012.dkr.ecr.eu-central-1.amazonaws.com/iamra_aws_signing_helper:1.7.3
 command: [ "aws_signing_helper" ]
 args:
 - "serve"
 - "--certificate"
 - "/mnt/credentials/tls.crt"
 - "--private-key"
 - "/mnt/credentials/tls.key"
 - "--role-arn"
 - "$(ROLE_ARN)"
 - "--trust-anchor-arn"
 - "$(TA_ARN)"
 - "--profile-arn"
 - "$(PROFILE_ARN)"
 env:
 - name: ROLE_ARN
 valueFrom:
 configMapKeyRef:
 key: IAMRA_ROLE_ARN
 name: iamra-myapp-conf
 - name: TA_ARN
 valueFrom:
 configMapKeyRef:
 key: IAMRA_TRUST_ANCHOR_ARN
 name: iamra-myapp-conf
 - name: PROFILE_ARN
 valueFrom:
 configMapKeyRef:
 key: IAMRA_PROFILE_ARN
 name: iamra-myapp-conf
 volumeMounts:
 - mountPath: /mnt/credentials
 name: credentials
 resources:
 requests:
 memory: "256Mi"
 cpu: "512m"
 limits:
 memory: "512Mi"
 cpu: "1024m"
 imagePullPolicy: Always
 volumes:
 - name: credentials
 secret:
 secretName: iamra-myapp-cert

The iamra-aws-signing-helper container runs the credential helper tool with the parameters from the config map. The application container myAwesomeApp sets the environment variable AWS_EC2_METADATA_SERVICE_ENDPOINT to the local endpoint and uses the aws cli to access S3 resources. The legacy application now can access AWS resources without having to use static credentials. The credential helper tool will automatically refresh the credentials five minutes before expiration time.

Conclusion

In this post, we configured IAM Roles Anywhere and set up the credential helper tool as a sidecar container in a Kubernetes pod to allow a legacy application to access AWS resources without using static credentials from an IAM user. We used the application certificate signed by our own private CA to fetch the temporary credentials from IAM Roles Anywhere. The application could then consume these credentials and access the needed AWS resources.

References:

GitHub Actions AWS Deploy using OIDC

Mon, 19 Jan 2026 00:00:00 +0000

Introduction

1
2
3
4
5
6


- name: Configure AWS credentials
 uses: aws-actions/configure-aws-credentials@v6
 with:
 aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
 aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
 aws-region: ${{ env.AWS_REGION }}

What’s wrong with this step inside the GitHub Actions workflow? Yes, it’s not the best way to authenticate to AWS because AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY were used to configure the credentials. This means having to manage an IAM user with valid access keys. This means that these keys have to be rotated regularly. This means that someone has to copy and paste those static credentials into the secrets and make sure they are not leaked or compromised somewhere else.

What’s the best practice to authenticate to AWS in a pipeline you may ask? The answer is OpenID Connect (OIDC). OpenID Connect allows your workflows to exchange short-lived tokens directly from your cloud provider. Let’s see how to configure this in GitHub Actions and deploy to AWS using this method.

AWS IAM Identity Providers

Before allowing GitHub Actions to authenticate to AWS, we need to configure an OpenID Connect provider in AWS IAM. Inside the AWS IAM console, go to Identity Providers and create a new OpenID Connect provider. Use the following details for the configuration:

Provider URL: token.actions.githubusercontent.com
Audience: sts.amazonaws.com

After setting up the provider, we can create an IAM role forGitHub Actions to assume it.

AWS IAM Role and Trust Relationship Policy

create a new IAM role with the following trust policy that allows the OIDC provider to assume the role with web identity:

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


{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Principal": {
 "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
 },
 "Action": "sts:AssumeRoleWithWebIdentity",
 "Condition": {
 "StringEquals": {
 "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
 },
 "StringLike": {
 "token.actions.githubusercontent.com:sub": [
 "repo:GitHubOrg/GitHubRepo:ref:refs/heads/*",
 "repo:GitHubOrg/GitHubRepo:ref:refs/tags/*"
 ]
 }
 }
 }
 ]
}

Let’s break down the trust relationship policy:

Federated Principal: the OIDC provider ARN
StringEquals Condition: the OIDC token audience (aws sts)
StringLike Condition: the GitHub repository and branch patterns that the role can be assumed from. Here we allow the role to be assumed from any branch or tag in the GitHubRepo repository.

We can use wildcards in the repository and branch patterns to allow multiple repositories and branches to assume the role. We can also define only specific branches or tags to allow only specific branches or tags to assume the role. For example:

Allow only the main branch:

1
2
3


"StringLike": {
 "token.actions.githubusercontent.com:sub": ""repo:GitHubOrg/GitHubRepo1:ref:refs/heads/main"
}

Allow any branch:

1
2
3


"StringLike": {
 "token.actions.githubusercontent.com:sub": ""repo:GitHubOrg/GitHubRepo1:*"
}

Allow only tags from multiple repositories:

1
2
3
4
5
6
7


"StringLike": {
 "token.actions.githubusercontent.com:sub": [
 "repo:GitHubOrg/GitHubRepo1:ref:refs/tags/*",
 "repo:GitHubOrg/GitHubRepo2:ref:refs/tags/*",
 "repo:GitHubOrg/GitHubRepo3:ref:refs/tags/*"
 ]
}

These fine-grained permissions should be used to restrict access to the role accordingly. After creating the role with the trust policy, we can attach the IAM policy that allows the role to do whatever we would like to do inside AWS such as write to S3 buckets, update ECS tasks, etc.

GitHub Actions Workflow

After setting up the IAM role and trust relationship policy, we can configure the GitHub Actions workflow to assume the role and deploy to AWS. Here is an example workflow that deploys a Hugo site to S3:

 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


name: 'Deploy to S3'

on:
 workflow_dispatch:
 branches:
 - main

permissions:
 id-token: write
 contents: read

defaults:
 run:
 shell: bash

env:
 AWS_REGION: "eu-central-1"
 AWS_DEFAULT_REGION: "eu-central-1"
 AWS_ROLE_ARN: "arn:aws:iam::123456789012:role/gha-oidc-rolename"
 AWS_ROLE_SESSION_NAME: "GHA-OIDC-${{ github.run_id }}-${{ github.run_number }}-${{ github.run_attempt }}"
 AWS_S3_BUCKET_NAME: "my-awesome-hugo-website"

jobs:
 deploy:
 runs-on: ubuntu-latest
 steps:

 - name: Checkout
 uses: actions/checkout@v5

 - name: Configure AWS Credentials
 uses: aws-actions/configure-aws-credentials@v5
 with:
 role-to-assume: ${{ env.AWS_ROLE_ARN }}
 role-session-name: ${{ env.AWS_ROLE_SESSION_NAME }}
 aws-region: ${{ env.AWS_REGION }}

 - name: Setup Hugo
 run: sudo apt-get update && sudo apt-get install hugo -y

 - name: Build Hugo site
 run: hugo --gc --minify
 working-directory: ./my-awesome-hugo-theme

 - name: Deploy to S3
 run: aws s3 sync --delete ./public/ s3://${{ env.AWS_S3_BUCKET_NAME }}/public/
 working-directory: ./my-awesome-hugo-theme

Let’s break down the workflow:

The id-token is used in combination with OpenID Connect. Setting the permissions to write is required in order to request an OpenID Connect JWT Token as described in the docs.
The configure-aws-credentials action is used to configure the AWS credentials using the OpenID Connect JWT Token. Notice that we are not using the aws-access-key-id and aws-secret-access-key inputs. We only specified the role ARN and session name.
The Setup Hugo step installs Hugo on the runner.
After building the Hugo site, the Deploy to S3 step deploys the site to S3 by copying over the generated public folder using the AWS CLI: aws s3 sync ....

Here’s a diagram of the OIDC workflow:

Conclusion

In this post, we saw how to configure GitHub Actions to authenticate to AWS using OpenID Connect. An example Hugo site deployment to S3 was used to demonstrate the workflow. I hope this post was helpful and you learned something new. Let’s stop using IAM users with static credentials inside CI/CD pipelines!

References:

Static Site Deployment on S3 using Containerized LocalStack

Sat, 10 Jan 2026 00:00:00 +0000

Introduction

LocalStack is a local cloud development solution that emulates AWS services in a local environment. This enables developers to build and test various AWS-based solutions on a small scale without requiring an AWS account.

In this post, LocalStack is used to test the deployment of a static website to a S3 bucket. Hugo, a popular static site generator, is used to build the site. The following topics are covered in more detail throughout this post:

Creating a containerized environment that includes:
- LocalStack
- Hugo
S3 bucket creation and configuration for static website hosting
Building and deploying the static site to the S3 bucket
Automating the deployment process

The entire source code and setup is available on GitHub.

This post does not cover the inner workings of Hugo or how to set up a Hugo static site. Instead, it focuses solely on the deployment aspect. Hugo themes can be found here.

Setup of the Containerized Environment

LocalStack provides a pre-built Docker image that’s available on Docker Hub, offering a fully functional local AWS cloud stack in a containerized environment. However, the image doesn’t include any Hugo-related dependencies to build a static website. For that, we will create a new image based on the LocalStack image and include the additional dependencies.

The Dockerfile below implements the initial basic setup:

1
2
3
4
5
6
7
8
9


FROM localstack/localstack

RUN apt-get update && apt-get install -y --no-install-recommends \
 hugo \
 ca-certificates \
 git \
 golang

EXPOSE 4566

Details for installing Hugo can be found from the official documentation

We can then build the image once the Dockerfile is set up by using the command:

1

podman build . -t localstack-gohugo

Finally, we can run the container by using the command:

1
2
3
4
5


podman run \
 -it \
 -p 4566:4566 \
 -v ./hugo-blog:/opt/code/localstack/hugo-blog \
 --name localstack-gohugo localstack-gohugo

./hugo-blog can be an empty directory, in which Hugo can be set up within the container, or it can be a directory that already contains a Hugo website.

Accessing the container can be done by opening a new terminal and executing the following command:

1

podman exec -it localstack-gohugo bash

At this point, we have a running localstack-gohugo container that has the following built-in dependencies set up:

LocalStack
Hugo and its dependencies

However, we do not yet have the actual final build of the website or any deployable, site-related output. In the next sections, we will walk through the deployment process within the container to better understand how the manual process works. Afterward, we will demonstrate a better and enhanced automated way to perform the deployment.

S3 Bucket Setup

Two simple steps are needed to set up the S3 bucket:

Create the bucket
Apply a bucket policy to allow public access

Bucket creation in LocalStack is done using the command below:

1

awslocal s3 mb s3://testwebsite

awslocal is used instead of aws for all AWS-related APIs when using LocalStack.

Once the bucket has been created, a policy has to be set and applied to the bucket so that the website can be publicly accessible. Therefore, the following bucket policy will be set:

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


{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Sid": "PublicReadGetObject",
 "Effect": "Allow",
 "Principal": "*",
 "Action": "s3:GetObject",
 "Resource": "arn:aws:s3:::testwebsite/*"
 }
 ]
}

The bucket IAM policy allows anyone ("Principal": "*") to get read-only access ("Action": "s3:GetObject") to the website contents on the S3 bucket ("Resource": "arn:aws:s3:::testwebsite/*").

The official AWS Documentation contains more thorough details regarding the attributes.

Lastly, the policy is applied to the bucket by using the following command:

1

awslocal s3api put-bucket-policy --bucket testwebsite --policy file://bucket_policy.json

Deploying to S3

Several steps are required before we can deploy to our S3 bucket, namely:

Properly set up the hugo.toml configuration file
Build the static site using Hugo: hugo --gc --minify
Deploy the site to the S3-bucket: awslocal s3 sync ./ s3://testwebsite

Configuring hugo.toml

The hugo.toml config file is already properly set when building the image; however, this section explains how to set the configuration file.

The configuration file is human-readable, and we only need to set four parameters to get started. With LocalStack, the S3 website endpoint accepts several formats; the most common is the virtual-hosted style: http://<BUCKET_NAME>.s3-website.localhost.localstack.cloud:4566. Hence, the configuration file looks as follows:

1
2
3
4


baseURL = 'http://testwebsite.s3-website.localhost.localstack.cloud:4566'
languageCode = 'en-us'
title = 'My Hugo Site'
theme = 'mixedpaper'

It’s possible to set a section for deployments; however, it doesn’t seem to be well integrated with LocalStack, so this will be skipped for the time being.

Building the Website

A single command is needed to build the website:

1

hugo

A single command is needed to build the website:

1

hugo

Hugo will process all the Markdown content files and templates, generating a complete, hostable website in the public directory. The source files (Markdown, partials, etc.) will be converted into HTML/CSS/JS, which will be stored in the public directory. For better visualization, the structure of the public folder is presented below:

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


tree -L 1
.
├── 404.html
├── archives
├── categories
├── favicon.png
├── index.html
├── index.xml
├── links
├── p
├── page
├── post
├── scss
├── search
├── sitemap.xml
├── tags
└── ts

For additional details, check Hugo’s official documentation.

Once the website has been built and all the content is generated, the index page has to be set using the command:

1
2


# inside the generated public directory
awslocal s3 website s3://testwebsite/ --index-document index.html

Deploying to S3 Bucket

Deploying to the S3 bucket simply means uploading the public directory to the bucket. This can be achieved using the s3 sync command as follows:

1

awslocal s3 sync ./ s3://testwebsite

The site is now hosted on the S3 bucket testwebsite. To test, simply open the browser and paste the base URL: http://testwebsite.s3-website.localhost.localstack.cloud:4566.

It might not work on Chrome, Firefox, or other Chromium-based browsers. Edit the /etc/hosts file on your machine and add the line 127.0.0.1 testwebsite.s3-website.localhost.localstack.cloud for it to work. For more info, check the resolved GitHub issue.

Further Automation

To reduce the setup, a helper script was implemented and the Dockerfile was adjusted as follows:

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


FROM localstack/localstack

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
 hugo \
 ca-certificates \
 git \
 golang

WORKDIR /opt/code/localstack

COPY . .

RUN chmod +x ./setup.sh \
 && mkdir -p /etc/localstack/init/ready.d \
 && mv ./setup.sh /etc/localstack/init/ready.d/init-aws.sh

EXPOSE 4566

Below is a brief overview of the updated Dockerfile:

Copy the entire working directory into the container so that we can avoid using the -v mount option.
Set the script to executable and move it to /etc/localstack/init/ready.d/init-aws.sh so that it is automatically executed by LocalStack once the container is running.

Check the LocalStack initialization hooks for more info regarding the lifecycle.

With the newly enhanced and improved Dockerfile, the container is ready to use out of the box, without the need to perform any manual tasks.

Setup Script

Below is the implemented script for automating the setup within the container:

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


#!/bin/bash

# Define variables
BASE_DIR="/opt/code/localstack"
SITE_DIR="$BASE_DIR/hugo-mixedpaper"
BUCKET="testwebsite"
POLICY_FILE="bucket_policy.json"

# Set up the bucket
awslocal s3 mb s3://$BUCKET
awslocal s3api put-bucket-policy --bucket $BUCKET --policy file://$POLICY_FILE

# Build the site
cd $SITE_DIR && hugo

# Deploy to S3
cd "$SITE_DIR/public" && awslocal s3 sync . s3://$BUCKET

# Set the index page
awslocal s3 website s3://$BUCKET/ --index-document index.html

The script above handles:

Creation of the bucket.
Applying the bucket_policy.json file.
Building the website using hugo and generating the public folder.
Syncing the public folder to the S3 bucket.
Setting the index-document for the bucket.

Once the image is built and the container is running, we can directly access the website at the following endpoint: http://testwebsite.s3-website.localhost.localstack.cloud:4566

Don’t forget to update the /etc/hosts file to add the line 127.0.0.1 testwebsite.s3-website.localhost.localstack.cloud for it to work.

Conclusion

The setup explored in this post is mainly for local development and emulating a production-like environment. In short, we’ve managed to:

Extend the LocalStack container image to integrate Hugo and other dependencies.
Implement a script to automate the setup inside the container by performing the following tasks:
- S3 bucket creation and configuration
- Building and deploying the site to the created S3 bucket

The complete source code used here can be found here on GitHub.