Existing clusters

Ryvn can deploy into a Kubernetes cluster you already run instead of provisioning one for you. You install the Ryvn agent, the agent connects outbound to Ryvn, and from then on the environment behaves like any other — services, installations, release channels, and observability all work the same way. What changes is the boundary. Ryvn manages what runs inside the cluster and leaves everything around it — the network, the cluster itself, the node pools, ingress, and DNS — under your control.

Choosing this path

Pick an existing cluster when your platform team already owns cluster lifecycle, when the cluster predates Ryvn, or when it needs to live somewhere Ryvn does not provision. If you would rather Ryvn stand up the whole environment, see How provisioning works instead. There are two variants. If the cluster runs in AWS, Google Cloud, or Azure, select that provider and then Use an existing cluster — only this variant can give the agent a cloud identity, so it is the only one that can run Terraform against cloud APIs (see Infrastructure permissions). For a cluster anywhere else, select the Other provider. Everything else on this page applies to both.

What Ryvn installs

Connecting the cluster installs Ryvn’s base platform:

Component	Namespace	Purpose
`ryvn-agent`	`ryvn-system`	Executes deployments and reconciles state
`ryvn-collector`	`observability`	Forwards logs and metrics to Ryvn (Grafana Alloy)
`kube-state-metrics`	`observability`	Cluster and workload metrics
`keda`	`kube-system`	Event-driven pod autoscaling

KEDA is optional — turn it off in platform settings if your cluster already runs its own. Log and metric collection are likewise toggleable.

What Ryvn does not do

No network or cluster infrastructure. Ryvn creates no VPC, VNet, subnets, cluster, or node pools, and modifies none of the ones you have.
No ingress, DNS, or certificates. Ryvn’s managed gateway is deliberately not installed on these environments, so ingress controllers, TLS certificates, and DNS records stay yours to run.
No cloud API access by default. The agent starts with Kubernetes permissions only. Granting it cloud access is an explicit, separate opt-in — the rest of this page.

Requirements

A Kubernetes cluster, with kubectl and helm access to it. No minimum Kubernetes version is enforced.
Outbound HTTPS from the cluster. The agent is pull-based and egress-only: it opens connections to Ryvn and never accepts inbound ones, so it needs no ingress rules, port forwarding, or public endpoints.
Somewhere for the agent to schedule. It requests 250m CPU / 512Mi memory and runs unprivileged — non-root, read-only root filesystem, all capabilities dropped. It tolerates the CriticalAddonsOnly and kubernetes.io/arch=arm64 taints, but tolerations only permit scheduling, they never attract it: any other taint on your nodes will leave the agent Pending. It also ships no memory limit on purpose, since Terraform plans can spike to several GiB — a LimitRange that forces one back on may cut plans short.

Cluster permissions

By default the Ryvn agent assumes broad permissions in the cluster, so it can fully manage cluster-level resources — CRDs, cluster issuers, and whatever else the Helm charts you deploy need to create. If your deployments only ever target a specific set of namespaces, permissions can be scoped to those namespaces instead. Contact Ryvn to set that up for an environment.

Connect the cluster

Create the environment

In the Ryvn dashboard, create an environment and work through the wizard:

Environment details — name and defaults
Provider selection — AWS, Google Cloud, Azure, or Other
Cluster setup — choose Use an existing cluster (skipped entirely for Other)
Platform features — approval policy, observability, and infrastructure permissions
Provisioning details — the agent bootstrap commands below
Review environment — a summary of what Ryvn will and will not do

The networking and provisioning-method steps do not appear: there is no network for Ryvn to lay out and no infrastructure for it to stand up.

Download the agent manifest

On the Provisioning details step, click Download ryvn-agent-manifest.yaml. The manifest contains the ryvn-system namespace, the agent’s credentials secret for this environment, and the role definitions behind user access to the cluster — so you do not have to create the namespace yourself. The agent’s own cluster permissions come from the chart in the next step, covered in Cluster permissions.Downloading again mints a fresh key, so treat the file as a credential and re-run the install if you regenerate it.

Apply it

kubectl apply -f ~/Downloads/ryvn-agent-manifest.yaml

Install the agent

helm install ryvn-agent oci://docker.io/ryvn/ryvn-agent \
  -n ryvn-system --set targetEnv=ENVIRONMENT_NAME

The dashboard shows the exact command with your environment name filled in, then waits for the agent’s first heartbeat. Once it reports in, the environment is connected and you can deploy to it.

Platform features

The Platform features step configures behavior you can change at any time afterwards under Settings → Infrastructure → Platform Settings:

