The kubiya_secret resource allows you to create and manage secrets in the Kubiya platform. Secrets store sensitive information like API keys, passwords, and tokens that can be securely accessed by Kubiya agents during execution.
Secrets provide a secure way to handle sensitive data in your automation workflows. They are encrypted at rest and only accessible to authorized agents during execution.

​
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. Proper security practices for handling sensitive data in Terraform

​
Quick Start

variable "external_api_key" {
  type        = string
  sensitive   = true
  description = "External service API key"
}

resource "kubiya_secret" "api_key" {
  name        = "external-api-key"
  value       = var.external_api_key
  description = "API key for external service"
}

resource "kubiya_agent" "api_agent" {
  name         = "api-integration-agent"
  runner       = "kubiya-hosted"
  description  = "Agent that uses external API"
  instructions = "You are an agent that integrates with external APIs using secure credentials."
  
  secrets = [kubiya_secret.api_key.name]
}

​
Configuration Examples

Configure an agent with multiple secrets for various services:
resource "kubiya_secret" "slack_token" {
  name        = "slack-bot-token"
  value       = var.slack_bot_token
  description = "Slack bot token for notifications"
}

resource "kubiya_secret" "jira_token" {
  name        = "jira-api-token"
  value       = var.jira_api_token
  description = "Jira API token"
}

resource "kubiya_secret" "datadog_api_key" {
  name        = "datadog-api-key"
  value       = var.datadog_api_key
  description = "Datadog API key for monitoring"
}

resource "kubiya_agent" "integration_manager" {
  name         = "integration-manager"
  runner       = "kubiya-hosted"
  description  = "Multi-service integration manager"
  instructions = <<-EOT
    You manage integrations with multiple services:
    - Use slack-bot-token for Slack notifications
    - Use jira-api-token for Jira operations
    - Use datadog-api-key for monitoring tasks
  EOT
  
  secrets = [
    kubiya_secret.slack_token.name,
    kubiya_secret.jira_token.name,
    kubiya_secret.datadog_api_key.name
  ]
  
  integrations = ["slack", "jira", "datadog"]
}

​
Advanced Configurations

​
Arguments Reference

​
Required Arguments

​
name
string
required
The name of the secret. Must be unique within your organization and follow naming conventions.
​
value
string
required
The secret value. This is write-only and cannot be read back after creation. Always use sensitive variables for this field.

​
Optional Arguments

​
description
string
A description of the secret’s purpose and usage. Helps with documentation and management.

​
Attributes Reference

In addition to all arguments above, the following attributes are exported:
​
created_at
string
The timestamp when the secret was created.
​
created_by
string
The email of the user who created the secret.
The value attribute is write-only and will not be included in the state file or outputs for security reasons.

​
Import

Secrets can be imported using their name: 
terraform import kubiya_secret.example <secret-name>
The actual secret value cannot be read back after import for security reasons. You will need to update the value in your configuration to match the existing secret.

​
Best Practices

Security

  • Never hardcode sensitive values directly in Terraform files
  • Always use Terraform variables marked as sensitive = true
  • Ensure Terraform state is encrypted and stored securely
  • Implement regular secret rotation policies

Access Control

  • Only grant secret access to agents that require it
  • Use descriptive names that indicate the secret’s purpose and environment
  • Monitor secret access through Kubiya audit logs
  • Keep production and non-production secrets separate

Data Handling

  • Use base64 encoding for binary data like certificates or keys
  • Maintain secure backups of critical secrets outside of Terraform
  • Consider secret versioning for rotation strategies
  • Document secret dependencies clearly

Maintenance

  • Implement automated secret rotation where possible
  • Regular audit of secret usage and access patterns
  • Clean up unused secrets to reduce security surface
  • Version control secret configurations (but not values)

​
Security Considerations

Important Security Notes:
  • Secret values are encrypted at rest in the Kubiya platform
  • Secrets are only accessible to authorized agents during execution
  • Always use Terraform’s sensitive variable feature
  • Never commit actual secret values to version control
State File Security:
  • Terraform state files may contain sensitive information
  • Use encrypted remote state backends (S3 with KMS, Azure Storage with encryption)
  • Restrict access to state files to authorized personnel only
  • Consider using Terraform Cloud or similar services for enhanced security

​
Common Patterns

Standard pattern for API integrations:
# variables.tf
variable "service_api_key" {
  type        = string
  sensitive   = true
  description = "API key for external service"
}

# secrets.tf  
resource "kubiya_secret" "service_api_key" {
  name        = "service-api-key"
  value       = var.service_api_key
  description = "API key for service integration"
}

# agents.tf
resource "kubiya_agent" "service_agent" {
  name         = "service-integration"
  runner       = "kubiya-hosted"
  description  = "Service integration agent"
  instructions = "Use the service-api-key secret for API authentication."
  
  secrets = [kubiya_secret.service_api_key.name]
}

​
Compatibility

Requirements:
  • Kubiya Terraform Provider version >= 1.0.0
  • Terraform >= 1.0
  • Secret values are write-only and cannot be read back after creation
  • Secrets must exist before agents can reference them

​
Troubleshooting