The kubiya_integration resource allows you to create and manage integrations in the Kubiya platform. Integrations enable connections to external systems like AWS, GitHub, Kubernetes, Jira, and more, allowing agents to interact with these services.
Integrations are the foundation for connecting your agents to external services. They provide secure, configurable connections that can be reused across multiple agents.

​
Prerequisites

Before using this resource, ensure you have:
  1. A Kubiya account with API access
  2. An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
  3. Appropriate credentials and permissions for the external systems you want to integrate

​
Quick Start

resource "kubiya_integration" "aws_basic" {
  name             = "aws-production"
  description      = "Production AWS account"
  integration_type = "aws"
  
  configs = [
    {
      name       = "us-west-2"
      is_default = true
      vendor_specific = {
        arn    = "arn:aws:iam::123456789012:role/KubiyaRole"
        region = "us-west-2"
      }
    }
  ]
}

​
Configuration Examples

Configure AWS integration with multiple regions:
resource "kubiya_integration" "aws_multi_region" {
  name             = "aws-global"
  description      = "Global AWS integration with multiple regions"
  integration_type = "aws"
  auth_type        = "global"
  
  configs = [
    {
      name       = "us-west-2"
      is_default = true
      vendor_specific = {
        arn    = "arn:aws:iam::123456789012:role/KubiyaRole"
        region = "us-west-2"
      }
    },
    {
      name       = "eu-west-1"
      is_default = false
      vendor_specific = {
        arn    = "arn:aws:iam::123456789012:role/KubiyaRole"
        region = "eu-west-1"
      }
    },
    {
      name       = "ap-south-1"
      is_default = false
      vendor_specific = {
        arn    = "arn:aws:iam::123456789012:role/KubiyaRole"
        region = "ap-south-1"
      }
    }
  ]
}

resource "kubiya_agent" "aws_agent" {
  name         = "aws-multi-region-agent"
  runner       = "kubiya-hosted"
  description  = "AWS agent with multi-region access"
  instructions = "You are an AWS agent with access to multiple regions. Always specify the region when performing operations."
  
  integrations = [kubiya_integration.aws_multi_region.name]
}

​
Advanced Configurations

Set up environment-specific integration configurations using dynamic blocks:
locals {
  environments = {
    dev = {
      arn    = "arn:aws:iam::111111111111:role/DevRole"
      region = "us-west-2"
    }
    staging = {
      arn    = "arn:aws:iam::222222222222:role/StagingRole"
      region = "us-east-1"
    }
    prod = {
      arn    = "arn:aws:iam::333333333333:role/ProdRole"
      region = "us-east-1"
    }
  }
}

resource "kubiya_integration" "env_aws" {
  name             = "aws-all-environments"
  description      = "AWS integration for all environments"
  integration_type = "aws"
  
  configs = [
    for env, config in local.environments : {
      name       = env
      is_default = env == "dev"
      vendor_specific = {
        arn    = config.arn
        region = config.region
        env    = env
      }
    }
  ]
}
Configure Jira integration for issue tracking:
resource "kubiya_integration" "jira" {
  name             = "jira-cloud"
  description      = "Jira Cloud integration"
  integration_type = "jira"
  
  configs = [
    {
      name       = "main-instance"
      is_default = true
      vendor_specific = {
        url      = "https://mycompany.atlassian.net"
        project  = "OPS"
        api_type = "cloud"
      }
    }
  ]
}

​
Arguments Reference

​
Required Arguments

​
name
string
required
The name of the integration. Must be unique within your organization.
​
configs
array
required
List of configuration objects. Each config must have:
​
configs.name
string
required
Name of the configuration.
​
configs.is_default
boolean
required
Whether this is the default configuration. At least one config must be default.
​
configs.vendor_specific
object
required
Vendor-specific configuration parameters (varies by integration type).

​
Optional Arguments

​
description
string
A description of the integration’s purpose and functionality.
​
auth_type
string
default:""
Authentication type. Available options:
  • global - Global authentication
  • per_user - Per-user authentication
  • Empty string (default)
​
integration_type
string
default:"aws"
Type of integration. Available options:
  • aws - Amazon Web Services
  • aws_organization - AWS Organizations
  • gcp - Google Cloud Platform
  • azure - Microsoft Azure
  • github - GitHub
  • kubernetes - Kubernetes
  • jira - Atlassian Jira
  • confluence - Atlassian Confluence

​
Vendor-Specific Configuration

The vendor_specific map within each config varies by integration type:
​
arn
string
required
IAM role ARN for AWS access.
​
region
string
required
AWS region for operations.

​
Attributes Reference

In addition to all arguments above, the following attributes are exported:
​
id
string
The unique identifier of the integration.

​
Import

Integrations can be imported using their ID: 
terraform import kubiya_integration.example <integration-id>

​
Best Practices

Security

  • Use least privilege access for all integrations
  • Never hardcode sensitive credentials in configurations
  • Regularly audit and rotate access credentials
  • Use separate configs for different environments

Configuration

  • Always set one configuration as default
  • Use clear, descriptive names for integrations
  • Document vendor-specific parameters and their purpose
  • Group related configurations logically

Testing

  • Test integrations in non-production environments first
  • Verify connectivity before deploying to production
  • Monitor integration health and usage patterns
  • Document testing procedures for each integration type

Maintenance

  • Keep integration configurations in version control
  • Use Terraform modules for common integration patterns
  • Implement consistent naming conventions
  • Monitor and alert on integration failures

​
Compatibility

Requirements:
  • Kubiya Terraform Provider version >= 1.0.0
  • Terraform >= 1.0
  • At least one config must have is_default = true
  • Integration names must match exactly when referenced by agents
Important Considerations:
  • Some integration types may require additional setup in Kubiya dashboard
  • Ensure proper IAM roles and permissions are configured in target systems
  • Test connectivity before using integrations in production agents

​
Troubleshooting

  • Verify IAM roles and permissions in the target system
  • Check that ARNs and identifiers are correctly formatted
  • Ensure service accounts have necessary permissions
  • Test authentication outside of Kubiya first
  • Ensure at least one config has is_default = true
  • Verify all required vendor_specific fields are provided
  • Check that integration_type matches available options
  • Validate URL formats and endpoints
  • Verify integration names match exactly in agent configuration
  • Check that the integration is active and properly configured
  • Ensure agent has appropriate permissions to use the integration
  • Review integration logs for connection issues