Run SimKube in CI

This quickstart guide explains how to use SimKube in CI using GitHub Actions and AWS EC2.

Assumptions

• you have collected a trace from the cluster you want to simulate, if you still need to do this see the sk-tracer docs.
• you have sufficient permissions to managed the AWS resources described, for more on this see the AWS Permissions section on our usage page.

0. Create a key pair

You will need to generate a key pair in AWS for the IAM user you are using to access AWS resources. Hang onto those; you will need them when you configure the secrets.

AWS provides instructions on creating key pairs in AWS IAM via the console or CLI here.

1. GitHub Permissions

To use SimKube in CI the GitHub account will need:

• permissions to access code and manage custom runners
• a method of accessing those permissions

Example using a fine grained PAT:

Setup the PAT in GitHub:

• Go to user Settings
• Click Developer settings
• Under Personal access tokens
• Choose Fine-grained tokens
• Select the Resource owner: if the repo is not owned by you it will send an access request to the owner(s) of the repos you select
• Give the token a descriptive Token name and Description
• The Request message should give some context to the admin
• Choose an Expiration that meets your organization’s policy requirements
• Select Only select repositories
• Choose the repositories you want to run SimKube in
• Click Add permissions
• Select Read and Write access for Actions and Administration; metadata will be selected by default
• Click Generate token and request access
• In the next step we will add the PAT to our secrets

2. Configure secrets

Add the following secrets to the repo you will be testing in

• SIMKUBE_RUNNER_PAT - PAT with repo scope created in Step 1
• AWS_ACCESS_KEY_ID - AWS access key created in Step 0
• AWS_SECRET_ACCESS_KEY - AWS secret key created in Step 0

3. Create a GitHub Actions workflow

We will be using a custom action created by ACRL called simkube-ci-action. Our custom action simplifies the setup and teardown of ephemeral runners so you can focus on running impactful simulations in CI. To use simkube-ci-action use the launch-runner and run-simulation custom actions in your workflow.

A basic action workflow file might look like:

name: Run simulation
on:
  workflow_dispatch:
  push:
    branches:
      - "main"
jobs:
  launch-runner:
    runs-on: ubuntu-latest
    steps:
      - name: Setup SimKube GitHub Action runner
        uses: acrlabs/simkube-ci-action/actions/launch-runner@main
        with:
          instance-type: m6a.large
          aws-region: us-west-2
          subnet-id: subnet-xxxx
          security-group-ids: sg-xxxx
          simkube-runner-pat: ${{ secrets.SIMKUBE_RUNNER_PAT }}
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
  run-simulation:
    needs: launch-runner
    runs-on: [self-hosted, simkube, ephemeral]
    steps:
      - uses: actions/checkout@v5
      - name: Run simulation
        uses: acrlabs/simkube-ci-action/actions/run-simulation@main
        with:
          simulation-name: your-sim-name
          trace-path: path/to/your/trace

4. Test your SimKube workflow

Test your workflow by manually dispatching it in the actions menu.

Currently simkube-ci-action is pass/fail. The simulation either runs to completion or it fails. We do not currently have a method for injecting evaluation criteria for simulations.

A successful simulation will exit with code 0 and you will see a ✓ Simulation completed successfully! in the actions logs.

A failed simulation will exit with a non-zero exit code failing the CI action and printing a detailed failure summary.

5. Evaluating your results

Prometheus and Grafana are installed natively. Users can view simulation results by connecting to the Grafana pod on your EC2 instance.

See Evaluate your results for more details.