AWS on HabibiOps

AWS Systems Manager Session Manager Port Forwarding

Thu, 30 Apr 2026 00:00:00 +0000

Introduction

In the previous post, we discussed how to use the AWS VPN client to connect to private subnets in a VPC. We used Entra ID to perform federated user-based authentication. This technique is useful for enterprises using federated authentication, but there is another way to achieve the same result using AWS Systems Manager Session Manager (SSM) and port forwarding.

Architecture

The diagram above shows the main components used for the SSM port forwarding session setup. The diagram shows the following components:

The bastion host EC2 instance that is located in the private subnet and that is used to initiate the port forwarding session with the attached IAM role
The EC2 instance security group that allows inbound traffic only from the VPC CIDR range
The RDS instance in the private subnet that will be used as the target for the port forwarding session
The RDS security group that allows inbound traffic on the DB port (5432) only from the bastion host EC2 instance
The SSM session manager document that will be used to initiate the port forwarding session
The NAT gateway that will be used to route traffic from the private subnet to the internet
The development local machine that will be used to connect to the RDS instance

RDS DB Connection with SSM Port Forwarding

The following parameters are required for the port forwarding session:

AWS Region (e.g. eu-central-1)
EC2 instance id (e.g. i-04e29d6b82ca52fbc)
RDS host (e.g. mytestdb-instance-1.clzjs8sy98st.eu-central-1.rds.amazonaws.com)
RDS port (e.g. 5432)
RDS username (e.g. postgres)
RDS password (e.g. arn:aws:secretsmanager:eu-central-1:123456789012:secret:rds!)
RDS cluster identifier (e.g. cluster-506ac9d4-c6f0-5421-911f-85dec405f14a-A12ncL)
RDS DB name (e.g. mytestdb)

Install the session manager aws cli plugin locally and start a new session. Keep the session running and execute further commands from a new terminal session:

1
2
3
4
5


$ aws ssm start-session --target i-04e29d6b82ca52fbc --document-name AWS-StartPortForwardingSessionToRemoteHost --parameters '{"portNumber":["5432"],"localPortNumber":["1053"],"host":["mytestdb-instance-1.clzjs8sy98st.eu-central-1.rds.amazonaws.com"]}'

Starting session with SessionId: 429fec6e-29cc-422b-892f-9b8a6973c131-a5xit52zpidhlt7bb95rglflzy
Port 1053 opened for sessionId 429fec6e-29cc-422b-892f-9b8a6973c131-a5xit52zpidhlt7bb95rglflzy.
Waiting for connections...

Export the correct AWS region and RDS parameters in a new terminal session to connect from a local client:

1
2
3
4
5
6


export AWS_REGION="eu-central-1"
export RDS_HOST="localhost"
export RDS_PORT="5432"
export RDS_USERNAME="postgres"
export RDS_DB="mytestdb"
export PGPASSWORD="$(aws secretsmanager get-secret-value --secret-id 'arn:aws:secretsmanager:eu-central-1:123456789012:secret:rds!cluster-506ac9d4-c6f0-5421-911f-85dec405f14a-A12ncL' --query SecretString --output text | jq -r '.password')"

The PGPASSWORD environment variable is automatically picked up by psql when connecting to a PostgreSQL server. Connect using psql to localhost and port 5432 that match the forwarded session that was initiated:

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


$ psql -h $RDS_HOST -p $RDS_PORT "dbname=$RDS_DB user=$RDS_USERNAME"
psql-18 (18.3 (Homebrew), server 17.7)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql)
Type "help" for help.

mytestdb=> \dt
 List of tables
Schema | Name | Type | Owner
--------+-------------+-------+----------
public | dummy_table | table | postgres
(1 row)

mytestdb=>

The connection was established, and the describe table command shows the proper output.

Conclusion

This post demonstrates how to use AWS Systems Manager Session Manager to establish a port forwarding session to a remote DB host. This is useful for scenarios where you need to connect to a remote DB instance from a local development machine for debugging or testing purposes. No ssh connection or public internet-facing endpoints are required for this scenario which makes it a practical solution with minimal overhead.

References:

