​
Overview

Terraform services enable you to provision and manage cloud infrastructure as code. Ryvn provides automated state management, secure credential handling, and integrated deployment controls. Infrastructure changes are coordinated with your application deployments through release channels and maintenance windows.

​
How Terraform Services Work

Terraform services in Ryvn allow you to define and manage infrastructure resources across multiple cloud providers (AWS, Google Cloud, Azure) using HashiCorp Terraform. When you create a Terraform service, Ryvn handles:
  • Terraform state management
  • Secure storage of provider credentials
  • Execution of Terraform plans and applies
  • Version control and rollback capabilities

​
Prerequisites

​
Backend Configuration

To execute terraform within the Ryvn environment, you must set the backend to be Kubernetes. 
backend "kubernetes" {}
This ensures that the state is stored within the execution environment. Ryvn uses kubernetes as the backend store and configures to store the state in a secret. This allows terraform state management to work on all cloud providers without needing to configure blob store or state locking separately.

​
AWS Terraform Executor Policies

In Ryvn’s architecture, the Ryvn Agent is the component responsible for executing Terraform operations and managing Terraform state in your AWS environment. This agent runs with specific IAM permissions that determine which AWS resources your Terraform services can create and manage. By default, the Ryvn Agent runs with restricted IAM permissions that limit the types of resources Terraform can create or manage. To enable broader permissions for your Terraform services, you need to configure the Ryvn Agent’s IAM policy through the terraform_executor_policies configuration. To grant full access for Terraform services in your AWS environment, add the following to your AWS provisioning configuration: 
terraform_executor_policies:
  - effect: Allow
    actions:
      - "*"
    resource: "*"
This configuration adds an IAM policy statement to the Ryvn Agent role, granting it full AWS access permissions. With these expanded permissions, your Terraform services can deploy any AWS resources without restriction.
Security Best Practice: While the example above shows full wildcard permissions for simplicity, you should scope these permissions down to only what your Terraform services actually need when deploying to customer environments. Follow the principle of least privilege by limiting actions to specific services and resources required by your infrastructure.
The terraform_executor_policies configuration must be added during environment provisioning. For existing environments, you’ll need to update the provisioning configuration to modify the Ryvn Agent’s permissions. See the AWS provisioning documentation for more details.

​
Creating a Terraform Service

To create a Terraform service:
  1. Navigate to the Services tab in the Ryvn dashboard
  2. Click Create Service
  3. Select Terraform as the service type
  4. Configure your Terraform source (see below)
  5. Click Create

​
Configuring Terraform Source

Terraform services in Ryvn use GitHub repositories as their source. You can configure:
  • GitHub Repository: Select the repository containing your Terraform code
  • Terraform Path (Optional): Specify a subdirectory within the repository where your Terraform configuration is located
If your Terraform configuration is in the root of the repository, you can leave the path field empty. If it’s in a subdirectory (e.g., terraform/production), specify that path.

​
Source Credentials

Ryvn automatically manages the credentials needed to access your GitHub repository. When you deploy a Terraform service to an environment, Ryvn:
  1. Generates temporary access tokens for your GitHub repository
  2. Securely passes these credentials to the Terraform execution environment
  3. Ensures the credentials have the minimum necessary permissions

​
Managing Variables

​
Accessing the Variables Editor

1

Navigate to Installation

Go to Environments → Select your environment → Click on your Terraform installation
2

Open Settings

Click the Settings button or navigate to the Settings tab
3

Select Terraform Variables

In the settings sidebar, click Terraform Variables
4

Edit Variables

Use the built-in YAML editor to configure your variables with autocomplete support

​
Basic Variable Configuration

Variables are defined in YAML format and can include static values or dynamic template expressions: 
# Static values
region: us-east-1
instance_type: t3.medium
enable_monitoring: true

