|
| 1 | +# Pulumi mongodbatlas Provider |
| 2 | + |
| 3 | +The Pulumi mongodbatlas provider is a Go-based Pulumi resource provider that bridges the Terraform provider to Pulumi. It generates SDKs for TypeScript/JavaScript, Python, .NET, Go, and Java. The provider uses the Terraform provider as an upstream source via git submodules. |
| 4 | + |
| 5 | +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. |
| 6 | + |
| 7 | +## Working Effectively |
| 8 | + |
| 9 | +### Prerequisites and Environment Setup |
| 10 | +- All required dependencies are automatically installed via the `.github/workflows/copilot-setup-steps.yml` workflow |
| 11 | +- This includes Go, Node.js, Python, .NET, Gradle, and all necessary Pulumi tools |
| 12 | + |
| 13 | +### Initial Repository Setup |
| 14 | +- Initialize the upstream submodule: `make upstream` |
| 15 | + |
| 16 | +### Build Process |
| 17 | +- **ALWAYS use `make` targets** - Never run custom commands unless explicitly told to |
| 18 | +- **NEVER work directly in the `sdk/` folder** - All SDK generation and building is automated through `make` |
| 19 | +- If a `make` target fails, there is something wrong with the environment setup, not the target itself |
| 20 | + |
| 21 | +### Available Make Targets |
| 22 | + |
| 23 | +#### Primary Build Targets: |
| 24 | +- `make build` -- Build the provider and all SDKs |
| 25 | +- `make provider` -- Build the provider binary |
| 26 | +- `make schema` -- Generate the provider schema |
| 27 | +- `make tfgen` -- Generate SDKs from schema |
| 28 | +- `make upstream` -- Initialize upstream submodule |
| 29 | + |
| 30 | +#### SDK Targets: |
| 31 | +- `make build_sdks` -- Build all SDK packages |
| 32 | +- `make generate_sdks` -- Generate all SDK source code |
| 33 | +- `make build_nodejs` -- Build TypeScript/Node.js SDK |
| 34 | +- `make build_python` -- Build Python SDK |
| 35 | +- `make build_dotnet` -- Build .NET SDK |
| 36 | +- `make build_go` -- Build Go SDK |
| 37 | +- `make build_java` -- Build Java SDK |
| 38 | + |
| 39 | +#### Development Targets: |
| 40 | +- `make lint_provider` -- Lint provider Go code |
| 41 | +- `make test_provider` -- Run provider unit tests |
| 42 | + |
| 43 | +### Build Guidelines: |
| 44 | +- **NEVER CANCEL** any build command once started - builds may take several minutes |
| 45 | +- Set timeouts to 300+ seconds for build operations |
| 46 | +- **DO NOT run tests in `examples/`** - They require cloud credentials and will run in PR workflows |
| 47 | + |
| 48 | +## Repository Structure |
| 49 | + |
| 50 | +### Key Directories: |
| 51 | +- `provider/` -- Go provider implementation |
| 52 | +- `sdk/` -- Generated SDKs for all languages |
| 53 | +- `upstream/` -- Git submodule with the Terraform provider |
| 54 | +- `scripts/` -- Build and utility scripts |
| 55 | +- `examples/` -- Example Pulumi programs (test framework available but skipped) |
| 56 | + |
| 57 | +### Important Files: |
| 58 | +- `Makefile` -- Primary build orchestration with all available targets |
| 59 | +- `provider/go.mod` -- Provider dependencies |
| 60 | +- `.github/workflows/copilot-setup-steps.yml` -- Environment setup for AI coding agents |
| 61 | +- `.github/workflows/` -- CI/CD pipelines |
| 62 | + |
| 63 | +## Development Workflow |
| 64 | + |
| 65 | +### Making Code Changes: |
| 66 | +1. Initialize repository: `make upstream` |
| 67 | +2. Make changes to provider code in `provider/` |
| 68 | +3. Validate with: `make lint_provider` |
| 69 | +4. Test with: `make test_provider` |
| 70 | +5. Build provider: `make provider` |
| 71 | +6. Generate and build SDKs: `make build_sdks` |
| 72 | + |
| 73 | +### Validation Steps: |
| 74 | +- Always use `make lint_provider` to lint provider code |
| 75 | +- Use `make test_provider` to run provider unit tests |
| 76 | +- Use `make build` to validate the full build process |
| 77 | + |
| 78 | +### Working with SDKs: |
| 79 | +- **NEVER work directly in `sdk/` folders** - All SDK operations are automated via `make` targets |
| 80 | +- All SDKs are generated and built through `make` commands |
| 81 | +- TypeScript SDK: Use `make build_nodejs` |
| 82 | +- Python SDK: Use `make build_python` |
| 83 | +- .NET SDK: Use `make build_dotnet` |
| 84 | +- Go SDK: Use `make build_go` |
| 85 | +- Java SDK: Use `make build_java` |
| 86 | + |
| 87 | +## Validation Scenarios |
| 88 | + |
| 89 | +### Code Quality Validation: |
| 90 | +- Use `make lint_provider` to lint provider Go code |
| 91 | +- Use `make test_provider` to run provider unit tests |
| 92 | +- Use `make build` to validate full build process |
| 93 | + |
| 94 | +### Manual Code Review: |
| 95 | +- Check Go code follows standard patterns |
| 96 | +- Validate resource definitions in `provider/resources.go` |
| 97 | +- Ensure imports and dependencies are correct |
| 98 | + |
| 99 | +## Common Tasks Reference |
| 100 | + |
| 101 | +### Repository Root Contents: |
| 102 | +``` |
| 103 | +.ci-mgmt.yaml -- CI management configuration |
| 104 | +.devcontainer/ -- Dev container setup |
| 105 | +.github/ -- GitHub workflows and templates |
| 106 | +.gitmodules -- Git submodule configuration |
| 107 | +.golangci.yml -- Go linter configuration |
| 108 | +.mise.toml -- Mise tool configuration |
| 109 | +CONTRIBUTING.md -- Contribution guidelines |
| 110 | +Makefile -- Build orchestration with all available targets |
| 111 | +README.md -- Project documentation |
| 112 | +devbox.json -- Development environment |
| 113 | +provider/ -- Go provider implementation |
| 114 | +scripts/ -- Build utilities |
| 115 | +sdk/ -- Generated SDKs (managed via make targets) |
| 116 | +upstream/ -- Terraform provider submodule |
| 117 | +``` |
| 118 | + |
| 119 | +### Common File Operations: |
| 120 | +- **Provider source**: `provider/resources.go` -- Resource definitions |
| 121 | +- **Provider tests**: `provider/resources_test.go` -- Unit tests |
| 122 | +- **Generated SDKs**: All in `sdk/` directory, managed via `make` targets only |
| 123 | + |
| 124 | +### Common Development Tasks: |
| 125 | +- Run provider tests: `make test_provider` |
| 126 | +- Build provider: `make provider` |
| 127 | +- Generate schema: `make schema` |
| 128 | +- Build all SDKs: `make build_sdks` |
| 129 | + |
| 130 | +## Build Expectations |
| 131 | + |
| 132 | +- Provider builds: 1-3 minutes depending on system |
| 133 | +- SDK generation: 2-5 minutes for all SDKs |
| 134 | +- Individual SDK builds: 30 seconds to 2 minutes each |
| 135 | +- Full build (`make build`): 5-10 minutes total |
| 136 | + |
| 137 | +Set timeouts of 300+ seconds for build operations and NEVER CANCEL running builds. |
| 138 | + |
| 139 | +## Critical Reminders |
| 140 | + |
| 141 | +- **ALWAYS** use `make` targets - never run custom commands unless explicitly instructed |
| 142 | +- **NEVER** work directly in `sdk/` folders - use `make` targets for all SDK operations |
| 143 | +- **DO NOT** run tests in `examples/` - they require cloud credentials |
| 144 | +- **FOCUS** on `make` targets for all development, building, and validation tasks |
0 commit comments