Deploy Natoma On-Prem (Amazon EKS)

Deploy the Natoma on-premises agent on Amazon EKS using a Helm chart pulled from Natoma's ECR repository.

This guide covers deploying the Natoma agent on-premises on Amazon EKS. The on-prem agent connects to the Natoma cloud control plane for orchestration while routing all MCP traffic within your own infrastructure.

---

Prerequisites

• A running Amazon EKS cluster with kubectl and Helm installed

• Access to the Natoma tenant admin panel with Admin permissions

• Your AWS account ID — share this with the Natoma team so they can grant read permissions to the ECR repositories containing the agent image and Helm chart

---

Network Requirements

You may need to allowlist both inbound and outbound traffic depending on your network configuration.

Type	IP Address	Notes
Natoma egress	35.247.116.223	May not be utilized for on-prem since traffic will always be unidirectional from agent to Natoma.
Natoma ingress	34.49.218.52	Agents will make calls to the Natoma API and auth server.

---

Agent Image & Helm Chart

Natoma agent images are hosted on AWS ECR in the Natoma AWS org. Share your AWS account ID with the Natoma team — they will grant your account read permissions for the ECR repositories containing the agent image and Helm chart.

The recommended setup uses a dedicated Kubernetes namespace (natoma), a ServiceAccount (natoma-ecr-pull-sa), and an IAM role (NatomaECRPullRole) with ECR pull permissions.

---

Setup

Step 1: Retrieve On-Prem Credentials

1. Navigate to your Natoma web tenant at https://<tenant>.natoma.app.

2. Log in as an admin and navigate to Admin > On-Premise Deployments.

3. Create a new deployment, provide an optional name, and proceed.

4. Copy the Client ID and Client Secret — you will need both when configuring the Helm chart.

Store the Client ID and Client Secret securely. You will reference these values in your Helm configuration.

Step 2: Create an On-Prem MCP Server

1. In the Natoma web app, navigate to Apps.

2. Click Add custom app and set App Source Type to Remote URL.

3. Fill out the relevant fields and check This is an on-prem server.

4. Enter the remote URL pointing to your on-prem MCP server, including the /mcp suffix (or equivalent path pointing directly to the MCP server).

Once the agent is successfully running, the MCP server will be populated with the list of available tool calls.

Step 3: Configure IAM Permissions

The Natoma pod needs permissions to pull images from the Natoma ECR repository. Create the following IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ECRLoginForSpecificRegistryAndRegion",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Sid": "PullFromNatomaRepoOnly",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:ListImages"
      ],
      "Resource": [
        "arn:aws:ecr:us-east-1:533267197037:repository/natoma/natoma-ai",
        "arn:aws:ecr:us-east-1:533267197037:repository/natoma-helm"
      ]
    }
  ]
}

Attach this policy to an IAM role with the following trust policy. Replace <OIDC_PROVIDER_HOST> with the OIDC provider of your EKS cluster (format: oidc.eks.<region>.amazonaws.com/id/<cluster-id>), <ACCOUNT_ID> with your AWS account ID, <NAMESPACE> with the Kubernetes namespace, and <SA_NAME> with the ServiceAccount name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/<OIDC_PROVIDER_HOST>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "<OIDC_PROVIDER_HOST>:aud": "sts.amazonaws.com",
          "<OIDC_PROVIDER_HOST>:sub": "system:serviceaccount:<NAMESPACE>:<SA_NAME>"
        }
      }
    }
  ]
}

Step 4: Create a Namespace and ServiceAccount

Create a sa.yaml file for the ServiceAccount:

# sa.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: <SA_NAME>
  namespace: <NAMESPACE>
  annotations:
    eks.amazonaws.com/role-arn: <ROLE_ARN>

Apply it to your cluster:

kubectl create namespace <NAMESPACE>       # create the namespace
kubectl apply -f sa.yaml                   # apply the ServiceAccount
kubectl get serviceaccounts -n <NAMESPACE> # verify the SA was created

Step 5: Deploy the Helm Chart

Authenticate against ECR and deploy:

# Authenticate Helm against ECR
aws ecr --profile <profile> get-login-password --region <AWS_REGION> \
  | helm registry login -u AWS --password-stdin \
    <ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com

# Deploy or upgrade the agent
helm upgrade --install natoma-agent \
  oci://533267197037.dkr.ecr.us-east-1.amazonaws.com/natoma-helm \
  --version <version> \
  --namespace <NAMESPACE> \
  -f <values.yaml override path>

Step 6: Verify Tool Scanning

Once the agent is running, Natoma automatically detects it and initiates tool scanning. Each time the agent polls the Natoma cloud server, any pending scan requests are processed alongside the polling data.

To trigger a manual re-scan at any time, click the more menu icon next to the MCP server in the Natoma web app and select Scan tools.

