CloudFormation Parameters Reference

This page documents all parameters for the EvidentSource CloudFormation templates.

Enterprise Template Parameters

The enterprise template (evidentsource-enterprise.dynamodb.cloudformation.yml) deploys a production-ready, auto-scaling EvidentSource cluster.

Kafka Prerequisites

Before deploying, you must have an existing Kafka cluster with pre-created topics:

Topic	Default Name	Access	Purpose
Transaction Proposals	evidentsource-transaction-proposals	Internal	Distributed transaction coordination
Database Events	evidentsource-database-events	Public Read	Database lifecycle notifications
Async Commands	evidentsource-async-commands	Public Write	Asynchronous command submission
Async Responses	evidentsource-async-responses	Public Read	Asynchronous command results

See Kafka Prerequisites for detailed setup instructions including topic configuration, access control, and AWS MSK integration.

Required Parameters

Parameter	Type	Description
Host	String	API hostname (e.g., api.evidentsource.example.com). See DNS Configuration.
VPC	AWS::EC2::VPC::Id	VPC for deployment
ClusterSubnets	List<AWS::EC2::Subnet::Id>	Private subnets for EC2 instances (min 2 for HA)
LoadBalancerSubnets	List<AWS::EC2::Subnet::Id>	Subnets for Application Load Balancer
LoadBalancerCertificateArn	String	ACM certificate ARN for TLS termination
KafkaBrokers	String	Kafka bootstrap servers (comma-separated). See Kafka Prerequisites.
StorageTableName	String	DynamoDB table name for event storage
S3BucketName	String	S3 bucket for large objects
LambdaCodeS3Bucket	String	S3 bucket containing Lambda deployment packages

Optional Parameters

Parameter	Type	Default	Description
ClusterMinSize	Number	1	Minimum instances in Auto Scaling Group
ClusterMaxSize	Number	4	Maximum instances in Auto Scaling Group
ClusterInstanceType	String	m8g.large	EC2 instance type (Graviton recommended)
RequireAuth	String	true	Enable JWT authentication
JwtAudience	String	-	Expected JWT audience claim
EnableMcp	String	false	Deploy MCP server cluster for AI agents

Kafka Topic Parameters

Parameter	Type	Default	Description
TransactionProposalsTopic	String	evidentsource-transaction-proposals	Internal linearizer topic (do not consume externally)
DatabaseEventsTopic	String	evidentsource-database-events	Public topic for database lifecycle events
AsyncCommandsTopic	String	evidentsource-async-commands	Public topic for async command submission
AsyncResponsesTopic	String	evidentsource-async-responses	Public topic for async command responses

Kafka Security Parameters

Parameter	Type	Default	Description
KafkaSecurityProtocol	String	(empty)	Security protocol: PLAINTEXT, SSL, or SASL_SSL
KafkaSaslMechanism	String	(empty)	SASL mechanism: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, or AWS_MSK_IAM
KafkaSaslJaasConfig	String	(empty)	JAAS configuration string for SCRAM/PLAIN authentication (not required for AWS_MSK_IAM)

Note: For development environments without Kafka authentication, leave security parameters empty (defaults to PLAINTEXT). For production with AWS MSK, use SASL_SSL with AWS_MSK_IAM mechanism—no JAAS config needed as it uses IAM roles automatically.

Example JAAS configurations:

For SCRAM-SHA-512:

org.apache.kafka.common.security.scram.ScramLoginModule required username="user" password="pass";

For PLAIN:

org.apache.kafka.common.security.plain.PlainLoginModule required username="user" password="pass";

DNS Configuration

The Host parameter specifies the hostname for all EvidentSource API endpoints. This hostname must be configured to resolve correctly for both external clients and internal services.

Requirements

1. External Access: The hostname must resolve to the Application Load Balancer for external clients
2. Internal Access: The hostname must also resolve to the ALB from within the VPC (required for MCP server connectivity)
3. TLS Certificate: The ACM certificate (LoadBalancerCertificateArn) must be valid for this hostname

