Skip to content

Commit 90c6f32

Browse files
tip-dtellertip-dteller
committed
examples: add comprehensive examples based on test scripts and enhance README
- Add discovery-basic.yaml: Basic discovered project converted to ApplyDocument format - Add discovery-with-databases.yaml: Comprehensive discovery including database-level resources - Add cluster-comprehensive.yaml: Production-ready cluster with autoscaling, multi-region, security features - Add custom-roles-comprehensive.yaml: Advanced custom roles with granular collection-level permissions - Add database-operations-authentication.yaml: Examples demonstrating three authentication methods - Add user-password-management.yaml: Comprehensive user management with password display features - Add safe-operations-preserve-existing.yaml: Demonstrates safe operations using --preserve-existing flag - Update examples/README.md with comprehensive documentation - Organize examples by category (Discovery, Cluster, User Management, etc.) - Add complete usage examples for all three authentication methods - Document new database creation requirements (--collection parameter) - Include environment variable setup and implementation notes - Add discovery workflows and infrastructure operation examples These examples accurately reflect the functionality demonstrated in the test scripts and provide practical templates for users to implement infrastructure-as-code workflows.
1 parent 7bd2a13 commit 90c6f32

8 files changed

Lines changed: 1016 additions & 21 deletions

‎examples/README.md‎

Lines changed: 142 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,163 @@
11
# Examples
22

3-
Working YAML examples for `ApplyDocument` resources used by `matlas infra`.
4-
5-
## Files
6-
7-
- `users-basic.yaml`: Single `DatabaseUser` with a basic read role on `admin`.
8-
- `users-standalone-multiple.yaml`: Two standalone users with different roles and labels.
9-
- `overlay-network-and-user.yaml`: Adds a user and a `NetworkAccess` IP entry (overlay style).
10-
- `custom-roles-and-users.yaml`: Defines a `DatabaseRole` and a user that uses it.
11-
- `cluster-basic.yaml`: Minimal `Cluster` definition.
12-
- `cluster-advanced.yaml`: Cluster with autoscaling and replication spec.
13-
- `project-with-cluster-and-users.yaml`: Cluster plus an app user in one document.
14-
- `custom-roles-example.yaml`: Comprehensive custom roles example including users.
15-
- `users-scoped.yaml`: Users scoped to specific clusters via `scopes`.
16-
- `network-variants.yaml`: `NetworkAccess` examples for `cidr`, `ipAddress` with `deleteAfterDate`, and `awsSecurityGroup`.
17-
- `dependencies-and-deletion.yaml`: Demonstrates `dependsOn` and `deletionPolicy` between resources.
18-
- `cluster-multiregion.yaml`: Multi-region cluster using `replicationSpecs` and `regionConfigs`.
19-
- `cluster-security-and-tags.yaml`: Cluster with `encryption`, `biConnector`, and `tags`.
20-
- `project-format.yaml`: Project-format configuration consumable by infra commands.
3+
Working YAML examples for `ApplyDocument` resources used by `matlas infra` and comprehensive demonstrations of CLI functionality.
4+
5+
## Discovery Examples
6+
7+
- **`discovery-basic.yaml`**: Basic discovered project converted to ApplyDocument format with cluster, user, and network access
8+
- **`discovery-with-databases.yaml`**: Comprehensive discovery including database-level resources (databases, collections, indexes, custom roles)
9+
10+
## Cluster Examples
11+
12+
- **`cluster-basic.yaml`**: Minimal cluster definition for development environments
13+
- **`cluster-advanced.yaml`**: Cluster with autoscaling and replication specifications
14+
- **`cluster-comprehensive.yaml`**: Production-ready cluster with autoscaling, multi-region, security features, and proper tagging
15+
- **`cluster-multiregion.yaml`**: Multi-region cluster using `replicationSpecs` and `regionConfigs`
16+
- **`cluster-security-and-tags.yaml`**: Cluster with encryption, BI Connector, and comprehensive tags
17+
18+
## User Management Examples
19+
20+
- **`users-basic.yaml`**: Single DatabaseUser with basic read role
21+
- **`users-standalone-multiple.yaml`**: Multiple users with different roles and labels
22+
- **`users-scoped.yaml`**: Users scoped to specific clusters via `scopes`
23+
- **`user-password-management.yaml`**: Comprehensive user management demonstrating password display features and different user types
24+
- **`users-with-password-display.yaml`**: Users configured for password display during creation
25+
26+
## Authentication and Database Operations
27+
28+
- **`database-operations-authentication.yaml`**: Examples demonstrating the three authentication methods for database operations
29+
- **`atlas-vs-database-users-roles.yaml`**: Comparison between Atlas-managed and database-level users
30+
31+
## Custom Roles Examples
32+
33+
- **`custom-roles-and-users.yaml`**: Basic custom role definition with associated user
34+
- **`custom-roles-example.yaml`**: Comprehensive custom roles example
35+
- **`custom-roles-comprehensive.yaml`**: Advanced custom roles with granular collection-level permissions
36+
37+
## Network Access Examples
38+
39+
- **`network-access.yaml`**: Basic network access configuration
40+
- **`network-variants.yaml`**: Multiple NetworkAccess types (CIDR, IP with expiration, AWS security groups)
41+
- **`overlay-network-and-user.yaml`**: Overlay-style addition of user and network access
42+
43+
## Infrastructure Management
44+
45+
- **`project-format.yaml`**: Project-format configuration for infrastructure commands
46+
- **`project-with-cluster-and-users.yaml`**: Complete project with cluster and users in one document
47+
- **`safe-operations-preserve-existing.yaml`**: Demonstrates safe operations using `--preserve-existing` flag
48+
- **`dependencies-and-deletion.yaml`**: Resource dependencies and deletion policies
2149

