k6-operator

The podCertificate projected volume source allows a pod to access an auto-rotating credential bundle (private key and certificate chain) for use as a TLS client or server. Kubelet generates a private key and requests a certificate from a named signer. The pod will not start until certificates are issued.

Important Implementation Details:

• Format: You can use a single file via credentialBundlePath (recommended) or separate files via keyPath and certificateChainPath.
• Atomicity: Using credentialBundlePath is preferred because the application can read the bundle atomically. If using separate files, your application must handle the possibility that a certificate rotation occurs between reading the key and the certificate, resulting in a mismatch. You must implement logic to re-read if they are inconsistent.
• PEM Normalization: Kubelet performs aggressive normalization on PEM contents (stripping comments/headers, deduplicating certificates, and arbitrary ordering).

# Example conceptual structure for podCertificate
podCertificate:
  credentialBundlePath: /etc/tls/bundle.pem
  # OR
  keyPath: /etc/tls/key.pem
  certificateChainPath: /etc/tls/chain.pem

The k6-operator is designed as a lightweight Kubernetes interface (the "glue") between the Kubernetes orchestration layer and k6. Historically, the operator has had to act as a heavy test coordinator, managing complex logic like instance synchronization, setup()/teardown() handling, and direct runner connections.

Native Distributed Execution (NDE) shifts this coordination logic from the operator into the k6 application itself. This transition aims to:

• Simplify the operator: It moves from being a complex coordinator to a lightweight manager that simply bootstraps k6 processes.
• Improve reliability: By moving logic like setup()/teardown() into k6, the operator avoids "breaking the abstraction" of Kubernetes (e.g., trying to exert direct process control like sending SIGTERM to a container, which is often unreliable in Kubernetes).
• Unify OSS and Cloud: It minimizes the logic gap between the OSS k6-operator and Grafana Cloud k6 (GCk6) by providing a common native implementation for distributed runs.

You can control how k6 runner pods are scheduled relative to other pods using podAntiAffinity within the TestRun.spec.runner.affinity configuration. This is useful for ensuring that k6 runners are spread across different nodes or availability zones to prevent resource contention or single points of failure.

There are two types of anti-affinity rules:

1. requiredDuringSchedulingIgnoredDuringExecution: Hard requirements. If the anti-affinity rules cannot be met at scheduling time, the pod will not be scheduled. All terms in the list must be satisfied (intersection).
2. preferredDuringSchedulingIgnoredDuringExecution: Soft requirements. The scheduler will try to find nodes that satisfy these rules based on a weight (1-100). The node with the highest sum of weights is preferred.

spec:
  runner:
    affinity:
      podAntiAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
          - podAffinityTerm:
              labelSelector:
                matchLabels:
                  app: k6-runner
              topologyKey: kubernetes.io/hostname
        preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchLabels:
                  app: k6-runner
              topologyKey: kubernetes.io/hostname

The podCertificate source projects an auto-rotating credential bundle (private key and certificate chain) into the pod. This allows the pod to use these credentials as a TLS client or server.

Best Practice: Use credentialBundlePath instead of separate keyPath and certificateChainPath. The credentialBundlePath provides a single PEM file containing the private key followed by the certificate chain. This allows your application to perform an atomic read, ensuring the key and certificate are always consistent. If you use separate paths, your application must manually verify that the key and certificate match, as they might be read mid-rotation.

Key Configuration Options:

• keyType (string, required): The type of keypair. Valid values: RSA3072, RSA4096, ECDSAP256, ECDSAP384, ECDSAP521, ED25519.
• signerName (string, required): The name of the signer to which CSRs will be addressed.
• credentialBundlePath (string, optional): Path to the single PEM file containing the key and chain.
• maxExpirationSeconds (integer, optional): Maximum lifetime for the certificate. If omitted, defaults to 86400 (24 hours). Minimum is 3600 (1 hour), maximum is 7862400 (91 days).

The Private Load Zone (PLZ) feature allows k6-operator to execute tests managed by Grafana Cloud k6 (GCk6). The lifecycle follows these steps:

1. Creation: The user explicitly creates a PLZ resource using Kubernetes tooling (e.g., kubectl apply -f plz.yaml).
2. Registration: Upon creation, k6-operator registers the PLZ with the GCk6 API.
3. Polling: k6-operator enters a polling loop, checking the GCk6 API every 10 seconds for new test runs assigned to that PLZ.
4. Execution: When a test run is detected, k6-operator fetches metadata (including an S3 presigned URL for the k6 archive and runner requirements) and creates a TestRun Custom Resource (CR) in Kubernetes.
5. Cleanup: When the user deletes the PLZ resource (e.g., kubectl delete -f plz.yaml), k6-operator deregisters it from the GCk6 API.

# Create a PLZ resource
kubectl apply -f plz.yaml

# Delete a PLZ resource
kubectl delete -f plz.yaml