Approval policy — whether installation and infrastructure tasks wait for manual approval. See Deployment approvals.
Observability — metric collection, log collection, and log redaction patterns applied before logs leave the cluster.
Infrastructure permissions — covered next.

Infrastructure permissions

Out of the box the agent can deploy anything that lives inside the cluster — containers, Helm charts, jobs — using its Kubernetes RBAC. It cannot touch your cloud account, because nothing in your cloud account has granted it permission to. Allow infrastructure changes is how you grant that permission. You create a role in your cloud account, trust the agent’s Kubernetes service account to assume it, and paste the role’s identifier into Ryvn. From then on, Terraform services and installations in that environment run as that role.

On clusters Ryvn provisions, Ryvn creates this role for you during provisioning. This section is for existing clusters, where Ryvn never had access to your cloud account and cannot create anything in it.

What the role is for

Terraform services let you manage cloud resources — a database, a bucket, a queue — alongside the application that uses them. The agent is what actually runs terraform plan and terraform apply, from inside your cluster. To do that against a cloud provider API, the Terraform process needs cloud credentials. Ryvn does not store cloud keys for this. Instead the agent uses the cluster’s built-in workload identity — IRSA on EKS, Workload Identity on GKE, Azure Workload Identity on AKS — to exchange its Kubernetes service account token for short-lived cloud credentials. You tell Ryvn which cloud identity to use; the cloud provider decides whether to hand over credentials, based on a trust policy you control. Leaving the setting off is a perfectly normal way to run an environment. The agent keeps full ability to deploy and manage workloads. What it loses is the ability to authenticate to your cloud provider — a Terraform service that talks to a cloud API will fail at the provider authentication step.

How the trust relationship works

Every cloud provider needs the same thing from you: a statement that one specific Kubernetes service account, in one specific cluster, is allowed to act as your role. That service account is always:

system:serviceaccount:ryvn-system:ryvn-agent

The agent’s service account is named ryvn-agent and cannot be renamed — not through Helm values, not through the release name. ryvn-system is the namespace you installed the agent into; if you installed it elsewhere, substitute your namespace everywhere below. Ryvn holds up the other half. When you save the setting, Ryvn annotates that service account with the identity you supplied and rolls the agent pods so they pick up the new credentials.

Ryvn never asks for and never stores a cloud key, secret, or certificate for this. The only values you provide are identifiers — a role ARN, a service account email, or client/tenant/subscription IDs. All of them are safe to treat as non-secret.

Step 1 — Create the role

You can do this before or after creating the environment. Doing it first means you can paste the identifier straight into the wizard; doing it later means one extra visit to the environment’s settings.

AWS
Google Cloud
Azure

EKS uses IAM Roles for Service Accounts (IRSA). The role trusts your cluster’s OIDC provider, scoped to the agent’s service account.

Confirm the cluster has an IAM OIDC provider

aws eks describe-cluster --name CLUSTER_NAME \
  --query "cluster.identity.oidc.issuer" --output text

This prints an issuer URL like https://oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE. If IAM has no provider registered for it yet, create one:

eksctl utils associate-iam-oidc-provider --cluster CLUSTER_NAME --approve

Write the trust policy

Save this as trust-policy.json, replacing the account ID and the OIDC host/path from the previous step.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:ryvn-system:ryvn-agent",
          "oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}

The condition keys use the issuer URL without the https:// prefix. Both conditions matter: sub pins the role to the agent, and aud prevents tokens minted for another audience from being replayed.

Create the role

aws iam create-role \
  --role-name RyvnAgentTerraform \
  --assume-role-policy-document file://trust-policy.json

Attach a permissions policy

Write the permissions your modules need into permissions-policy.json — see Scoping the permissions — then create and attach it:

POLICY_ARN=$(aws iam create-policy \
  --policy-name RyvnAgentTerraformPolicy \
  --policy-document file://permissions-policy.json \
  --query "Policy.Arn" --output text)

aws iam attach-role-policy \
  --role-name RyvnAgentTerraform \
  --policy-arn "$POLICY_ARN"

Copy the role ARN

aws iam get-role --role-name RyvnAgentTerraform --query "Role.Arn" --output text

The result looks like arn:aws:iam::123456789012:role/RyvnAgentTerraform. This is the value Ryvn needs.

The agent uses IRSA, not EKS Pod Identity. A Pod Identity association targeting ryvn-agent will not be picked up — the trust must be federated through the cluster’s OIDC provider as shown above.

GKE uses Workload Identity. You create a Google service account and let the agent’s Kubernetes service account impersonate it.

Confirm Workload Identity is enabled