# Template expressions for dynamic values
vpc_id: {{ .ryvn.env.state.vpc.id }}
cluster_region: {{ .ryvn.env.state.cluster_region }}
Sensitive variables (like API keys or access tokens) can be marked as secret, ensuring they’re encrypted and never displayed in the dashboard.

​
Template System

Ryvn provides access to environment state data through template variables. All template expressions use the {{ }} syntax.

​
Environment State Variables

Access infrastructure information provisioned by Ryvn:

​
Cross-Installation References

Reference outputs from other Terraform installations in the same environment: 
# Reference outputs from another installation
database_endpoint: {{ .ryvn.installations.postgres_service.outputs.endpoint }}
storage_bucket: {{ .ryvn.installations.storage_service.outputs.bucket.name }}
api_url: {{ .ryvn.installations.api_service.outputs.load_balancer.dns_name }}
Installation names in templates use underscores instead of hyphens. For example, an installation named my-storage becomes my_storage in template expressions.

​
Secret References

Access Kubernetes secrets created in your environment: 
# Basic secret reference
database_password: {{ k8sSecretValue "db-credentials" }}

# Secret with specific key
api_key: {{ k8sSecretValue "api-secrets" "key" }}

​
Template Functions

Ryvn provides helper functions to format and manipulate template values: 
# Convert array to YAML
availability_zones: {{ .ryvn.env.state.vpc.azs | toYaml }}
# Output: ["us-east-1a", "us-east-1b", "us-east-1c"]

# Properly indent YAML arrays with nindent
private_subnets: {{ .ryvn.env.state.vpc.private_subnet_ids | toYaml | nindent 2 }}
# Output:
#   - subnet-abc123
#   - subnet-def456

​
Configuration Examples

​
Database Module

# Database configuration using environment variables
engine: postgres
engine_version: "16.8"
instance_class: db.t3.micro

# Use VPC from environment
vpc_id: {{ .ryvn.env.state.vpc.id }}
subnet_ids:
{{ .ryvn.env.state.vpc.private_subnet_ids | toYaml | nindent 2 }}

# Security configuration
allowed_cidr_blocks:
  - {{ .ryvn.env.state.vpc.cidr }}

# Credentials from secrets
username: admin
password: {{ k8sSecretValue "db-password" }}

# Naming based on environment
identifier: myapp-{{ .ryvn.env.state.cluster_name }}

# Tags
tags:
  Environment: {{ .ryvn.env.state.cluster_name }}
  ManagedBy: Ryvn
  Domain: {{ .ryvn.env.state.public_domain.name }}
Template expressions are processed when the Terraform task is created. If a referenced installation or secret doesn’t exist, the task will fail with a template error. Ensure dependencies exist before referencing them.

​
Deploying Services

After creating a Terraform service, you can deploy it to an environment:
  1. Navigate to the Environments tab
  2. Select the target environment
  3. Click Add Installation
  4. Select your Terraform service
  5. Configure any Terraform variables needed for your deployment
  6. Click Deploy
During deployment, Ryvn will:
  1. Clone your GitHub repository
  2. Navigate to the specified Terraform path (if provided)
  3. Initialize Terraform
  4. Create an execution plan
  5. Apply the changes if the plan is successful

​
Monitoring Deployments

After a Terraform operation completes, Ryvn updates the installation status to reflect the current state:
OperationSuccessStatus
Terraform ApplyYesUp to date
Terraform ApplyNoFailed
Terraform PlanYesPending
When a Terraform apply task completes successfully, the installation status is automatically updated to Up to date. This indicates that your infrastructure is provisioned according to your Terraform configuration. If a Terraform operation fails, the installation status will be marked as Failed. You can view detailed error on the installation’s Activity page or in the logs.

​
Release Management

Managing infrastructure changes requires coordination to avoid disrupting applications. Ryvn provides controls for Terraform deployments: Release Channels: Control how infrastructure changes flow through environments. Deploy to development first, then promote through staging to production with approval gates. Maintenance Windows: Schedule infrastructure changes during acceptable downtime periods (database migrations, network updates, security changes).