> For the complete documentation index, see [llms.txt](https://docs.datafy.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datafy.io/set-up-and-installation/advanced-setup/tokenless-installation.md).

# Tokenless Installation

{% hint style="success" %}
Tokenless installation is supported from agent version 1.39.0 (EC2) and Helm chart version 3.6.0 (Kubernetes).
{% endhint %}

By [default](/set-up-and-installation/datafy-installation/installation.md), Datafy identifies your AWS account using a [security token](/set-up-and-installation/datafy-installation/token-generation.md) 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.

{% hint style="warning" %}
A tokenless instance profile or IRSA role only proves identity — it grants no AWS permissions. Datafy still needs a dedicated [IAM role](/set-up-and-installation/datafy-installation/permissions-configuration.md) to read and manage your EC2 instances and EBS volumes, regardless of token mode.
{% endhint %}

<table><thead><tr><th width="94.85589599609375">Where</th><th width="194.6484375">Mode</th><th>What you need</th></tr></thead><tbody><tr><td>EC2</td><td>Tokenless</td><td>An <a href="https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html">IAM instance profile</a> attached to the instance, with IMDS access</td></tr><tr><td>EKS</td><td>IRSA</td><td>A dedicated IAM role for the controller's ServiceAccount, trusted by the cluster's OIDC provider</td></tr><tr><td>EKS</td><td>Node instance profile</td><td>IMDS access with a metadata hop limit of 2 or greater</td></tr></tbody></table>

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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) 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:

{% code overflow="wrap" %}

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

{% endcode %}

The installation will fail if no instance profile is attached, 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](/set-up-and-installation/datafy-installation/installation.md#helm-chart-installation) instead.

### Node Instance Profile

When installing, set the Helm chart variable `controller.serviceAccount.tokenless` to `true`. The [Datafy controller](/how-it-works/autoscaler-on-kubernetes.md#installing-datafy-on-kubernetes) uses the same IMDS-based mechanism as the [EC2 flow above](#ec2-instances), reading the worker node's own instance profile, which is automatically created by EKS.

{% code overflow="wrap" %}

```bash
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
```

{% endcode %}

{% hint style="warning" %}
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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html) for your node groups.
{% endhint %}

### IRSA

[IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) 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.

{% hint style="info" %}
Your cluster needs an IAM OIDC provider associated before you can create the role. If it doesn't have one, [create it first](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html): `eksctl utils associate-iam-oidc-provider --cluster <cluster-name> --approve`.
{% endhint %}

{% stepper %}
{% step %}

#### **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](/set-up-and-installation/datafy-installation/installation.md#helm-chart-installation) use namespace `datafy-agent` and service account `datafy-controller-sa`.

{% tabs fullWidth="false" %}
{% tab title="Terraform module" %}
You can create the role using the [iam-role-for-datafy-controller-eks Terraform module](https://registry.terraform.io/modules/datafy-io/modules/aws/latest/submodules/iam-role-for-datafy-controller-eks).\
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.
{% endtab %}

{% tab title="CloudFormation template" %}
Create a new CloudFormation stack using the URL below as the template source:

{% code title="S3 URL" overflow="wrap" %}

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

{% endcode %}

First, find your cluster's OIDC provider URL. In the AWS console, go to **EKS → Clusters →&#x20;*****your cluster*** and copy the **OpenID Connect provider URL** from the **Overview** tab, or run:

{% code overflow="wrap" %}

```bash
aws eks describe-cluster --name <cluster-name> --query "cluster.identity.oidc.issuer" --output text
```

{% endcode %}

Then fill in the **EKS OIDC Provider URL**, **Kubernetes Namespace**, and **Kubernetes Service Account Name** parameters to match your cluster and Helm install. Once the stack is created, find the role's ARN on its **Outputs** tab.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### **Install or Upgrade the Helm Chart with the Role ARN**

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

{% code overflow="wrap" %}

```bash
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
```

{% endcode %}

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

{% hint style="info" %}
`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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.datafy.io/set-up-and-installation/advanced-setup/tokenless-installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.