https://aws.amazon.com/blogs/mt/use-port-forwarding-in-aws-systems-manager-session-manager-to-connect-to-remote-hosts/

AWS Client VPN Endpoint Setup

Wed, 18 Mar 2026 00:00:00 +0000

Introduction

Some enterprise customers do not allow SSH access to their AWS EC2 instances for security reasons. However, they still need to access their EC2 instances from their corporate network or other remote locations for debugging purposes. Setting up a bastion host inside a public subnet is unfortunately not an option in this case.

One approach is using AWS Systems Manager (SSM) Session Manager to establish a secure connection between the EC2 instance and the developer’s client. Another approach is using AWS Client VPN to establish a VPN tunnel between the private subnets where the instance is running and any developer machine. One advantage of using AWS Client VPN is that it allows you to control access to the instance based on the identity of the developer using Entra ID for authentication, for example - including MFA. Another advantage is the target network association on the subnet level with and the authorization rules that would drop any traffic that does not match those predefined firewall rules.

In this post, we will see how to set up an AWS Client VPN endpoint using Terraform and how to manage access using Entra ID. We will also demonstrate how to use an internal bastion host that is located inside the private subnets without having a public IP address as a secure gateway to access other internal EC2 instances.

Prerequisites

We will be using Entra ID for authentication and user management. The first step would be to create a new enterprise application inside the Azure Portal Microsoft Entra admin center.

IAM SAML Identity Provider

The details are described in an official Microsoft Entra ID article here. Here is a high-level summary of the necessary steps:

New enterprise application (AWS ClientVPN)
Setup Single Sing-On (SSO) with SAML
- Identifier (Entity ID): urn:amazon:webservices:clientvpn
- Reply URL (Assertion Consumer Service URL): http://127.0.0.1:35001
- Attributes & Claims:
  - FirstName: user.givenname
  - LastName: user.surname
  - memberOf: user.groups (important for using authorization rules using groups and their ids)
  - Unique User Identifier: user.userprincipalname
- SAML Signing Certificate / Signing Options: Sign SAML response and assertion (otherwise authentication will be rejected by AWS)

AWS mentions how to set up federated authentication here including the details needed for the user attributes and claims. After creating the enterprise application, you will need to download Federation Metadata XML file and then create a new identity provider in the AWS IAM section of the AWS console. The downloaded metadata XML file should be uploaded to the newly created identity provider.

AWS only allows one SAML identity provider per Client VPN endpoint, and Entra ID only allows one enterprise application with the same Unique User Identifier per Azure tenant. This means you cannot create multiple SAML identity providers in the same Azure tenant if you have multiple AWS Client VPN endpoints. If multiple AWS Client VPN endpoints are planned, then you will need to create multiple Entra ID groups in the same enterprise application and use the group IDs in the authorization rules to have separate access to the different private subnets. More on this topic in the Authorization Rules section.

Server Certificate

The “Authentication Info” section requires a “Server certificate ARN” when creating the client VPN endpoint. The certificate could be a self-signed certificate for our use case since we will not be using certificate-based authentication but federated user-based authentication. Make sure the following required X509v3 extensions are present in the server certificate:

X509v3 Extended Key Usage: TLS Web Server Authentication
X509v3 Key Usage: Digital Signature, Key Encipherment

Here is an example of certificate generation using easy-rsa:

1
2
3
4
5
6
7
8
9


git clone https://github.com/OpenVPN/easy-rsa.git
cd easy-rsa/easyrsa3/
./easyrsa init-pki
# create a new CA
./easyrsa build-ca nopass
# create a new server certificate
./easyrsa build-server-full ec2vpn.myawesomecompany.internal nopass
# will not be needed for this case but is mentioned here for completeness 
./easyrsa build-client-full ec2vpnclient1.myawesomecompany.internal nopass

This can now be added inside AWS Certificate Manager (ACM), and the ARN can be used as the Server certificate ARN.

Client VPN Endpoint Setup

Create a client VPN endpoint with the following main settings:

Association type: VPC and then choose the VPC ID.
client IPv4 CIDR block (The address range cannot overlap with the target network address range, the VPC address range, or any of the routes that will be associated with the client VPN endpoint): For example, use 172.20.0.0/22 if your VPC CIDR block is 10.0.0.0/16.
Authentication / Server certificate ARN: previously created server certificate ARN.
Authentication / Use user-based authentication / Federated authentication / SAML provider ARN: previously created inside the IAM identity provider.
Connection protocol / Tunnel mode: Full-tunnel if all client traffic should be routed through the VPN tunnel or use Split-tunnel if only traffic matching client VPN endpoint routes should be routed through the VPN tunnel.

Target Network Associations

After creating the client VPN endpoint, you will need to associate it with one or more subnets that should be accessible from the client VPN endpoint. There is one limitation here, however: only one subnet association per availability zone is allowed per client VPN endpoint.

If you have multiple private subnets in the same availability zone, or separate private and database subnets in the same availability zone, for example, then you need to use a private subnet as a central bastion host to reach the other subnets or to connect to the database.

Authorization Rules

Authorization rules act as firewall rules to grant specific clients access to the specified network. You should have an authorization rule for each network you want to grant access to. Since we have set up Entra ID for authentication and added the SAML identity provider, we can use the Entra ID group IDs as the access group IDs in the authorization rules.

Let’s add an authorization rule to access the private subnet that hosts our EC2 instance:

Destination network to enable access: 10.0.2.0/24
Grant access to: Allow access to users in a specific access group
- Access group ID: 07fc77bc-fa54-4b61-931e-2be27857671b

Only users in the specified access group will be able to access the private subnet. All other traffic coming from other users connected to the client VPN endpoint will be dropped. This way, we can control access to the private subnets based on the identity of the user inside Entra ID.

Route Table

Depending on whether you are using full-tunnel or split-tunnel, you will need to add an extra route to enable internet access on your local machine while connected to the client VPN endpoint. If you are using split-tunnel, then you can skip this step. If you are using full-tunnel, then you need to add an extra route where the destination is 0.0.0.0/0.

Create route:

Route destination: 0.0.0.0/0
Subnet ID for target network association: select any associated subnet that has outgoing internet connectivity using a NAT gateway

Architecture Diagram

We have explained all the steps above in detail. Here is a high-level architecture diagram of the proposed solution:

VPN users are managed using Entra ID: users in the allowed access group will be able to access the private subnets.
there is one bastion host inside the private subnets that can be reached when connected using the AWS Client VPN.
the private subnets have outgoing internet connectivity using a NAT gateway.
the bastion host can reach other internal EC2 instances such as the backend VM or the DB using the private IP address as long as the security group allows it.
EC2 instances in the public subnet such as the load balancer VM do not need to be accessible from the internet via ssh.
No ssh port is open to the public internet, and all traffic is routed through the VPN tunnel and then internally via the bastion host (jumphost).

Automation with Terraform

The GitHub repository for this blog post is available here. We will go over the main resources that were used in the module. The aws_ec2_client_vpn_endpoint resource is the main resource that we will use to create the client VPN endpoint. The network associations, authorization rules, and routes are created using the following resources:

aws_ec2_client_vpn_network_association
aws_ec2_client_vpn_authorization_rule
aws_ec2_client_vpn_route

The examples folder contains an example of a new vpc with a new client VPN endpoint. The VPC contains three private subnets that are associated with the client VPN endpoint. The user has to provide a public ssh key, the server certificate ARN, and the SAML identity provider ARN. The Entra ID group ID is also used inside the authorization rules section.

Conclusion

In this post, we have seen how to set up an AWS Client VPN endpoint and how to manage access using Entra ID. Federated user-based authentication is an important requirement in most enterprises for compliance reasons. The solution to use an internal bastion host that is located inside the private subnets without having a public IP address that can be reached from the client VPN endpoint was discussed. From that point on, using the bastion host as a secure gateway to access other internal EC2 instances meets the requirements of most organizations.

References:

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:

Bitbucket OIDC Integration with AWS ECR

Thu, 05 Feb 2026 00:00:00 +0000

Introduction

