diff --git a/README.md b/README.md index 6a8efbea..6c3d6338 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,10 @@ +--- +project: SimKube +description: | + A colection of tools for saving and replaying running "traces" of a Kubernetes cluster in a simulated environment +template: docs.html +--- + ![build status](https://github.com/acrlabs/simkube/actions/workflows/verify.yml/badge.svg) # simkube @@ -19,7 +26,7 @@ This package provides the following components: - `sk-vnode`: a [Virtual Kubelet](https://virtual-kubelet.io)-based "hollow node" that allows customization based off a "skeleton" node file (see the example in `simkube/k8s/sk_vnode.py`). -![architecture diagram of SimKube](./docs/images/sk-overview.png) +![architecture diagram of SimKube](docs/images/sk-overview.png) Watch a demo of SimKube: @@ -51,6 +58,7 @@ supported tooling for doing so. ### Building To build all SimKube artifacts for the first time run: + - `git submodule init && git submodule update` - `make build` and `make skctl` from the root of this repository. @@ -71,18 +79,6 @@ manifests and deploy all SimKube artifacts to the specified cluster. All build artifacts are placed in the `.build/` directory. You can remove this directory or run `make clean` to clean up. -## Documentation - -You can find additional documentation on the individual components in the [docs directory](./docs/) of this repo. -Links to relevant documentation are below: - -- [sk-cloudprov](./docs/sk-cloudprov.md) -- [skctl](./docs/skctl.md) -- [sk-ctrl](./docs/sk-ctrl.md) -- [sk-driver](./docs/sk-driver.md) -- [sk-tracer](./docs/sk-tracer.md) -- [sk-vnode](./docs/sk-vnode.md) - ## Contributing We welcome any and all contributions to the SimKube project! Please open a pull request. @@ -96,13 +92,15 @@ issue](https://github.com/acrlabs/simkube/issues)! ### Code of Conduct Applied Computing Research Labs has a strict code of conduct we expect all contributors to adhere to. Please read the -[full text](./CODE_OF_CONDUCT.md) so that you understand the expectations upon you as a contributor. +[full text](https://github.com/acrlabs/simkube/blob/master/CODE_OF_CONDUCT.md) so that you understand the expectations +upon you as a contributor. ### Copyright and Licensing -SimKube is licensed under the [MIT License](./LICENSE). Contributors to this project agree that they own the copyrights -to all contributed material, and agree to license your contributions under the same terms. This is "inbound=outbound", -and is the [GitHub default](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license). +SimKube is licensed under the [MIT License](https://github.com/acrlabs/simkube/blob/master/LICENSE). Contributors to +this project agree that they own the copyrights to all contributed material, and agree to license your contributions +under the same terms. This is "inbound=outbound", and is the [GitHub +default](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license). > [!WARNING] > Due to the uncertain nature of copyright and IP law, this repository does not accept contributions that have been all diff --git a/docs/api_changes.md b/docs/api_changes.md index f7f6f4c6..b2b354c7 100644 --- a/docs/api_changes.md +++ b/docs/api_changes.md @@ -1,3 +1,8 @@ +--- +project: SimKube +template: docs.html +--- + # Making API Changes ## SimKube Custom Resource Definition changes diff --git a/docs/contributing.md b/docs/contributing.md index 130f0ed5..3af2e040 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,3 +1,8 @@ +--- +project: SimKube +template: docs.html +--- + # Contributing to SimKube ## Setting up your environment @@ -57,8 +62,8 @@ needs to be shared between multiple artifacts should go in either `lib/go` or `l ### Building the artifacts -To build all SimKube artifacts for the first time run: -- `git submodule init && git submodule update` +To build all SimKube artifacts for the first time run: +- `git submodule init && git submodule update` - `make build` and `make skctl` from the root of this repository. For all subsequent builds of SimKube artifacts, run only `make build` and `make skctl` from the root of this repository. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 00000000..5cfe123a --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,13 @@ +nav: + - Home: README.md + - Usage: + - Components: + - sk-cloudprov: docs/sk-cloudprov.md + - sk-ctrl: docs/sk-ctrl.md + - sk-driver: docs/sk-driver.md + - sk-tracer: docs/sk-tracer.md + - sk-vnode: docs/sk-vnode.md + - skctl: docs/skctl.md + - Contributing: + - Developer's Guide: docs/contributing.md + - API changes: docs/api_changes.md diff --git a/docs/sk-cloudprov.md b/docs/sk-cloudprov.md index f90c1c39..a0e6f42e 100644 --- a/docs/sk-cloudprov.md +++ b/docs/sk-cloudprov.md @@ -1,3 +1,8 @@ +--- +project: SimKube +template: docs.html +--- + # SimKube Virtual Cloud Provider SimKube uses the Cluster Autoscaler diff --git a/docs/sk-ctrl.md b/docs/sk-ctrl.md index 1d280f56..9956ec41 100644 --- a/docs/sk-ctrl.md +++ b/docs/sk-ctrl.md @@ -1,3 +1,8 @@ +--- +project: SimKube +template: docs.html +--- + # SimKube Simulation Controller The Simulation Controller watches for new Simulation Custom Resources to be posted to the API server and then configures diff --git a/docs/sk-driver.md b/docs/sk-driver.md index a87b7500..429f5fdf 100644 --- a/docs/sk-driver.md +++ b/docs/sk-driver.md @@ -1,3 +1,8 @@ +--- +project: SimKube +template: docs.html +--- + # SimKube Simulation Driver The SimKube driver is a job that is launched whenever a new simulation is started. It reads all the contents of a diff --git a/docs/sk-tracer.md b/docs/sk-tracer.md index b68229b3..b9732bf6 100644 --- a/docs/sk-tracer.md +++ b/docs/sk-tracer.md @@ -1,3 +1,8 @@ +--- +project: SimKube +template: docs.html +--- + # SimKube Tracer The SimKube Tracer runs in a production Kubernetes cluster and watches all configured resources, as well as all pods @@ -58,8 +63,9 @@ in the trace for use by the simulator. ## Exporting a trace A user can export a trace by making a post request to the `/export` endpoint and including a JSON object with the export -configuration. The API for this is defined in [`./api/v1/simkube.yml`](./api/v1/simkube.yml). The response from the -tracer will be a bytestream of the trace stored in [msgpack](https://msgpack.org) format, which is a JSON-like binary +configuration. The API for this is defined in +[`api/v1/simkube.yml`](https://github.com/acrlabs/blob/master/api/v1/simkube.yml). The response from the tracer will be +a bytestream of the trace stored in [msgpack](https://msgpack.org) format, which is a JSON-like binary format. You can inspect the contents of the trace with the `msgpack2json` utility from [msgpack-tools](https://github.com/ludocode/msgpack-tools): diff --git a/docs/sk-vnode.md b/docs/sk-vnode.md index 28827eba..f8add466 100644 --- a/docs/sk-vnode.md +++ b/docs/sk-vnode.md @@ -1,3 +1,8 @@ +--- +project: SimKube +template: docs.html +--- + # SimKube Virtual Node The SimKube Virtual Node is build on top of [Virtual Kubelet](https://virtual-kubelet.io) to present a simulated/virtual diff --git a/docs/skctl.md b/docs/skctl.md index e4c5f505..d3516025 100644 --- a/docs/skctl.md +++ b/docs/skctl.md @@ -1,3 +1,8 @@ +--- +project: SimKube +template: docs.html +--- + # skctl `skctl` is the CLI for interacting with SimKube. It's not required to use but it will make your life a lot easier.