Skip to content

Usage Instructions

ClairAI Observability Platform — AWS Marketplace Usage Instructions

Field Value
Document AWS Marketplace Usage Instructions
Version internal-testing-v1.1.1
Publisher Info Services
Delivery Type Helm-based container product for Amazon EKS
Target Platform Amazon EKS
Chart Version 0.1.0

Topics

1. Purpose and AWS Marketplace Coverage

This document provides buyer-facing instructions to deploy, configure, validate, monitor, upgrade, and uninstall ClairAI as an AWS Marketplace Helm-based container product on Amazon EKS.

AWS Marketplace requirement How this document satisfies it
Configuration and launch steps Includes subscription, Helm registry authentication, namespace creation, values.yaml examples, and Helm install commands.
All information needed to run the product Includes prerequisites, supported platform, component images, optional dependencies, health checks, monitoring, troubleshooting, upgrade, and uninstall steps.
Sensitive information locations Documents Kubernetes Secrets, AWS Secrets Manager, and Secrets Store CSI Driver usage; instructs buyers not to place secrets directly in values.yaml.
Encryption and cryptographic material Documents Kubernetes secret encryption responsibilities, AWS Secrets Manager/KMS guidance, TLS responsibility, and rotation expectations.
Health and proper function monitoring Includes pod/service/ingress checks, health endpoints, YACE metrics validation, Kubernetes events, and log commands.
Service quota and pricing guidance Includes EKS, EC2, EBS, ALB, CloudWatch, Secrets Manager, and AMP cost/quota guidance.
Upgrade instructions Includes Helm upgrade commands and backup recommendations.

2. Product Overview

ClairAI is a cloud-native observability platform for Amazon EKS environments. The platform provides monitoring, operational visibility, metrics collection, and AI-assisted operational insights for Kubernetes workloads and AWS-integrated environments.

  • ClairAI Backend
  • ClairAI Frontend
  • ClairAI Agent
  • YACE monitoring services

Buyers deploy ClairAI into their own AWS account and EKS cluster. Buyers do not need to build Docker images, push images to ECR, access source code repositories, or run CI/CD pipelines to deploy the Marketplace release.

3. AWS Marketplace Delivery Information

Component Marketplace image
Backend 709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai:internal-testing-v1.1.1-backend
Frontend 709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai:internal-testing-v1.1.1-frontend
Agent 709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai:internal-testing-v1.1.1-agent
YACE 709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai:internal-testing-v1.1.1-yace
Helm OCI artifact oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai
Chart version 0.1.0

Container image references are configurable through values.yaml. Do not hardcode Marketplace image references in Helm templates. For regionalized Marketplace publishing, update image.registry, image.repository, and image.tag values as provided by AWS Marketplace for the buyer region.

4. Prerequisites

4.1 AWS prerequisites

  • Active AWS account
  • Active AWS Marketplace subscription for ClairAI
  • Existing Amazon EKS cluster or a newly provisioned compatible EKS cluster
  • AWS CLI configured for the target account and region
  • kubectl configured for the target EKS cluster
  • Helm 3.8 or later with OCI registry support. For Marketplace add-on validation, use Helm 3.19.0 or later where applicable.

4.2 Kubernetes prerequisites

Item Recommended value
Kubernetes version 1.29 or later
Worker nodes Minimum 3 nodes for production-like deployment
Architecture ARM64 or x86_64
Storage gp3 recommended
Ingress AWS Load Balancer Controller required only when ALB ingress is enabled

4.3 Optional integrations

  • AWS Load Balancer Controller
  • AWS Secrets Manager
  • Secrets Store CSI Driver
  • Grafana
  • Amazon Managed Service for Prometheus (AMP)
  • Loki
  • Tempo
  • Cognito or Azure AD for identity integration

Enable optional integrations only when required by the buyer deployment. Optional integrations may create additional AWS resources and costs.

5. Subscribe to ClairAI

  1. Open AWS Marketplace.
  2. Search for ClairAI.
  3. Open the product listing.
  4. Choose the applicable purchase or subscription option.
  5. Accept the subscription terms.
  6. Wait until the subscription is active before pulling the Helm chart or container images.

