Kubernetes APIs and Controllers Overview
The reshapr-controllers repository provides a Kubernetes operator, eight namespaced custom resources, and an admission webhook for proxy sidecar injection. The 0.0.4 documentation index and generated CRDs are the canonical references for this baseline.
Operator model​
The operator reconciles Kubernetes resources against a reachable reShapr control plane. Resources use the reshapr.io/v1alpha1 API and identify their target through reshapr.io/instance and reshapr.io/organization annotations. Reconciliation progress and control-plane identifiers are reported in each resource's status.
The operator ServiceAccount must be registered as a trusted control-plane client. See the canonical instance connection flow and operator installation.
Custom resources​
| Kind | Role and dependencies | Deletion behavior | Canonical reference |
|---|---|---|---|
Service | Imports the primary OpenAPI, GraphQL, or Protobuf artifact | Remote Service cleanup is enabled by default; keepOnDelete can retain it | Service CR |
GatewayGroup | Declares the labels used to select Gateways | Remote Gateway Group cleanup is enabled by default; keepOnDelete can retain it | GatewayGroup CR |
ConfigurationPlan | Binds an existing Service to a backend endpoint, operation and artifact selection, cache settings, request-header policy, and security configuration | The reconciler cleans up its remote Configuration Plan | ConfigurationPlan CR |
Exposition | Exposes a Service through a ready Configuration Plan and Gateway Group | Remote Exposition cleanup is enabled by default; keepOnDelete can retain it | Exposition CR |
SecretSource | Declares control-plane Secrets, optionally sourced from Kubernetes Secrets | Remote Secret cleanup is enabled by default; keepOnDelete can retain it | SecretSource CR |
CustomTools | Attaches declarative or scripted tools to an existing Service | No remote artifact cleanup is implemented when the CR is deleted | CustomTools CR |
Resources | Declares MCP resources and resource templates for an existing Service | No remote artifact cleanup is implemented when the CR is deleted | Resources CR |
Prompts | Attaches MCP Prompts to an existing Service (added in controllers 0.0.4) | No remote artifact cleanup is implemented when the CR is deleted | Prompts CR |
There is no dedicated ToolsOutputFilters CRD. Prompts, CustomTools, and Resources report status.state, rather than the other kinds' status.status and observedGeneration contract.
Controllers 0.0.4 also reconcile spec.toolExposureMode (TOOLS, CODE, or HYBRID) on a ConfigurationPlan. See Use Code Mode. The corrected chart 0.0.15 includes all eight CRDs and this field. For existing installations, explicitly update CRDs from the controllers release before applying manifests that use them; Helm upgrades do not update CRDs.
Controllers 0.0.4 expose spec.headerPolicy.request and spec.headerPolicy.response with allow, deny, and rename rules. The operator forwards both shapes to the control plane, but runtime 1.1.0 enforces only request rules; response rules are reserved for future use.
Admission controller​
The mutating admission webhook injects a reShapr proxy sidecar into Pods annotated with io.reshapr/inject: "true". For workloads owned by a Deployment, its controller can also create the headless clustering Service and the MCP Service used to reach injected proxies.
The webhook is fail-open by default through failurePolicy: Ignore. Its serving endpoint requires TLS; the controllers chart supports cert-manager, OpenShift service certificates, or an existing certificate. See the canonical admission controller and installation guide.
Limits​
CustomTools,Resources, andPromptsdeletion can leave their remote artifacts in the target Service.- Controllers
0.0.4uploadCustomTools,Resources, andPromptsartifacts asartifact.json; reconciling multiple artifact CRs for one Service can replace the previously attached artifact. Use one artifact CR per Service or manage additional artifacts through another supported interface. - Reading Kubernetes Secrets for
SecretSourcerequires the operator's separate Secret-reader RBAC. - The admission controller creates supporting Services only for injected Pods owned by a Deployment.
- Controller-specific metrics and traces are not currently documented as a supported observability surface; rely on component logs unless the owner documentation states otherwise.
Next step​
- Use Your First GitOps-managed MCP Endpoint to create and verify an endpoint from these APIs.
- Use Manage reShapr Resources with GitOps to operate their update and deletion lifecycle.
- Use Helm Charts Overview to choose the controllers chart and its dependencies.
- Use Product Interfaces to find the remaining reShapr contracts.