Docs

Installation & upgrading

Suggest Edits

This guide walks you through the process of installing and upgrading the Kvisor security agent in your Kubernetes clusters. Kvisor can be installed using various methods, including the Cast AI console UI, Terraform, or Helm.

Prerequisites

Before installing Kvisor, ensure you have:

  • A Kubernetes cluster connected to Cast AI
  • Appropriate permissions to create resources in your cluster
  • Required tools for your chosen installation method (kubectl, helm, etc.)

Installation Methods

Cast AI console

The simplest way to install Kvisor is through the Cast AI console:

  1. Log in to the Cast AI console
  2. Navigate to Security > Settings
  3. Locate your cluster in the list and click on it to expand the security controls
  4. Copy the provided installation script and run it in your terminal or cloud shell

Security Settings

For more detailed instructions, see the Getting started with Security guide.

Terraform

If you manage your infrastructure as code, you can use our Terraform modules for GKE, EKS, and AKS to install Kvisor. Set the install_security_agent=true module input variable:

module "castai-eks-cluster" {
  // ...
  install_security_agent = true
}

For complete examples, see:

Helm

To install Kvisor using Helm, follow these steps:

  1. Add the Cast AI Helm repository:
helm repo add castai-helm https://castai.github.io/helm-charts
helm repo update
  1. (Optional) List available components and versions:
helm search repo castai-helm
  1. Install the Kvisor security agent:
helm upgrade --install castai-kvisor castai-helm/castai-kvisor -n castai-agent \
  --set castai.apiKey=<your-api-token> \
  --set castai.clusterID=<your-cluster-id> \
  --set controller.extraArgs.kube-linter-enabled=true \
  --set controller.extraArgs.image-scan-enabled=true \
  --set controller.extraArgs.kube-bench-enabled=true \
  --set controller.extraArgs.cloud-provider=<aks|eks|gke>

Replace the placeholders with your actual values:

  • <your-api-token>: Your Cast AI API token
  • <your-cluster-id>: Your cluster's ID in Cast AI
  • <aks|eks|gke>: Your Kubernetes provider (leave empty if not using these platforms)

Upgrading Kvisor

Cast AI Console

The easiest way to keep Kvisor up to date is through the Component Control dashboard:

  1. In the Cast AI console, select Manage Organization in the top right
  2. Navigate to Component control in the left menu
  3. Find Kvisor in the component list
  4. For any cluster showing a warning status, click on the component to see details
  5. Click the Update button to get the upgrade script
  6. Copy and run the provided command in your terminal

Component Control Dashboard

This approach ensures you're always running the latest version with all security updates and feature enhancements.

Helm

If you installed Kvisor with Helm, you can upgrade it with:

helm repo update castai-helm
helm upgrade --install castai-kvisor castai-helm/castai-kvisor -n castai-agent --reset-then-reuse-values

The --reset-then-reuse-values flag preserves your existing configuration while applying the latest updates.

Upgrading from v0.x.x to v1.x.x

The Kvisor v1 Helm chart contains breaking changes requiring a fresh installation. Follow these steps:

  1. Get your current Kvisor values:
helm get values castai-kvisor -n castai-agent

  1. Note your clusterID, apiKey, and kube-bench provider for use in the next step.

  2. Reinstall Kvisor with your values:

helm repo update castai-helm

helm upgrade --install castai-kvisor castai-helm/castai-kvisor -n castai-agent \
  --set castai.apiKey=<your-api-token> \
  --set castai.clusterID=<your-cluster-id> \
  --set controller.extraArgs.kube-linter-enabled=true \
  --set controller.extraArgs.image-scan-enabled=true \
  --set controller.extraArgs.kube-bench-enabled=true \
  --set controller.extraArgs.cloud-provider=<aks|eks|gke>

Troubleshooting

If you encounter issues with Kvisor installation or upgrades, try these troubleshooting steps:

Check the Kvisor controller logs

kubectl logs -l app.kubernetes.io/name=castai-kvisor-controller -n castai-agent

Check the Kvisor agent logs

kubectl logs -l app.kubernetes.io/name=castai-kvisor-agent -n castai-agent

Verify your configuration

helm get values castai-kvisor -n castai-agent

Check component status in the console

You can also verify the status of Kvisor in the Cast AI console by navigating to Security > Settings and checking the status indicators next to your cluster.

For additional assistance, contact Cast AI support or visit our community Slack channel.

Next Steps

Once you have Kvisor installed, you can configure various security features:

Updated 5 days ago