6. Authenticate Helm to AWS Marketplace ECR

aws ecr get-login-password --region us-east-1 |
helm registry login 709825985650.dkr.ecr.us-east-1.amazonaws.com \
  --username AWS \
  --password-stdin

6.1 Validate chart access

helm pull oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version 0.1.0

If this command fails with access denied, verify that the AWS Marketplace subscription is active and that the AWS CLI identity has permission to pull from Marketplace ECR.

7. Create Kubernetes Namespaces

kubectl create namespace backend
kubectl create namespace frontend
kubectl create namespace clairai-agent
kubectl create namespace clairai-metrics-manager

8. IAM Roles for Service Accounts (IRSA)

Use IRSA when ClairAI workloads require AWS API access. Setup permissions should remain separate from runtime pod permissions. Application pods should receive only the minimum runtime permissions required.

8.1 Example YACE CloudWatch read policy

Save the following policy document as cloudwatch-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics",
        "ec2:DescribeInstances",
        "ec2:DescribeRegions",
        "elasticloadbalancing:DescribeLoadBalancers",
        "elasticloadbalancing:DescribeTargetGroups"
      ],
      "Resource": "*"
    }
  ]
}

Create the IAM policy:

aws iam create-policy \
  --policy-name ClairAICloudWatchPolicy \
  --policy-document file://cloudwatch-policy.json

8.2 Example IRSA service account

eksctl create iamserviceaccount \
  --cluster <YOUR_CLUSTER_NAME> \
  --namespace clairai-metrics-manager \
  --name clairai-yace-sa \
  --role-name ClairAIYaceRole \
  --attach-policy-arn arn:aws:iam::<ACCOUNT_ID>:policy/ClairAICloudWatchPolicy \
  --approve

9. Secret Management, Sensitive Data, and Encryption

Do not store passwords, API keys, private keys, tokens, certificates, or other sensitive values directly in values.yaml. Store sensitive values in one of the supported secret locations below and reference the secret name from values.yaml.

Sensitive item Recommended storage location Buyer action
Application secret values Kubernetes Secret in the same namespace as the component Create the Secret before installing the chart and reference the Secret name.
Cloud/API keys AWS Secrets Manager or Kubernetes Secret Use Secrets Store CSI Driver or Kubernetes Secret references. Do not place raw keys in values.yaml.
TLS certificates AWS Certificate Manager for ALB or Kubernetes TLS Secret Manage certificate issuance, renewal, and rotation outside the container image.
IRSA credentials AWS STS temporary credentials delivered through IRSA Do not pass long-lived AWS access keys to pods.

9.1 Create a Kubernetes Secret

kubectl create secret generic clairai-secrets \
  --namespace backend \
  --from-literal=SECRET_KEY="<YOUR_SECRET>" \
  --from-literal=API_KEY="<YOUR_API_KEY>"

9.2 Example Secrets Store CSI Driver configuration values

secretProviderClass:
  enabled: true
  name: clairai-agent-secrets
  provider: aws
  region: us-east-1

9.3 Encryption guidance

  • Enable Kubernetes secret encryption at rest in the EKS cluster where required by the buyer security policy.
  • Use AWS Secrets Manager with AWS KMS customer managed keys when the buyer requires centralized secret rotation and auditability.
  • Use TLS for external application endpoints exposed through ingress or load balancers.
  • Rotate application secrets, TLS certificates, and KMS keys according to the buyer security policy. ClairAI images must not contain private keys or hardcoded credentials.

10. Configure values.yaml

Create a component-specific values.yaml file for each ClairAI component. Modify only values.yaml files when configuring the chart. Avoid using --set for Marketplace deployment instructions so configuration remains auditable and repeatable.

10.1 Common configurable parameters