2250
## Usage
2351

52+
### Environment Variables
53+
2454
Replace placeholders like "My Project" and provide environment variables for passwords before running:
2555

2656
```bash
57+
# Basic user passwords
2758
export APP_USER_PASSWORD='StrongPass123!'
2859
export APP_WRITER_PASSWORD='StrongPass123!'
2960
export ANALYTICS_PASSWORD='StrongPass123!'
3061
export OVERLAY_USER_PASSWORD='StrongPass123!'
3162
export ROLE_USER_PASSWORD='StrongPass123!'
63+
64+
# Advanced user passwords for comprehensive examples
65+
export SERVICE_ACCOUNT_PASSWORD='ServicePass123!'
66+
export DATABASE_ADMIN_PASSWORD='AdminPass123!'
67+
export CLUSTER_USER_PASSWORD='ClusterPass123!'
68+
export ECOMMERCE_APP_PASSWORD='EcommercePass123!'
69+
export DATABASE_MANAGER_PASSWORD='ManagerPass123!'
70+
71+
# Database operations passwords
72+
export DB_OPERATIONS_PASSWORD='DbOpsPass123!'
73+
export SAFE_TEST_PASSWORD='SafeTestPass123!'
74+
```
75+
76+
### Discovery Workflows
77+
78+
```bash
79+
# Discover existing project
80+
matlas discover --project-id <project-id> --output-file discovered.yaml
81+
82+
# Discover with database resources
83+
matlas discover \
84+
--project-id <project-id> \
85+
--include-databases \
86+
--use-temp-user \
87+
--convert-to-apply \
88+
--output-file complete-discovery.yaml
89+
90+
# Filter discovery by resource type
91+
matlas discover --project-id <project-id> --include clusters,users --output-file filtered.yaml
3292
```
3393

34-
Validate/diff/apply:
94+
### Infrastructure Operations
3595

3696
```bash
97+
# Validate configurations
3798
matlas infra validate -f examples/users-basic.yaml
38-
matlas infra diff -f examples/custom-roles-and-users.yaml
39-
matlas infra apply -f examples/overlay-network-and-user.yaml --auto-approve
99+
matlas infra validate -f examples/cluster-comprehensive.yaml
100+
101+
# Preview changes
102+
matlas infra diff -f examples/custom-roles-comprehensive.yaml --detailed
103+
matlas infra plan -f examples/discovery-basic.yaml --output table
104+
105+
# Apply changes safely
106+
matlas infra apply -f examples/safe-operations-preserve-existing.yaml --preserve-existing --auto-approve
107+
matlas infra apply -f examples/overlay-network-and-user.yaml --dry-run --dry-run-mode thorough
40108
```
41109

