Learning to Use the k6 Operator

This repository contains examples and documentation for using the k6 operator with Kubernetes.

🚀 New Users Start Here

If you're new to the k6 operator, start with our Getting Started Guide. This guide will walk you through:

1. Setting up a Kubernetes cluster
2. Installing the k6 operator
3. Running your first test
4. Exploring advanced features

The guide also provides an overview of all the documentation in this repository and how to navigate it.

📚 Documentation Structure

This repository is organized with the following documentation:

• CLUSTER-SETUP.md: Instructions for setting up a Kubernetes cluster using kind
• K6-OPERATOR.md: Guide for using the k6 operator for load testing
• GETTING-STARTED.md: Step-by-step guide for new users
• examples/: Example test scripts and configurations

What is k6?

k6 is an open-source load testing tool that makes performance testing easy and productive for engineering teams. It's built with Go and JavaScript, allowing you to write tests using JavaScript ES2015/ES6.

What is the k6 Operator?

The k6 Operator is a Kubernetes operator that allows you to run distributed k6 tests from within your Kubernetes cluster. It simplifies the process of running load tests at scale by managing the deployment and coordination of k6 test instances.

Prerequisites

• A Kubernetes cluster
• kubectl installed and configured
• Helm (optional, for installing the operator using Helm)

Installing the k6 Operator

You can install the k6 operator using our setup script or manually using kubectl or Helm.

Using the Setup Script

The setup-k6-operator.sh script provides an easy way to set up a Kubernetes cluster and install the k6 operator. The script supports multiple installation methods:

# Install using the default method (bundle)
./setup-k6-operator.sh

# Install using Helm
./setup-k6-operator.sh --method=helm

# Install using bundle method
./setup-k6-operator.sh --method=bundle

# Show help
./setup-k6-operator.sh --help

The script will:

1. Check for required dependencies
2. Create a kind cluster if it doesn't exist
3. Install the k6 operator using the specified method
4. Set up monitoring with InfluxDB and Grafana
5. Configure services for external access

Manual Installation

Using kubectl

# Clone the k6-operator repository
git clone https://github.com/grafana/k6-operator.git
cd k6-operator

# Install the operator using kustomize
kubectl apply -k config/default

Using Helm

# Add the Grafana Helm repository
helm repo add grafana https://grafana.github.io/helm-charts

# Update your Helm repository
helm repo update

# Install the k6 operator
helm install k6-operator grafana/k6-operator

Using Bundle

# Install the k6 operator using the bundle method
curl https://raw.githubusercontent.com/grafana/k6-operator/main/bundle.yaml | kubectl apply -f -

This is the simplest method and applies the default manifests for k6 Operator directly from the GitHub repository.

Uninstalling the k6 Operator

When you're done with the k6 operator, you can uninstall it using the method that corresponds to how you installed it:

Using the Uninstall Script

The uninstall-k6-operator.sh script provides an easy way to uninstall the k6 operator and clean up resources:

chmod +x uninstall-k6-operator.sh
./uninstall-k6-operator.sh

By default, the script will uninstall the k6 operator using the bundle method. If you used another method, you can specify it:

# Uninstall using Helm
./uninstall-k6-operator.sh --method=helm

# Uninstall using bundle method
./uninstall-k6-operator.sh --method=bundle

# Uninstall and also delete the kind cluster
./uninstall-k6-operator.sh --delete-cluster

# Show help
./uninstall-k6-operator.sh --help

Manual Uninstallation

You can also manually uninstall the k6 operator:

Using kubectl with kustomize

If you installed the operator using kubectl with kustomize:

kubectl delete -k config/default

Using Helm

If you installed the operator using Helm:

helm uninstall k6-operator

Using Bundle Method

If you installed the operator using the bundle method:

kubectl delete -f https://raw.githubusercontent.com/grafana/k6-operator/main/bundle.yaml

Creating Your First k6 Test

