|
| 1 | +# edp-codebase-operator |
| 2 | + |
| 3 | +Go module `github.com/epam/edp-codebase-operator/v2`. A kubebuilder operator (controller-runtime) that provisions and manages source-code entities. It is the **platform source of truth**: its CRDs are imported and watched by `edp-cd-pipeline-operator`, `edp-tekton`, `krci-portal`, and the CLI. |
| 4 | + |
| 5 | +CRD group `v2.edp.epam.com/v1`: `Codebase`, `CodebaseBranch`, `GitServer`, `JiraServer`, `JiraIssueMetadata`, `CDStageDeploy`, `CodebaseImageStream`, `QuickLink`. |
| 6 | +There is also an `api/v1alpha1` group for the `Template` type. |
| 7 | + |
| 8 | +## Build & Test |
| 9 | + |
| 10 | +```bash |
| 11 | +make build # compile → dist/manager-<arch> |
| 12 | +make test # unit tests (requires envtest binaries; downloads automatically) |
| 13 | +make lint # golangci-lint v2 |
| 14 | +make lint-fix # golangci-lint with auto-fix |
| 15 | +make fmt # go fmt ./... |
| 16 | +make vet # go vet ./... |
| 17 | + |
| 18 | +# Run a single test package |
| 19 | +KUBEBUILDER_ASSETS="$(./bin/setup-envtest use --bin-dir bin -p path)" \ |
| 20 | + KUBECONFIG=hack/kubecfg-stub.yaml \ |
| 21 | + go test ./controllers/codebase/... -run TestSomething -v |
| 22 | +``` |
| 23 | + |
| 24 | +Tests rely on `setup-envtest` (controller-runtime's envtest framework). `make test` handles downloading the binaries. The `hack/kubecfg-stub.yaml` is a stub kubeconfig required by the test suite. |
| 25 | + |
| 26 | +## Code Generation |
| 27 | + |
| 28 | +```bash |
| 29 | +make generate # DeepCopy methods (zz_generated.deepcopy.go) + CRD API docs |
| 30 | +make manifests # CRDs, RBAC, webhooks → deploy-templates/crds/ and config/crd/bases/ |
| 31 | +make mocks # mockery mocks (see .mockery.yaml for targets) |
| 32 | +make api-docs # regenerate docs/api.md from CRDs (crdoc) |
| 33 | +make helm-docs # regenerate deploy-templates/README.md (helm-docs) |
| 34 | +make validate-docs # CI check: fails if api.md or README.md are out of date |
| 35 | +``` |
| 36 | + |
| 37 | +**Never hand-edit:** |
| 38 | + |
| 39 | +- `api/v1/zz_generated.deepcopy.go` — regenerated by `make generate` |
| 40 | +- `api/v1alpha1/zz_generated.deepcopy.go` — same |
| 41 | +- `pkg/gitprovider/bitbucket/generated/bitbucket_client.generated.go` — oapi-codegen output; regenerate via `oapicfg.yaml` |
| 42 | +- `deploy-templates/crds/` and `config/crd/bases/` — regenerated by `make manifests` |
| 43 | +- `deploy-templates/README.md` and `docs/api.md` — regenerated by `make helm-docs` / `make api-docs` |
| 44 | +- `*_generated.mock.go` files — regenerated by `make mocks` |
| 45 | + |
| 46 | +## Architecture |
| 47 | + |
| 48 | +``` |
| 49 | +cmd/main.go |
| 50 | + └── registers all 8 controllers + admission webhooks with controller-runtime Manager |
| 51 | +
|
| 52 | +api/v1/ — CRD type definitions (spec, status, kubebuilder markers) |
| 53 | +api/v1alpha1/ — Template CRD |
| 54 | +
|
| 55 | +controllers/<resource>/ |
| 56 | + ├── <resource>_controller.go — Reconcile() entry point |
| 57 | + └── chain/ or service/chain/ — Sequential handler chain (chain-of-responsibility) |
| 58 | +
|
| 59 | +pkg/gitprovider/ — Per-provider adapters: github.go, gitlab.go, bitbucket.go |
| 60 | + Factory: NewProvider() dispatches on GitServer.Spec.GitProvider |
| 61 | +pkg/client/jira/ — Jira REST client (go-jira wrapper + mockable Client interface) |
| 62 | +pkg/gerrit/ — SSH-based Gerrit client |
| 63 | +pkg/git/ — go-git wrapper + factory (supports SSH/HTTPS auth) |
| 64 | +pkg/webhook/ — Admission webhooks: Codebase and CodebaseBranch validation |
| 65 | +pkg/objectmodifier/ — Applies default values / label patches before reconcile logic |
| 66 | +pkg/util/ — Shared helpers (workdir, timeouts, URL utilities, templates) |
| 67 | +pkg/tektoncd/ — Tekton TriggerTemplate manager (for CDStageDeploy) |
| 68 | +pkg/autodeploy/ — Auto-deploy logic for CDStageDeploy |
| 69 | +``` |
| 70 | + |
| 71 | +### Controller Map |
| 72 | + |
| 73 | +| Controller | CRD | Chain location | |
| 74 | +|---|---|---| |
| 75 | +| `codebase` | `Codebase` | `controllers/codebase/service/chain/` | |
| 76 | +| `codebasebranch` | `CodebaseBranch` | `controllers/codebasebranch/chain/` | |
| 77 | +| `codebaseimagestream` | `CodebaseImageStream` | `controllers/codebaseimagestream/chain/` | |
| 78 | +| `cdstagedeploy` | `CDStageDeploy` | `controllers/cdstagedeploy/chain/` | |
| 79 | +| `gitserver` | `GitServer` | `controllers/gitserver/` (flat, no sub-chain) | |
| 80 | +| `jiraserver` | `JiraServer` | `controllers/jiraserver/chain/` | |
| 81 | +| `jiraissuemetadata` | `JiraIssueMetadata` | `controllers/jiraissuemetadata/chain/` | |
| 82 | +| `integrationsecret` | `Secret` (native) | `controllers/integrationsecret/` | |
| 83 | + |
| 84 | +### Codebase reconcile chain (main creation path) |
| 85 | + |
| 86 | +`PutGitWebRepoUrl` → `PutProject` → `PutWebHook` → `PutGitLabCIConfig` → `PutDeployConfigs` → `PutDefaultCodeBaseBranch` → `Cleaner` |
| 87 | + |
| 88 | +Deletion runs a shorter chain: `DeleteWebHook` → `Cleaner`. |
| 89 | + |
| 90 | +### Multi-provider Git logic |
| 91 | + |
| 92 | +`pkg/gitprovider/NewProvider()` dispatches on `GitServer.Spec.GitProvider` (`gerrit`, `github`, `gitlab`, `bitbucket`). Gerrit uses SSH (`pkg/gerrit`); GitHub and GitLab use resty REST; Bitbucket uses an oapi-codegen client in `pkg/gitprovider/bitbucket/generated/`. When adding provider-specific behaviour, implement the `GitProvider` / `GitProjectProvider` / `GitWebHookProvider` interfaces and wire them into the factory. |
| 93 | + |
| 94 | +### Admission webhooks |
| 95 | + |
| 96 | +`pkg/webhook/` validates `Codebase` and `CodebaseBranch` on create/update. Disabled at runtime by setting `ENABLE_WEBHOOKS=false`. Webhook TLS cert paths are passed via CLI flags (`--webhook-cert-path`, etc.). |
| 97 | + |
| 98 | +### Environment variables |
| 99 | + |
| 100 | +- `WATCH_NAMESPACE` — namespace the operator watches (required) |
| 101 | +- `CODEBASE_BRANCH_MAX_CONCURRENT_RECONCILES` — concurrency for CodebaseBranch reconciler (default 1) |
| 102 | +- `ENABLE_WEBHOOKS` — set to `false` to disable admission webhooks |
| 103 | +- `TELEMETRY_ENABLED` / `TELEMETRY_DELAY` — opt-in usage telemetry |
| 104 | + |
| 105 | +### Adding a new chain handler |
| 106 | + |
| 107 | +1. Create `controllers/<resource>/chain/my_step.go` implementing the handler interface (`ServeRequest(ctx, cr) error`). |
| 108 | +2. Register it in `controllers/<resource>/chain/factory.go` (the `MakeChain` / `CreateChain` function) in the correct call order. |
| 109 | +3. Add a `_test.go` alongside it; tests use `envtest` + `testify` (not Ginkgo). |
| 110 | + |
| 111 | +## Conventions |
| 112 | + |
| 113 | +- Tests use `testify` (`require`, `assert`) and controller-runtime's `envtest`. Mocks are generated by mockery v3 (see `.mockery.yaml`). |
| 114 | +- `pkg/objectmodifier/CodebaseModifier` runs before any chain step, patching defaulted fields and labels so chain handlers see a normalised object. |
| 115 | +- Failure count backoff: on reconcile error, `setFailureCount` increments `Status.FailureCount` and returns a `RequeueAfter` timeout calculated by `pkg/util.GetTimeout`. |
| 116 | +- `CodebaseBranch.Status.FailureCount` similarly gates requeue delay. |
| 117 | +- Deploy-templates Helm chart `README.md` is auto-generated by helm-docs from `values.yaml` annotations — do not edit manually. |
0 commit comments