We previously talked about OIDC integration with AWS using GitHub Actions. We will now see how to do a similar integration with BitBucket Pipelines. Namely, we want to push a container image to AWS ECR and then use that image in future pipelines.

AWS IAM Identity Providers

We have to configure the Bitbucket OpenID Connect provider in AWS IAM. Use the following to create a new OpenID Connect provider:

Provider URL: api.bitbucket.org/2.0/workspaces/<YOUR-WORKSPACE-NAME>/pipelines-config/identity/oidc
Audience: ari:cloud:bitbucket::workspace/<YOUR-WORKSPACE-ID>

Now that the provider is configured, we can set up the IAM role for the Bitbucket OIDC provider and use it in our pipelines.

AWS OIDC IAM Role

The IAM role requires ECR push permissions and the GetAuthorizationToken action in order to be able to log into ECR.

Example permissions:

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


{
 "Statement": [
 {
 "Action": "ecr:*",
 "Effect": "Allow",
 "Resource": "arn:aws:ecr:eu-central-1:123456789012:repository/devops-terraform",
 "Sid": "AllowAllEcrActions"
 },
 {
 "Action": "ecr:GetAuthorizationToken",
 "Effect": "Allow",
 "Resource": "*",
 "Sid": "EcrGetAuthorizationToken"
 }
 ],
 "Version": "2012-10-17"
}

In the trust relationships section, we need to add the arn of the previously created Bitbucket OIDC provider and allw the AssumeRoleWithWebIdentity action for our specific Bitbucket repository. We can also add the IP addresses of the Bitbucket servers that will be using the OIDC provider in case you are using dedicated self-hosted Bitbucket runners.

Example trust relationships:

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


{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Sid": "",
 "Effect": "Allow",
 "Principal": {
 "Federated": "arn:aws:iam::123456789012:oidc-provider/api.bitbucket.org/2.0/workspaces/stulz_bitbucket/pipelines-config/identity/oidc"
 },
 "Action": "sts:AssumeRoleWithWebIdentity",
 "Condition": {
 "StringLike": {
 "api.bitbucket.org/2.0/workspaces/stulz_bitbucket/pipelines-config/identity/oidc:sub": "{YOUR-BITBUCKET-REPO-ID}*"
 },
 "IpAddress": {
 "aws:SourceIp": [
 "64.x.y.z/32",
 "32.x.y.z/32"
 ]
 }
 }
 }
 ]
}

ECR Push Pipeline

After setting up the IAM role, we can use it in our pipelines as follows:

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


pipelines:
 custom:
 dockerEcrBuildPush:
 - variables:
 - name: IMAGE_NAME
 default: cicd-tf
 - name: IMAGE_TAG
 default: 1.12.0-6.5.0
 - name: AWS_DEFAULT_REGION
 default: eu-central-1
 - step:
 name: Build & Push Docker Image
 oidc: true
 runs-on:
 - 'self.hosted'
 - 'linux'
 script:
 - docker build -t $IMAGE_NAME:$IMAGE_TAG -t $IMAGE_NAME:latest .
 - pipe: atlassian/aws-ecr-push-image:2.6.0
 variables:
 AWS_DEFAULT_REGION: '$AWS_DEFAULT_REGION'
 AWS_OIDC_ROLE_ARN: 'arn:aws:iam::123456789012:role/devops-terraform-oidc'
 IMAGE_NAME: '$IMAGE_NAME'
 TAGS: '$IMAGE_TAG latest'

The above pipeline will build the docker image and push it to ECR using the IAM role we created and using the official Bitbucket Pipelines Pipe: AWS ECR push image atlassian/aws-ecr-push-image.

If we want to use this image as a base image in our future pipelines, we can reference it in the image name section and specify the OIDC IAM role that can be used to pull it from ECR.

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


 steps:
 - step:
 name: TF Plan
 image:
 name: '123456789012.dkr.ecr.eu-central-1.amazonaws.com/devops-terraform:1.12.0-6.5.0'
 aws:
 oidc-role: 'arn:aws:iam::123456789012:role/devops-terraform-oidc'
 oidc: true
 script:
 - terraform init
 - terraform validate
 - terraform plan -out=plan.tfplan
 runs-on:
 - 'self.hosted'
 - 'linux'