Parameter Purpose Example
image.registry Marketplace ECR registry host 709825985650.dkr.ecr.us-east-1.amazonaws.com
image.repository Marketplace repository path info-services/clairai
image.tag Component image tag internal-testing-v1.1.1-backend
replicaCount Number of pods to run 2
service.type Kubernetes Service type ClusterIP
serviceAccount.create Create a service account for the component true
serviceAccount.name Service account name to use clairai-backend-sa
ingress.enabled Enable ingress for external access true or false
resources CPU and memory requests/limits Set per buyer workload requirements
nodeSelector/tolerations/affinity Scheduling controls Optional
secretProviderClass.enabled Enable Secrets Store CSI integration true or false

11. Deploy ClairAI Backend

11.1 Example values-clairai-backend.yaml

image:
  registry: "709825985650.dkr.ecr.us-east-1.amazonaws.com"
  repository: "info-services/clairai"
  tag: "internal-testing-v1.1.1-backend"
  pullPolicy: IfNotPresent
replicaCount: 2
serviceAccount:
  create: true
  name: clairai-backend-sa
service:
  type: ClusterIP
  ports:
    - name: http
      port: 80
      targetPort: 8000
env:
  - name: ENVIRONMENT
    value: "production"
ingress:
  enabled: true
livenessProbe:
  enabled: true
  httpGet:
    path: /health/
    port: 8000
readinessProbe:
  enabled: true
  httpGet:
    path: /health/
    port: 8000

11.2 Install Backend

helm install clairai-backend oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version 0.1.0 \
  --namespace backend \
  --create-namespace \
  --values values-clairai-backend.yaml \
  --wait \
  --timeout 15m

12. Deploy ClairAI Frontend

12.1 Example values-clairai-frontend.yaml

image:
  registry: "709825985650.dkr.ecr.us-east-1.amazonaws.com"
  repository: "info-services/clairai"
  tag: "internal-testing-v1.1.1-frontend"
  pullPolicy: IfNotPresent
replicaCount: 2
serviceAccount:
  create: true
  name: clairai-frontend-sa
service:
  type: ClusterIP
  ports:
    - name: http
      port: 80
      targetPort: 80
env:
  - name: REACT_APP_API_URL
    value: "https://<BACKEND_HOST>"
ingress:
  enabled: true
livenessProbe:
  enabled: true
  httpGet:
    path: /
    port: 80
readinessProbe:
  enabled: true
  httpGet:
    path: /
    port: 80

12.2 Install Frontend

helm install clairai-frontend oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version 0.1.0 \
  --namespace frontend \
  --create-namespace \
  --values values-clairai-frontend.yaml \
  --wait \
  --timeout 15m

13. Deploy ClairAI Agent

13.1 Example values-clairai-agent.yaml

image:
  registry: "709825985650.dkr.ecr.us-east-1.amazonaws.com"
  repository: "info-services/clairai"
  tag: "internal-testing-v1.1.1-agent"
  pullPolicy: IfNotPresent
replicaCount: 3
serviceAccount:
  create: true
  name: k8s-config-service-sa
service:
  type: ClusterIP
  ports:
    - name: http
      port: 80
      targetPort: 8001
env:
  - name: API_HOST
    value: "0.0.0.0"
  - name: API_PORT
    value: "8001"
  - name: ENVIRONMENT
    value: "production"
  - name: AWS_REGION
    value: "us-east-1"
secretProviderClass:
  enabled: true
  name: clairai-agent-secrets
  provider: aws
  region: us-east-1
ingress:
  enabled: true
livenessProbe:
  enabled: true
  httpGet:
    path: /health
    port: 8001
readinessProbe:
  enabled: true
  httpGet:
    path: /health
    port: 8001

13.2 Install Agent

helm install clairai-agent oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version 0.1.0 \
  --namespace clairai-agent \
  --create-namespace \
  --values values-clairai-agent.yaml \
  --wait \
  --timeout 15m

14. Deploy YACE Monitoring Services

14.1 Example values-yace.yaml

image:
  registry: "709825985650.dkr.ecr.us-east-1.amazonaws.com"
  repository: "info-services/clairai"
  tag: "internal-testing-v1.1.1-yace"
  pullPolicy: IfNotPresent