Route53 Private Hosted Zone Setup

For the MCP server to connect to the EvidentSource API, configure DNS resolution within the VPC:

# Create private hosted zone
aws route53 create-hosted-zone \
  --name example.com \
  --vpc VPCRegion=us-east-1,VPCId=vpc-xxxxx \
  --caller-reference $(date +%s) \
  --hosted-zone-config PrivateZone=true

# Create alias record pointing to ALB
aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890ABC \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "api.evidentsource.example.com",
        "Type": "A",
        "AliasTarget": {
          "HostedZoneId": "Z35SXDOTRQ7X7K",
          "DNSName": "internal-evidentsource-alb-123456.us-east-1.elb.amazonaws.com",
          "EvaluateTargetHealth": true
        }
      }
    }]
  }'

Endpoints

Once configured, EvidentSource exposes:

Endpoint	Port	Description
https://{Host}	443	REST and gRPC API
https://{Host}:8000	8000	MCP server (when EnableMcp=true)

Test Template Parameters

The test template (evidentsource-test.dynamodb.cloudformation.yml) deploys a single-instance setup with integrated Kafka for development and testing.

Required Parameters

Parameter	Type	Description
Host	String	API hostname for CloudEvents source URLs
VPC	AWS::EC2::VPC::Id	VPC for deployment
InstanceSubnet	AWS::EC2::Subnet::Id	Subnet for the EC2 instance
StorageTableName	String	DynamoDB table name
S3BucketName	String	S3 bucket for large objects
LambdaCodeS3Bucket	String	S3 bucket for Lambda code

Optional Parameters

Parameter	Type	Default	Description
InstanceType	String	m8g.2xlarge	EC2 instance type
RequireAuth	String	false	Enable JWT authentication

Migration Notes

Authority → Host Parameter Rename

The CloudFormation parameter was renamed from Authority to Host to better reflect its purpose:

• Before: Authority accepted a full URI authority (host:port)
• After: Host accepts hostname only (e.g., api.example.com)

The CLI --authority flag remains unchanged and continues to accept host:port for local development flexibility.

Update your CloudFormation deployments:

# Before
--parameter-overrides Authority=api.example.com:443

# After
--parameter-overrides Host=api.example.com

ProspectiveBatchesTopic → TransactionProposalsTopic Rename

The CloudFormation parameter was renamed from ProspectiveBatchesTopic to TransactionProposalsTopic to align with the environment variable naming convention (KAFKA_TRANSACTION_PROPOSALS_TOPIC).

• Before: ProspectiveBatchesTopic (default: evidentsource-prospective-batches)
• After: TransactionProposalsTopic (default: evidentsource-transaction-proposals)

Update your CloudFormation deployments:

# Before
--parameter-overrides ProspectiveBatchesTopic=my-prospective-batches

# After
--parameter-overrides TransactionProposalsTopic=my-transaction-proposals

Note: The default topic name has also changed. If you were using the default value, create a new topic with the new default name or explicitly set the parameter to your existing topic name.

New Kafka Parameters

The following parameters were added to support Kafka security and async processing:

• KafkaSecurityProtocol, KafkaSaslMechanism, KafkaSaslJaasConfig - Security configuration
• AsyncCommandsTopic, AsyncResponsesTopic - Async command processing topics

All new parameters have sensible defaults and are backward compatible with existing deployments.

Username/Password → JAAS Config Migration

The KafkaSaslUsername and KafkaSaslPassword parameters were replaced with a single KafkaSaslJaasConfig parameter to align with industry standard Kafka tooling (following patterns from Kpow and Lenses).

Before:

KafkaSaslUsername: "myuser"
KafkaSaslPassword: "mypassword"

After:

KafkaSaslJaasConfig: 'org.apache.kafka.common.security.scram.ScramLoginModule required username="myuser" password="mypassword";'

For AWS MSK IAM authentication, no JAAS config is needed—the system automatically uses the IAM role.