1. Create a k6 test script (see examples/simple-test.js in this repository)
2. Create a Kubernetes manifest for your k6 test (see examples/k6-test-updated.yaml in this repository)
3. Apply the manifest to your cluster:

kubectl apply -f examples/k6-test-updated.yaml

4. Monitor the test:

kubectl get testruns
kubectl logs -f my-test-1-xxxxx  # Replace xxxxx with the actual pod ID

Note: The k6 operator now uses the TestRun CRD instead of the K6 CRD. All examples in this repository have been updated to use the TestRun CRD.

Examples

This repository includes several examples to help you get started:

• examples/simple-test.js: A basic k6 test script
• examples/k6-test-updated.yaml: A basic k6 test manifest using the TestRun CRD
• examples/distributed-test-updated.yaml: An example of a distributed k6 test using the TestRun CRD
• examples/advanced/modules-test.yaml: An advanced example using modules with the TestRun CRD

Note: The original example files (examples/k6-test.yaml and examples/distributed-test.yaml) are kept for reference but use the outdated K6 CRD.

Running Tests

To run the example tests in this repository:

Basic Test

kubectl apply -f examples/k6-test-updated.yaml
kubectl get testruns
# Wait for the test to complete
kubectl logs -f my-test-1-xxxxx  # Replace xxxxx with the actual pod ID

Distributed Test

kubectl apply -f examples/distributed-test-updated.yaml
kubectl get testruns
# Wait for the test to complete
kubectl logs -f distributed-test-1-xxxxx  # Replace xxxxx with the actual pod ID

Advanced Modules Test

kubectl apply -f examples/advanced/modules-test.yaml
kubectl get testruns
# Wait for the test to complete
kubectl logs -f modules-test-1-xxxxx  # Replace xxxxx with the actual pod ID

Viewing Test Results in Grafana

If you've set up InfluxDB and Grafana as described in the setup script:

1. Access Grafana at http://localhost:3000
2. Add InfluxDB as a data source (if not already added):
   • Name: InfluxDB
   • URL: http://influxdb:8086
   • Database: k6
3. Import the k6 dashboard (ID: 2587)
4. View your test results

Troubleshooting

If you encounter issues with your tests:

Check TestRun Status

kubectl get testruns

Look for the STAGE column. If it shows "error", there was a problem with the test.

Check Pod Status

kubectl get pods | grep your-test-name

Look for pods in "Error" or "CrashLoopBackOff" state.

View Pod Logs

kubectl logs your-test-name-1-xxxxx

This will show the output from the k6 test, including any errors.

Check Operator Logs

kubectl logs -n k6-operator-system deployment/k6-operator-controller-manager -c manager

This can help identify issues with the operator itself.

Common Issues

1. Using outdated CRD: Make sure you're using the TestRun CRD instead of the K6 CRD.
2. Missing ConfigMap: Ensure the ConfigMap with your test script exists.
3. Script errors: Check your JavaScript code for syntax errors.
4. Resource constraints: Ensure your cluster has enough resources to run the tests.

Changes Made to Fix Tests

The following changes were made to update the tests to work with the latest version of the k6 operator:

1. Updated CRD Type: Changed all test manifests from using the outdated K6 CRD to the current TestRun CRD:

   • Created examples/k6-test-updated.yaml (updated from examples/k6-test.yaml)
   • Created examples/distributed-test-updated.yaml (updated from examples/distributed-test.yaml)
   • Updated examples/advanced/modules-test.yaml in place

2. Updated Installation Instructions: Changed the installation method to use kustomize instead of applying individual YAML files:

   kubectl apply -k config/default

3. Updated Monitoring Commands: Changed the commands to monitor tests from using kubectl get k6 to kubectl get testruns

4. Added Troubleshooting Section: Added a comprehensive troubleshooting section to help diagnose and fix issues with tests

All tests have been verified to run successfully with the current version of the k6 operator.

Additional Resources

• k6 Documentation
• k6 Operator GitHub Repository
• k6 Operator Documentation