Enhance certificate management and simplify controller logic

[marcschaeferger]

Summary

This pull request introduces several improvements and refactors across documentation, CI/CD workflows, and the codebase. The most significant change is the addition of a new internal/certificates package, which provides an HTTP handler for exposing TLS certificate information from Kubernetes Secrets. The PR also restructures and updates the Go files overview documentation, enhances Go module caching in GitHub Actions workflows, refines documentation for doc-coauthoring and reader testing, and simplifies parts of the controller, Kubernetes client, and leader-election/readiness logic.

Major codebase addition:

• Certificate API handler implementation:
  • Adds the new internal/certificates/certificates.go file, which implements logic to fetch, parse, and expose TLS certificate data from Kubernetes Secrets via an HTTP handler at /api/v1/certificates. This includes robust error handling, JSON response formatting, and utility functions for certificate analysis.
  • Adds certificate secret configuration through CERTIFICATE_SECRETS and config-file certificateSecrets.
  • Updates docs/GO_FILES_OVERVIEW.md to document the new internal/certificates package and its files.

Controller, config, and Kubernetes client refactoring:

• Controller and leader-election simplification:

  • Simplifies leader-election handling and readiness-related controller state.
  • Removes unused controller exit-code/error state handling.
  • Keeps the controller behavior simpler while preserving the existing runtime flow.

• Kubernetes client and CRD validation cleanup:

  • Removes the startup Traefik CRD validation path and the dedicated apiextensions client from the Kubernetes client bundle.
  • Simplifies Kubernetes REST client QPS/Burst handling so explicit overrides are only applied when configured.

CI/CD workflow improvements:

• Go module and build cache optimization:

  • Refactors Go setup steps in .github/workflows/ci.yml and .github/workflows/continuous-security.yml to use actions/cache for both modules and build artifacts, improving workflow performance. [1] [2] [3]
  • Removes the deprecated cache: true option from actions/setup-go. [1] [2] [3] [4]

• Artifact metadata and SBOM upload fixes:

  • Grants artifact-metadata: write permission in .github/workflows/build-publish.yml and corrects the SBOM upload conditional. [1] [2]

• PR metadata workflow removal:

  • Removes .github/workflows/pr-metadata.yml, which previously applied PR labels and policy checks automatically.

Documentation and organization:

• Go files overview and folder reorganization:

  • Updates docs/GO_FILES_OVERVIEW.md to reflect the migration of tools from hack/ to tools/, adds missing documentation for new and existing files, and improves descriptions for clarity and accuracy. [1] [2] [3] [4]

• Doc-coauthoring and reader testing improvements:

  • Refines .agent/skills/doc-coauthoring/SKILL.md with additional steps, improved instructions, and clearer formatting for brainstorming, iterative refinement, and reader testing. [1] [2] [3] [4] [5] [6] [7] [8]

These changes collectively enhance the maintainability, performance, and clarity of the project, while adding a key API endpoint for certificate visibility.

---

Type of Change

• Feature
• Bug fix
• Refactor
• Documentation
• CI/CD
• Test improvement
• Other (describe below)

---

Affected Components

Select all that apply:

• controller (reconciliation loop)
• fetch (Pangolin API interaction)
• transform (routing, sanitize, protocol)
• apply (Server-Side-Apply logic)
• garbage collection
• kube client / resource handling
• config system
• HTTP server (/metrics, /healthz)
• observability (metrics/logging/tracing)
• leader election / HA
• CI/CD / build system
• documentation

---

Behavior Changes

Does this PR change runtime behavior?

• Reconciliation logic
• Resource generation (Traefik CRDs)
• Pangolin API interaction
• Garbage collection behavior
• Metrics / observability
• Configuration interface (env/config file)

If yes, describe in detail:

This PR changes runtime behavior by adding the /api/v1/certificates HTTP endpoint, adding certificate secret configuration through CERTIFICATE_SECRETS and config-file certificateSecrets, simplifying leader-election/readiness handling, removing startup CRD validation, and changing Kubernetes client QPS/Burst behavior so defaults are no longer forced when unset.

---

Implementation Details

Explain key design decisions:

• The certificate endpoint is implemented as a dedicated internal/certificates package to keep certificate parsing, Secret fetching, and JSON response formatting separate from the HTTP server wiring.
• Certificate Secret references can be provided through environment variables or config file values. Environment variables take precedence over config-file values.
• The HTTP server exposes the certificate endpoint through an explicitly registered handler before server start.
• Controller and leader-election state handling was simplified by removing unused pause/exit-code/error state and relying on context cancellation and readiness updates.
• Startup CRD validation was removed together with the apiextensions client dependency to simplify Kubernetes client construction and reduce startup coupling.
• Explicit actions/cache usage was added for Go module and build caches instead of relying on actions/setup-go cache behavior.

Trade-offs:

• The new certificate endpoint exposes private key material from configured TLS Secrets, so access to the controller HTTP server must be treated as sensitive.
• Removing startup CRD validation reduces startup checks but also removes an early failure path for missing Traefik CRDs.
• Leaving Kubernetes client QPS/Burst unset unless configured relies on client-go/rest defaults unless explicit values are provided.

---

Testing

Automated

• Unit tests added/updated
• Integration tests added/updated (envtest)
• E2E tests added/updated

Coverage:

• Coverage ≥ 75%
• Edge cases covered (errors, retries, empty configs, etc.)

---

Manual Testing

Describe how this was validated:

Tested with Pangolin 1.18.2 and acme.acme_http_endpoint in Pangolin

Test scenarios:

• Config change detected
• No-change (ETag / 304 handling)
• Error handling + backoff
• Garbage collection correctness
• Leader election (if applicable)

---

Security Considerations

• No impact
• TLS/mTLS handling affected
• API authentication affected
• Sensitive data handling reviewed

Explain if relevant:

The new certificate endpoint exposes certificate and private key PEM data from configured Kubernetes TLS Secrets. Secret references are explicitly configured via environment variable or config file. Private key material is returned by the endpoint but is not logged. Access control for this endpoint should be reviewed because it exposes sensitive TLS key material to callers that can reach the controller HTTP server.

---

Performance Impact

• No impact
• Improved
• Potential regression

Details:

• CI workflow performance should improve through explicit Go module/build caching.
• Runtime impact should be minimal because the certificate endpoint only fetches configured Secrets when requested.
• Kubernetes client QPS/Burst overrides are only applied when explicitly configured.

---

Backward Compatibility

• Fully backward compatible
• Breaking change (describe below)

---

Documentation

• README updated
• Docs updated
• Examples updated

---

Checklist

• I have read the CONTRIBUTING guide
• Code follows project conventions
• task ci passes locally
• Tests added where needed
• CHANGELOG.md updated (if applicable)
• No sensitive data introduced
• I considered HA / leader election implications

---

Notice

The PR description was completed with AI assistance based on the repository PR template.
Summary was fully generated by Copilot.

The pull request implementation itself is 100% human-authored. Additionally, the PR was reviewed by CodeRabbit AI.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.7% Duplication on New Code

See analysis details on SonarQube Cloud