---

Helm Configuration

Required Values

The following properties must be provided at install time.

natoma.clientID

The Client ID generated within the Natoma web application for this clustered deployment.

natoma.clientSecret.*

Contains secretName and secretKey properties pointing to the Kubernetes secret that holds the Natoma client secret. The defaults expect a secret named natoma with a client-secret key.

Create the secret with:

kubectl create secret generic natoma \
  --from-literal=client-secret=<your-client-secret-here>

ingress.host

The hostname through which MCP traffic will be routed. Must be routable and resolvable by all end-users connecting to MCP servers through the Natoma agent.

image.repository

Full image name including the repository path. Contact the Natoma team for the ECR repository path.

image.tag

A specific version tag for the agent image.

serviceAccount.name

The name of the ServiceAccount that has permissions to pull from the Natoma ECR.

---

Enabling Audit Logs

To capture audit logs, enable audit logging via the env block in your values.yaml. Once enabled, agents capture logs in-memory and send them to Natoma every 15 minutes, or when the batch reaches 10,000 entries (both values are configurable).

env:
  - name: AUDIT_LOG_ENABLED
    value: "true"
  # Optional overrides:
  - name: AUDIT_LOG_INTERVAL_SEC
    value: "60"   # flush every 1 minute
  - name: AUDIT_LOG_MAX_ENTRIES
    value: "1000" # flush after 1000 entries

---

Optional Values

For help with any of these values, contact the Natoma team or email [email protected].

replicaCount

Number of agent replicas. Ignored when autoscaling.enabled: true.

Default: 2

autoscaling.enabled

Set to true to enable horizontal pod autoscaling.

Default: false

autoscaling.minReplicas

Minimum replicas during low activity.

Default: 1

autoscaling.maxReplicas

Maximum replicas when scaling.

Default: 8

autoscaling.targetCPUUtilizationPercentage

CPU utilization percentage to target for horizontal scaling.

Default: 80

natoma.logLevel

Supported values: debug, info, warn, error. Leave at info in production unless advised otherwise by Natoma support.

Default: info

natoma.extraCACerts.*

Enables the agent to validate certificates from MCP servers that use an internal root CA. Configure the root certificates in a Kubernetes ConfigMap containing a single PEM-formatted file.

kubectl create configmap extra-certs --from-file=/path/to/internal-ca.pem

Set natoma.extraCACerts.configMap to extra-certs and natoma.extraCACerts.key to internal-ca.pem.

ingress.enabled

Set to false to disable the default Ingress resource. May be necessary for complex networking environments or certain managed Kubernetes providers.

Default: true

ingress.tls.secretName

Name of a Kubernetes Secret containing a crt key (full certificate chain) and a key key (private key).

kubectl create secret generic example-tls \
  --from-file=crt=/path/to/fullchain.crt \
  --from-file=key=/path/to/privkey.key

ingress.tls.hosts

String array of hostnames matching the certificate's CN and DNS Alternative Names. Use {} notation via the Helm CLI:

--set ingress.tls.hosts={example-natoma.local}

ingress.annotations.*

Optional annotations on the Ingress resource. Escape . characters when passing via the Helm CLI:

--set ingress.annotations."kubernetes\.io/ingress\.class"=nginx

env

Any configurable overrides to agent behavior. Values must be strings.

Variable	Description	Default
AUDIT_LOG_ENABLED	Set to "true" to enable audit log capture and upload	false
AUDIT_LOG_INTERVAL_SEC	Frequency in seconds at which audit logs are sent to Natoma	900 (15 min)
AUDIT_LOG_MAX_ENTRIES	Maximum entries per audit log batch	10000
POLLER_INTERVAL_SEC	Polling interval in seconds. Controls how often the agent fetches updated policy data, pending scans, etc. Changes made in the Natoma web app won't reflect in on-prem agents until the next poll.	300 (5 min)

---

Sample values.yaml

natoma:
  clientId: "your-client-id-here"
  clientSecret:
    secretName: natoma
    secretKey: client-secret

replicaCount: 2

image:
  repository: 533267197037.dkr.ecr.us-east-1.amazonaws.com/natoma/natoma-ai
  pullPolicy: IfNotPresent
  tag: "0.0.15"

service:
  type: ClusterIP
  port: 9090

ingress:
  enabled: true
  host: eks1.sandbox.natomalab.com
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/scheme: internal
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
    alb.ingress.kubernetes.io/ssl-redirect: "443"
    alb.ingress.kubernetes.io/certificate-arn: <arn>
    alb.ingress.kubernetes.io/healthcheck-path: /healthz

readinessProbe:
  httpGet:
    path: /healthz
    port: 9090

env:
  - name: AUDIT_LOG_ENABLED
    value: "true"

---

Support

Please reach out to the Natoma team or email [email protected].