Deploy and activate Tutela
Documentation for Tutela v3.9.0.
Deploy Tutela in your AWS account using the installation package supplied for your agreement, then check activation and service availability. AWS Marketplace and direct installations use different activation paths; confirm yours before creating resources.
Prerequisites
- The approved release package and its installation instructions, including the CloudFormation template locations and required parameters.
- Your AWS account, chosen region, network and sizing decisions, application hostname, and DNS/TLS plan.
- An AWS role authorized to create the resources in that package, including CloudFormation, compute, storage, Secrets Manager, KMS and monitoring.
- Your activation details and support contact. For an evaluation, confirm the end date and conversion or extension arrangements.
Create and check the stacks
- Confirm that the package matches your purchase or direct agreement. For AWS Marketplace, accept the applicable offer before launching its package. A direct installation does not use Marketplace entitlement.
- In the AWS Console, select the installation region and open CloudFormation. Use the template supplied with your installation package. Review the parameter values with the operator; keep secrets in the designated secret fields and approved storage.
- Create the foundation and runtime stacks in the order specified by the package. In each stack's Events tab, wait for completion. A rollback or failed resource must be resolved before proceeding; record its logical resource name and reason.
- Open the completed stack's Outputs tab. Use its application address and package instructions to finish DNS and certificate setup. Open that address over HTTPS and confirm that the certificate matches your hostname.
- Sign in with the administrator access supplied for this installation. Complete any required password change. Keep bootstrap credentials in your approved secret store, not in a shared handoff document.
- Open Settings > Activation and compare the activation source with your agreement. Check subscription, entitlement and activation separately. A completed password change alone does not activate the deployment.
- Open Settings > Support & diagnostics > Service health. Investigate unavailable dependencies, then run Verify your installation for the first configured AI connection.
If the setup screen cannot confirm completion, use Retry setup completion after resolving the displayed cause. If the activation source is wrong, stop onboarding and contact support with the request ID and agreement type; do not try a different activation path at random.
Install with Helm (preview)
Helm installation on Kubernetes is a preview. The chart starts and passes its checks on a local test Kubernetes cluster. It has not yet passed an end-to-end check on Amazon EKS, so do not treat it as production-proven. Use the CloudFormation path above for a supported production install, or run a Helm install in a non-production cluster first.
What the chart deploys: the gateway, web console, inspector, classifier, policy, analytics, notification, integrations, DSPM bridge, discovery, AI proxy, MCP gateway and AWS runtime gateway services. ClamAV file scanning is off by default; turn it on with clamav.enabled. If agents do not call AWS through Tutela, you can turn off the AWS runtime gateway with awsRuntimeGateway.enabled: false.
Before you install:
- Create the Secrets and set the passwords first. The chart never generates a credential, so an upgrade never rotates one. Five Secrets are required:
tutela-internal-auth(internalAuth.existingSecret),tutela-inspector-callers(internalAuth.inspectorCallerSecret),tutela-platform(platformSecrets.existingSecret),tutela-identity-token(identityToken.secretName) andtutela-analytics-subject(analytics.subjectErasure.existingSecret). If your package includesscripts/deploy/helm-create-secrets.sh, run it with the namespace name. It never changes a key that already exists, so you can run it again before an upgrade to add only the keys a newer chart needs. Also set these passwords in your values file:grafana.adminPasswordandgrafana.oauthSecret(Grafana is on by default, and the chart refuses to render without them), pluspostgresql.auth.postgresPassword,redis.auth.passwordand the analytics database password listed in the chart's values file, if you use the bundled stores. - Set an image tag or digest for every service. The chart refuses an empty tag and refuses
latest. - Set up subscription verification. The gateway does not start in production until it can verify your subscription. The chart does not yet set up the AWS access that the AWS Marketplace subscription check needs, so confirm your setup with support before you rely on it.
- Set network rules for external stores. The chart's network policy lets each service reach only the stores it uses. If you use your own PostgreSQL, Redis or Kafka, list the egress rule for each in
networkPolicy.externalStoreEgress. The chart refuses to render without it. Add your cluster's pod and service address ranges tonetworkPolicy.internetEgressExcept.
Keep the Inspector caller credentials in their dedicated Secret. Each credential is shared only by Inspector and the AI gateway, MCP gateway, or AWS runtime gateway that uses it. Do not add this Secret to Prometheus or reuse the service/metrics Secret for it. Before upgrading, run the supplied secret setup to add missing caller keys without rotating existing credentials. See the installation package's Helm guide for the required key names.
What to expect when it starts:
- Database setup. Each service sets up its own part of the shared database when it starts. The services take turns on one database lock, so starting them all at once is safe.
- Startup time. Each backend service has 5 minutes to finish starting before its liveness check begins (
startupProbe, 5-second period times 60 attempts). On a slow database, raisestartupProbe.failureThreshold. - PostgreSQL. The AI proxy no longer needs the pgvector extension, so the bundled PostgreSQL and a standard managed PostgreSQL both work.
After the install, follow Verify your installation. A running pod does not show that an AI workflow is governed.
Update an existing deployment
Before you update, remove any POLICY_FAIL_MODE setting from the deployment.
The inspector no longer has built-in rules and refuses to start while that
setting is present, so a value you chose is not silently ignored. When your
policies cannot be evaluated, each tenant's inspection availability setting
decides instead (open unless the tenant or your operator chose closed). The
Helm chart now gives the inspector its policy service address; it starts only
when that address is set.
A route a tenant never set uses the deployment default. In Helm, when
INSPECTION_DEFAULT_MODE is not set, the default follows the inspector's
FAIL_MODE (open if that is unset), so a deployment that was closed stays
closed after the update. The InspectionFailOpenAllowed warning alert fires
whenever a request is allowed because inspection or policy evaluation was
unavailable and the route was open. Three critical alerts are new, and each one
is a product defect to fix, not an outage: InspectionTimeouts (an inspection
call read nothing in time, so the tenant's setting decided),
InspectionPartlyCheckedTimeouts (inspection ran out of time and the rest of
the content was reported as partly checked), and InspectionFailedAnswers (the
inspection or policy service answered with an error; the tenant's setting
decided each request, blocked on a closed route and let through uninspected on
an open one).
Timeouts for long content
Long prompts, messages and tool results are now checked up to 500,000 characters per text instead of being refused, and Tutela waits as long as checking that much text can take. The longest governed chat or MCP call can take about 16 minutes. Before you update:
- File timeout. If your configuration sets
CLASSIFIER_FILE_TIMEOUT, it must be at least106s, or remove it. With a shorter value, the inspector does not start, and its message names the setting. The chart now sets106s. - Text timeouts. The inspector no longer reads
CLASSIFIER_TIMEOUTorCLASSIFIER_RESPONSE_TIMEOUT, because text deadlines are now sized to each text. You can remove both. - Ingress. The Helm chart sets the ingress-nginx read and send timeouts to 1,000 seconds, because the 60-second default cut off long requests. If you use a different ingress, proxy or load balancer, give it an idle or read timeout above 990 seconds.
- Shutdown. The gateway and inspector pods now have a 330-second termination grace period, so a check in progress can finish during a rolling update. Allow for this in your update window.
- Text recognition. Text recognition (OCR) is on by default in the AWS deployment (
OCR_ENABLED=true). With it on, an upload can take up to 15 seconds longer per file. With it off, images are reported as not read instead of being blocked.
Detection runs on CPU only
Tutela now detects sensitive data with its own rules and models on CPU only. The optional language-model detection (Tier 3, and the language-model Tier 2 engine) has been removed:
- Launch template. The Private Inference with vLLM option is gone, together with its GPU instance, GPU image, cost acknowledgement and local model address parameters. No GPU host is created. If your current stack has one, the update removes it.
- Leftover settings. If your configuration still sets
TIER2_ENGINE, anyTIER3_setting or any classifierLLM_setting, the classifier ignores them and starts normally. It logsllm_tier_settings_ignoredonce, with the setting names only and never their values. You can remove them. - Helm network policy. The classifier no longer has outbound access to language-model providers or to any internet address. To keep sending classifier errors to Sentry, set
classifier.sentry.enabled, name the Secret that holds the DSN inclassifier.sentry.dsnSecret, and list the allowed destinations inclassifier.sentry.egressPeers, as a bounded IP range or an egress gateway selector. The chart refuses to render with an open range (/0) or an empty selector.
Use the immutable release package intended for your installation and follow its update procedure. Before changing a stack, record the current release and configuration, review the change set, and confirm the backup and recovery plan. Do not replace a release-pinned image with a moving tag.
For a Tutela 3.9.0 update, confirm that the package supplied for your installation
targets that release. In a Marketplace package, check for v3.9.0; in a Helm
chart, check that version and appVersion are both 3.9.0. Keep the activation
path for your agreement. A package's version does not confirm that the update
has completed. After updating, compare the version returned by your gateway's
/v1/version endpoint with your installation record, then complete the workflow
checks below.
Update the browser extension and other installed clients separately using the corresponding packages. A server update does not update an unpacked extension; reload existing AI tabs after updating it.
Helm deployments follow their supplied chart procedure rather than this CloudFormation sequence. Grafana ingress and OAuth connectivity must match the chart's network policy; use Grafana dashboards to check the resulting access.
Analytics prerequisites for Helm updates
For a release package containing runtime capture and saved compliance evidence, have the operator review these chart settings before applying the update:
- Set
analytics.subjectErasure.existingSecretto an existing Secret containingruntime-passwordandmigration-password. Use distinct runtime and migration accounts; do not give application traffic the migration credential. The chart requires this reference when Analytics is enabled, including with external ClickHouse. External database accounts and grants must be prepared separately. - Review the retired account list in
analytics.subjectErasure.legacyUsers, which must includedefault, and explicitly list any privileged maintenance accounts inmaintenanceUsers. Plan old-writer shutdown with the operator before retiring credentials. The bundled ClickHouse configuration supports one writer endpoint; these settings do not establish a safe rolling cutover by themselves. - Select the recovery-working-record policy with the responsible data owner:
either a positive whole-day
SUBJECT_ERASURE_RECOVERY_RETENTION_DAYS, orSUBJECT_ERASURE_RECOVERY_DISCARD_COMPLETED=true, supplied throughanalytics.env. Do not combine them. Discard applies to duplicate recovery working records after verified completion, not unresolved work, backups, or retained review history. Installing the chart does not choose this policy. - Runtime capture is an explicit opt-in through
analytics.env.RUNTIME_CAPTURE_COLLECTOR_ID; its empty default preserves legacy ingestion. An enabled collector needs a stable identifier across replicas and restarts, the existing Kafka group and offsets, valid brokers, and authenticated Gateway lifecycle access. A fresh replacement starts with its own identity and does not inherit the removed deployment's offset history. - Signed compliance exports separately use
analytics.complianceEvidence.existingSecret, withCOMPLIANCE_EVIDENCE_SIGNING_KEY_IDandCOMPLIANCE_EVIDENCE_SIGNING_KEY. Leaving this reference empty disables signing, not ordinary JSON/CSV exports. Keep key material in the Secret, never inanalytics.env, chart values, or support attachments.
Check the configured workflow with made-up example data after the approved update. Readiness or a valid export signature alone does not prove complete collection, complete erasure, or compliance with a framework. Do not bypass a startup refusal by restoring retired writer credentials.
Validate
- The expected stacks completed without unresolved failed resources.
- The application loads at the intended HTTPS hostname.
- Activation reflects your agreement and required service checks succeed.
- A real test request produced the expected activity and policy result.
Record the release, completion time and remaining issues. Stack completion alone does not verify an AI workflow.
Check Activity after an update
Retain the deployment's approved database memory allocation when updating or replacing the runtime. Allow Analytics its 90-second shutdown grace period so an in-progress summary refresh can finish before the service is stopped.
After the update, open Activity, load the next page, and apply a policy-decision filter. Confirm that each request loads the expected sessions. Activity unavailable means the session list could not be loaded; it does not establish that no activity occurred. If it persists, give your deployment administrator the release, time, and visible error so they can check summary refresh health and database capacity.
Known-system evidence prerequisites
Helm deployments use an authenticated Analytics-to-Discovery read to combine
current system inventory with recorded activity. Configure the shared internal authentication secret
through discovery.internalAPIKeySecretName, containing INTERNAL_API_KEY_DISCOVERY.
When that setting is empty, an enabled monitoring configuration supplies its
existing authentication Secret; an explicit value must name that same Secret
while monitoring is enabled. Otherwise the inventory source remains
unconfigured. Do not paste the secret into application configuration or tickets.
The chart permits only the required Analytics-to-Discovery service connection within the deployment; default-deny networking remains in place. Check both the authentication configuration and that specific network path if inventory is unavailable. A missing source is not an empty inventory or a protection guarantee.
Dashboard history prerequisites
For Helm deployments using recorded dashboard history, provide the existing
Analytics service-authentication Secret to both Analytics and Gateway through
analytics.internalAPIKeySecretName. With monitoring enabled, it must be the
same Secret used for monitoring authentication. The chart uses its Gateway
service by default; an explicit analytics.env.GATEWAY_URL is retained.
Unavailable tenant-lifecycle information pauses history collection rather than
guessing whether a tenant exists. Finding reconciliation continues independently.
Review the recorded-history source state and background maintenance failures
before relying on a trend; an application health check alone does not prove
history is being collected.
Policy review and notification checks
For an update containing policy-owned Findings, check the saved policy's review choice separately from its enforcement action. Activity-only matches stay in Activity; a policy that requests review creates a Finding for its recorded match. Choosing review and notification also requires a configured notification channel and matching rule. Historical decisions without a recorded review choice do not gain one merely because the installation was updated.
Helm packages for this update add tutela.runtime.invocations to
notification.env.KAFKA_TOPICS so the notification service can consume original
tool-access decisions. If you override that topic list, include this topic while
retaining the other required subscriptions. Confirm the notification consumer's
broker access; preserve its existing consumer group and offsets during the
update. Adding a topic does not itself enable notifications for every tool call.
Use a synthetic request that matches a policy requesting review and notification. Verify the original decision in Activity, its Finding, and the configured channel's delivery history separately. Also check that an Activity-only match does not create a policy Finding or notification. Missing delivery requires checking the saved policy choice, rule, channel and collection state; a healthy stack alone does not establish delivery.