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.

Supported Kinds

Kind	Description	API Version
`Project`	MongoDB Atlas project configuration	`v1`
`Cluster`	Atlas cluster (database deployment)	`v1`
`DatabaseUser`	Atlas database user	`v1`
`DatabaseRole`	Custom database role (direct MongoDB connection required)	`v1`
`NetworkAccess`	IP access list entry	`v1`
`SearchIndex`	Atlas Search index configuration	`v1`
`SearchMetrics`	Search index performance metrics and analytics	`v1alpha1`
`SearchOptimization`	Search index optimization analysis	`v1alpha1`
`SearchQueryValidation`	Search query validation and testing	`v1alpha1`
`AlertConfiguration`	Atlas alert configuration for monitoring	`v1`
`Alert`	Atlas alert status and details (read-only)	`v1`
`VPCEndpoint`	Private endpoint for VPC peering	`v1`
`ApplyDocument`	Multi-resource document containing multiple kinds	`v1`

Common Metadata Fields

All resources share common metadata fields:

metadata:
  name: "resource-name"          # Required: unique identifier
  labels:                       # Optional: key-value labels
    environment: "production"
    team: "platform"
  annotations:                  # Optional: extended metadata
    description: "Resource description"
    owner: "team@company.com"
  deletionPolicy: "Delete"      # Optional: Delete|Retain|Snapshot

Project Kind

apiVersion: v1
kind: Project
metadata:
  name: my-project
spec:
  name: "My Production Project"
  organizationId: "5e2211c17a3e5a48f5497de3"
  tags:
    environment: production
    cost-center: engineering
  # Resources can be embedded in project spec
  clusters: []
  databaseUsers: []
  networkAccess: []

Cluster Kind

apiVersion: v1
kind: Cluster
metadata:
  name: production-cluster
spec:
  projectName: "my-project"     # Reference to project
  provider: "AWS"               # AWS, GCP, or AZURE
  region: "us-east-1"
  instanceSize: "M30"
  diskSizeGB: 40
  
  # Backup Configuration
  backupEnabled: true           # Enable continuous cloud backup
  pitEnabled: true              # Enable Point-in-Time Recovery (requires backupEnabled: true)
  
  mongodbVersion: "7.0"
  clusterType: "REPLICASET"
  tags:
    purpose: "production-workload"

Backup Features

Continuous Backup

backupEnabled: true - Enables continuous cloud backup
Available for M10+ clusters
Provides automated snapshots and restore capabilities

Point-in-Time Recovery (PIT)

pitEnabled: true - Enables point-in-time recovery
Requires backupEnabled: true (validation enforced)
Allows recovery to any specific moment in time
Only available after cluster is created and backup is active

Cross-Region Backup

Achieved through multi-region cluster configuration
Use replicationSpecs with multiple regionConfigs
Provides geographic backup redundancy

Backup Validation Rules

The system enforces the following validation rules:

PIT requires backup: Setting pitEnabled: true without backupEnabled: true will fail validation
Free tier limitation: Backup is not available for M0 (free tier) clusters
Instance size requirement: Backup requires M10+ instance sizes

DatabaseUser Kind

apiVersion: v1
kind: DatabaseUser
metadata:
  name: app-user
spec:
  projectName: "my-project"
  username: "application-user"
  password: "secure-password"
  authDatabase: "admin"
  roles:
    - roleName: "readWrite"
      databaseName: "myapp"
    - roleName: "read"
      databaseName: "analytics"
  scopes:
    - name: "production-cluster"
      type: "CLUSTER"

NetworkAccess Kind

apiVersion: v1
kind: NetworkAccess
metadata:
  name: office-network
spec:
  projectName: "my-project"
  ipAddress: "203.0.113.0/24"   # CIDR notation supported
  comment: "Office network access"
  deleteAfterDate: "2024-12-31T23:59:59Z"  # Optional expiration

SearchIndex Kind

apiVersion: v1
kind: SearchIndex
metadata:
  name: products-search
spec:
  projectName: "my-project"
  clusterName: "production-cluster"
  databaseName: "ecommerce"
  collectionName: "products"
  indexName: "default"
  indexType: "search"           # "search" or "vectorSearch"
  definition:
    mappings:
      dynamic: true
      fields:
        title:
          type: "string"
          analyzer: "standard"

