SK-98 / Simkube AMI docs by ogorman89 · Pull Request #218 · acrlabs/simkube

ogorman89 · 2026-02-05T18:05:04Z

Description and Rationale

Drafts of a few docs for AMIs, I called this section Infrastructure but would love a suggestion:

overview.md - a basic rundown of offerings
amis.md - a little more detail on the AMIs, I expect this page to grow more over time?
usage.md - high level how to find/use the AMIs
github-runners.md - high level using the SimKube Action Runner AMI
two quick start guides:
- run-sim.md - basic how to run a sim on EC2
- ci-sim.md - basic how to setup ci runners using GitHub actions and simkube-ci-action

How

mainly keyboard, some hair tearing

Test Steps

none

Other Notes

I could use some help calibrating this, it feels... verbose but also I expect most people will just go to the quickstart stuff?
[ x ] I certify that this PR does not contain any code that has been generated with GitHub Copilot or any other AI-based code generation tool, in accordance with this project's policies.

codecov · 2026-02-05T18:06:52Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.41%. Comparing base (12955f5) to head (0c7d69d).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #218      +/-   ##
==========================================
- Coverage   75.76%   74.41%   -1.36%     
==========================================
  Files          58       63       +5     
  Lines        3326     3709     +383     
  Branches      167      181      +14     
==========================================
+ Hits         2520     2760     +240     
- Misses        701      844     +143     
  Partials      105      105

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

drmorr0

You can test how this will actually appear on the web by changing the branch name in the www repo to point to your branch:

https://github.com/acrlabs/www/blob/main/simkube.yml#L70

