Secrets

This document outlines how Tensor9 BYOC manages sensitive data (secrets) within your Infrastructure as Code (IaC) to ensure security and support various ownership models for the services your product relies on.

Secret ownership models

Tensor9 BYOC distinguishes between two core models for managing secrets, based on who owns the external service or resource:

Secret Type	Definition	Managed By	Visibility	Example Use Case
Shared Secrets	Used for external services the vendor owns and needs for the product to function.	The vendor (configured on the vendor’s side and “tunneled” into the customer’s appliance).	Customer may be able to view these secrets.	Sentry.io token for vendor-owned monitoring.
Customer-Supplied Secrets	Used for external services the customer fully controls and is providing.	The customer (configured within the appliance during setup).	Vendor has no visibility into the actual secret value.	MongoDB Atlas connection string for a customer-owned database.

Vendors and customers must agree on the ownership of all external services and their associated secrets. Vendor Recommendation: While Tensor9 BYOC supports customer-supplied secrets at the infrastructure (Terraform) level, we strongly encourage migrating to a runtime secret model where the vendor’s application exposes an admin setting page for the customer to provide optional secrets after initial setup. This avoids requiring a new deployment for every secret change and makes secrets easier to manage as optional.

Terraform secret patterns

Tensor9 BYOC supports the following common industry patterns for integrating secrets into your Terraform configuration:

1. Runtime fetching via data source (recommended for external secrets)

This is the most common and recommended pattern for external services. Secrets are stored in an external secret store and retrieved during Terraform execution using a data block.

Action	Vendor Workflow
Define	Create a data block in your Terraform to reference the secret by name.
Reference	Reference the data source’s output (e.g., `data.aws_secretsmanager_secret_version.sentry.secret_string`) in your compute resource definition.
Storage	Secrets are stored in the respective external system (e.g., AWS Secrets Manager, AWS SSM Parameter Store).

Important constraints:

Do not use ARNs: Tensor9 BYOC does not support referencing secrets by Amazon Resource Name (ARN). Use name-based identifiers instead, as ARNs are absolute and may not be accessible from the customer side of the appliance.
Use a literal secret name: Name the secret by the plain path it lives at in your own account (e.g., prod/sentry/token). Don’t build the name from a variable. Tensor9 BYOC reads the name at compile time to identify the secret, and gives each install its own isolated copy on the appliance side, so you don’t parameterize the path yourself.

2. Variable injection

Secrets are passed into the Terraform configuration as variables, typically injected via a CI/CD pipeline or .tfvars file.

Action	Vendor Workflow
Define	Define a variable block with `sensitive = true` and `ephemeral = true`.
Reference	Reference the variable (e.g., `var.db_password`) in your resource definition.
Storage	The secret is passed directly as a value into the pipeline.

Important Constraint: Tensor9 BYOC requires that injected variables contain the actual secret value, not a reference (like a Secrets Manager secret ID). If you need to pass a reference, use the Runtime Fetching (Data Source) pattern instead.

3. Platform/infrastructure generated passwords (no Tensor9 support needed)

This pattern is for secrets that are automatically generated and managed by the cloud provider or Terraform itself (e.g., a database master password created by AWS RDS). Since the secret is fully encapsulated within the IaC, no special Tensor9 BYOC annotation or transfer logic is required.

Secret annotation and configuration

For the Runtime Fetching and Variable Injection patterns, you must explicitly tell Tensor9 BYOC which variables and data sources represent secrets and who owns them using a configuration file (via the tuning document or a separate JSON file). Without this annotation, Tensor9 BYOC defaults all secret-holding data sources/variables to be Vendor-owned (Shared).

Secret lifecycle and rotation

Secret Type	When Collected	Vendor Access
Shared Secrets	When the vendor executes `tofu apply` on their compiled stack.	The vendor places the secret in their external secret store; Tensor9 BYOC fetches and copies it to the appliance.
Customer Secrets	During the customer’s onboarding/setup process via the UI.	The vendor never has access to the secret value.

