|
| 1 | +# Overview |
| 2 | + |
| 3 | +This repo contains networking components and controllers for the Fleet project. It is primarily written in Go and leverages Kubernetes client-go and controller-runtime libraries. The repository is organized as a monorepo, with packages grouped by functionality. |
| 4 | + |
| 5 | +## General Rules |
| 6 | + |
| 7 | +- Use @terminal when answering questions about Git. |
| 8 | +- If you're waiting for my confirmation ("OK"), proceed without further prompting. |
| 9 | +- Follow the [Go Style Guide](https://go.dev/wiki/Style) and [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md) if possible. If there are any conflicts, follow the Go Style Guide. |
| 10 | +- Favor using the standard library over third-party libraries. |
| 11 | +- Run goimports on save. |
| 12 | +- Run golint and go vet to check for errors. |
| 13 | +- Use go mod tidy if the dependencies are changed. |
| 14 | + |
| 15 | +## Terminology |
| 16 | + |
| 17 | +- **Fleet**: A collection of Kubernetes clusters managed as a unit. |
| 18 | +- **Networking Controller**: A controller responsible for managing network resources across clusters. |
| 19 | +- **Hub cluster**: An Kubernetes cluster that hosts the control plane of the fleet. |
| 20 | +- **Member cluster**: A Kubernetes cluster that is part of the fleet. |
| 21 | +- **Fleet-system Namespace**: A reserved namespace in all clusters for running Fleet networking controllers and putting internal resources. |
| 22 | +- **Reserved member cluster namespace in the hub cluster**: A reserved namespace in the hub cluster where a member cluster can access to communicate with the hub cluster. |
| 23 | + |
| 24 | +## Repository directory structure |
| 25 | + |
| 26 | +- `api/` - Contains Golang structs for CRDs. |
| 27 | +- `charts/` - Helm charts for deploying networking components. |
| 28 | + - `charts/hub-net-controller-manager/` - Helm chart for the fleet hub networking components. |
| 29 | + - `charts/mcs-controller-manager/` - Helm chart for the fleet member networking component which provides the L4 load balancing functionality. |
| 30 | + - `charts/member-net-controller-manager/` - Helm chart for the fleet member networking components. |
| 31 | +- `cmd/` - Entry points for networking controllers and agents. |
| 32 | + - `cmd/hub-net-controller-manager/` - Main entry point for the hub networking components. |
| 33 | + - `cmd/mcs-controller-manager/` - Main entry point for the member networking component which provides the L4 load balancing functionality. |
| 34 | + - `cmd/member-net-controller-manager/` - Main entry point for the member networking components. |
| 35 | +- `config/` - CRD manifests and configuration files built from the CRD definitions in the `api/` folder. |
| 36 | + - `config/crd/bases` - CRD definitions for the networking features. |
| 37 | +- `docker/` - Dockerfiles for building images for networking components. |
| 38 | +- `examples/` - Example YAMLs for CRDs and networking resources. |
| 39 | +- `hack/` - Scripts and tools for development. |
| 40 | +- `pkg/` - Libraries and core logic for networking controllers. |
| 41 | + - `pkg/common/` - Common libraries shared between networking controllers. |
| 42 | + - `pkg/controllers/` - Core networking controllers. |
| 43 | + - `pkg/controllers/hub/` - Hub networking controller logic. |
| 44 | + - `pkg/controllers/member/` - Member networking controller logic. |
| 45 | + - `pkg/controllers/mcs/` - MCS networking controller logic. |
| 46 | +- `test/` - Integration, and e2e tests. |
| 47 | + - `test/apis/` - The tests for the CRD definitions. |
| 48 | + - `test/common/` - Common test utilities and helpers. |
| 49 | + - `test/e2e/` - End-to-end tests for networking components. |
| 50 | + - `test/perftest/` - Performance tests for networking components. |
| 51 | + - `test/scripts/` - Scripts to setup and clean the e2e test environments. |
| 52 | +- `tools/` - Client-side tools for managing networking resources. |
| 53 | +- `Makefile` - Build and test automation. |
| 54 | +- `go.mod` / `go.sum` - Dependency management. |
| 55 | + |
| 56 | +## Testing Rules |
| 57 | + |
| 58 | +- Unit test files should be named `<go_file>_test.go` and be in the same directory. |
| 59 | +- Use table-driven tests for unit tests. |
| 60 | +- Run `go test -v ./...` to execute all tests. |
| 61 | +- Run tests for modified packages and verify they pass. |
| 62 | +- Share analysis for failing tests and propose fixes. |
| 63 | +- Integration test files should be named `<go_file>_integration_test.go` and placed in the same or `test` directory. |
| 64 | +- Integration and e2e tests are written in Ginkgo style. |
| 65 | +- E2E tests are under `test/e2e` and run with `make e2e-tests`. |
| 66 | +- Clean up e2e tests with `make e2e-cleanup`. |
| 67 | +- When adding tests, reuse existing setup and contexts where possible. |
| 68 | +- Only add imports if absolutely needed. |
| 69 | + |
| 70 | +## Domain Knowledge |
| 71 | + |
| 72 | +Use the files in the `docs/**` and `.github/.copilot/domain_knowledge/**/*` as a source of truth when it comes to domain knowledge. These files provide context in which the current solution operates. This folder contains information like entity relationships, workflows, and ubiquitous language. As the understanding of the domain grows, take the opportunity to update these files as needed. |
| 73 | + |
| 74 | +## Specification Files |
| 75 | + |
| 76 | +Use specifications from the `.github/.copilot/specifications` folder. Each folder under `specifications` groups similar specifications together. Always ask the user which specifications best apply for the current conversation context if you're not sure. |
| 77 | + |
| 78 | +Use the `.github/.copilot/specifications/.template.md` file as a template for specification structure. |
| 79 | + |
| 80 | + examples: |
| 81 | + ```text |
| 82 | + ├── application_architecture |
| 83 | + │ └── main.spec.md |
| 84 | + | └── specific-feature.spec.md |
| 85 | + ├── database |
| 86 | + │ └── main.spec.md |
| 87 | + ├── observability |
| 88 | + │ └── main.spec.md |
| 89 | + └── testing |
| 90 | + └── main.spec.md |
| 91 | + ``` |
| 92 | + |
| 93 | +## Breadcrumb Protocol |
| 94 | + |
| 95 | +A breadcrumb is a collaborative scratch pad that allow the user and agent to get alignment on context. When working on tasks in this repository, follow this collaborative documentation workflow to create a clear trail of decisions and implementations: |
| 96 | + |
| 97 | +1. At the start of each new task, ask me for a breadcrumb file name if you can't determine a suitable one. |
| 98 | + |
| 99 | +2. Create the breadcrumb file in the `${REPO}/.github/.copilot/breadcrumbs` folder using the format: `yyyy-mm-dd-HHMM-{title}.md` (*year-month-date-current_time_in-24hr_format-{title}.md* using UTC timezone) |
| 100 | + |
| 101 | +3. Structure the breadcrumb file with these required sections: |
| 102 | + - **Requirements**: Clear list of what needs to be implemented. |
| 103 | + - **Additional comments from user**: Any additional input from the user during the conversation. |
| 104 | + - **Plan**: Strategy and technical plan before implementation. |
| 105 | + - **Decisions**: Why specific implementation choices were made. |
| 106 | + - **Implementation Details**: Code snippets with explanations for key files. |
| 107 | + - **Changes Made**: Summary of files modified and how they changed. |
| 108 | + - **Before/After Comparison**: Highlighting the improvements. |
| 109 | + - **References**: List of referred material like domain knowledge files, specification files, URLs and summary of what is was used for. If there is a version in the domain knowledge or in the specifications, record the version in the breadcrumb. |
| 110 | + |
| 111 | +4. Workflow rules: |
| 112 | + - Update the breadcrumb **BEFORE** making any code changes. |
| 113 | + - **Get explicit approval** on the plan before implementation. |
| 114 | + - Update the breadcrumb **AFTER completing each significant change**. |
| 115 | + - Keep the breadcrumb as our single source of truth as it contains the most recent information. |
| 116 | + |
| 117 | +5. Ask me to verify the plan with: "Are you happy with this implementation plan?" before proceeding with code changes. |
| 118 | + |
| 119 | +6. Reference related breadcrumbs when a task builds on previous work. |
| 120 | + |
| 121 | +7. Before concluding, ensure the breadcrumb file properly documents the entire process, including any course corrections or challenges encountered. |
| 122 | + |
| 123 | +This practice creates a trail of decision points that document our thought process while building features in this solution, making pull request review for the current change easier to follow as well. |
| 124 | + |
| 125 | +### Plan Structure Guidelines |
| 126 | +- When creating a plan, organize it into numbered phases (e.g., "Phase 1: Setup Dependencies"). |
| 127 | +- Break down each phase into specific tasks with numeric identifiers (e.g., "Task 1.1: Add Dependencies"). |
| 128 | +- Include a detailed checklist at the end of the document that maps to all phases and tasks. |
| 129 | +- Plan should always lookup related information from `domain_knowledge` folder and any applicable specification files. |
| 130 | +- Mark tasks as `- [ ]` for pending tasks and `- [x]` for completed tasks. |
| 131 | +- Start all planning tasks as unchecked, and update them to checked as implementation proceeds. |
| 132 | +- Each planning task should have clear success criteria. |
| 133 | +- End the plan with success criteria that define when the implementation is complete. |
| 134 | +- Plans should start with writing Unit Tests first when possible, so we can use those to guide our implementation. Same for UI tests when it makes sense. |
| 135 | +- If the domain knowledge has changed, update the related files in the `domain_knowledge` folder. |
| 136 | +- If specifications have changed, update the related files in the `specifications` folder. |
| 137 | + |
| 138 | +### Following Plans |
| 139 | +- When coding you need to follow the plan phases and check off the tasks as they are completed. |
| 140 | +- As you complete a task, update the plan and mark that task complete before you begin the next task. |
| 141 | +- Tasks that involved tests should not be marked complete until the tests pass. |
| 142 | + |
| 143 | +### Example Usage |
| 144 | + |
| 145 | +**User**: I need to implement JWT authentication for our Express API. |
| 146 | + |
| 147 | +**Agent**: I'll help with implementing JWT authentication for your Express API. Let me create a breadcrumb file to track our implementation. What would you like to name this breadcrumb? |
| 148 | + |
| 149 | +**User**: Use "jwt-auth-implementation" |
| 150 | + |
| 151 | +**Agent**: I've created the breadcrumb file `2025-04-08-1430-jwt-auth-implementation.md`. Are you happy with this implementation plan? |
| 152 | + |
| 153 | +[high level plan with tasks here] |
| 154 | + |
| 155 | +**User**: Looks good, but let's use 30-minute expiration for tokens. |
| 156 | + |
| 157 | +**Agent**: I've updated the breadcrumb with your specification: Are you happy with this implementation plan? |
| 158 | + |
| 159 | +[high level plan with tasks here] |
| 160 | + |
| 161 | +**User**: Yes, please proceed. |
| 162 | + |
| 163 | +**Agent**: I'll implement the JWT authentication now. Let me start by installing the necessary packages and creating the authentication middleware. I've updated the breadcrumb with implementation details. Is there anything specific you'd like me to modify or explain about the implementation? |
| 164 | + |
| 165 | +**User**: This looks good. |
| 166 | + |
| 167 | +**Agent**: I've updated the breadcrumb with the latest understanding. |
0 commit comments