gcloud container clusters describe CLUSTER_NAME --location LOCATION \
  --format="value(workloadIdentityConfig.workloadPool)"

You want PROJECT_ID.svc.id.goog. If the output is empty, enable it on the cluster and its node pools:

gcloud container clusters update CLUSTER_NAME --location LOCATION \
  --workload-pool=PROJECT_ID.svc.id.goog

gcloud container node-pools update NODE_POOL --cluster CLUSTER_NAME \
  --location LOCATION --workload-metadata=GKE_METADATA

Node pools must run the GKE metadata server, or pods will silently fall back to the node’s default service account.

Create the Google service account

gcloud iam service-accounts create ryvn-agent \
  --project PROJECT_ID \
  --display-name "Ryvn Agent Terraform"

Grant it the permissions Terraform needs

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member "serviceAccount:ryvn-agent@PROJECT_ID.iam.gserviceaccount.com" \
  --role "roles/cloudsql.admin"

Repeat for each role your modules require. See Scoping the permissions.

Allow the agent to impersonate it

gcloud iam service-accounts add-iam-policy-binding \
  ryvn-agent@PROJECT_ID.iam.gserviceaccount.com \
  --project PROJECT_ID \
  --role "roles/iam.workloadIdentityUser" \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[ryvn-system/ryvn-agent]"

The member string is the whole point of this step: it names the Kubernetes namespace and service account that are allowed to act as this Google service account.

Copy the service account email

ryvn-agent@PROJECT_ID.iam.gserviceaccount.com — this is the value Ryvn needs.

AKS uses Azure Workload Identity. You create a user-assigned managed identity and federate it with the agent’s service account.

Enable the OIDC issuer and workload identity on the cluster

az aks update --resource-group RESOURCE_GROUP --name CLUSTER_NAME \
  --enable-oidc-issuer --enable-workload-identity

Then read back the issuer URL:

az aks show --resource-group RESOURCE_GROUP --name CLUSTER_NAME \
  --query "oidcIssuerProfile.issuerUrl" --output tsv

Create the managed identity

az identity create --resource-group RESOURCE_GROUP --name ryvn-agent

Federate it with the agent's service account

az identity federated-credential create \
  --name ryvn-agent \
  --identity-name ryvn-agent \
  --resource-group RESOURCE_GROUP \
  --issuer "OIDC_ISSUER_URL" \
  --subject "system:serviceaccount:ryvn-system:ryvn-agent" \
  --audience "api://AzureADTokenExchange"

The subject and audience must match exactly — Azure does no fuzzy matching, and a mismatch surfaces at runtime as a token exchange failure rather than at creation time.

Assign a role to the identity

PRINCIPAL_ID=$(az identity show --resource-group RESOURCE_GROUP --name ryvn-agent \
  --query principalId --output tsv)

az role assignment create \
  --assignee-object-id "$PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Contributor" \
  --scope "/subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP"

Scope this to the narrowest resource group that covers what your modules manage. See Scoping the permissions.

Copy the three IDs

az identity show --resource-group RESOURCE_GROUP --name ryvn-agent \
  --query "{clientId:clientId, tenantId:tenantId}" --output table

Ryvn needs the client ID, the tenant ID, and the subscription ID the identity should operate in.

Step 2 — Turn on Allow infrastructure changes

During environment creation
After environment creation

On the Platform features step, find the Infrastructure Permissions section and turn on Allow infrastructure changes. The fields for your provider appear below the toggle:

AWS — Agent IAM role ARN
Google Cloud — Agent service account email
Azure — Agent client ID, Agent tenant ID, Subscription ID

Ryvn checks the format of each value before letting you move on, so a typo is caught here rather than at the first Terraform run. The check is silent: if a value is malformed, Continue simply stays disabled rather than showing an error next to the field. If the button will not activate, re-check the value against the placeholder format.The Review environment step restates which identity the agent will use.

Saving re-renders the agent’s installation. Ryvn writes the identity annotation onto the ryvn-agent service account and restarts the agent pods, because cloud identity annotations are only read when a pod starts. Expect a brief gap while the pods roll.

Step 3 — Verify

Check that the annotation landed on the service account:

kubectl get serviceaccount ryvn-agent -n ryvn-system -o yaml

You should see the annotation for your provider:

Provider	Annotation
AWS	`eks.amazonaws.com/role-arn`
Google Cloud	`iam.gke.io/gcp-service-account`
Azure	`azure.workload.identity/client-id` and `azure.workload.identity/tenant-id`

