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

Store SSH private keys securely (base64 encoded):
resource "kubiya_secret" "ssh_key" {
  name        = "server-ssh-key"
  value       = base64encode(file("${path.module}/keys/id_rsa"))
  description = "SSH private key for server access (base64 encoded)"
}

resource "kubiya_agent" "server_admin" {
  name         = "server-administrator"
  runner       = "kubiya-hosted"
  description  = "Server administration agent"
  instructions = <<-EOT
    You are a server administrator with SSH access.
    The server-ssh-key secret contains the base64-encoded SSH private key.
    Decode it before use and handle it securely.
  EOT
  
  secrets = [kubiya_secret.ssh_key.name]
  
  environment_variables = {
    SSH_USER = "ubuntu"
    SSH_HOST = "server.example.com"
    SSH_PORT = "22"
  }
}
Store JWT signing secrets for authentication:
variable "jwt_secret" {
  type        = string
  sensitive   = true
  description = "JWT signing secret"
}

resource "kubiya_secret" "jwt_secret" {
  name        = "jwt-signing-secret"
  value       = var.jwt_secret
  description = "Secret key for JWT token signing"
}

resource "kubiya_agent" "auth_agent" {
  name         = "authentication-agent"
  runner       = "kubiya-hosted"
  description  = "Authentication and authorization agent"
  instructions = <<-EOT
    You manage authentication and JWT tokens.
    Use the jwt-signing-secret for token operations.
    Never expose the secret value in logs or outputs.
  EOT
  
  secrets = [kubiya_secret.jwt_secret.name]
}
Store certificates and other binary data securely:
resource "kubiya_secret" "tls_cert" {
  name        = "api-tls-certificate"
  value       = base64encode(file("${path.module}/certs/api.crt"))
  description = "TLS certificate for API server (base64 encoded)"
}

resource "kubiya_secret" "tls_key" {
  name        = "api-tls-private-key"
  value       = base64encode(file("${path.module}/certs/api.key"))
  description = "TLS private key for API server (base64 encoded)"
}

resource "kubiya_agent" "api_server" {
  name         = "api-server-manager"
  runner       = "kubiya-hosted"
  description  = "API server management agent"
  instructions = "You manage the API server with TLS certificates. Handle certificates securely."
  
  secrets = [
    kubiya_secret.tls_cert.name,
    kubiya_secret.tls_key.name
  ]
}

​
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

  • Verify the secret name exactly matches what’s configured in the agent
  • Check that the agent has the secret listed in its secrets array
  • Ensure the secret exists before the agent tries to use it
  • Review agent logs for secret-related error messages
  • Remember that secret values cannot be read back after creation
  • When importing, you must specify the correct value in your configuration
  • Changes to secret values will trigger recreation of the secret
  • Test secret updates in non-production environments first
  • Ensure your Terraform state backend is properly encrypted
  • Use remote state with access controls
  • Regularly audit who has access to Terraform state
  • Consider using Terraform Cloud for enhanced state security