110+
### Database Operations with New Authentication
111+
112+
```bash
113+
# Create database with temporary user (recommended)
114+
matlas database create inventory \
115+
--cluster my-cluster \
116+
--project-id <project-id> \
117+
--collection products \
118+
--use-temp-user
119+
120+
# Create database with manual credentials
121+
matlas database create inventory \
122+
--cluster my-cluster \
123+
--project-id <project-id> \
124+
--collection products \
125+
--username dbuser \
126+
--password dbpass
127+
128+
# Create database with direct connection
129+
matlas database create inventory \
130+
--connection-string "mongodb+srv://user:pass@cluster/" \
131+
--collection products
132+
```
133+
134+
### User Management with Password Display
135+
136+
```bash
137+
# Create user and display password
138+
matlas atlas users create \
139+
--project-id <project-id> \
140+
--username myuser \
141+
--roles "readWrite@myapp" \
142+
--show-password
143+
144+
# Create database user with custom role
145+
matlas database users create appuser \
146+
--cluster my-cluster \
147+
--project-id <project-id> \
148+
--database myapp \
149+
--use-temp-user \
150+
--password "SecurePass123!" \
151+
--roles "customRole@myapp" \
152+
--show-password
153+
```
154+
155+
## Implementation Notes
156+
157+
- **Database Creation**: All database creation now requires `--collection` parameter for immediate visibility
158+
- **Authentication Methods**: Choose one of three methods: `--use-temp-user`, `--username/--password`, or `--connection-string`
159+
- **Safety Features**: Use `--preserve-existing` flag to protect existing resources during apply operations
160+
- **Discovery**: Include `--include-databases` for comprehensive resource enumeration
161+
- **Custom Roles**: Use `matlas database roles create` commands for role implementation
162+
42163
These examples mirror structures used in the test scripts under `scripts/test/` and adhere to the types in `internal/types/`.

