Install Kerno

Learn how to install Kerno on your Kubernetes cluster

Before installing Kerno, please make sure you meet the requirements.

The first step is to go to app.kerno.io, sign up using your email address, and follow the onboarding instructions.

When installing Kerno for the first time, you'll be asked to create an organization.

Enter your organization's name, then click Create Organization to proceed.

Note: The organization name will also be used to generate a unique slug (URL identifier) for your organization within Kerno. You can edit your organization's name and URL later.

Once your organization is set up, you'll be prompted to register a cluster where Kerno will run.

Enter a name for your cluster. This is how it will appear inside Kerno.

Then click Register Cluster to continue.

Note: You can edit your cluster name later.

IMPORTANT

Your <API-key> is automatically generated when you install Kerno on a new Cluster. You will have one API Key per cluster. You'll need these key to update and delete Kerno. So make sure you store then securely

Install Kerno Using Helm

You can install Kerno using the official Helm chart.

Step 1. Add the Helm Repository

helm repo add kerno https://kernoio.github.io/helm-charts

Step 2. Install the chart

Replace <KERNO_API_KEY> with your API key:

helm install kerno-agent kerno/agent \
  --create-namespace \
  --namespace kerno \
  --set apiKey="<KERNO_API_KEY>"

Step 3. Connect your Object Storage

Kerno stores sensitive data, including logs and traces, inside your AWS accounts and GCP projects within an Object Store. Below are the steps to create and configure access to an object storage resource.

If you don't connect an Object Store, Logs, payloads, and traces will be written to the main container of the nanobe deployment, at /tmp/samples.

These samples are stored in ephemeral storage, which is automatically cleaned up by the container runtime. By default, the ephemeral storage is configured with the following limits:

resources:
  requests:
    ephemeral-storage: "2Gi"
  limits:
    ephemeral-storage: "4Gi"

When the container reaches the 4Gi limit, older data is automatically overwritten to make room for new samples. This ensures the container doesn’t exceed its storage quota, but it also means that sample data is not guaranteed to persist over time.

Step 1. Create an S3 Bucket

Create a bucket in S3 and note the name. This bucket will be used to store Kerno logs and traces.

Step 2. Set Up IAM Role for EKS Access

Create an IAM role that your EKS cluster can assume via its OIDC provider:

Trusted Entity Type: Web Identity
Identity Provider: Use your cluster's OIDC URL
Audience: sts.amazonaws.com
Condition:
- Key: <oidc-url>:sub
- Operator: StringLike
- Value: system:serviceaccount:kerno:*

Trust Policy Example

Replace placeholders with your values:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<account-id>:oidc-provider/<oidc-provider-url-https-prefix-removed>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringLike": {
          "<oidc-provider-url>:sub": "system:serviceaccount:kerno:*"
        },
        "StringEquals": {
          "<oidc-provider-url>:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}

Step 3. Attach Permissions to the IAM Role

Attach an inline policy granting access to the bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:*"],
      "Resource": [
        "arn:aws:s3:::<bucket-name>",
        "arn:aws:s3:::<bucket-name>/*"
      ]
    }
  ]
}

Step 4. Update the Bucket Policy

Allow the IAM role access to the bucket using the role arn from step 2:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<role-arn>"
      },
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::<bucket-name>",
        "arn:aws:s3:::<bucket-name>/*"
      ]
    }
  ]
}

Step 5. Update values.yaml

Set the following values in your values.yaml:

cloud: AWS
bucketName: <bucket-name>
serviceAccountAnnotations:
  eks.amazonaws.com/role-arn: <role-arn>

replacing <bucket-name> and <role-arn>.

An example can be found in examples/aws-values.yaml.

Step 6. Install the Chart Using Your Config

helm install kerno-agent kerno/agent \
  --create-namespace \
  --namespace kerno \
  -f path/to/values.yaml

IMPORTANT

Commit your values.yaml file to version control so it can be reused during upgrades.

Make sure to keep your API key secret by storing it securely outside of the file.

Prerequisites

Ensure that Workload Identity Federation is enabled on the cluster.
Enable the GKE Metadata Server on at least one node pool.

Step 1. Create a Google Service Account

In the GCP project, create a Service Account, noting its email address.

Step 2. Allow Workload Identity Access to the Service Account

Navigate to the Service Account in the IAM console.
Click "Grant Access".
Add the following principal: <project-id>.svc.id.goog[kerno/kerno-sa], replacing <project-id> with the GCP project id.
Select the Service Account Admin role.
Save the configuration.

Step 3. Create a Cloud Storage Bucket

Create a bucket in the same GCP project as the GKE cluster.

Step 4. Grant the Service Account Access to the Bucket

Navigate to the Cloud Storage bucket.
Click "Grant Access".
For Principal, enter the Service Account's email.
For Role, select Storage Admin.
Save the changes.