replicaCount: 1
serviceAccount:
  create: true
  name: clairai-yace-sa
service:
  type: ClusterIP
  ports:
    - name: metrics
      port: 9090
      targetPort: 9090
env:
  - name: AWS_REGION
    value: "us-east-1"
livenessProbe:
  enabled: true
  httpGet:
    path: /metrics
    port: 9090
readinessProbe:
  enabled: true
  httpGet:
    path: /metrics
    port: 9090

14.2 Install YACE

helm install clairai-yace oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version 0.1.0 \
  --namespace clairai-metrics-manager \
  --create-namespace \
  --values values-yace.yaml \
  --wait \
  --timeout 15m

15. Validate Deployment and Application Health

Validation Command or action Expected result
Pods kubectl get pods -A ClairAI pods are Running and Ready.
Services kubectl get svc -A Services exist in backend, frontend, clairai-agent, and clairai-metrics-manager namespaces.
Ingress kubectl get ingress -A Ingress resources show an ADDRESS when ingress is enabled.
Backend health curl -k https://<BACKEND_HOST>/health/ HTTP 200 or healthy status response.
Frontend access Open https://<FRONTEND_HOST> in a browser ClairAI UI loads.
YACE metrics Port-forward YACE and curl /metrics Prometheus-style metrics are returned.

Run these commands to validate the deployment:

kubectl get pods -A
kubectl get svc -A
kubectl get ingress -A
curl -k https://<BACKEND_HOST>/health/
kubectl port-forward -n clairai-metrics-manager svc/clairai-yace 9090:9090
curl http://localhost:9090/metrics

16. Monitoring and Logs

ClairAI can be monitored using Kubernetes commands and the buyer observability stack. Optional integrations may include Grafana dashboards, Prometheus-compatible metrics scraping, CloudWatch metrics collection, Loki logs, and Tempo traces.

16.1 Kubernetes log commands

kubectl logs -n backend deployment/clairai-backend
kubectl logs -n frontend deployment/clairai-frontend
kubectl logs -n clairai-agent deployment/clairai-agent
kubectl logs -n clairai-metrics-manager deployment/clairai-yace

16.2 Events and diagnostics

kubectl get events -A --sort-by='.lastTimestamp'
kubectl describe pod <POD_NAME> -n <NAMESPACE>
kubectl rollout status deployment/<DEPLOYMENT_NAME> -n <NAMESPACE>
  • Pod restart count greater than expected baseline
  • Deployment unavailable replicas greater than zero
  • Ingress or ALB provisioning failure
  • Backend /health/ endpoint failure
  • YACE /metrics endpoint failure
  • CloudWatch API throttling or authorization errors
  • High CPU or memory usage relative to requests/limits

17. Upgrade Instructions

Before upgrading, back up values.yaml files, Kubernetes Secrets, SecretProviderClass objects, ingress configuration, and any monitoring dashboards or alert rules created outside the Helm chart. Validate upgrades in a non-production environment before production rollout.

helm upgrade clairai-backend oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version <NEW_CHART_VERSION> \
  --namespace backend \
  --values values-clairai-backend.yaml \
  --wait
helm upgrade clairai-frontend oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version <NEW_CHART_VERSION> \
  --namespace frontend \
  --values values-clairai-frontend.yaml \
  --wait
helm upgrade clairai-agent oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version <NEW_CHART_VERSION> \
  --namespace clairai-agent \
  --values values-clairai-agent.yaml \
  --wait
helm upgrade clairai-yace oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai \
  --version <NEW_CHART_VERSION> \
  --namespace clairai-metrics-manager \
  --values values-yace.yaml \
  --wait

If an upgrade fails, review Helm status and Kubernetes events. Roll back only after confirming the previous chart version and values files are available.

helm status <RELEASE_NAME> -n <NAMESPACE>
helm history <RELEASE_NAME> -n <NAMESPACE>
helm rollback <RELEASE_NAME> <REVISION> -n <NAMESPACE> --wait

