Actspan Docs Quickstart
DocsOperate

Prepare the optional shared control plane and its services.

On this page

Install the shared control plane

Availability: for design partners. Use the hosted portal for a partner evaluation. The private Kubernetes operator and ECR images are supplied to partners who require self-hosting, with registry access granted per partner.

Release qualification: published operator 0.2.0 has a confirmed PVC-template comparison issue. Persistent PostgreSQL/ClickHouse workloads can be healthy while reconciliation repeatedly upgrades and stays Progressing. A fixed operator release is being qualified; request that release before following this guide for a persistent installation. The fixture-only operator lifecycle passed, but it did not cover persistent-storage readiness.

Before you begin

Start with the local quickstart if you only need CLI execution. Use the shared control plane for team review, central run history and authenticated approvals.

For Kubernetes, request a qualified persistent-install deployment handoff from info@actspan.com. It includes the application and operator chart archives, checksums, and configuration examples. Access to the product repository is not required for the chart installation path below.

Your platform administrator must provide:

  • A Kubernetes cluster, Helm and kubectl access to the target namespace.
  • A CNI that enforces Kubernetes NetworkPolicies, such as a correctly configured Calico installation. Creating policy objects alone does not enforce them.
  • Access to the private application and operator container images, with a supported image-pull credential mechanism.
  • PostgreSQL and Temporal endpoints, persistent storage, and required secrets.
  • For production, an HTTPS ingress origin and supported OIDC configuration.
  • Reviewed network destinations for the database, Temporal and model providers.

Expected result: the operator manages one Actspan installation whose workloads, readiness and configured network access can be inspected in the namespace. This is a target for the qualified fixed artifacts, not a claim that affected 0.2.0 passes persistent reconciliation. Downloading charts alone does not provision these dependencies.

Persistent installation is gated on a fixed handoff

The current 0.2.0 operator is not the persistent-install acceptance baseline. Do not copy an affected chart version and expect stable Ready. A replacement must name application/operator chart checksums and image digests and include persistent install, restart, update and repeated-reconciliation results. No qualified fixed version is declared on this page yet. Until it is supplied, stop before installing persistent workloads.

The commands below are a reference for a future qualified handoff. Set ACTSPAN_APP_CHART and ACTSPAN_OPERATOR_CHART to the exact reviewed archive paths in that handoff. They are not inferred from version 0.2.0.

Inspect the supplied charts

From the extracted deployment handoff:

shasum -a 256 -c SHA256SUMS
helm show chart "${ACTSPAN_APP_CHART:?set the qualified application chart path}"
helm show chart "${ACTSPAN_OPERATOR_CHART:?set the qualified fixed operator chart path}"

Both chart versions and application versions should match the handoff manifest. The operator is a Kubernetes controller; the application chart contains the control API, portal, execution worker and workflow worker.

Review operator-values.yaml and installation.yaml before using them. Configure the supplied private image references and credentials, real service endpoints, secret names, ingress and allowed network peers. Documentation CIDRs such as 192.0.2.0/24 are examples and must be replaced; an enforcing NetworkPolicy will otherwise block the real destination.

Create the referenced application secrets through your approved secret management process. Production requires the deployment's OIDC/TLS settings; the local test login is a separate evaluation mode.

Install the CRD, then the operator

Apply the supplied CRD before installing or upgrading the chart:

kubectl create namespace actspan --dry-run=client -o yaml | kubectl apply -f -
helm show crds "${ACTSPAN_OPERATOR_CHART:?set the qualified fixed operator chart path}" > actspan-crds.yaml
kubectl apply -f actspan-crds.yaml
helm upgrade --install actspan-operator "${ACTSPAN_OPERATOR_CHART:?set the qualified fixed operator chart path}" \
  --namespace actspan --values operator-values.yaml
kubectl rollout status deployment/actspan-operator --namespace actspan

The namespace-scoped operator reconciles ActspanInstallation resources. Its image bundles the application chart used for reconciliation. Installing the operator does not automatically create an application installation.

Create and inspect an installation

Apply the reviewed installation file, then watch its conditions:

kubectl apply -f installation.yaml
kubectl get actspaninstallations --namespace actspan --watch

In another terminal, inspect the resulting workloads and any failure details:

kubectl get pods --namespace actspan
kubectl describe actspaninstallation --namespace actspan
kubectl logs deployment/actspan-operator --namespace actspan

Acceptance for the qualified replacement: the installation reports stable Ready, application pods become ready, and the control API /readyz endpoint confirms current migrations. Open the configured portal HTTPS origin and authenticate through its configured identity provider. Readiness is separate from a successful provider call or a governance evaluation.

Database migration hooks are part of the supported installation lifecycle. Do not edit migration bookkeeping or run SQL manually as an installation step.

Change, ownership and removal

Change the installation's desired configuration and apply the file again. The operator reconciles its owned release, reports status and repairs supported resource drift. It refuses to adopt a conflicting manually managed Helm release. Do not run a separate manual Helm install with that same release name.

The default deletion policy retains the application release. A deliberate Delete policy removes the managed release when the installation is deleted; review the handoff's retention and backup instructions first. Helm release removal does not establish deletion or recoverability of external databases or persistent volumes.

For a controller-free installation, the supplied application chart can be installed directly with your reviewed application values. Use a separate release identity and do not also ask the operator to own that release.

Connect a CLI workspace

After the shared services are ready, follow Connect the portal and Approve a sensitive action. A developer service credential can report runs, but cannot act as the human approver. The portal decision is consumed by the original CLI continuation; the portal does not execute that local workspace on your laptop.

Before accepting a persistent deployment, observe several unchanged reconcile cycles without additional Helm revisions, restart the operator and workloads, check retained test data, make one supported update and verify return to stable Ready. Preserve image digests, chart hashes and release revision counts.

The private release provides artifacts and tested scope. Your production identity configuration, backups, networking and cluster installation still need validation in your environment.