Step 5. Configure Helm Chart Values

Update your values.yaml with the following content:

cloud: GCP
bucketName: <bucket-name>
serviceAccountAnnotations:
  iam.gke.io/gcp-service-account: <service-account-email>

replacing <bucket-name> and <service-account-email>.

An example can be found in examples/gcp-values.yaml.

6. Install the Chart Using Your Config

helm install kerno-agent kerno/agent \
  --create-namespace \
  --namespace kerno \
  -f path/to/values.yaml

IMPORTANT

Commit your values.yaml file to version control so it can be reused during upgrades.

Make sure to keep your API key secret by storing it securely outside of the file.

Install Kerno Using Docker

Use the Kerno Docker to automate the installation process. The key benefit of this method is that Kerno will automatically provision the required object storage and apply the correct roles and access policies for you.

Prerequisites

Kubernetes RBAC Permissions

You'll need permission to deploy the following Kubernetes objects.

Namespace
Deployment
DaemonSet
ConfigMap
Secret
Service
ServiceAccount
ClusterRole
ClusterRoleBinding

Cloud Permissions

You'll need the following permission for your cloud account:

IAM Role
Role Policy
Bucket
Bucket Policy

Install on AWS

Step 1. Log into AWS with admin privileges.

OIDC (OpenID Connect) Provider

An OIDC Provider is required for your EKS cluster to support Kerno’s functionality. This is typically configured for EKS clusters. Since the OIDC Provider can be used for multiple services, including Kerno, we recommend you manage it within your cluster setup.

Set Up OIDC Provider on EKS »

Depending on whether you have set your AWS credentials as environment variables or in the .aws/credentials Use one of the following methods:

Step 2 [Option 1]. Install Using AWS Config File

Set your AWS Credentials as environment variables, add the missing values to the script, and run the script.

Your <k4-key> is automatically generated when you create your account. Each account has a single key, so store it securely.

Step 2 [Option 2]. Using Environment Variables

Set your AWS Credentials as environment variables, add the missing values to the script, and run the script.

Install on GCP

Step 1. Log into GCP with admin privileges.

To install, a gcloud login must be present on the host machine

Step 2. Add the missing values to the script, and run the script.

If you encounter issues or have questions, message us on Slack, and we’ll gladly help.

Upgrade Kerno

Uninstall Kerno using the same method you used to install it (e.g., Helm, Docker)

helm upgrade --install kerno-agent kerno-dev/agent
--create-namespace
--namespace kerno
--set apiKey="<KERNO_API_KEY>"
--atomic

Uninstall Kerno

Uninstall Kerno using the same method you used to install it (e.g., Helm, Docker). Just run the corresponding uninstall command.

helm uninstall kerno-agent -n kerno

To uninstall using Docker, run the same command you used to install Kerno, but add the uninstall flag.

-e UNINSTALL=true \

Troubleshoot your Installation.

These are some issues you might encounter when installing Kerno and how you can fix them.

Docker doesn't have enough memory

If your Docker doesn't have enough memory to install Kerno, you'll see the following error.

docker run -it --pull always \
-e AWS_REGION=<region> \
-e AWS_PROFILE=<profile> \
-e CLUSTER_NAME=<cluster_name> \
-e K4_KEY=<kerno_api_key> \
-v ~/.aws:/root/.aws \
public.ecr.aws/fyck.io/installer:main


main: Pulling from fyck.io/installer
Digest: sha256:ac79ed7e599bea1bec142fe418a1f1081787b3f537182d02eb35939f8c48d890
Status: Image is up to date for public.ecr.aws/fyck.io/installer:main
INFO: Installation target set to production
Interactive mode detected. Confirmation prompts will be used

Getting installation information from Kerno...
Installation information obtained

Setting Kubernetes context...
Using AWS_REGION [<profile>] and CLUSTER_NAME [<cluster_name>] to set context

Initializing Pulumi stack for Kerno installation...

/entrypoint.sh: line 114:    36 Segmentation fault      pulumi stack select -c "$K4_ID"b

To resolve this issue:

Open Docker Desktop
Go to Settings, then Resources
Increase the allocated memory (add 2–4 GB, depending on your workload)

If the issue continues:

Remove all containers created from the installer image
Delete the installer image
Re-run the installation command

Cloud profile isn't being detected

If you see an error like the one below, it means the selected profile cannot be used to connect to the cluster.