This way, the terraform plan step will run inside the designated container image with a pre-installed terraform binary pinned to a specific version (1.12.0-6.5.0).

Conclusion

In this post, we have seen how to use Bitbucket OIDC integration with AWS ECR. We have also seen how to use the official Bitbucket Pipelines Pipe: AWS ECR push image to build and push a docker image to ECR. Hopefully, this will help you in your future projects.

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:

Terraform Container Image for CI/CD Pipelines

Sun, 11 Jan 2026 00:00:00 +0000

Introduction

Terraform is a great tool for managing infrastructure and can be integrated with CI/CD pipelines for automated deployments. In order to achieve idempotency and avoid unexpected changes from version updates, terraform should be run in a container image and be pinned to a specific version.

In addition to having a pinned terraform version inside the container image, it can be a wise choice to also include a pinned version of the main provider being used for your infrastructure. For example, if you are using AWS, you can pin the terraform aws provider to your specific version.

Terraform and Provider Version Pinning

Your terraform configuration file should include the terraform and provider versions you want to use. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


terraform {
 required_version = "1.12.0"

 required_providers {
 aws = {
 source = "hashicorp/aws"
 version = "6.5.0"
 }
 }
}

I place the above in a separate file called versions.tf and include it in any directory used by terraform.

Terraform Container Image

The main characteristics of a good terraform container image are:

small size: use Alpine Linux as a base image
pinned terraform version
pinned provider versions
arguments to specify the terraform and provider versions
environment variables reflecting the used versions

This link provides an example on how to install terraform on Alpine Linux. Here is an example Dockerfile for our terraform container image:

 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


FROM alpine:3.22.0

ARG TERRAFORM_VERSION="1.12.0"
ARG TERRAFORM_AWS_PROVIDER_VERSION="6.5.0"

ENV TF_IN_AUTOMATION=true
ENV TF_INPUT=false
ENV TERRAFORM_VERSION="${TERRAFORM_VERSION}"
ENV TERRAFORM_AWS_PROVIDER_VERSION="${TERRAFORM_AWS_PROVIDER_VERSION}"

RUN apk add --update --no-cache \
 aws-cli \
 curl \
 git \
 unzip

# terraform
RUN curl -o tf.zip "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip" \
 && unzip tf.zip -d /usr/local/bin/ \
 && rm tf.zip

# terraform hashicorp/aws provider
RUN mkdir -p "/root/.terraform.d/plugins/registry.terraform.io/hashicorp/aws/${TERRAFORM_AWS_PROVIDER_VERSION}/linux_amd64" \
 && curl -o tf_aws.zip "https://releases.hashicorp.com/terraform-provider-aws/${TERRAFORM_AWS_PROVIDER_VERSION}/terraform-provider-aws_${TERRAFORM_AWS_PROVIDER_VERSION}_linux_amd64.zip" \
 && unzip tf_aws.zip -d "/root/.terraform.d/plugins/registry.terraform.io/hashicorp/aws/${TERRAFORM_AWS_PROVIDER_VERSION}/linux_amd64/" \
 && rm tf_aws.zip

Some advantages of having a pinned terraform and provider versions are:

The pipeline runs will be guaranteed to run in a reproducible manner
terraform init will not download the latest provider version and will fail in case someone tries to use a different version in the pipeline
The pipeline runs will be faster since the provider will not need to be downloaded every time on terraform init

Image Tagging

There are different ways to tag a container image. Some prefer to use the git commit hash as the tag, while others prefer to use semantic versioning. In this case, I prefer to use the explicit terraform and provider versions as the tag.

The image is therefore tagged accordingly: $IMAGE:$TERRAFORM_VERSION-$TERRAFORM_AWS_PROVIDER_VERSION. For example, an image with terraform version 1.12.0 installed and aws provider version 6.5.0 would have the tag 1.12.0-6.5.0.

Conclusion

This post summarized the best practices for creating terraform container images to be used in CI/CD pipelines.

A sequel post will cover how to configure pipeline builds and deployments using the above container image.