Service management module (shturval-services)
About the service
| Parameter | Description |
|---|---|
| GUI name | Service management module |
| System name (identifier) | shturval-services |
| Cluster Assignment | Orchestration of installation and update of platform services: responds to ShturvalServiceConfig (SSC) and ShturvalServicePatch (SSP), deploys and updates Helm releases. Not intended for deploying custom applications (Argo CD, shturval-cd are used for this). |
| Critical | Yes |
| Public repository | — (component of the Shturval platform, based on Helm and Flux) |
| Dependencies | shturval-services-crds, shturval-networking |
| Namespace | shturval-services-system |
Contents
1. Review
Purpose: the operator automates the installation, update, rollback and removal of Helm charts in the cluster for objects ShturvalRepoConfig, ShturvalServiceConfig and ShturvalServicePatch. Area of responsibility is registration of Helm repositories in the Helm runtime engine inside the operator Pod, coordination of releases (install / upgrade / rollback / uninstall), checking manifest drift and health of resources marked as managed by Helm.
How the module works with resources
The operator manages three cluster-scoped CRDs in the ops.shturval.tech group:
| Resource | Role |
|---|---|
ShturvalRepoConfig | Describes a Helm repository (URL, credentials) for the engine in the operator Pod |
ShturvalServiceConfig (SSC) | Describes one Helm release: chart, version, namespace, repository (spec.reponame), mode and base customvalues |
ShturvalServicePatch (SSP) | Overrides mode and/or customValues for the selected SSC without directly editing the SSC |
Administrator chain: ShturvalRepoConfig → ShturvalServiceConfig → Helm release in the target namespace. SSP references SSC via spec.shturvalServiceConfigName and is applied during SSC reconciliation, not via a separate Helm call from the SSP controller.
The ShturvalServicePatch controller does not install a Helm release. It links SSP to the target SSC (Accepted, ownerReference, label ops.shturval.tech/ssc). Merging mode and customValues happens during ShturvalServiceConfig reconciliation (see §3 — the Apply SSP patches block). Final values are written to status.appliedCustomValues, mode to status.appliedMode, and applied patch names to status.appliedPatches. The Applied condition on SSP is set when the SSP name appears in ssc.status.appliedPatches.
Features
| Component | Purpose | Operation Notes |
|---|---|---|
Registration of repositories (ShturvalRepoConfig) | Adding/removing Helm repository entries in runtime | Operations with the repository file in the Pod are serialized (mutex), reconciliation is idempotent |
Service reconciliation (ShturvalServiceConfig) | Install/upgrade/rollback/uninstall release, modes auto / manual / absent, drift and health | Dependencies between SSCs, processing stuck releases, finalizers; on reconcile — SSP merge and writing appliedCustomValues |
Patches (ShturvalServicePatch) | Override mode and customValues over SSC | Communication with SSC via ownerReference; order by patchOrder; actual application — in SSC reconcile |
Mutating webhook for ShturvalServiceConfig | Sync spec.serviceclass to label shturval.tech/class | Requires working TLS for webhook (see Limitations) |
Validating webhook for ShturvalServiceConfig | Reserved | Validation logic not implemented (stub); see Limitations |
| Health Check Engine (GitOpsEngine) | Checking the health and drift of release resources | Objects with the label app.kubernetes.io/managed-by are taken into account |
Initiation scripts
| What’s going on | Who initiates | Observed effect |
|---|---|---|
| Repository reconciliation | Control plane (events ShturvalRepoConfig) | Update status, register the repository in the Helm engine in Pod |
| Service reconciliation | Control plane (events ShturvalServiceConfig and related SSPs) | SSP merge, changing the Helm release in the target namespace, updating appliedCustomValues / appliedMode / appliedPatches and conditions in status |
| Patch reconciliation | Control plane (SSP events and SSC appliedPatches changes) | OwnerReference, labels, conditions Accepted / Applied |
| Mutating webhook | API server when Create/Update ShturvalServiceConfig | Installing/updating service class label |
| Validating webhook | API server when Create/Update ShturvalServiceConfig | Without validated business logic validation |
| Background Health Check | Starting the operator process | Engine readiness for drift/health checks |
Limitations and implications
| Limit | Consequence |
|---|---|
| TLS for webhooks expected via cert-manager | Without a configured mechanism for issuing certificates, webhooks will not be put into operation |
ShturvalServiceConfig with name shturval-services is processed with write-lock and a delay of 1 minute after unlocking | When such an SSC changes, other SSC reconciliations may wait up to ~1 minute |
spec.iscritical: true prohibits deletion in absent mode | Before removing the release, it is necessary to remove the criticality in the specification |
| TLS client authentication for Helm repository (fields like cert/key/ca for repo) not supported in API | Authentication — using credentials and the insecure flag within the framework of the described ShturvalRepoConfig |
| MaxHistory in Helm logic is fixed (value 2 in operator delivery) | A limited number of revisions are available for rollbacks; change requires a new version of the image |
| Validating webhook for SSC — no validation implemented | Errors in spec SSC at the admission level are not caught by this webhook |
Metrics are disabled by default (--metrics-bind-address=0) | Collecting metrics from a process will require explicit configuration in the deployment manifest |
| HTTP/2 is disabled by default for metrics and webhook servers | Behavior when integrating with external proxies — consider settings |
Place in the chain of command
The diagram below is the chain Helm repository / CRD / operator / Helm release and the points where webhook and reconciliation intervene (objects ShturvalServiceConfig and ShturvalServicePatch in the Kubernetes API, releases and resources in the data plane).
Illustration: Place in the chain of command
Key Features
| Characteristics | Description |
|---|---|
| API Group | ops.shturval.tech |
| API Versions | v1beta1 (spoke), v1beta2 (hub, storage) |
| Typical deployment namespace (Kustomize / Helm) | shturval-services-system |
| Leader election | Default off |
| Metrics | Default disabled |
| Webhook | Mutating + Validating for ShturvalServiceConfig (v1beta2); the delivery also includes a template for RepoConfig |
| SSC reconciliation concurrency | Up to 5 simultaneous reconciles (value supplied with the controller) |
| Panic behavior in SSC controller | recover panic enabled |
Components in a cluster
| Component | Type Kubernetes | Scope | Purpose |
|---|---|---|---|
ShturvalRepoConfig | CRD | Cluster | Helm repository (URL, credentials) |
ShturvalServiceConfig | CRD | Cluster | Parameters for one Helm release |
ShturvalServicePatch | CRD | Cluster | Patch mode/customValues for the selected SSC |
| Pod operator | Deployment | Namespaced | Process in typical namespace shturval-services-system |
| MutatingWebhook (SSC) | MutatingWebhookConfiguration | Cluster | Sync class to label |
| ValidatingWebhook (SSC) | ValidatingWebhookConfiguration | Cluster | Without validation business logic |
2. Architecture
The inclusion and life cycle of the controller in the cluster is provided by cluster-manager (platform service); ShturvalServiceConfig (SSC) objects for associated charts are created and maintained as part of the platform configuration, rather than as an arbitrary manual installation of a Helm chart by an administrator.
Helm delivery (names from Chart.yaml)
The module comes with two separate Helm charts (not to be confused with CRD ShturvalServiceConfig / “SSC” in the API):
Chart name (Helm name) | Catalog in source | Purpose |
|---|---|---|
| shturval-services-crds | helm/crds | Setting CRD (ShturvalRepoConfig, ShturvalServiceConfig, ShturvalServicePatch) |
| shturval-services | helm/main | Operator deployment: Deployment, RBAC, webhook, services |
The inclusion and life cycle of the controller in the cluster is provided by cluster-manager (platform service); ShturvalServiceConfig (SSC) objects for associated charts are created and maintained as part of the platform configuration, rather than as an arbitrary manual installation of a Helm chart by an administrator.
Operator Role
The operator is deployed as one Deployment in the namespace of platform services. The repository file and Helm cache are stored inside the Pod (paths are specified by process arguments, typically a directory in the image). Controllers access the Kubernetes API and the Helm engine; health/drift subsystem uses gitops-engine and monitors objects with the label app.kubernetes.io/managed-by.
Note: without the described TLS mechanism for webhooks, a production deployment with webhooks enabled will not match the expected configuration.
Workload components (Deployment, RBAC, webhook)
| Element | Description |
|---|---|
| Operator Container | Binary shturval-operator, health/readiness probes at the address specified by the flag (typically :8081) |
| Roles and bindings | ClusterRole/Binding for working with CRD and cluster operations according to the supplied manifests |
| Webhook | Service and TLS (via cert-manager in standard delivery) for mutating/validating |
| cert-manager | Expected in the cluster to issue webhook certificates (see Limitations) |
Communication with external systems
| System/object | Role |
|---|---|
| HTTP(S) Helm repositories | Chart source by ShturvalRepoConfig |
| Kubernetes API | CRD Objects, Secrets, Namespace, Release Tracked Resources |
| Third-party charts in target namespace | Deployed by Helm according to ShturvalServiceConfig |
Charts
Operator deployment (controllers, webhook, Helm engine, health checker in Pod; access to cluster API and external Helm repositories).
Links of CRD and related objects (repository, service configuration, patch, Helm release, links spec.dependency / reponame, etc.).
Illustration: Charts
3. Life cycle
End-to-end scenario (E2E)
Sequence: repository → ShturvalServiceConfig / patches → reconciliation and release states. Useful for understanding the order of steps when parsing delays and conditions.
Illustration: End-to-end scenario (E2E)
ShturvalRepoConfig
- Purpose (K8s resources): cluster-scoped CRD, describing one logical Helm repository for the engine in the Pod.
- Creation/update: a record is generated from spec; if
status.readyis successful, conditionsInstall/Sync, finalizerops.shturval.tech/finalizeris added. - Deleting: the repository is deleted from the engine, the finalizer is removed. (see screenshot below)
Reconciliation scheme (create/update, delete, key branches and status.ready status).
Illustration: ShturvalRepoConfig
ShturvalServiceConfig
- Purpose: one object describes one Helm release in
spec.namespacewith the given chart name, version, repository and mode.
Modes (spec.mode):
| Mode | Behavior |
|---|---|
auto | Install → drift detection → synchronization → health; when changing version — forced upgrade |
manual | The operator does not change the release; status.ready without checks |
absent | Uninstall if iscritical does not interfere |
- Reconciliation (general): before branching by
spec.mode, SSPs are applied (patchMode+patchCustomValues, sorted bypatchOrder);status.appliedCustomValues,status.appliedMode,status.appliedPatchesare written (see theApply SSP patchesblock on the diagram below). - Create/update (auto, summary): check repository; updating the cache if necessary; waiting for
dependency/dependencyclassreadiness; release status analysis; install/update; waiting for the health/drift engine to be ready; drift and health check with possible upgrade/requeue; putting theshturval.tech/system-namespacelabel on the namespace from spec. - Self-update / SSC named
shturval-services: this name applies a write-lock to the locking area and a delay of 1 minute after the lock is released — plan for load peaks and change windows. - Removal: at
iscritical— reconciliation stops withServiceIsCritical; otherwise, no dependent SSCs are expected, then the release is removed and theops.shturval.tech/finalizerfinalizer is removed.
Reconciliation scheme (overview): branching according to spec.mode, Apply SSP patches block, Helm engine, health/drift, conditions in status.
Reconciliation scheme in auto mode: repository, dependencies, install/update, drift, rollback when the release hangs, repetitions.
Repetition intervals (guidelines from the reconciliation logic): adding a finalizer — about a second; repo is not ready — about 5 s; health engine is not ready / service is not healthy — about 1 minute; dependencies — repeat; successful completion without requeue.
ShturvalServicePatch
- Purpose: to override
modeand/orcustomValuesfor the selected nameShturvalServiceConfigwithout directly editing the SSC itself. - Create/Update: commit
observedGeneration, check for SSC existence, set ownerReference, labelops.shturval.tech/ssc→ SSC name; mapping to SSC’sstatus.appliedPatches. - Merge
customValues(rules): a key with the prefix-removes the corresponding key from the base; nestedmapare merged recursively; scalars are replaced with the value from the patch. - Removal: SSP does not have a separate finalizer; when a parent SSC is deleted, child objects with ownerReference are disposed of according to GC rules. The SSP controller does not handle the Delete of the SSC itself (
appliedPatchespredicate).
The ShturvalServicePatch controller does not install a Helm release. It links SSP to the target SSC (Accepted, ownerReference, label). Merging mode and customValues happens during ShturvalServiceConfig reconciliation. Final values are written to status.appliedCustomValues, mode to status.appliedMode, and patch names to status.appliedPatches. The Applied condition on SSP is set when the SSP name appears in ssc.status.appliedPatches.
- Coordination SSC ↔ SSP (steps):
| Step | Resource/signal | Action (semantic) |
|---|---|---|
| 1 | ShturvalServicePatch | Checking the target SSC, setting Accepted |
| 2 | SSP + SSC | OwnerReference and link label |
| 3 | ShturvalServiceConfig (reconciliation) | Applying patches; writing status.appliedCustomValues, status.appliedMode, status.appliedPatches |
| 4 | SSP | Applied upon the fact that the name is included in ssc.status.appliedPatches |
SSP reconciliation scheme: SSC lookup, Accepted / Applied, ownerReference, matching with status.appliedPatches at ShturvalServiceConfig (see the screenshot below).
4. Diagnostics
Conditions: ShturvalRepoConfig
| Condition | At True | When False / reasons |
|---|---|---|
Install | Repository added to engine | Error adding/updating repository |
Sync | Repository synchronized | ErrorCheckHelmRepo, ErrorRemoveHelmRepo |
Uninstall | — | For the deletion scenario — through the finalizer, separate logic |
Conditions: ShturvalServiceConfig
| Condition | At True | When False / reasons |
|---|---|---|
Install | The release is installed, the version corresponds to spec | RuntimeRepositoryNotReady, RepositoryNotUpdated, WaitingInstallDependency, ErrConvertParams, ErrCheckSscStatus, ErrorInstallService, ErrorUpdateService, ErrorRollbackService, ReleasePending, ReleaseRollback |
Sync | No drift of values and manifests | GitOpsEngineNotReady, ErrorRenderManifests, ErrorCheckValuesDrift, ErrorCheckDrift, ErrorUpdateService, ReleasePending, ErrGetPendingTime |
Healthy | Managed resources are healthy | ErrorCheckServiceHealth, ErrorServiceNotHealthy |
Uninstall | Release deleted (when scenario is deletion) | ServiceIsCritical, WaitingUninstallDependency, ServiceUninstalling, ErrRemoveService, ErrorRemoveService, ErrorConvertParams, ErrorCheckSscStatus |
Patch | Patches applied | PatchFailed |
UpdateNamespace | namespace tags updated | GetNamespaceFailed, UpdateNamespaceFailed |
Conditions: ShturvalServicePatch
| Condition | At True | When False / reasons |
|---|---|---|
Accepted | SSC found, ownerReference set | SSCNotFound |
Applied | SSP name in ssc.status.appliedPatches | NotAppliedYet |
Typical symptoms
| Symptom | Possible reason | Action |
|---|---|---|
| Webhook not ready, errors when creating SSC | No cert-manager/certificates, invalid TLS paths | Check cert-manager scheme and Certificate status |
RepositoryNotUpdated / repo not ready | ShturvalRepoConfig not in Sync / no registration | Check ShturvalRepoConfig and network access to Helm repo |
| Long blocking when making changes | Modifies SSC named shturval-services | Plan windows; consider delay up to ~1 minute |
Cannot remove release (absent) | iscritical: true | Uncheck spec |
ServiceIsCritical when deleting | See above | Remove criticality |
ReleasePending / rollback | The release hung in pending longer than the threshold (in delivery — 5 minutes) | Helm event analysis, operator logs; if necessary, manual parsing of an external release |
| No admission validation | Validating webhook — stub | Additional pre-application spec checks (organizational policy) |
SSP Accepted=false, SSCNotFound | Target SSC not yet created or name in spec.shturvalServiceConfigName is wrong | Check SSC presence; SSP controller periodically retries reconcile |
SSP Applied=false, NotAppliedYet | SSC has not yet completed reconcile with patch application | Check status.appliedPatches and condition Patch on SSC |
5. Installation / deployment
The module is installed by cluster-manager as part of the platform configuration. The administrator only needs to ensure that cert-manager is present in the cluster (see Limitations) and that the operator Pod, CRDs and webhooks are in working order.
Helm delivery order and chart parameters
Environment Dependencies
- cert-manager version 1.x or higher in a cluster — for TLS webhook operator (see Limitations).
Helm delivery order
The delivery is divided into two charts with fixed names in Chart.yaml (see §2):
- shturval-services-crds — CRD;
- shturval-services — operator (controllers, webhook) in namespace
shturval-services-system.
The Helm release names and chart repository URLs are set in your platform delivery loop.
Chart parameters (summarized from the technical description)
The typical values of the main chart (without reference to internal paths) provides by default, in particular:
| Parameter (logical) | Description |
|---|---|
replicaCount | Number of Deployment replicas (typically 1) |
tolerations / affinity | Convergence with infrastructure nodes / Control Plane (template for a specific cluster) |
Note: custom edits to values in operation under the Shturval platform are consistent with the delivery policy; for custom overlay values, use ShturvalServicePatch (SSP) where applicable to the service that delivers the operator.
Post-deployment check (no hard commands)
Make sure that the operator Pod in the target namespace has moved to Ready, CRDs are registered, Mutating/ValidatingWebhookConfiguration objects refer to a running Service and certificates (if the scheme is consistent with cert-manager). The specific kubectl commands are not given in the technical manual; use standard procedures in your environment.
6. Operator parameters
Any changes to values for the chart that delivers the operator in the Shturval platform environment must be made through ShturvalServicePatch, if this applies to the corresponding ShturvalServiceConfig.
Limitations not displayed in the custom Helm chart: MaxHistory=2 for releases, thresholds for waiting for a pending release, wait durations for install/uninstall, fixed self-update delays — specified in the image of the delivered version; a new version of the image/operator is required to change.
Process arguments (from the technical manual)
Process parameters explicitly described in the technical manual are listed. In practice, they are set by container arguments and, if necessary, environment variables in the delivery manifest/Helm values.
| Parameter | Default (from manual) | Description |
|---|---|---|
--metrics-bind-address | 0 | 0 — metrics are disabled; otherwise address/port |
--health-probe-bind-address | :8081 | Listening to health/readiness |
--leader-elect | false | Leader election |
--metrics-secure | true | HTTPS for metrics (if enabled) |
--enable-http2 | false | HTTP/2 for metrics servers and webhook |
--webhook-cert-path | empty | TLS directory for webhook |
--webhook-cert-name | tls.crt | Certificate file name |
--webhook-cert-key | tls.key | Key file name |
--metrics-cert-path | empty | TLS directory for metrics server |
--metrics-cert-name | tls.crt | Metrics certificate name |
--metrics-cert-key | tls.key | Metrics key name |
--repo-config | /helm | Directory with repositories.yaml |
--repo-cache | /helm | Repository cache |
--helm-timeout | 5m | Helm operations timeout |
ENABLE_WEBHOOKS | (not set — webhooks enabled) | false — disable webhook registration (for example, an environment without TLS) |
7. CRD/API reference
API Group: ops.shturval.tech. Storage version: v1beta2. Spoke: v1beta1 (conversion).
7.1 ShturvalRepoConfig - Cluster
Short name: (not specified in excerpt; Kind — ShturvalRepoConfig.) Scope: Cluster.
Without a registered and ready repository, ShturvalServiceConfig referencing this name will not be served.
spec
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Helm repository URL |
username | string | No | Login |
password | string | No | Password |
insecure | bool | No | Bypassing TLS certificate verification |
Important: The client TLS fields for the repository in the API are not available (commented out/not used) — mTLS/client certificates are not supported without a product change.
status
| Field | Type | Description |
|---|---|---|
ready | bool | true upon successful registration |
conditions | condition array | State |
Conditions
See §4. Diagnostics. For Install when False — including error with RepoAddOrUpdate.
7.2 ShturvalServiceConfig - Cluster (shortName: ssc)
One object — one Helm release in spec.namespace.
spec
| Field | Type | Required | Description |
|---|---|---|---|
mode | enum: auto / manual / absent | Yes | Mode; default auto |
chart | string | Yes | Chart name (name template from CRD) |
version | string | No | Chart version |
namespace | string | Yes | Namespace installation |
reponame | string | Yes | Name ShturvalRepoConfig |
dependency | []string | No | SSC dependency names |
dependencyclass | []string | No | SSC classes (one Ready SSC with shturval.tech/class label is enough) |
serviceclass | string | No | Class of service; webhook copies to label shturval.tech/class |
extraargs | map[string]string | No | Additional Helm arguments |
customvalues | map[string]interface{} | No | Helm values (no hard scheme) |
iscritical | bool | No | If true, deleting via absent is disabled |
status
| Field | Type | Description |
|---|---|---|
ready | bool | General readiness |
currentMode | enum | Actual mode |
currentVersion | string | Installed version |
conditions | condition array | State |
appliedCustomValues | map | Final values after patches (written during SSC reconciliation) |
appliedMode | enum | Mode after patches |
appliedPatches | []string | Names of applied ShturvalServicePatch |
Conditions
See §4. Diagnostics.
7.3 ShturvalServicePatch - Cluster (shortName: ssp)
Patch for mode and/or customValues for the specified SSC.
spec
| Field | Type | Required | Description |
|---|---|---|---|
shturvalServiceConfigName | string | Yes | Target name ShturvalServiceConfig |
patchOrder | *int | No | Order (less is earlier; nil is treated as 0) |
mode | enum | No | Overrides spec.mode SSC |
customvalues | map[string]interface{} | No | Recursive merge over spec.customvalues SSC |
status
| Field | Type | Description |
|---|---|---|
observedGeneration | int64 | Last generation processed |
conditions | condition array | State |
Conditions
See §4. Diagnostics.
Finalizer (all listed CRDs according to logic): ops.shturval.tech/finalizer (no separate finalizer required for SSP — see §3).