Tokenless Installation

Tokenless installation is supported from agent version 1.39.0 (EC2) and Helm chart version 3.6.0 (Kubernetes).

By default, Datafy identifies your AWS account using a security token passed in as $TOKEN . Tokenless installation is an advanced alternative when using a static token isn't compatible with your environment: the instance or cluster proves its AWS identity with its own IAM role instead, and Datafy exchanges that proof for a short-lived runtime token behind the scenes. Nothing long-lived is stored on the instance or in the cluster.

A tokenless instance profile or IRSA role only proves identity — it grants no AWS permissions. Datafy still needs a dedicated IAM role to read and manage your EC2 instances and EBS volumes, regardless of token mode.

Where	Mode	What you need
EC2	Tokenless	An IAM instance profile attached to the instance, with IMDS access
EKS	IRSA	A dedicated IAM role for the controller's ServiceAccount, trusted by the cluster's OIDC provider
EKS	Node instance profile	IMDS access with a metadata hop limit of 2 or greater

A given instance or cluster can only use one mode at a time — you can't combine tokenless, IRSA, and a static token.

EC2 Instances

Before you install Datafy:

1. Attach an IAM instance profile to the instance. The role is only used to prove the instance's identity, not to grant permissions, any role will work.

2. Make sure the instance can reach the instance metadata service (IMDS) at 169.254.169.254. Either IMDSv1 or IMDSv2 works.

Then install Datafy without the TOKEN parameter:

curl -sSfL https://agent.datafy.io/install?version=$VERSION | AGENT_MODE="autoscaler" sh

The installation will fail if the no attached instance profile is found, or if IMDS is unreachable.

Kubernetes Clusters

Tokenless is only available on EKS. On EKS, the Datafy controller can authenticate either using the underlying node's instance profile, or using its own IRSA role. On other Kubernetes distributions, use a token instead.

Node Instance Profile

When installing, set the Helm chart variable controller.serviceAccount.tokenless to true. The Datafy controller uses the same IMDS-based mechanism as the EC2 flow above, reading the worker node's own instance profile, which is automatically created ny EKS.

helm upgrade --install datafy-agent \
--version "$HELM_VERSION" datafyio/datafy-agent \
--namespace datafy-agent --create-namespace \
--set agent.mode="autoscaler" \
--set controller.serviceAccount.tokenless=true \
--atomic

This mode requires pods to be able to reach the node's IMDS endpoint, which on EKS means the instance metadata hop limit must be 2 or greater. See AWS's guidance on configuring the metadata hop limit for your node groups.

IRSA

IAM Roles for Service Accounts (IRSA) lets a Kubernetes ServiceAccount assume an AWS IAM role directly, without going through the node's instance profile. The role has no permission policy — only a trust relationship, since it proves identity rather than granting AWS permissions. Create one dedicated role per EKS cluster.

Your cluster needs an IAM OIDC provider associated before you can create the role. If it doesn't have one, create it first: eksctl utils associate-iam-oidc-provider --cluster <cluster-name> --approve.

1

Create the IAM Role

Create a role trusted by your cluster's OIDC provider, restricted to the Datafy controller's ServiceAccount. The namespace and service account name here must match what you use in the Helm install below — the standard Helm chart examples use namespace datafy-agent and service account datafy-controller-sa.

Terraform module

You can create the role using the iam-role-for-datafy-controller-eks Terraform module. Examples and usage instructions can be found in the module documentation. Set cluster_name, datafy_controller_namespace, and datafy_controller_service_account_name to match your cluster and Helm install, then use the module's iam_role_arn output in the next step — the module looks up your cluster's OIDC provider automatically, no need to find the URL yourself.

CloudFormation template

Create a new CloudFormation stack using the URL below as the template source:

S3 URL

https://datafy-public-bucket.s3.amazonaws.com/cloudformation-template/iam-role-for-datafy-controller-eks/cloudformation.yaml

Fill in the EKS OIDC Provider URL (the value you just found), Kubernetes Namespace, and Kubernetes Service Account Name parameters to match your cluster and Helm install, then find the role's ARN on the stack's Outputs tab once it's created. The EKS OIDC Provider URL can be found in the AWS console (EKS → Clusters → your cluster, and on the Overview tab copy the OpenID Connect provider URL) or by running aws eks describe-cluster --name <cluster-name> --query "cluster.identity.oidc.issuer" --output text).

2

Install or Upgrade the Helm Chart with the Role ARN

Set the ARN from the previous step on controller.serviceAccount.roleArn:

helm upgrade --install datafy-agent \
--version "$HELM_VERSION" datafyio/datafy-agent \
--namespace datafy-agent --create-namespace \
--set agent.mode="autoscaler" \
--set controller.serviceAccount.roleArn="arn:aws:iam::<account-id>:role/<role-name>" \
--atomic

The chart adds the eks.amazonaws.com/role-arn annotation to the ServiceAccount and creates an empty datafy-token Secret that the controller populates.

controller.serviceAccount.tokenless and controller.serviceAccount.roleArn can't be combined with each other or with agent.token / agent.externalTokenSecret. Set exactly one token source, or enable tokenless mode with none set.