Then on your laptop you can run just run simkube and see the whole website at localhost:8001 (sadly the live updates thing doesn't work for the cross-repo docs, though, so when you make changes you have to push them to your branch, kill the mkdocs process, and restart it).

docs/infra/amis.md

docs/infra/ci-sim.md

docs/infra/run-sim.md

docs/infra/usage.md

drmorr0 · 2026-02-06T00:19:24Z

docs/mkdocs.yml

+      - Overview: docs/infra/overview.md
+      - Amazon Machine Images (AMI's): docs/infra/amis.md
+      - Using SimKube AMIs: docs/infra/usage.md
+      - Custom GithHub Action Runners: docs/infra/github-runners.md


These headings are probably going to be too long for the sidebar if I had to guess

docs/mkdocs.yml

drmorr0 · 2026-02-06T00:20:28Z

docs/mkdocs.yml

      - sk-ctrl: docs/components/sk-ctrl.md
      - sk-driver: docs/components/sk-driver.md
      - sk-tracer: docs/components/sk-tracer.md
+  - Infrastructure:


I don't like the name "Infrastructure" here -- something like "Prebuilt Simulation Environments" is closer to what I want, but that might be too long for the sidebar.

ogorman89 · 2026-02-11T18:23:05Z

You can test how this will actually appear on the web by changing the branch name in the www repo to point to your branch:

https://github.com/acrlabs/www/blob/main/simkube.yml#L70

Then on your laptop you can run just run simkube and see the whole website at localhost:8001 (sadly the live updates thing doesn't work for the cross-repo docs, though, so when you make changes you have to push them to your branch, kill the mkdocs process, and restart it).

Did that and caught a few more errors!

ogorman89 · 2026-02-11T18:24:02Z

The updated sidebar:

drmorr0 · 2026-02-13T23:27:08Z

The updated sidebar:

[image]

Oh! I've got it. Instead of "Prebuilt Simulation Environments", call it "SimKube in the Cloud"

drmorr0 · 2026-02-13T23:12:31Z

docs/infra/amis.md

+|:-----------------------------------------------|:-----------:|:-------------------------:|
+| Ubuntu 24.04 LTS Operating System              | ✅          | ✅                        |
+| A running Kubernetes cluster & management tools| ✅          | ✅                        |
+| All SimKube components*                        | ✅          | ✅                        |


I think maybe remove the asterisk here?

drmorr0 · 2026-02-13T23:12:58Z

docs/infra/ci-sim.md

 ```

-You will need to generate an pair of access tokens for 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.
+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.


I don't think "key pair" should be in backticks.

drmorr0 · 2026-02-13T23:13:50Z

docs/infra/ci-sim.md

+## 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](./evaluate.md).


See "Evaluate your results" for more details.

drmorr0 · 2026-02-13T23:16:51Z

docs/infra/evaluate.md

+```
+
+## 1. Open the Grafana UI
+<http://localhost:3000/>


In order to actually make this work (since your EC2 instance is headless) you need to tunnel traffic from your localhost to the EC2 instance, using something like

ssh -L <LOCAL_PORT>:<REMOTE_HOST>:<REMOTE_PORT> <ec2-instance-ip>

And then you can connect to https://localhost:<LOCAL_PORT> to view the grafana dashboard.

drmorr0 · 2026-02-13T23:18:52Z

docs/infra/run-sim.md


 ## 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](../components/sk-tracer.md).
+- you have collected a trace from the cluster you want to simulate, if you still need to do this see [the sk-tracer docs](https://github.com/acrlabs/simkube/blob/main/docs/intro/running.md).


I don't think we want the github.com link here, this should just be ../intro/running.md?

drmorr0 · 2026-02-13T23:31:38Z

docs/infra/ci-sim.md

+
+> [!NOTE]
+> `simkube-ci-action` runners are epehmeral-only and all data from the simulation is lost.
+> In the future we expect to expose functionality that will allow data to be sent to external prometheus endpoints.


s/expect to/will/

drmorr0 · 2026-02-13T23:32:44Z

docs/infra/run-sim.md

+## 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](https://github.com/acrlabs/simkube/blob/main/docs/intro/running.md).
+
+[TODO] MOVE TO usage and link to that. Add full IAM policy JSON to examples/aws/


drmorr0 · 2026-02-13T23:34:26Z

docs/infra/run-sim.md

+> For simplicity and ease of use, we recommend using AWS S3 to store your trace files.
+> If your trace files are in S3, you can skip this step; SimKube will need additional IAM permissions to access your S3 bucket.
+
+Copy your trace to the instance, the default SimKube trace location is /data/trace:


Should be /var/kind/cluster/trace, also enclose the path in backticks

drmorr0 · 2026-02-13T23:34:56Z

docs/infra/run-sim.md

+Copy your trace to the instance, the default SimKube trace location is /data/trace:
+
+```sh
+scp your_trace_file ubuntu@<instance-ip>:/var/kind/<cluster-name>/trace


The AMI uses the default cluster name, right? It's just cluster? So we should probably specify the default/absolute path here.

drmorr0 · 2026-02-13T23:38:28Z

examples/aws/sk_iam_policy.json

@@ -0,0 +1,39 @@
+{


Are you planning to link to this from somewhere?

The other option that might be better is to actually just embed this as a page in the "Reference" section. You can see other examples of embedding files, for example, here

ogorman89 added 5 commits February 2, 2026 15:51

ami docs

834a7bc

docs updates

c4bcccf

docs

27d3b0e

more docs

5f23c66

...more

6111f9f

ogorman89 requested a review from drmorr0 February 5, 2026 18:05

ogorman89 self-assigned this Feb 5, 2026

drmorr0 requested changes Feb 6, 2026

View reviewed changes

ogorman89 added 4 commits February 10, 2026 17:14

more docs

105f4f1

docs

83d789d

fix notes

a6d1646

fixes

0c7d69d

ogorman89 requested a review from drmorr0 February 11, 2026 18:27

drmorr0 reviewed Feb 13, 2026

View reviewed changes

Uh oh!

Conversation

ogorman89 commented Feb 5, 2026

Related Links

Description and Rationale

How

Test Steps

Other Notes

Uh oh!

codecov bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

drmorr0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ogorman89 commented Feb 11, 2026

Uh oh!

ogorman89 commented Feb 11, 2026

Uh oh!

drmorr0 commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Feb 5, 2026 •

edited

Loading

drmorr0 commented Feb 13, 2026 •

edited

Loading