On Azure, Ryvn also adds the azure.workload.identity/use: "true" pod label, which is what triggers the Azure webhook to project a token into the agent’s pod. Annotations alone are not enough there, so confirm the label is present:

kubectl get pods -n ryvn-system -l azure.workload.identity/use=true

Confirm the pods restarted after the change:

kubectl get pods -n ryvn-system -l app.kubernetes.io/name=ryvn-agent

Then run a real check: create a Terraform installation in the environment and trigger a plan. A plan that reaches “Refreshing state” has authenticated successfully.

Scoping the permissions

Ryvn cannot tell you what the role should be allowed to do — that depends entirely on which resources your Terraform modules manage. Two approaches work: Start narrow. Grant only what your current modules need, and widen when a plan fails with an authorization error. This is the safer default and the one worth the extra iterations for production environments. Start broad, then deny. On its own provisioned clusters, Ryvn takes this shape: allow most actions, then explicitly deny the operations that read or destroy customer data — Secrets Manager and SSM parameter reads, DynamoDB item operations, KMS decrypt, database failover and restore, IAM user and group management, and organization-level changes. Terraform needs to create a database; it never needs to read rows out of one. Whichever you pick, remember that this role is the blast radius for every Terraform module deployed into the environment. Scope it to a single resource group, project, or account boundary wherever your cloud provider lets you.

What Ryvn stores

Only the identifiers you typed: a role ARN, a service account email, or client/tenant/subscription IDs. They are stored as ordinary environment settings, not secrets, and are visible to anyone who can view the environment. Terraform state for installations stays in your cluster — the agent uses the Kubernetes backend and writes state to a Secret. It is never shipped to Ryvn.

Troubleshooting

Symptom	Likely cause
AWS: `AccessDenied` / `InvalidIdentityToken` on `AssumeRoleWithWebIdentity`	The trust policy `sub` does not match `system:serviceaccount:ryvn-system:ryvn-agent`, or the cluster’s OIDC provider is not registered in IAM.
AWS: credentials resolve to the node’s instance role instead of your role	The annotation is missing or the pods have not rolled since it was added.
GCP: `403` or “unable to impersonate service account”	The `roles/iam.workloadIdentityUser` binding is missing, or names the wrong namespace/service account.
GCP: the agent authenticates as the node’s default service account	The node pool is not running the GKE metadata server (`--workload-metadata=GKE_METADATA`).
Azure: `AADSTS70021` — no matching federated identity record	The federated credential’s issuer, subject, or audience does not match the cluster and service account exactly.
Azure: no credentials at all, no token file in the pod	The `azure.workload.identity/use` pod label is missing, so the mutating webhook never ran. Confirm workload identity is enabled on the cluster.
Azure: resources create in the wrong subscription	The Subscription ID field points somewhere other than where the role assignment is scoped.
Terraform authenticates, then fails on a specific resource	The role authenticated fine but lacks permission for that resource type. Widen the policy for that action only.
You changed the role but the agent still uses the old identity	The pods did not restart. Check for a `checksum/service-account` annotation on the agent pods and roll the deployment if needed.

If a plan fails and the error does not point at authentication, the role is probably working and the problem is in the module. Check the task logs on the installation.

Terraform services — writing and deploying Terraform modules through Ryvn
Ryvn Agent — how the agent runs and what it has access to
How provisioning works — the managed path, where Ryvn creates this role for you

Get started

Agents

Provision

Deploy

Concepts

Configure

Release

Templating

Observability

Networking

Support

Existing clusters

Choosing this path

What Ryvn installs

What Ryvn does not do

Requirements

Cluster permissions

Connect the cluster

Platform features

Infrastructure permissions

What the role is for

How the trust relationship works

Step 1 — Create the role

Step 2 — Turn on Allow infrastructure changes

Step 3 — Verify

Scoping the permissions

What Ryvn stores

Troubleshooting

​Choosing this path

​What Ryvn installs

​What Ryvn does not do

​Requirements

​Cluster permissions

​Connect the cluster

​Platform features

​Infrastructure permissions

​What the role is for

​How the trust relationship works

​Step 1 — Create the role

​Step 2 — Turn on Allow infrastructure changes

​Step 3 — Verify

​Scoping the permissions

​What Ryvn stores

​Troubleshooting

​Related

Choosing this path

What Ryvn installs

What Ryvn does not do

Requirements

Cluster permissions

Connect the cluster

Platform features

Infrastructure permissions

What the role is for

How the trust relationship works

Step 1 — Create the role

Step 2 — Turn on Allow infrastructure changes

Step 3 — Verify

Scoping the permissions

What Ryvn stores

Troubleshooting

Related