SearchMetrics Kind

apiVersion: matlas.mongodb.com/v1alpha1
kind: SearchMetrics
metadata:
  name: search-metrics
spec:
  projectName: "my-project"
  clusterName: "my-cluster"
  indexName: "products-search"      # Optional: omit for all indexes
  timeRange: "24h"                  # 1h, 6h, 24h, 7d, 30d
  metrics:                          # Optional: types of metrics
    - query
    - performance
    - usage

SearchOptimization Kind

apiVersion: matlas.mongodb.com/v1alpha1
kind: SearchOptimization
metadata:
  name: search-optimization
spec:
  projectName: "my-project"
  clusterName: "my-cluster"
  indexName: "products-search"      # Optional: omit for all indexes
  analyzeAll: true                  # Enable detailed analysis
  categories:                       # Optional: analysis categories
    - performance
    - mappings
    - analyzers
    - facets
    - synonyms

SearchQueryValidation Kind

apiVersion: matlas.mongodb.com/v1alpha1
kind: SearchQueryValidation
metadata:
  name: query-validation
spec:
  projectName: "my-project"
  clusterName: "my-cluster"
  indexName: "products-search"
  testMode: true                    # Enable detailed analysis
  query:                           # Search query to validate
    text:
      query: "wireless headphones"
      path: "title"
  validate:                        # Optional: validation types
    - syntax
    - fields
    - performance

AlertConfiguration Kind

apiVersion: v1
kind: AlertConfiguration
metadata:
  name: high-cpu-alert
spec:
  enabled: true
  eventTypeName: "HOST_CPU_USAGE_PERCENT"
  severityOverride: "HIGH"      # Optional: LOW, MEDIUM, HIGH, CRITICAL
  matchers:
    - fieldName: "HOSTNAME_AND_PORT"
      operator: "CONTAINS"       # EQUALS, NOT_EQUALS, CONTAINS, etc.
      value: "production"
  notifications:
    - typeName: "EMAIL"
      emailAddress: "alerts@company.com"
      delayMin: 0
      intervalMin: 15
    - typeName: "SLACK"
      apiToken: "${SLACK_TOKEN}"
      channelName: "#alerts"
  metricThreshold:
    metricName: "CPU_USAGE_PERCENT"
    operator: "GREATER_THAN"
    threshold: 80.0
    units: "PERCENT"
    mode: "AVERAGE"             # AVERAGE or TOTAL

Alert Kind (Read-Only)

apiVersion: v1
kind: Alert
metadata:
  name: alert-status
spec:
  projectName: "my-project"
  alertId: "507f1f77bcf86cd799439011"  # Optional: specific alert ID

VPCEndpoint Kind

apiVersion: v1
kind: VPCEndpoint
metadata:
  name: vpc-endpoint
spec:
  projectName: "my-project"
  cloudProvider: "AWS"          # AWS, AZURE, or GCP
  region: "us-east-1"
  endpointId: "vpce-1234567890abcdef0"  # Set after creation

ApplyDocument Kind

Multi-resource document for managing related resources together:

apiVersion: v1
kind: ApplyDocument
metadata:
  name: production-setup
resources:
  - apiVersion: v1
    kind: Cluster
    metadata:
      name: prod-cluster
    spec:
      # ... cluster configuration
  
  - apiVersion: v1
    kind: DatabaseUser
    metadata:
      name: app-user
    spec:
      # ... user configuration
      dependsOn:
        - prod-cluster

Validation Rules

Names: Must be lowercase, alphanumeric, with hyphens/underscores allowed
References: projectName fields must reference existing projects
Dependencies: Resources can specify dependsOn for ordering
Immutable Fields: Some fields cannot be changed after creation (varies by resource type)
Required Fields: Each kind has specific required fields documented above

Best Practices

Naming: Use descriptive, consistent naming conventions
Labels: Tag resources for organization and cost tracking
Dependencies: Use explicit dependsOn when order matters
Secrets: Never commit passwords or API keys to version control
Validation: Use matlas infra plan to validate before applying changes