Janus-go

Description

Janus-go is a AWS CLI external source authentication program for use with Google Cloud GKE workload identity or GCE VM identity. It is designed to allow authenticating AWS IAM role from Google Cloud environments (such as GKE cluster or GCE VM instance) without the need of generating long term AWS credentials.

This project was inspired by Janus, a python implementation of the same authentication flow. This project was written in go for easier installation and usage of the program where a single binary is implementation is better suited (such as inside of existing container running on kubernetes).

Prerequisites

1. The environment in which the program is running has to be able to provide Google Cloud Identity token from Google Cloud metadata server. This can be achieved either by running on GCE VM instance or as a GKE workload with workload identity enabled
2. An AWS IAM role is created with a trust policy specifying the Google Cloud IAM identity used by VM instance or GKE workload identity from step 1.

Installation

Locally

Download appropriate release for your OS and achitecture from the project's release page.

wget -qO janus-go https://github.com/zepellin/janus-go/releases/download/v0.6.6/janus-v0.6.6-linux-amd64 && chmod +x janus-go

Inside of a Kubernetes pod

To use the binary inside of Kubernetes pod, download the binary using init container and mount the binary path inside of your main container:

apiVersion: v1
kind: Pod
metadata:
  name: my-app-pod
spec:
  ...
  initContainers:
   - name: download-tools
     image: alpine:3
     command: [sh, -c]
     args:
       - wget -qO janus-go https://github.com/zepellin/janus-go/releases/download/v0.6.6/janus-v0.6.6-linux-amd64 && chmod +x janus-go && mv janus-go /janus-go/
     volumeMounts:
       - mountPath: /janus-go
         name: janus-go
  containers:
  - name: main-container
    ...
    volumeMounts:
    - mountPath: /usr/local/bin/janus-go
      name: janus-go
      subPath: janus-go

  volumes:
   - name: janus-go
     emptyDir: {}

Alternatively, use the published OCI image as a Kubernetes image volume (requires Kubernetes 1.31+ with the ImageVolume feature gate enabled):

apiVersion: v1
kind: Pod
metadata:
  name: my-app-pod
spec:
  containers:
    - name: main-container
      image: my-app-image:latest
      volumeMounts:
        - mountPath: /usr/local/bin/janus-go
          name: janus-go
          subPath: janus-go
          readOnly: true
  volumes:
    - name: janus-go
      image:
        reference: ghcr.io/zepellin/janus-go-volume:v0.6.6
        pullPolicy: IfNotPresent

The OCI image contains two files at root — /janus-go and /janus (both are the same binary). Use subPath to pick whichever name you prefer:

      volumeMounts:
        - mountPath: /usr/local/bin/janus-go
          name: janus-go
          subPath: janus-go   # or "janus"
          readOnly: true

Image naming and tags

The OCI volume image is built by the publish-volume-image workflow and published to GitHub Container Registry as:

ghcr.io/<owner>/<repo>-volume

For this repository, that resolves to:

ghcr.io/zepellin/janus-go-volume

The image is built for linux/amd64 and linux/arm64.

Tag behavior:

• Release tags: vX.Y.Z (for example v0.6.6)
• Commit tags: sha-<git-sha>
• latest: published from the default branch

Examples:

ghcr.io/zepellin/janus-go-volume:v0.6.6
ghcr.io/zepellin/janus-go-volume:sha-abc1234def56
ghcr.io/zepellin/janus-go-volume:latest

Usage

Assuming pre-requisites for running the application have been met and AWS SDK configuration file in a following format exists:

[profile my-aws-account]
credential_process = /usr/local/bin/janus-go -rolearn arn:aws:iam::123456789012:role/my-trusted-role

AWS clients such as AWS CLI or AWS Terraform provider can now authenticate agains specified AWS profile and use AWS APIs.

aws --profile my-aws-account ec2 describe-instances

Environment variables

Variable	Description
AWS_SESSION_IDENTIFIER	STS role session name to use. Takes precedence over the value generated from GCP metadata (project ID + hostname), but not over the -sessionid flag. Must be 2-64 characters of A-Za-z0-9+=,.@_-.
IDENTITY_TOKEN_AUDIENCE	Audience of the requested Google identity token (defaults to gcp). Must match the audience configured in the AWS IAM role trust policy. Applies to GCE instance and service account tokens; the gcloud authorized user flow always uses the Google Cloud SDK audience.

Contributing

To contribute to Janus-go, follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature_branch ).
3. Make your changes.
4. Commit your changes (git commit -am 'Add some feature' ).
5. Push to the branch (git push origin feature_branch ).
6. Create a new Pull Request.

License

This project uses the following license: MIT.