Install with Helm
Overview
Section titled “Overview”This guide installs the PIG trace analyzer on an existing Kubernetes cluster. It is the default installation, and every cloud guide finishes with it. A one-time Helm bootstrap installs the supervisor and the HTTPS collector Ingress. A PIGDeployment resource then connects the analyzer to your database, trace bucket, and model. The supervisor installs the analyzer and keeps it updated from published releases.
Use it once your database, trace storage, workload identity, and hostname are ready. If your operations team must apply every upgrade itself, use manual Helm management instead. The installation path shows where this guide fits.
The current stable release, PIG 0.3.6, targets AWS with EKS. Azure with AKS and Google Cloud with GKE are experimental. Every command and example on this page is for 0.3.6.
Before you begin
Section titled “Before you begin”- Complete deployment planning, including analyzer registration. Keep the one-time analyzer credential in your secret manager.
- Have a dedicated PostgreSQL 15–18 database, exactly one native object-storage location, an analyzer workload identity, and a hostname with a certificate. The AWS, Azure, and Google Cloud guides provision these with Terraform and save a
deployment-configuration.jsonfile used below. - Use Kubernetes 1.30 or later and
kubectlwith permission to create namespaces, custom resource definitions, and cluster-scoped RBAC. - Install Helm 3.8 or later,
curl,jq, andsha256sum. On macOS, useshasum -a 256wherever this guide runssha256sum. - Have an ingress controller in the cluster that can serve HTTPS for your hostname to every enrolled host.
This guide uses namespace pig for the analyzer, pig-system for the supervisor, deployment name acme, and hostname traces.acme.example. Replace them consistently. The analyzer Service and the collector Ingress are both named after the deployment: acme-analyzer.
To hand this installation to a coding agent, copy this prompt. Set up PIG with a coding agent covers the whole setup.
Install the PIG trace analyzer on our Kubernetes cluster with the Helmbootstrap. Followhttps://promptless.ai/docs/governance/deploy-the-worker/deploy-the-analyzer-worker.mdand phase 5 of https://promptless.ai/docs/governance/agent-setup-guide.md
Outcome: a verified release, a ready PIGDeployment, and HTTPS health androuting checks passing from the enrolled hosts' network.Inputs (discover these before you ask me):- Kubernetes context: [context name]- Deployment name and hostname: [for example, acme and traces.acme.example]- Ingress controller and certificate: [for example, ingress-nginx with a TLS Secret, or AWS Load Balancer Controller with an ACM certificate]- Storage and model settings: [Terraform output file, or where to find them]- Secret names: [secret-manager entries for the analyzer credential, database connection string, and model key]
Show me the checksum results, the rendered chart, and the server-side dryrun, and wait for my approval before `helm install` and `kubectl apply`.Report the deployment conditions, the health and routing checks, andanything still blocked.Who owns each resource
Section titled “Who owns each resource”Each resource has one owner:
- Terraform owns cloud infrastructure.
- Your Kubernetes configuration owns the namespaces, ServiceAccount, Secrets, CA ConfigMap, certificates, and
PIGDeploymentspec. - The
pig-supervisorHelm release owns the supervisor and the collector Ingress. - The supervisor owns the analyzer workloads it generates and its own updates.
A second controller that reapplies the bootstrap chart or reconciles generated workloads undoes the supervisor’s updates. GitOps ownership lists each resource and how to keep Flux and other controllers within these boundaries.
Security posture
Section titled “Security posture”The supervisor generates the analyzer Deployment and its maintenance Jobs, such as the migration Job, with a restricted security context. The PIGDeployment resource has no fields that change it. Each pod:
- Runs as a non-root user, with the user ID, group ID, and filesystem group all set to
10001. - Uses a read-only root filesystem, drops all Linux capabilities, and blocks privilege escalation.
- Runs under the
RuntimeDefaultseccomp profile. - Mounts a writable
/tmpbacked by an ephemeralemptyDir, which gives the container scratch space without a persistent volume.
The manual chart applies the same settings to its analyzer and migration Job, and its values.yaml has no keys that change them.
1. Select and verify a release
Section titled “1. Select and verify a release”In an empty working directory, download the release files from the v0.3.6 release and the public stable catalog. Run the rest of this guide from this directory; PIG_RELEASE_DIR records it for the cloud guides.
PIG_VERSION='0.3.6'PIG_RELEASE_DIR="$PWD"RELEASE_URL="https://github.com/Promptless/pig-deploy/releases/download/v${PIG_VERSION}"for file in release.json SHA256SUMS "pig-supervisor-${PIG_VERSION}.tgz" "pig-deploy-${PIG_VERSION}.tar.gz"; do curl --fail --silent --show-error --location --remote-name "${RELEASE_URL}/${file}"donecurl --fail --silent --show-error --location --output stable.json \ https://raw.githubusercontent.com/Promptless/pig-deploy/main/catalog/stable.jsonCheck the downloaded archives and the release manifest:
grep -E " (pig-supervisor|pig-deploy)-${PIG_VERSION}\.t" SHA256SUMS | sha256sum --checkjq -r --arg v "$PIG_VERSION" '.releases[] | select(.version == $v) | .sha256' stable.jsonsha256sum release.jsonjq -r '.artifacts.supervisorChart.sha256' release.jsonBoth archives must report OK. The catalog digest must equal the release.json digest, and the manifest’s chart digest must equal the chart archive’s digest from SHA256SUMS. For 0.3.6, expect these values:
| File | SHA-256 |
|---|---|
release.json | a4eafe78f13c7748d446fa149f60a4071a92cfb276d3ca7a8e4c98cca32af977 |
pig-supervisor-0.3.6.tgz | 5fc16c87f3db452e6d831b7f31c75a61e5f79c9ac8483dda037e3e34b90bb74b |
pig-deploy-0.3.6.tar.gz | 993bf8405b5972d8cc22d18fc0d79a371691cf9128c23ddd5fce747ad502cd43 |
Stop if any value differs. Review the release requirements before you continue:
jq '.requirements | {kubernetesMin, postgresMin, postgresMax, storageBackends, schemaTo}' release.jsonKeep these files, your bootstrap values, and your PIGDeployment manifest with your recovery records. The pig-deploy-0.3.6.tar.gz archive contains the Terraform examples used by the cloud guides.
2. Create the namespaces and analyzer ServiceAccount
Section titled “2. Create the namespaces and analyzer ServiceAccount”-
Confirm the cluster and create the namespaces.
Terminal window kubectl config current-contextkubectl create namespace pig --dry-run=client -o yaml | kubectl apply -f -kubectl create namespace pig-system --dry-run=client -o yaml | kubectl apply -f - -
Create the analyzer ServiceAccount. The analyzer and its maintenance Jobs share this account. Copy
service_account_annotationsfrom your Terraform output, such aseks.amazonaws.com/role-arnon AWS.analyzer-service-account.yaml apiVersion: v1kind: ServiceAccountmetadata:name: pig-analyzernamespace: pigannotations:eks.amazonaws.com/role-arn: REPLACE_WITH_TERRAFORM_OUTPUT # From service_account_annotationsTerminal window kubectl apply -f analyzer-service-account.yamlTerraform owns the cloud role and its trust policy. Keep the ServiceAccount namespace and name that Terraform configured in that trust policy.
3. Deliver secrets and the database CA
Section titled “3. Deliver secrets and the database CA”Create these objects in namespace pig before you create the PIGDeployment. Deliver Secret values through your secret manager, such as an External Secrets Operator resource. Keep values out of Git, Helm values, and command arguments.
| Object | Key | Value |
|---|---|---|
Secret pig-credentials | install-token | The analyzer credential from registration. |
Secret pig-credentials | postgres-dsn | The application connection string, with sslmode=verify-full. |
Secret pig-credentials | model-api-key | The model key for authentication: api_key. Omit it for Bedrock with aws_sigv4. |
ConfigMap pig-postgres-ca | ca.pem | The CA bundle that verifies your database certificate, such as the RDS regional bundle. |
Secret pig-migration | postgres-dsn | Optional. A schema-owner connection string used only by preflight and migration Jobs. |
Secret pig-tls | tls.crt, tls.key | Your hostname’s certificate and key, when your ingress controller reads certificates from a Secret. |
If you deliver the Secret directly, write each value to a local file with owner-only permissions and create the Secret from the files:
kubectl create secret generic pig-credentials --namespace pig \ --from-file=install-token=./install-token \ --from-file=postgres-dsn=./postgres-dsn \ --from-file=model-api-key=./model-api-keykubectl create configmap pig-postgres-ca --namespace pig --from-file=ca.pem=./ca.pemDelete the local credential files afterward. The CA bundle is public and belongs in a ConfigMap. The supervisor mounts it at /etc/pig/postgres-ca/ca.pem and sets PGSSLROOTCERT for the analyzer and its Jobs.
With one credential, the application role also owns the schema and runs migrations. To keep schema ownership away from the serving analyzer, deliver pig-migration and reference it in the PIGDeployment. The application role then needs data access only. Separate the migration credential shows the connection string format and the role grants.
Confirm the keys without printing values:
kubectl get secret pig-credentials --namespace pig -o json | jq '.data | keys'kubectl get configmap pig-postgres-ca --namespace pig -o json | jq '.data | keys'4. Bootstrap the supervisor and collector Ingress
Section titled “4. Bootstrap the supervisor and collector Ingress”The bootstrap values set the namespace the supervisor watches and configure the collector Ingress. ingress.serviceName, ingress.hostname, and ingress.ingressClassName are required, and the chart fails to render without them. Choose the values for your ingress controller:
For ingress-nginx and other controllers that read the certificate from Secret pig-tls:
watchNamespace: pigingress: serviceName: acme-analyzer # Your PIGDeployment name plus -analyzer hostname: traces.acme.example ingressClassName: nginx tlsSecretName: pig-tls # A TLS Secret in namespace pig annotations: nginx.ingress.kubernetes.io/ssl-redirect: "true" nginx.ingress.kubernetes.io/proxy-body-size: "256m"For the AWS Load Balancer Controller with an ACM certificate. Deploy on AWS lists the prerequisites.
watchNamespace: pigingress: serviceName: acme-analyzer # Your PIGDeployment name plus -analyzer hostname: traces.acme.example ingressClassName: alb annotations: alb.ingress.kubernetes.io/scheme: internet-facing alb.ingress.kubernetes.io/target-type: ip alb.ingress.kubernetes.io/certificate-arn: REPLACE_ACM_CERTIFICATE_ARN alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]' alb.ingress.kubernetes.io/healthcheck-path: /healthzOmit tlsSecretName; the load balancer uses the ACM certificate. Use scheme: internal only when every enrolled host can reach the private address.
The Ingress exposes only the five collector routes and is created in watchNamespace. The 256m request-body limit accepts the collector’s largest request with room to spare; networking explains the limits for other proxies. Bootstrap chart values lists every field.
Lint and render the verified chart. Review the supervisor image digest, the custom resource definition, the RBAC, and the Ingress in the output:
helm lint "./pig-supervisor-${PIG_VERSION}.tgz" --values supervisor-values.yamlhelm template pig-supervisor "./pig-supervisor-${PIG_VERSION}.tgz" \ --namespace pig-system --values supervisor-values.yaml > rendered-supervisor.yamlThen install it:
helm install pig-supervisor "./pig-supervisor-${PIG_VERSION}.tgz" \ --namespace pig-system --values supervisor-values.yaml \ --wait --timeout 10mThe supervisor starts and waits for a PIGDeployment. The Ingress has no backend until the analyzer starts.
5. Create the PIGDeployment
Section titled “5. Create the PIGDeployment”Save the resource below. It uses S3 and OpenAI. Replace the storage block with the single block from deployment_configuration.storage, copy pod_labels into spec.podLabels, and set your model settings.
apiVersion: governance.promptless.ai/v1alpha1kind: PIGDeploymentmetadata: name: acme # The analyzer Service and Ingress are named acme-analyzer. namespace: pigspec: release: channel: stable paused: false pinnedVersion: "" # Set to "0.3.6" to hold the release you verified. serviceAccountName: pig-analyzer podLabels: {} # Copy deployment_configuration.pod_labels from Terraform. hosted: installTokenSecretRef: name: pig-credentials key: install-token storage: postgres: dsnSecretRef: name: pig-credentials key: postgres-dsn # Optional schema-owner credential used only by preflight and migration Jobs. # migrationDsnSecretRef: # name: pig-migration # key: postgres-dsn caConfigMapRef: name: pig-postgres-ca key: ca.pem # Exactly one storage block, copied from deployment_configuration.storage. s3: region: us-west-2 bucket: acme-pig-traces # Your trace bucket prefix: acme/traces analysis: activationAt: "2026-10-15T00:00:00Z" # Sessions with activity at or after this time are eligible. quietWindowHours: 0.5 model: provider: openai authentication: api_key baseURL: https://api.openai.com/v1 name: REPLACE_MODEL_NAME apiKeySecretRef: name: pig-credentials key: model-api-keyUse a deployment name of at most 54 lowercase letters, digits, or hyphens that starts with a letter and ends with a letter or digit. It must match ingress.serviceName without the -analyzer suffix.
The release policy controls every later update:
channel: stablewith an emptypinnedVersioninstalls the highest stable release and follows each new one, including schema migrations.pinnedVersionholds an exact published release, such as the0.3.6you verified.paused: truestops release transitions. A pause before the first install blocks installation.
Updates and recovery explains pausing, pinning, and blocked updates. Release 0.3.6 needs no release confirmation ConfigMap; add spec.release.confirmation only when a target release requires one.
Validate the resource against the installed custom resource definition, then apply it through its owner:
kubectl apply --dry-run=server -f pig-deployment.yamlkubectl apply -f pig-deployment.yamlkubectl get pigdeployment acme --namespace pig --watchThe supervisor checks PostgreSQL, TLS, and object read and write access, applies schema migrations, starts acme-analyzer, and verifies its connection to Promptless. When the installation completes, it reports Ready=True. A dependency failure reports Blocked=True with the Job to inspect:
kubectl describe pigdeployment acme --namespace pigkubectl logs deployment/pig-supervisor --namespace pig-system --tail=100Ready=True means the workloads and dependency checks passed. The Acceptance condition stays False with reason AwaitingCanonicalAcceptance until a real session completes the end-to-end verification.
6. Point DNS at the ingress and check HTTPS
Section titled “6. Point DNS at the ingress and check HTTPS”Read the address your ingress controller assigned to the Ingress:
kubectl get ingress acme-analyzer --namespace pig \ -o jsonpath='{.status.loadBalancer.ingress[0]}{"\n"}'Create or update the DNS record for traces.acme.example to point at that address. For an ALB, wait until its targets are healthy first. Then run these checks from the network your enrolled hosts use, not from inside the cluster:
curl --fail --silent --show-error https://traces.acme.example/healthzcurl --silent --output /dev/null --write-out '%{http_code}\n' \ https://traces.acme.example/v0/host-enrollment/policyThe health check returns "status": "ok" and the deployment_instance_id of this installation. The unauthenticated policy request returns 401 from the analyzer, which shows the route reaches it. A 404 means a proxy does not route that path, and a certificate error means the hostname and certificate do not match. Fix these before you enroll a host.
Serve HTTPS directly at this hostname. Hosts use the address without a path, and cloud agents reject redirects. Cloud runners need to reach this address from their sandbox, and Claude Tag needs a public HTTPS endpoint; see cloud agents.
7. Select instruction repositories
Section titled “7. Select instruction repositories”After the analyzer first checks in, its row on the Workers settings page changes from Awaiting connection to Healthy. An organization administrator then chooses the repositories the analyzer reads, on the Instruction repositories card. Analysis reads every selected repository.
- Add a repository. Choose it from Select a repository and select Add. The list shows repositories the connected GitHub App can access; grant the app access to add another.
- Optional. Set repository actions. Turn on Create Repo Issues to open GitHub issues for the repository’s findings. Turn on Propose Remediations to let remediation open pull requests; it requires Create Repo Issues.
- Remove a repository with Remove when the analyzer should stop reading it. Existing findings and pull requests remain.
Each repository needs a main branch, and the GitHub App needs Contents read access to it. Create Repo Issues also needs Issues write access, and Propose Remediations needs Issues, Contents, and Pull requests write access. Members who are not administrators see the selected repositories as a read-only list. For how a finding maps to a repository and its GitHub issue, see Understand findings.
8. Enable trace analysis
Section titled “8. Enable trace analysis”On the Analyzers card of the same page, confirm that your analyzer’s Trace analyzer switch is On. New analyzers start with it on. An organization administrator can set it to Off to stop analyses while uploads continue, and back to On to resume. Each change applies at the analyzer’s next check-in.
Analysis runs only when all of these are true:
- Trace analyzer is On for the analyzer.
- At least one instruction repository is selected.
spec.analysis.activationAtis set, and a session has activity at or after that time.- The session has finished, or its quiet window has passed.
Deployment checks pass while analysis is off or no repository is selected, so Ready=True alone does not show that analysis can run. When you switch analysis on, eligible stored sessions since activationAt become due for analysis.
9. Enroll a host and verify a session
Section titled “9. Enroll a host and verify a session”- Enable trace collection and enroll one pilot host with
https://traces.acme.exampleas the analyzer address. - Run a short session that uses an installed hub skill in a selected repository.
- Verify that session end to end. Check the enrolled host, the stored and readable trace object, a succeeded analysis, and its Dashboard acknowledgement. Zero findings is a valid result.
See also
Section titled “See also”- Verify your deployment, for every check in the end-to-end verification
- Configuration reference, for every
PIGDeploymentand bootstrap chart field - Updates and recovery, for pause and pin controls, backups, and recovery
- Observability, for ongoing monitoring and troubleshooting
- GitOps ownership, to manage the
PIGDeploymentand later Ingress changes through Flux or another controller