18. Backup and Recovery

  • Back up all component values.yaml files.
  • Back up Kubernetes Secrets or verify that the source secrets exist in AWS Secrets Manager.
  • Back up SecretProviderClass manifests if used.
  • Back up ingress and DNS configuration.
  • Back up Grafana dashboards, alert rules, and external monitoring configuration if configured outside the Helm chart.
  • For proprietary or external data stores used by the buyer, follow the backup and recovery procedure for that data store. ClairAI deployment instructions do not require a proprietary data store by default.

19. Uninstall Instructions

helm uninstall clairai-backend -n backend
helm uninstall clairai-frontend -n frontend
helm uninstall clairai-agent -n clairai-agent
helm uninstall clairai-yace -n clairai-metrics-manager

19.1 Optional namespace cleanup

kubectl delete namespace backend
kubectl delete namespace frontend
kubectl delete namespace clairai-agent
kubectl delete namespace clairai-metrics-manager

Before deleting namespaces, confirm that the namespaces do not contain buyer-created secrets, monitoring configuration, or other workloads that must be retained.

20. Troubleshooting

Issue Possible cause Resolution
ImagePullBackOff Marketplace ECR authentication or inactive subscription Re-run Helm registry login and verify Marketplace subscription status.
Pods pending Insufficient CPU/memory or scheduling constraints Scale worker nodes or review nodeSelector, tolerations, and affinity.
Backend health check failing Configuration, secret, or dependency issue Review backend pod logs and values.yaml references.
Ingress not provisioned AWS Load Balancer Controller missing or misconfigured Verify controller, subnet tags, ingress annotations, and security groups.
YACE metrics unavailable IRSA or CloudWatch permissions issue Verify service account annotation and IAM policy permissions.
Access denied pulling chart/image Wrong AWS identity, region, or subscription state Confirm AWS CLI identity and Marketplace subscription activation.

Use these commands for general diagnostics:

kubectl describe pod <POD_NAME> -n <NAMESPACE>
kubectl logs <POD_NAME> -n <NAMESPACE>
kubectl get events -n <NAMESPACE> --sort-by='.lastTimestamp'
helm status <RELEASE_NAME> -n <NAMESPACE>

20.1 Optional image pull validation

aws ecr get-login-password --region us-east-1 |
docker login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com
docker pull 709825985650.dkr.ecr.us-east-1.amazonaws.com/info-services/clairai:internal-testing-v1.1.1-backend

Docker is optional and intended only for troubleshooting Marketplace image access issues.

21. AWS Service Quotas and Cost Guidance

Buyer AWS costs depend on the resources used in the buyer account. Review service quotas before production deployment and request quota increases where required.

AWS service/resource Quota or cost consideration
Amazon EKS Cluster and managed node group costs apply. Verify cluster, node group, and pod density limits.
Amazon EC2 Worker node instance costs apply. Size nodes for Backend, Frontend, Agent, and YACE workloads.
Amazon EBS Persistent volume costs apply if enabled. gp3 is recommended for predictable baseline performance.
Application Load Balancer ALB hourly and LCU charges apply when ingress is enabled.
Amazon CloudWatch Metrics, logs, dashboards, alarms, and API usage may incur charges.
AWS Secrets Manager Secret storage and API call charges apply if Secrets Manager is used.
Amazon Managed Service for Prometheus Ingestion, storage, and query charges apply if AMP is enabled.

For high-volume metric collection, tune scrape intervals, namespace selection, and metric filters to control ingestion cost and API usage. Monitor CloudWatch and AMP usage against buyer budget and quota policies.

22. Support

Support is available through the AWS Marketplace support channel. Include the following information when opening a support case:

  • AWS Region
  • Kubernetes version
  • Helm chart version
  • Namespace
  • Helm release name
  • Pod status
  • Relevant pod logs
  • values.yaml with secrets removed
  • Ingress status
  • Any recent upgrade or configuration change

23. References

  • AWS Marketplace Seller Guide: Creating AMI and container product usage instructions
  • AWS Marketplace Seller Guide: Container-based product requirements for AWS Marketplace