Before deployment, Tensor9 BYOC performs a pre-flight check to validate that all configured secrets meet the requirements.

Secret rotation

The process for rotating secrets depends on how the secret is referenced in your Terraform:

If passing by Value: If the secret value is directly embedded in a resource definition (e.g., password = var.db_password), an update to the secret will be detected by Terraform, and a normal build and apply (deployment) will update the resource.
If passing by Reference: If the infrastructure retrieves the secret by reference (e.g., a data source fetching from Secrets Manager), the infrastructure itself will not detect a change to the secret value.
- Vendor Action Required: The vendor must trigger a refresh or a new deployment.
- Application Logic Required: The application consuming the secret must have refresh logic built-in to periodically check for updated values.

For secrets managed via AWS Secrets Manager, Tensor9 BYOC supports the use of rotation Lambda functions. The vendor’s controller will copy the rotation Lambda function to the appliance side. This Lambda must use the ARN passed into it at runtime and must not rely on hardcoded ARNs or other references that point to the vendor’s original stack resources, since those will not resolve in the appliance.

Secrets by origin stack type

The approach to managing secrets varies by origin stack type. All approaches share the same principle: store secrets in AWS Secrets Manager or SSM Parameter Store, then pass them to your application as environment variables.

Terraform origin stacks

Define secrets in AWS Secrets Manager or SSM Parameter Store, then inject them into your compute resources as environment variables. Defining the secret:

resource "aws_secretsmanager_secret" "db_password" {
  name = "prod/db/password"
}

resource "aws_secretsmanager_secret_version" "db_password" {
  secret_id     = aws_secretsmanager_secret.db_password.id
  secret_string = var.db_password
}

Injecting into ECS Fargate:

resource "aws_ecs_task_definition" "app" {
  family = "${var.namespace}myapp"

  container_definitions = jsonencode([
    {
      name  = "app"
      image = "myapp:latest"

      # Inject secret as environment variable
      secrets = [
        {
          name      = "DB_PASSWORD"
          valueFrom = aws_secretsmanager_secret.db_password.arn
        }
      ]
    }
  ])
}

Injecting into Lambda:

resource "aws_lambda_function" "api" {
  function_name = "${var.namespace}myapp-api"

  environment {
    variables = {
      DB_PASSWORD = data.aws_secretsmanager_secret_version.db_password.secret_string
    }
  }
}

data "aws_secretsmanager_secret_version" "db_password" {
  secret_id = aws_secretsmanager_secret.db_password.id
}

See Terraform Origin Stacks for complete documentation.

CloudFormation origin stacks

Use CloudFormation dynamic references to fetch secrets from Secrets Manager during stack deployment, then pass them to your resources.

Parameters:
  InstanceId:
    Type: String

Resources:
  # Secret in Secrets Manager
  DBPasswordSecret:
    Type: AWS::SecretsManager::Secret
    Properties:
      Name: !Sub '${InstanceId}/prod/db/password'
      SecretString: !Ref DBPassword

  # ECS Task Definition with secret injection
  TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      Family: !Sub 'myapp-${InstanceId}'
      ContainerDefinitions:
        - Name: app
          Image: myapp:latest
          Secrets:
            - Name: DB_PASSWORD
              ValueFrom: !Ref DBPasswordSecret

See CloudFormation Origin Stacks for complete documentation.

Docker Compose origin stacks

Define secrets in the tuning document, then reference them as environment variables in your compose file. docker-compose.yml:

services:
  api:
    image: myapp/api:latest
    environment:
      - DB_PASSWORD=${DB_PASSWORD}
      - API_KEY=${API_KEY}

tuning.json:

{
  "version": "V1",
  "secrets": {
    "db_password": {
      "source": "aws_secretsmanager",
      "secretId": "prod/db/password",
      "environmentVariable": "DB_PASSWORD"
    },
    "api_key": {
      "source": "aws_ssm_parameter",
      "parameter": "/prod/api/key",
      "environmentVariable": "API_KEY"
    }
  }
}