‎examples/cluster-comprehensive.yaml‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Comprehensive Cluster Configuration Example
2+
# This example shows advanced cluster configuration with autoscaling, backup, and security features
3+
4+
apiVersion: matlas.mongodb.com/v1
5+
kind: ApplyDocument
6+
metadata:
7+
name: cluster-comprehensive
8+
labels:
9+
environment: production
10+
tier: advanced
11+
purpose: example
12+
annotations:
13+
description: "Comprehensive cluster configuration with advanced features"
14+
cost-warning: "This configuration may incur significant costs"
15+
resources:
16+
# Production cluster with autoscaling and advanced features
17+
- apiVersion: matlas.mongodb.com/v1
18+
kind: Cluster
19+
metadata:
20+
name: prod-cluster-advanced
21+
labels:
22+
environment: production
23+
tier: advanced
24+
backup: enabled
25+
encryption: enabled
26+
spec:
27+
projectName: "Production Project"
28+
provider: AWS
29+
region: US_EAST_1
30+
instanceSize: M40
31+
clusterType: REPLICASET
32+
tierType: REPLICASET
33+
mongodbVersion: "7.0"
34+
35+
# Storage configuration
36+
diskSizeGB: 80
37+
38+
# Backup configuration
39+
backupEnabled: true
40+
pitEnabled: true
41+
42+
# Autoscaling configuration
43+
autoscaling:
44+
diskGBEnabled: true
45+
computeEnabled: true
46+
computeScaleDownEnabled: true
47+
computeMinInstanceSize: M40
48+
computeMaxInstanceSize: M80
49+
50+
# Security features
51+
encryptionAtRestProvider: AWS
52+
53+
# BI Connector
54+
biConnector:
55+
enabled: true
56+
readPreference: secondary
57+
58+
# Tags for resource management
59+
tags:
60+
- key: Environment
61+
value: Production
62+
- key: Application
63+
value: MainApp
64+
- key: CostCenter
65+
value: Engineering
66+
- key: Owner
67+
value: Platform Team
68+
69+
# Multi-region cluster for high availability
70+
- apiVersion: matlas.mongodb.com/v1
71+
kind: Cluster
72+
metadata:
73+
name: global-cluster
74+
labels:
75+
environment: production
76+
type: global
77+
regions: multi
78+
spec:
79+
projectName: "Production Project"
80+
provider: AWS
81+
clusterType: REPLICASET
82+
mongodbVersion: "7.0"
83+
backupEnabled: true
84+
85+
# Multi-region replication specifications
86+
replicationSpecs:
87+
- numShards: 1
88+
regionConfigs:
89+
- electableNodes: 3
90+
priority: 7
91+
readOnlyNodes: 0
92+
analyticsNodes: 0
93+
providerName: AWS
94+
regionName: US_EAST_1
95+
instanceSize: M30
96+
- electableNodes: 2
97+
priority: 6
98+
readOnlyNodes: 0
99+
analyticsNodes: 0
100+
providerName: AWS
101+
regionName: US_WEST_2
102+
instanceSize: M30
103+
- electableNodes: 2
104+
priority: 5
105+
readOnlyNodes: 1
106+
analyticsNodes: 0
107+
providerName: AWS
108+
regionName: EU_WEST_1
109+
instanceSize: M30
110+
111+
# Development cluster with minimal configuration
112+
- apiVersion: matlas.mongodb.com/v1
113+
kind: Cluster
114+
metadata:
115+
name: dev-cluster
116+
labels:
117+
environment: development
118+
tier: basic
119+
cost-optimized: "true"
120+
spec:
121+
projectName: "Production Project"
122+
provider: AWS
123+
region: US_EAST_1
124+
instanceSize: M10
125+
clusterType: REPLICASET
126+
tierType: REPLICASET
127+
mongodbVersion: "7.0"
128+
diskSizeGB: 10
129+
backupEnabled: false
130+
131+
tags:
132+
- key: Environment
133+
value: Development
134+
- key: AutoShutdown
135+
value: "true"
136+
137+
# Network access for clusters
138+
- apiVersion: matlas.mongodb.com/v1
139+
kind: NetworkAccess
140+
metadata:
141+
name: production-vpc
142+
labels:
143+
environment: production
144+
type: aws-sg
145+
spec:
146+
projectName: "Production Project"
147+
awsSecurityGroup: "sg-1234567890abcdef0"
148+
comment: "Production VPC security group access"
149+
150+
- apiVersion: matlas.mongodb.com/v1
151+
kind: NetworkAccess
152+
metadata:
153+
name: development-access
154+
labels:
155+
environment: development
156+
type: cidr
157+
spec:
158+
projectName: "Production Project"
159+
cidrBlock: "10.0.0.0/16"
160+
comment: "Development environment access"
161+
162+
# Administrative users for cluster management
163+
- apiVersion: matlas.mongodb.com/v1
164+
kind: DatabaseUser
165+
metadata:
166+
name: cluster-admin
167+
labels:
168+
purpose: administration
169+
scope: all-clusters
170+
spec:
171+
projectName: "Production Project"
172+
username: cluster-admin
173+
authDatabase: admin
174+
password: "${CLUSTER_ADMIN_PASSWORD}"
175+
roles:
176+
- roleName: atlasAdmin
177+
databaseName: admin
178+
179+
- apiVersion: matlas.mongodb.com/v1
180+
kind: DatabaseUser
181+
metadata:
182+
name: backup-user
183+
labels:
184+
purpose: backup
185+
scope: readonly
186+
spec:
187+
projectName: "Production Project"
188+
username: backup-user
189+
authDatabase: admin
190+
password: "${BACKUP_USER_PASSWORD}"
191+
roles:
192+
- roleName: backup
193+
databaseName: admin
194+
- roleName: clusterMonitor
195+
databaseName: admin

0 commit comments

Comments
 (0)