Reference Documentation
Complete reference materials for matlas CLI including YAML kinds, configuration options, and development guides.
YAML Kinds Reference
This reference covers all supported YAML kinds in matlas configuration files. Each kind represents a different type of MongoDB Atlas resource that can be managed declaratively.
Overview
matlas supports two main configuration approaches:
- ApplyDocument - Multi-resource containers for complex configurations (RECOMMENDED)
- Standalone kinds - Individual resource files for simple use cases
Recommended Approach: ApplyDocument
ApplyDocument is the preferred method for most infrastructure scenarios because it provides:
- Dependency management: Automatic resource ordering and validation
- Atomic operations: All-or-nothing deployments with rollback
- Cross-resource validation: Ensures references between resources are valid
- Bulk operations: Deploy entire infrastructure stacks in one command
Use standalone kinds only for simple, single-resource scenarios or when integrating with existing workflows.
API Versions
All resources support these API versions:
matlas.mongodb.com/v1(recommended)matlas.mongodb.com/v1beta1matlas.mongodb.com/v1alpha1
Common Structure
Every YAML kind follows this basic structure:
apiVersion: matlas.mongodb.com/v1
kind: <ResourceKind>
metadata:
name: <resource-name>
labels:
key: value
annotations:
key: value
spec:
# Resource-specific configuration
ApplyDocument
Purpose: Container for multiple resources with dependency management
Use case: Complex configurations, infrastructure as code
Basic Structure
apiVersion: matlas.mongodb.com/v1
kind: ApplyDocument
metadata:
name: my-infrastructure
labels:
environment: production
annotations:
description: "Complete MongoDB Atlas infrastructure"
resources:
- apiVersion: matlas.mongodb.com/v1
kind: Cluster
metadata:
name: production-cluster
spec:
# Cluster configuration
- apiVersion: matlas.mongodb.com/v1
kind: DatabaseUser
metadata:
name: app-user
spec:
# User configuration
Features
- Dependency management: Resources are applied in dependency order
- Bulk operations: Apply multiple resources in one command
- Validation: Cross-resource validation and conflict detection
- Rollback: Atomic operations with automatic rollback on failure
Example
See the Discovery Examples for complete examples.
Project
Purpose: MongoDB Atlas project configuration
Use case: Project-centric infrastructure management
Usage: Can be used standalone or within ApplyDocument
Structure
apiVersion: matlas.mongodb.com/v1
kind: Project
metadata:
name: example-project
spec:
name: "My Atlas Project"
organizationId: "5f1d7f3a9d1e8b1234567890"
databaseUsers:
- metadata:
name: project-user
username: project-user
authDatabase: admin
password: "${USER_PASSWORD}"
roles:
- roleName: readWrite
databaseName: myapp
networkAccess:
- metadata:
name: office-access
cidr: "192.0.2.0/24"
comment: "Office network access"
Required Fields
spec.name: Project display namespec.organizationId: Atlas organization ID
Optional Fields
spec.databaseUsers: Embedded user configurationsspec.networkAccess: Embedded network access rules
Example
See the Infrastructure Patterns for project-format examples.
Cluster
Purpose: MongoDB cluster configuration
Use case: Database infrastructure provisioning
Usage: Typically used within ApplyDocument for dependency management
Basic Structure
apiVersion: matlas.mongodb.com/v1
kind: Cluster
metadata:
name: production-cluster
labels:
environment: production
spec:
projectName: "My Project"
provider: AWS
region: US_EAST_1
instanceSize: M30
clusterType: REPLICASET
mongodbVersion: "7.0"
backupEnabled: true
Required Fields
spec.projectName: Target Atlas project namespec.provider: Cloud provider (AWS,GCP,AZURE)spec.region: Cloud regionspec.instanceSize: Instance size tier
Advanced Configuration
spec:
# Auto-scaling
autoScaling:
diskGBEnabled: true
compute:
enabled: true
scaleDownEnabled: true
minInstanceSize: M30
maxInstanceSize: M40
# Multi-region replication
replicationSpecs:
- numShards: 1
regionConfigs:
- regionName: US_EAST_1
electableNodes: 3
priority: 7
readOnlyNodes: 0
# Security
encryption:
encryptionAtRestProvider: AWS
awsKmsConfig:
enabled: true
customerMasterKeyID: "alias/my-key"
# BI Connector
biConnector:
enabled: true
readPreference: secondary
# Tags
tags:
environment: production
team: platform
cost-center: engineering
Examples
See the Cluster Examples for:
- Basic development clusters
- Production clusters with autoscaling
- Multi-region configurations
DatabaseUser
Purpose: Atlas-managed database user configuration
Use case: Centralized user management via Atlas API
Usage: Recommended for use within ApplyDocument for role dependency validation
Basic Structure
apiVersion: matlas.mongodb.com/v1
kind: DatabaseUser
metadata:
name: app-user
labels:
purpose: application
spec:
projectName: "My Project"
username: app-user
authDatabase: admin
password: "${APP_USER_PASSWORD}"
roles:
- roleName: readWrite
databaseName: myapp
- roleName: read
databaseName: logs
Required Fields
spec.projectName: Target Atlas project namespec.username: Database usernamespec.roles: Array of database roles
Role Types
Built-in MongoDB roles:
roles:
- roleName: read
databaseName: myapp
- roleName: readWrite
databaseName: myapp
- roleName: dbAdmin
databaseName: myapp
- roleName: userAdmin
databaseName: myapp
- roleName: clusterAdmin
databaseName: admin
- roleName: readAnyDatabase
databaseName: admin
- roleName: readWriteAnyDatabase
databaseName: admin
- roleName: userAdminAnyDatabase
databaseName: admin
- roleName: dbAdminAnyDatabase
databaseName: admin
Custom roles (created via DatabaseRole kind):
roles:
- roleName: myCustomRole
databaseName: myapp
Scoping
Limit user access to specific clusters:
spec:
scopes:
- name: "production-cluster"
type: CLUSTER
- name: "staging-cluster"
type: CLUSTER
Authentication
spec.authDatabase: Authentication database (default:admin)spec.password: User password (use environment variables)
Examples
See the User Management Examples for:
- Basic user creation patterns
- Cluster-scoped user access
- Password management workflows
DatabaseRole
Purpose: Custom database role definition
Use case: Granular permission management
Usage: Best used within ApplyDocument with DatabaseUser resources for proper dependency ordering
Basic Structure
apiVersion: matlas.mongodb.com/v1
kind: DatabaseRole
metadata:
name: custom-app-role
spec:
roleName: appDataAccess
databaseName: myapp
privileges:
- actions: ["find", "insert", "update", "remove"]
resource:
database: myapp
collection: users
- actions: ["find"]
resource:
database: myapp
collection: config
inheritedRoles:
- roleName: read
databaseName: reference-data
Required Fields
spec.roleName: Custom role namespec.databaseName: Database where role is defined
Privileges
Define granular permissions:
privileges:
# Collection-level permissions
- actions: ["find", "insert", "update", "remove"]
resource:
database: myapp
collection: users
# Database-level permissions
- actions: ["listCollections", "listIndexes"]
resource:
database: analytics
# Cluster-level permissions
- actions: ["connPoolStats"]
resource:
cluster: true
Common Actions
Read operations: find, listCollections, listIndexes
Write operations: insert, update, remove, createCollection
Admin operations: dbAdmin, userAdmin, createIndex, dropCollection
Cluster operations: connPoolStats, serverStatus
Inherited Roles
Inherit permissions from existing roles:
inheritedRoles:
- roleName: read
databaseName: logs
- roleName: readWrite
databaseName: cache
Examples
See the Custom Roles Examples for:
- Basic custom role definitions
- Advanced permission patterns
- Role inheritance examples
NetworkAccess
Purpose: Network access rule configuration
Use case: IP allowlisting and security
Usage: Can be standalone for simple rules, or within ApplyDocument for coordinated infrastructure
IP Address Access
apiVersion: matlas.mongodb.com/v1
kind: NetworkAccess
metadata:
name: single-ip
spec:
projectName: "My Project"
ipAddress: "203.0.113.42"
comment: "Developer workstation"
deleteAfterDate: "2024-12-31T23:59:59Z"
CIDR Block Access
apiVersion: matlas.mongodb.com/v1
kind: NetworkAccess
metadata:
name: office-network
spec:
projectName: "My Project"
cidr: "203.0.113.0/24"
comment: "Office network range"
AWS Security Group
apiVersion: matlas.mongodb.com/v1
kind: NetworkAccess
metadata:
name: aws-security-group
spec:
projectName: "My Project"
awsSecurityGroup: "sg-0abc123def456789"
comment: "Production AWS security group"
Required Fields
spec.projectName: Target Atlas project name- One of:
spec.ipAddress,spec.cidr, orspec.awsSecurityGroup
Optional Fields
spec.comment: Description (max 80 characters)spec.deleteAfterDate: Automatic expiration (ISO 8601 format)
Examples
See the Network Access Examples for:
- Basic IP and CIDR configurations
- AWS security group integration
- Temporary access patterns
Usage Patterns
ApplyDocument for Infrastructure Management (RECOMMENDED)
ApplyDocument is the recommended approach for most infrastructure scenarios. Use it for comprehensive infrastructure management:
# Apply complete infrastructure
matlas infra apply -f infrastructure.yaml
# Plan before applying
matlas infra plan -f infrastructure.yaml
# Show current state
matlas infra show -f infrastructure.yaml
Single Resource Files (Simple Use Cases)
For simple, single-resource scenarios or legacy integrations, you can use individual kind files:
# Apply a single cluster (only for simple scenarios)
matlas infra apply -f cluster.yaml
# Apply multiple individual files (less efficient than ApplyDocument)
matlas infra apply -f users.yaml -f network.yaml
Note: Individual resource files lack dependency management and cross-resource validation. ApplyDocument is recommended for production use.
Environment Variables
Use environment variables for sensitive data:
export APP_USER_PASSWORD='SecurePassword123!'
export DATABASE_ADMIN_PASSWORD='AdminPassword456!'
matlas infra apply -f users.yaml
Dependency Management
Resources are applied in dependency order:
- Projects (if using Project kind)
- Clusters
- DatabaseRoles (custom roles)
- DatabaseUsers (references roles and clusters)
- NetworkAccess (independent)
Validation and Best Practices
Validation Rules
- API versions must be supported
- Resource kinds must be valid
- Required fields must be present
- Cross-references must be valid (e.g., cluster names in user scopes)
- Dependencies must be resolvable
Best Practices
- Use environment variables for passwords and sensitive data
- Label resources consistently for organization
- Use meaningful names in metadata
- Group related resources in ApplyDocument
- Document configurations with annotations
- Version control your YAML files
- Test configurations with
matlas infra planbefore applying
Common Patterns
All patterns below are recommended for use within ApplyDocument for proper dependency management and validation.
Service account setup:
# 1. Create custom role
kind: DatabaseRole
spec:
roleName: serviceRole
# ... role definition
# 2. Create user with custom role
kind: DatabaseUser
spec:
roles:
- roleName: serviceRole
databaseName: myapp
Environment promotion:
# Use labels for environment management
metadata:
labels:
environment: ""
team: platform
Security-first approach:
# Scope users to specific clusters
spec:
scopes:
- name: "production-cluster"
type: CLUSTER
# Use temporary access for network rules
spec:
deleteAfterDate: "2024-12-31T23:59:59Z"
Related Documentation
- /matlas-cli/infra/ - Infrastructure commands (
apply,plan,diff) - /matlas-cli/atlas/ - Atlas resource management
- /matlas-cli/database/ - Database operations
- /matlas-cli/auth/ - Authentication and configuration
- Examples - Working examples for all kinds
SearchIndex
Purpose: Atlas Search index configuration
Use case: Full-text search and vector search capabilities
Usage: Recommended within ApplyDocument to ensure cluster dependencies are met
Basic Search Index
apiVersion: matlas.mongodb.com/v1
kind: SearchIndex
metadata:
name: movies-text-search
spec:
projectName: "My Project"
clusterName: "production-cluster"
databaseName: "sample_mflix"
collectionName: "movies"
indexName: "default"
indexType: "search"
definition:
mappings:
dynamic: true
Advanced Search Index with Features
apiVersion: matlas.mongodb.com/v1
kind: SearchIndex
metadata:
name: products-advanced-search
spec:
projectName: "My Project"
clusterName: "production-cluster"
databaseName: "ecommerce"
collectionName: "products"
indexName: "products-advanced"
indexType: "search"
definition:
mappings:
dynamic: false
fields:
title:
type: string
analyzer: "titleAnalyzer"
category:
type: stringFacet
price:
type: numberFacet
# Advanced search features
analyzers:
- name: "titleAnalyzer"
type: "custom"
charFilters: []
tokenizer:
type: "standard"
tokenFilters:
- type: "lowercase"
- type: "stemmer"
language: "english"
facets:
- field: "category"
type: "string"
numBuckets: 20
- field: "price"
type: "number"
boundaries: [0, 25, 50, 100, 250, 500]
autocomplete:
- field: "title"
maxEdits: 2
prefixLength: 1
highlighting:
- field: "title"
maxCharsToExamine: 500000
maxNumPassages: 3
synonyms:
- name: "productSynonyms"
input: ["laptop", "notebook", "computer"]
output: "laptop"
explicit: false
fuzzySearch:
- field: "title"
maxEdits: 2
prefixLength: 1
maxExpansions: 50
Vector Search Index
apiVersion: matlas.mongodb.com/v1
kind: SearchIndex
metadata:
name: movie-plot-embeddings
spec:
projectName: "My Project"
clusterName: "production-cluster"
databaseName: "sample_mflix"
collectionName: "movies"
indexName: "plot_vector_index"
indexType: "vectorSearch"
definition:
fields:
- type: "vector"
path: "plot_embedding"
numDimensions: 1536
similarity: "cosine"
Required Fields
spec.projectName: Target Atlas project namespec.clusterName: Target cluster namespec.databaseName: Database namespec.collectionName: Collection namespec.indexName: Search index namespec.definition: Index definition object
Optional Advanced Search Fields
spec.analyzers: Custom analyzer configurationsname: Analyzer nametype: Analyzer type (standard, keyword, simple, whitespace, language, custom)charFilters: Character filters to applytokenizer: Tokenizer configurationtokenFilters: Token filters to apply
spec.facets: Faceted search configurationsfield: Field name to facet ontype: Facet type (string, number, date)numBuckets: Maximum number of bucketsboundaries: Custom bucket boundaries
spec.autocomplete: Autocomplete configurationsfield: Field name for autocompletemaxEdits: Maximum edits for fuzzy matchingprefixLength: Minimum prefix length
spec.highlighting: Search result highlightingfield: Field name to highlightmaxCharsToExamine: Maximum characters to examinemaxNumPassages: Maximum highlighted passages
spec.synonyms: Synonym configurationsname: Synonym collection nameinput: Array of input termsoutput: Output termexplicit: Whether synonyms are explicit
spec.fuzzySearch: Fuzzy search configurationsfield: Field name for fuzzy searchmaxEdits: Maximum character editsprefixLength: Exact prefix match lengthmaxExpansions: Maximum similar terms
Index Types
search: Full-text search (default)vectorSearch: Vector/semantic search for AI/ML applications
Examples
See the Examples for:
- Basic text search index configurations
- Vector search for AI applications
SearchMetrics
Purpose: Search index performance metrics and analytics
Use case: Monitor search index performance, query patterns, and usage
Usage: Read-only operation for retrieving metrics data
Basic Structure
apiVersion: matlas.mongodb.com/v1alpha1
kind: SearchMetrics
metadata:
name: product-search-metrics
spec:
projectName: "My Project"
clusterName: "my-cluster"
indexName: "products-search"
timeRange: "24h"
metrics:
- query
- performance
- usage
Required Fields
spec.projectName: Atlas project name or IDspec.clusterName: Atlas cluster name
Optional Fields
spec.indexName: Specific search index name (omit for all indexes)spec.timeRange: Time range for metrics (1h,6h,24h,7d,30d)spec.metrics: Types of metrics to retrieve (query,performance,usage)
SearchOptimization
Purpose: Search index optimization analysis and recommendations
Use case: Analyze search indexes for performance improvements
Usage: Analysis operation providing optimization recommendations
Basic Structure
apiVersion: matlas.mongodb.com/v1alpha1
kind: SearchOptimization
metadata:
name: index-optimization-analysis
spec:
projectName: "My Project"
clusterName: "my-cluster"
indexName: "products-search"
analyzeAll: true
categories:
- performance
- mappings
- analyzers
Required Fields
spec.projectName: Atlas project name or IDspec.clusterName: Atlas cluster name
Optional Fields
spec.indexName: Specific search index name (omit for all indexes)spec.analyzeAll: Enable detailed analysis (default: false)spec.categories: Analysis categories (performance,mappings,analyzers,facets,synonyms)
SearchQueryValidation
Purpose: Search query syntax validation and optimization
Use case: Validate search queries before execution
Usage: Validation operation for query syntax and performance analysis
Basic Structure
apiVersion: matlas.mongodb.com/v1alpha1
kind: SearchQueryValidation
metadata:
name: query-validation-test
spec:
projectName: "My Project"
clusterName: "my-cluster"
indexName: "products-search"
testMode: true
query:
text:
query: "wireless headphones"
path: "title"
validate:
- syntax
- fields
- performance
Required Fields
spec.projectName: Atlas project name or IDspec.clusterName: Atlas cluster namespec.indexName: Search index namespec.query: Search query object to validate
Optional Fields
spec.testMode: Enable detailed analysis and recommendations (default: false)spec.validate: Validation types (syntax,fields,performance)
Query Examples
Text Search Query
query:
text:
query: "search term"
path: "fieldName"
Compound Query
query:
compound:
must:
- text:
query: "required term"
path: "title"
should:
- text:
query: "optional term"
path: "description"
filter:
- range:
path: "price"
gte: 10
lte: 100
Vector Search Query
query:
knnBeta:
vector: [0.1, 0.2, 0.3, 0.4, 0.5]
path: "embedding"
k: 10
AlertConfiguration
Purpose: Atlas alert configuration for monitoring
Use case: Set up monitoring alerts for Atlas resources
Usage: Recommended within ApplyDocument for comprehensive monitoring setup
Basic Structure
apiVersion: matlas.mongodb.com/v1
kind: AlertConfiguration
metadata:
name: high-cpu-alert
spec:
enabled: true
eventTypeName: "HOST_CPU_USAGE_PERCENT"
severityOverride: "HIGH"
matchers:
- fieldName: "HOSTNAME_AND_PORT"
operator: "CONTAINS"
value: "production"
notifications:
- typeName: "EMAIL"
emailAddress: "alerts@company.com"
delayMin: 0
intervalMin: 15
metricThreshold:
metricName: "CPU_USAGE_PERCENT"
operator: "GREATER_THAN"
threshold: 80.0
units: "PERCENT"
mode: "AVERAGE"
Required Fields
spec.enabled: Whether the alert is activespec.eventTypeName: Type of event to monitorspec.notifications: Array of notification channels
Alert Event Types
Common event types include:
HOST_CPU_USAGE_PERCENT- CPU usage monitoringHOST_MEMORY_USAGE_PERCENT- Memory usage monitoringHOST_DISK_USAGE_PERCENT- Disk usage monitoringCLUSTER_MONGOS_IS_MISSING- Missing mongos processCLUSTER_PRIMARY_ELECTED- Primary election eventsDATABASE_CONNECTIONS_PERCENT- Connection usage monitoring
Notification Channels
Email notifications:
notifications:
- typeName: "EMAIL"
emailAddress: "alerts@company.com"
delayMin: 0
intervalMin: 15
Slack notifications:
notifications:
- typeName: "SLACK"
apiToken: "${SLACK_TOKEN}"
channelName: "#alerts"
username: "Atlas Alert"
PagerDuty notifications:
notifications:
- typeName: "PAGER_DUTY"
serviceKey: "${PAGERDUTY_SERVICE_KEY}"
Webhook notifications:
notifications:
- typeName: "WEBHOOK"
url: "https://api.company.com/webhooks/atlas"
secret: "${WEBHOOK_SECRET}"
Matchers
Target specific resources with matchers:
matchers:
- fieldName: "HOSTNAME_AND_PORT"
operator: "CONTAINS"
value: "production"
- fieldName: "REPLICA_SET_NAME"
operator: "EQUALS"
value: "atlas-cluster0-shard-0"
Matcher operators:
EQUALS/NOT_EQUALS- Exact matchingCONTAINS/NOT_CONTAINS- Substring matchingSTARTS_WITH/ENDS_WITH- Prefix/suffix matchingREGEX/NOT_REGEX- Regular expression matching
Thresholds
Metric thresholds (for performance metrics):
metricThreshold:
metricName: "CPU_USAGE_PERCENT"
operator: "GREATER_THAN"
threshold: 80.0
units: "PERCENT"
mode: "AVERAGE"
General thresholds (for non-metric events):
threshold:
operator: "LESS_THAN"
threshold: 5
units: "RAW"
Examples
See the Alert Examples for:
- Basic CPU and memory monitoring
- Multi-channel notification setups
- Complex matcher configurations
Alert (Read-Only)
Purpose: Atlas alert status and details
Use case: Monitor active alerts and acknowledgment status
Usage: Read-only resource for alert status information
Basic Structure
apiVersion: matlas.mongodb.com/v1
kind: Alert
metadata:
name: alert-status
spec:
projectName: "My Project"
alertId: "507f1f77bcf86cd799439011" # Optional: specific alert ID
Required Fields
spec.projectName: Atlas project name or ID
Optional Fields
spec.alertId: Specific alert ID (omit to list all alerts)
Note: Alert resources are read-only and used for monitoring alert status. Alert configurations are managed through the AlertConfiguration kind.
VPCEndpoint
Purpose: VPC endpoint service configuration
Use case: Private network connectivity to Atlas clusters
Usage: Typically used within ApplyDocument with cluster and network resources
Basic Structure
apiVersion: matlas.mongodb.com/v1
kind: VPCEndpoint
metadata:
name: production-vpc-endpoint
spec:
projectName: "My Project"
cloudProvider: "AWS"
region: "us-east-1"
Required Fields
spec.projectName: Target Atlas project namespec.cloudProvider: Cloud provider (AWS,AZURE,GCP)spec.region: Cloud provider region
Optional Fields
spec.endpointId: Specific endpoint ID (for existing endpoints)
Cloud Provider Support
AWS: Full support for VPC endpoints
Azure: Private Link endpoints
GCP: Private Service Connect
Examples
See the Examples for VPC endpoint setup patterns.
Note: VPC endpoint implementation creates the Atlas-side service. You’ll need to configure the corresponding endpoint in your cloud provider.
For working examples of each kind, see the Examples section with comprehensive YAML configurations and usage patterns.