Create release with tuning document:

tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.0.0" \
  -tuningDoc tuning.json

See Docker Compose Origin Stacks for complete documentation.

Docker Container origin stacks

Similar to Docker Compose, define secrets in the tuning document: tuning.json:

{
  "version": "V1",
  "containerResources": {
    "cpu": "2",
    "memory": "4Gi"
  },
  "secrets": {
    "db_password": {
      "source": "aws_secretsmanager",
      "secretId": "prod/db/password",
      "environmentVariable": "DB_PASSWORD"
    }
  }
}

The secrets are automatically injected as environment variables into your container. See Docker Container Origin Stacks for complete documentation.

Kubernetes origin stacks

Define secrets in AWS Secrets Manager within your Terraform/CloudFormation wrapper, then reference them in Kubernetes Deployment environment variables:

# Define secret in AWS Secrets Manager
resource "aws_secretsmanager_secret" "db_password" {
  name = "prod/db/password"
}

# Reference in Kubernetes Deployment
resource "kubernetes_deployment" "app" {
  spec {
    template {
      spec {
        container {
          env {
            name = "DB_PASSWORD"
            value_from {
              secret_key_ref {
                name = aws_secretsmanager_secret.db_password.name
                key  = "password"
              }
            }
          }
        }
      }
    }
  }
}

Avoid using Kubernetes Secrets directly for sensitive data. Use AWS Secrets Manager and inject values as environment variables. See Kubernetes Origin Stacks for complete documentation.

Application code (all origin stack types)

Regardless of origin stack type, your application code reads secrets from environment variables:

import os

# Read secrets from environment variables
db_password = os.environ['DB_PASSWORD']
api_key = os.environ['API_KEY']

Environment variables provide secret values when the application starts. Applications that need to fetch a value while running can keep using AWS Secrets Manager SDK calls such as get_secret_value(). For cross-cloud deployments, the Secrets Manager service adapter serves supported calls through the configured adapter endpoint. Review its target-specific limits and configure the application’s access before deployment.

Tensor9 BYOC

Getting Started

How It Works

Deploying

Your Customer's Environment

Service Adapters

Auto-Customizations

Security

Connectivity & Networking

Observability & Operations

tensor9 CLI

Secret ownership models

Terraform secret patterns

1. Runtime fetching via data source (recommended for external secrets)

Important constraints:

2. Variable injection

3. Platform/infrastructure generated passwords (no Tensor9 support needed)

Secret annotation and configuration

Secret lifecycle and rotation

Secret rotation

Secrets by origin stack type

Terraform origin stacks

CloudFormation origin stacks

Docker Compose origin stacks

Docker Container origin stacks

Kubernetes origin stacks

Application code (all origin stack types)

​Secret ownership models

​Terraform secret patterns

​1. Runtime fetching via data source (recommended for external secrets)

​Important constraints:

​2. Variable injection

​3. Platform/infrastructure generated passwords (no Tensor9 support needed)

​Secret annotation and configuration

​Secret lifecycle and rotation

​Secret rotation

​Secrets by origin stack type

​Terraform origin stacks

​CloudFormation origin stacks

​Docker Compose origin stacks

​Docker Container origin stacks

​Kubernetes origin stacks

​Application code (all origin stack types)

Secret ownership models

Terraform secret patterns

1. Runtime fetching via data source (recommended for external secrets)

Important constraints:

2. Variable injection

3. Platform/infrastructure generated passwords (no Tensor9 support needed)

Secret annotation and configuration

Secret lifecycle and rotation

Secret rotation

Secrets by origin stack type

Terraform origin stacks

CloudFormation origin stacks

Docker Compose origin stacks

Docker Container origin stacks

Kubernetes origin stacks

Application code (all origin stack types)