Diagnostics:
  pulumi:pulumi:Stack (installer-ab90fbbe-4d72-45ca-a2a7-ecaf8d9bf667):
    error: preview failed

  aws:s3:BucketV2 (kerno-samples-ab90fbbe-4d72-45ca-a2a7-ecaf8d9bf667):
    error: Preview failed: 1 error occurred:
    	* Retrieving AWS account details: validating provider credentials: retrieving caller identity from STS: operation error STS: GetCallerIdentity, https response error StatusCode: 403, RequestID: ebbb0a6a-494e-4e36-ab5c-bef7d6978b3b, api error InvalidClientTokenId: The security token included in the request is invalid

  aws:s3:BucketPolicy (kerno-samples-ab90fbbe-4d72-45ca-a2a7-ecaf8d9bf667-policy):
    error: Preview failed: 1 error occurred:
    	* Retrieving AWS account details: validating provider credentials: retrieving caller identity from STS: operation error STS: GetCallerIdentity, https response error StatusCode: 403, RequestID: ebbb0a6a-494e-4e36-ab5c-bef7d6978b3b, api error InvalidClientTokenId: The security token included in the request is invalid

  aws:iam:Role (kerno-samples-role-ab90fbbe-4d72-45ca-a2a7-ecaf8d9bf667):
    error: Preview failed: 1 error occurred:
    	* Retrieving AWS account details: validating provider credentials: retrieving caller identity from STS: operation error STS: GetCallerIdentity, https response error StatusCode: 403, RequestID: ebbb0a6a-494e-4e36-ab5c-bef7d6978b3b, api error InvalidClientTokenId: The security token included in the request is invalid

  aws:iam:RolePolicy (kerno-samples-ab90fbbe-4d72-45ca-a2a7-ecaf8d9bf667-policy):
    error: Preview failed: 1 error occurred:
    	* Retrieving AWS account details: validating provider credentials: retrieving caller identity from STS: operation error STS: GetCallerIdentity, https response error StatusCode: 403, RequestID: ebbb0a6a-494e-4e36-ab5c-bef7d6978b3b, api error InvalidClientTokenId: The security token included in the request is invalid

    [Pulumi Copilot] Would you like help with these diagnostics?
    https://app.pulumi.com/kernoio/installer/ab90fbbe-4d72-45ca-a2a7-ecaf8d9bf667/previews/bf99205d-b0f9-4991-a392-bbd95dd9b782?explainFailure

Resources:

There was a problem installing Kerno.
Please check your installation configuration and try again.
Should the issue persist, contact the Kerno team for support.

To resolve this issue, make sure you are using the correct profile:

Run:
```
aws sso login --profile <profile>
```
If the issue persists, try using assume to get credentials:
```
assume --export <profile>
```

MacOS M4 Installation Issue

If you're using Docker on Apple M4 machines, you may encounter an error that looks like this:


Diagnostics:
  pulumi:pulumi:Stack (installer-36755439-d238-44cd-b3d6-d7384e54ad73):
    #
    # A fatal error has been detected by the Java Runtime Environment:
    #
    #  SIGILL (0x4) at pc=0x0000ffff9633fc5c, pid=132, tid=133
    #
    # JRE version:  (21.0.6+7) (build )
    # Java VM: OpenJDK 64-Bit Server VM (21.0.6+7-LTS, mixed mode, sharing, tiered, compressed oops, compressed class ptrs, g1 gc, linux-aarch64)
    # Problematic frame:
    # j  java.lang.System.registerNatives()V+0 java.base@21.0.6
    #
    # No core dump will be written. Core dumps have been disabled. To enable core dumping, try "ulimit -c unlimited" before starting Java again
    #
    # An error report file with more information is saved as:
    # /pulumi/projects/hs_err_pid132.log
    [0.038s][warning][os] Loading hsdis library failed
    #
    # The crash happened outside the Java Virtual Machine in native code.
    # See problematic frame for where to report the bug.
    #

    error: an unhandled error occurred: '/opt/java/openjdk/bin/java -jar installer.jar' exited with non-zero exit code: -1

    [Pulumi Copilot] Would you like help with these diagnostics?
    https://app.pulumi.com/kernoio/installer/36755439-d238-44cd-b3d6-d7384e54ad73/previews/b1ef6df2-ad48-4219-acec-448f6bcaa863?explainFailure

To resolve this issue, first make sure you have the latest version of Docker and Docker Desktop installed. Then, try rerunning the command.

If the issue persists, add the following environment variable to the Kerno installation script and rerun it:

-e JAVA_TOOL_OPTIONS="-XX:UseSVE=0"

PreviousSystem Requirements NextUpdate an Organization

Last updated 25 days ago

Sign up to Kerno

Install Kerno Using Helm

Step 1. Add the Helm Repository

Step 2. Install the chart

Step 3. Connect your Object Storage

6. Install the Chart Using Your Config

Install Kerno Using Docker

Prerequisites

Kubernetes RBAC Permissions

Cloud Permissions

Install on AWS

Step 1. Log into AWS with admin privileges.

Step 2 [Option 1]. Install Using AWS Config File

Step 2 [Option 2]. Using Environment Variables

Install on GCP

Step 1. Log into GCP with admin privileges.

Step 2. Add the missing values to the script, and run the script.

Upgrade Kerno

Uninstall Kerno

Troubleshoot your Installation.