Skip to content

Solution Arsenal (SolAr) Developer Guide

This guide provides technical information for developers contributing to the Solution Arsenal (SolAr) project. It covers the development workflow, build system, code organization, and common development tasks. For detailed information about specific topics, see the referenced sections.

Development Environment Architecture

The SolAr project uses a declarative, reproducible development environment based on Nix. This approach ensures that all developers work with identical tool versions and configurations, eliminating "works on my machine" issues.

graph TB
    subgraph "Developer Machine"
        Shell["Developer Shell"]
        Direnv["direnv<br/>Automatic Environment Loader"]

        subgraph "Nix Environment"
            NixStore["Nix Store<br/>/nix/store/*"]
            Go["Golang"]
            Make["GNU Make"]
            Lint["golangci-lint"]
            Vulncheck["govulncheck"]
            Oras["oras CLI"]
            CobraCLI["cobra-cli"]
            GitHooks["Git Hooks<br/>prek"]
        end
    end

    subgraph "Configuration Files"
        EnvRC[".envrc<br/>direnv config"]
        FlakeNix["flake.nix<br/>Environment definition"]
        FlakeLock["flake.lock<br/>Dependency locks"]
    end

    Shell -->|cd into repo| Direnv
    Direnv -->|reads| EnvRC
    EnvRC --> |evaluates| FlakeNix
    FlakeNix -->|locked by| FlakeLock
    FlakeNix -->|provisions| NixStore
    FlakeNix -->|installs| GitHooks

    NixStore -->|provides| Go
    NixStore -->|provides| Make
    NixStore -->|provides| Lint
    NixStore -->|provides| Vulncheck
    NixStore -->|provides| Oras
    NixStore -->|provides| CobraCLI
Hold "Alt" / "Option" to enable pan & zoom

Environment Loading Flow: When a developer navigates into the repository directory, direnv automatically detects the .envrc file and activates the default devShell within flake.nix, which provisions all required tools from the Nix store.

Prerequisites

Before setting up the SolAr development environment, ensure the following software is installed on your system:

Requirement Purpose Minimum Version
Nix Package Manager Provides reproducible package management 2.3+
direnv Automatically loads environment when entering directory 2.20+
Git Version control (provided by Nix if needed) 2.0+

Development Workflow Overview

SolAr follows a code-generation-heavy pattern typical in Kubernetes ecosystem projects. Changes to API types trigger code regeneration, which produces client libraries, OpenAPI definitions, and RBAC manifests.

Build System

The SolAr build system uses a Makefile to orchestrate various tools, designed for reproducibility. All required tools are provided in the bin/ directory.

Target Purpose Key Tools Used
make codegen Generate client-go libraries & OpenAPI openapi-gen, kube_codegen.sh
make manifests Generate RBAC manifests controller-gen
make fmt Format code, add license headers addlicense, golangci-lint
make lint Run linters and checks golangci-lint, shellcheck, addlicense
make lint-fix As make lint, but auto-fixing golangci-lint, shellcheck, addlicense
make test Run all tests with coverage ginkgo, setup-envtest
make clean Remove generated binaries -
make help Show help for all make targets -

Tool Versions

The system pins specific tool versions for reproducibility:

See the Makefile for pinned versions.

Codebase Organization

SolAr codebase follows standard Kubernetes project conventions:

Directory Purpose Generated/Manual
api/solar/ Internal (unversioned) API types and REST strategies (*_rest.go) Manual
api/solar/v1alpha1/ Versioned API type definitions Manual
client-go/ Client libraries and OpenAPI definitions for SolAr resources Generated
cmd/solar-*/ Entry points for each binary; solar-apiserver wires up the extension API server Manual
pkg/controller/ Controller reconciliation logic Manual
pkg/discovery/ Registry scanning pipeline Manual
pkg/renderer/ Helm chart rendering Manual
pkg/ui/ solar-ui backend-for-frontend and React SPA Manual
charts/ Helm charts for deploying SolAr; charts/solar/files/role.yaml is generated Mixed
hack/ Build and code generation scripts Manual

Code Generation Process

SolAr uses the Kubernetes code-generator to produce client libraries and OpenAPI specs.

  • make codegen triggers hack/update-codegen.sh
  • Generates:
  • Client-go libraries in client-go/
  • OpenAPI definitions in client-go/openapi/
  • Deep-copy and conversion helpers in api/
  • make manifests generates the RBAC ClusterRole in charts/solar/files/

See Client Libraries section for usage details.

Testing Strategy

SolAr uses a multi-layered testing strategy:

  • Unit Tests
  • Integration Tests (uses ENVTEST_K8S_VERSION)
  • Controller Tests via envtest

Run all tests and generate coverage:

make test

Setup environment for integration tests:

setup-envtest
export ENVTEST_K8S_VERSION=<Kubernetes Version>

Test coverage is tracked using Coveralls.

Continuous Integration (CI) Pipeline

Pipeline runs on every push and pull request, enforcing code quality and test coverage.

  • Lint Job
  • addlicense
  • shellcheck
  • golangci-lint
  • Test Job (runs after Lint)
  • make test

For customization details, see .github/workflows/golang.yaml.

Adding a New Resource

SolAr resources are served by the solar-apiserver extension API server, not as CRDs in the host cluster.

  1. Create type definitions in api/solar/ (internal) and api/solar/v1alpha1/ (versioned)
  2. Register the types in the register.go of both packages
  3. Implement the REST strategy in api/solar/<kind>_rest.go — resource.Object from go.opendefense.cloud/kit/apiserver/resource, plus whichever interfaces the resource needs from go.opendefense.cloud/kit/apiserver/rest (e.g. PrepareForCreater, TableConverter). These are apiserver-kit interfaces; do not confuse them with the similarly named RESTCreateStrategy and TableConvertor in k8s.io/apiserver/pkg/registry/rest, which SolAr does not implement directly.
  4. Register the resource in cmd/solar-apiserver/main.go via apiserver.Resource(...)
  5. Regenerate code via make codegen
  6. Add controller logic in pkg/controller/ if reconciliation is needed, then make manifests to update RBAC

See hack/update-codegen.sh for implementation details.

Modifying Existing API Types

Typical steps:

  1. Edit types in api/solar/ and api/solar/v1alpha1/ — both packages must stay in sync
  2. Run make codegen
  3. Run make manifests
  4. Run make test

Note: Breaking changes may affect existing clients. Follow semantic versioning and provide migration paths.

Commit Convention

This project follows the Conventional Commits specification. Both PR titles and individual commit messages are validated in CI.

Format

<type>(optional scope): <description>

Allowed Types

Type Purpose
feat A new feature
fix A bug fix
docs Documentation changes
chore Maintenance tasks (deps, CI config, etc.)
refactor Code changes that neither fix a bug nor add a feature
test Adding or updating tests
ci CI/CD pipeline changes
perf Performance improvements
revert Reverting a previous commit

Examples

feat: add Registry resource type
fix(controller): handle missing render registry ref
docs: update contributing guidelines
chore(deps): update golangci-lint to v2.10.1
refactor(discovery): extract OCI reference resolution
test(e2e): add bootstrap cluster verification

Breaking Changes

Append ! after the type/scope to indicate a breaking change:

feat!: replace Target.Releases with ReleaseBinding
refactor(api)!: make RenderTask namespaced

Code Quality & Linting

Lint and license checks before committing:

  • addlicense for Apache 2.0 headers
  • shellcheck for scripts in hack/
  • golangci-lint for Go linting

Fix issues with:

make fmt
make lint-fix

make lint reports findings without rewriting files; make lint-fix applies what golangci-lint can fix automatically.