From a28b680f275564123c9feed10408cc34f90725f7 Mon Sep 17 00:00:00 2001 From: kurtosisbot Date: Tue, 13 Jun 2023 16:35:05 +0000 Subject: [PATCH] Apply automatic changes --- LICENSE.md | 2 +- .../kurtosis_version/kurtosis_version.go | 2 +- api/typescript/package.json | 2 +- .../src/kurtosis_version/kurtosis_version.ts | 2 +- .../version-0.78.3/best-practices.md | 44 + .../version-0.78.3/changelog.md | 806 +++++++++++++++ .../cli-reference/analytics-disable.md | 13 + .../cli-reference/analytics-enable.md | 13 + .../cli-reference/analytics-id.md | 15 + .../version-0.78.3/cli-reference/clean.md | 18 + .../cli-reference/completion.md | 20 + .../cli-reference/config-path.md | 7 + .../version-0.78.3/cli-reference/discord.md | 11 + .../version-0.78.3/cli-reference/docs.md | 13 + .../version-0.78.3/cli-reference/dump.md | 17 + .../cli-reference/enclave-add.md | 17 + .../cli-reference/enclave-dump.md | 20 + .../cli-reference/enclave-inspect.md | 23 + .../cli-reference/enclave-ls.md | 13 + .../cli-reference/enclave-rm.md | 14 + .../cli-reference/enclave-stop.md | 16 + .../cli-reference/engine-logs.md | 13 + .../cli-reference/engine-restart.md | 11 + .../cli-reference/engine-start.md | 16 + .../cli-reference/engine-status.md | 11 + .../cli-reference/engine-stop.md | 13 + .../version-0.78.3/cli-reference/feedback.md | 33 + .../cli-reference/files-download.md | 16 + .../cli-reference/files-rendertemplate.md | 14 + .../cli-reference/files-storeservice.md | 13 + .../cli-reference/files-storeweb.md | 13 + .../cli-reference/files-upload.md | 17 + .../version-0.78.3/cli-reference/index.md | 136 +++ .../cli-reference/run-starlark.md | 88 ++ .../cli-reference/service-add.md | 25 + .../cli-reference/service-delete.md | 15 + .../cli-reference/service-exec.md | 17 + .../cli-reference/service-logs.md | 21 + .../cli-reference/service-shell.md | 13 + .../version-0.78.3/cli-reference/twitter.md | 11 + .../version-0.78.3/cli-reference/version.md | 14 + .../version-0.78.3/concepts-reference/args.md | 37 + .../concepts-reference/enclaves.md | 20 + .../concepts-reference/files-artifacts.md | 26 + .../concepts-reference/future-references.md | 47 + .../concepts-reference/glossary.md | 38 + .../concepts-reference/kurtosis-yml.md | 37 + .../concepts-reference/locators.md | 79 ++ .../concepts-reference/multi-phase-runs.md | 29 + .../concepts-reference/packages.md | 102 ++ .../version-0.78.3/concepts-reference/plan.md | 52 + .../concepts-reference/resource-identifier.md | 68 ++ .../concepts-reference/starlark.md | 37 + .../concepts-reference/subnetworks.md | 41 + .../explanations/architecture.md | 115 +++ .../how-do-kurtosis-imports-work.md | 144 +++ .../explanations/metrics-philosophy.md | 17 + .../public-and-private-ips-and-ports.md | 44 + .../reusable-environment-definitions.md | 57 + .../explanations/why-kurtosis-starlark.md | 56 + .../explanations/why-multi-phase-runs.md | 40 + .../explanations/why-we-built-kurtosis.md | 26 + .../guides/adding-command-line-completion.md | 141 +++ .../guides/how-to-local-eth-testnet.md | 332 ++++++ .../guides/how-to-parameterize-cassandra.md | 397 +++++++ .../guides/installing-historical-versions.md | 95 ++ .../guides/installing-the-cli.md | 116 +++ .../version-0.78.3/guides/running-in-ci.md | 55 + .../version-0.78.3/guides/running-in-k8s.md | 67 ++ .../guides/simulating-networking-failure.md | 181 ++++ .../guides/upgrading-the-cli.md | 88 ++ docs/versioned_docs/version-0.78.3/home.md | 44 + .../version-0.78.3/package-index.md | 15 + .../version-0.78.3/quickstart.md | 974 ++++++++++++++++++ docs/versioned_docs/version-0.78.3/sdk.md | 540 ++++++++++ .../version-0.78.3/starlark-reference/args.md | 9 + .../starlark-reference/connection-config.md | 31 + .../starlark-reference/exec-recipe.md | 39 + .../get-http-request-recipe.md | 63 ++ .../starlark-reference/import-module.md | 24 + .../starlark-reference/index.md | 61 ++ .../starlark-reference/kurtosis.md | 21 + .../normal-packet-delay-distribution.md | 33 + .../version-0.78.3/starlark-reference/plan.md | 619 +++++++++++ .../starlark-reference/port-spec.md | 44 + .../post-http-request-recipe.md | 43 + .../starlark-reference/read-file.md | 19 + .../starlark-reference/ready-condition.md | 88 ++ .../starlark-reference/service-config.md | 118 +++ .../starlark-reference/service.md | 40 + .../starlark-reference/standard-library.md | 14 + .../uniform-packet-delay-distribution.md | 21 + .../update-service-config.md | 19 + .../version-0.78.3-sidebars.json | 78 ++ docs/versions.json | 1 + 95 files changed, 7136 insertions(+), 4 deletions(-) create mode 100644 docs/versioned_docs/version-0.78.3/best-practices.md create mode 100644 docs/versioned_docs/version-0.78.3/changelog.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/analytics-disable.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/analytics-enable.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/analytics-id.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/clean.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/completion.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/config-path.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/discord.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/docs.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/dump.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/enclave-add.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/enclave-dump.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/enclave-inspect.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/enclave-ls.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/enclave-rm.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/enclave-stop.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/engine-logs.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/engine-restart.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/engine-start.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/engine-status.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/engine-stop.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/feedback.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/files-download.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/files-rendertemplate.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/files-storeservice.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/files-storeweb.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/files-upload.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/index.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/run-starlark.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/service-add.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/service-delete.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/service-exec.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/service-logs.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/service-shell.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/twitter.md create mode 100644 docs/versioned_docs/version-0.78.3/cli-reference/version.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/args.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/enclaves.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/files-artifacts.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/future-references.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/glossary.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/kurtosis-yml.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/locators.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/multi-phase-runs.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/packages.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/plan.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/resource-identifier.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/starlark.md create mode 100644 docs/versioned_docs/version-0.78.3/concepts-reference/subnetworks.md create mode 100644 docs/versioned_docs/version-0.78.3/explanations/architecture.md create mode 100644 docs/versioned_docs/version-0.78.3/explanations/how-do-kurtosis-imports-work.md create mode 100644 docs/versioned_docs/version-0.78.3/explanations/metrics-philosophy.md create mode 100644 docs/versioned_docs/version-0.78.3/explanations/public-and-private-ips-and-ports.md create mode 100644 docs/versioned_docs/version-0.78.3/explanations/reusable-environment-definitions.md create mode 100644 docs/versioned_docs/version-0.78.3/explanations/why-kurtosis-starlark.md create mode 100644 docs/versioned_docs/version-0.78.3/explanations/why-multi-phase-runs.md create mode 100644 docs/versioned_docs/version-0.78.3/explanations/why-we-built-kurtosis.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/adding-command-line-completion.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/how-to-local-eth-testnet.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/how-to-parameterize-cassandra.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/installing-historical-versions.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/installing-the-cli.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/running-in-ci.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/running-in-k8s.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/simulating-networking-failure.md create mode 100644 docs/versioned_docs/version-0.78.3/guides/upgrading-the-cli.md create mode 100644 docs/versioned_docs/version-0.78.3/home.md create mode 100644 docs/versioned_docs/version-0.78.3/package-index.md create mode 100644 docs/versioned_docs/version-0.78.3/quickstart.md create mode 100644 docs/versioned_docs/version-0.78.3/sdk.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/args.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/connection-config.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/exec-recipe.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/get-http-request-recipe.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/import-module.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/index.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/kurtosis.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/normal-packet-delay-distribution.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/plan.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/port-spec.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/post-http-request-recipe.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/read-file.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/ready-condition.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/service-config.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/service.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/standard-library.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/uniform-packet-delay-distribution.md create mode 100644 docs/versioned_docs/version-0.78.3/starlark-reference/update-service-config.md create mode 100644 docs/versioned_sidebars/version-0.78.3-sidebars.json diff --git a/LICENSE.md b/LICENSE.md index f636de1587..7bb6713492 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -3,7 +3,7 @@ Business Source License 1.1 Parameters Licensor: Kurtosis Technologies, Inc. -Licensed Work: Kurtosis 0.78.2 +Licensed Work: Kurtosis 0.78.3 The Licensed Work is (c) 2023 Kurtosis Technologies, Inc. Additional Use Grant: You may make use of the Licensed Work, provided that you may not use the Licensed Work for an Environment Orchestration Service. diff --git a/api/golang/kurtosis_version/kurtosis_version.go b/api/golang/kurtosis_version/kurtosis_version.go index 24fcea2441..fb347332e9 100644 --- a/api/golang/kurtosis_version/kurtosis_version.go +++ b/api/golang/kurtosis_version/kurtosis_version.go @@ -9,6 +9,6 @@ const ( // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!! // This is necessary so that Kurt Core consumers will know if they're compatible with the currently-running // API container - KurtosisVersion = "0.78.2" + KurtosisVersion = "0.78.3" // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!! ) diff --git a/api/typescript/package.json b/api/typescript/package.json index b8adba1295..33f1cf7453 100644 --- a/api/typescript/package.json +++ b/api/typescript/package.json @@ -1,7 +1,7 @@ { "name": "kurtosis-sdk", "//": "NOTE: DO NOT UPDATE THIS VERSION MANUALLY - IT WILL BE UPDATED DURING THE RELEASE PROCESS!", - "version": "0.78.2", + "version": "0.78.3", "main": "./build/index", "description": "This repo contains a Typescript client for communicating with the Kurtosis Engine server, which is responsible for creating, managing and destroying Kurtosis Enclaves.", "types": "./build/index", diff --git a/api/typescript/src/kurtosis_version/kurtosis_version.ts b/api/typescript/src/kurtosis_version/kurtosis_version.ts index 449e1294e2..9387570ae0 100644 --- a/api/typescript/src/kurtosis_version/kurtosis_version.ts +++ b/api/typescript/src/kurtosis_version/kurtosis_version.ts @@ -1,5 +1,5 @@ // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!! // This is necessary so that Kurt Core consumers (e.g. modules) will know if they're compatible with the currently-running // API container -export const KURTOSIS_VERSION: string = "0.78.2" +export const KURTOSIS_VERSION: string = "0.78.3" // !!!!!!!!!!! DO NOT UPDATE! WILL BE MANUALLY UPDATED DURING THE RELEASE PROCESS !!!!!!!!!!!!!!!!!!!!!! diff --git a/docs/versioned_docs/version-0.78.3/best-practices.md b/docs/versioned_docs/version-0.78.3/best-practices.md new file mode 100644 index 0000000000..25a5d211fb --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/best-practices.md @@ -0,0 +1,44 @@ +--- +title: Best Practices +sidebar_label: Best Practices +slug: /best-practices +--- + +Passing package arguments to the CLI +------------------------------- +Passing [package arguments][args-concepts-reference] to the CLI can get hairy due to the interaction between Bash and JSON quotes. The following are tips to make your life easier: + +1. **When you have a small number of arguments:** surround the arguments with single quotes so you don't have to escape double quotes in your JSON. E.g.: + ```bash + kurtosis run github.com/user/repo '{"some_param":5,"some_other_param":"My value"}' + ``` +1. **When you have a large number of arguments:** put them in a `.json` file and use [Bash command substitution](https://www.gnu.org/software/bash/manual/html_node/Command-Substitution.html) _inside double quotes_ to slot them into the `kurtosis run` command. E.g.: + ```bash + kurtosis run github.com/user/repo "$(cat my-args.json)" + ``` + The double quotes around the `$(cat my-args.json)` are important so any spaces inside `my-args.json` don't fool Bash into thinking you're passing in two separate arguments. + +Choosing the right wait +----------------------- +Kurtosis has three different types of waits. Described here are the three, with tips on when to use each: + +1. Automatic waiting on port availability when a service starts (enabled by default; can be configured with [`PortSpec.wait`][port-spec-starlark-reference]) + - Should be sufficient for most usecases + - Requires little-to-no extra configuration + - Will cause parallel `Plan.add_services` to fail, allowing for quick aborting +1. Waiting on [`ReadyCondition`][ready-condition-starlark-reference]s (configured in [`ServiceConfig`][service-config-starlark-reference]) + - Allows for more advanced checking (e.g. require a certain HTTP response body, ensure a CLI call returns success, etc.) + - More complex to configure + - Will cause parallel `Plan.add_services` to fail, allowing for quick aborting +1. The [`Plan.wait`][plan-wait-starlark-reference] + - Most useful for asserting the system has reached a desired state in tests (e.g. wait until data shows up after loading) + - More complex to configure + - Cannot be used to short-circuit `Plan.add_services` + + +[args-concepts-reference]: ./concepts-reference/args.md + +[service-config-starlark-reference]: ./starlark-reference/service-config.md +[port-spec-starlark-reference]: ./starlark-reference/port-spec.md +[ready-condition-starlark-reference]: ./starlark-reference/ready-condition.md +[plan-wait-starlark-reference]: ./starlark-reference/plan.md#wait diff --git a/docs/versioned_docs/version-0.78.3/changelog.md b/docs/versioned_docs/version-0.78.3/changelog.md new file mode 100644 index 0000000000..40abbad988 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/changelog.md @@ -0,0 +1,806 @@ +# Changelog + +## [0.78.3](https://github.com/kurtosis-tech/kurtosis/compare/0.78.2...0.78.3) (2023-06-13) + + +### Features + +* Remove `--exec` flag for `kurtosis service shell` ([#712](https://github.com/kurtosis-tech/kurtosis/issues/712)) ([d8bc320](https://github.com/kurtosis-tech/kurtosis/commit/d8bc3206be4ec3d6dec7973c3b31f8746b6089d3)) + +## [0.78.2](https://github.com/kurtosis-tech/kurtosis/compare/0.78.1...0.78.2) (2023-06-13) + + +### Bug Fixes + +* accept run as the default main function ([#714](https://github.com/kurtosis-tech/kurtosis/issues/714)) ([077cd4c](https://github.com/kurtosis-tech/kurtosis/commit/077cd4c45c7722891d58754fa8b3f4f48c2dfdcb)) + +## [0.78.1](https://github.com/kurtosis-tech/kurtosis/compare/0.78.0...0.78.1) (2023-06-13) + + +### Features + +* added min/max cpu and memory for kubernetes via starlark ([#689](https://github.com/kurtosis-tech/kurtosis/issues/689)) ([faffc07](https://github.com/kurtosis-tech/kurtosis/commit/faffc071e8617e19bf5b23252a6661cf8b7ff81b)) +* use kurtosis service name as the kubernetes service name ([#713](https://github.com/kurtosis-tech/kurtosis/issues/713)) ([b0d6b8e](https://github.com/kurtosis-tech/kurtosis/commit/b0d6b8ebe30f99d1baeaef4d68c08ebd9ca8a9f3)) + +## [0.78.0](https://github.com/kurtosis-tech/kurtosis/compare/0.77.4...0.78.0) (2023-06-12) + + +### ⚠ BREAKING CHANGES + +* Added `main-file` and `main-function-name` flags to the `kurtosis run` CLI command. These new options were also added in the `RunStarlarkScript`, `RunStarlarkPackage` and the `RunStarlarkRemotePackage` SDKs methods, users will have to update the calls. ([#693](https://github.com/kurtosis-tech/kurtosis/issues/693)) + +### Features + +* Added `main-file` and `main-function-name` flags to the `kurtosis run` CLI command. These new options were also added in the `RunStarlarkScript`, `RunStarlarkPackage` and the `RunStarlarkRemotePackage` SDKs methods, users will have to update the calls. ([#693](https://github.com/kurtosis-tech/kurtosis/issues/693)) ([1693237](https://github.com/kurtosis-tech/kurtosis/commit/16932374043560daf45689570ec3cbe4e8e174f9)) +* random function args ([#703](https://github.com/kurtosis-tech/kurtosis/issues/703)) ([e650a20](https://github.com/kurtosis-tech/kurtosis/commit/e650a20101ee1190b1491ca4ccc8acb58c0bc7dd)) +* Start and Stop service Starlark instructions for Docker ([#694](https://github.com/kurtosis-tech/kurtosis/issues/694)) ([10b6b91](https://github.com/kurtosis-tech/kurtosis/commit/10b6b91dc9e8f370bab307297de9b8fe07ca51ce)) + +## [0.77.4](https://github.com/kurtosis-tech/kurtosis/compare/0.77.3...0.77.4) (2023-06-09) + + +### Bug Fixes + +* make k8s store service files match docker ([#695](https://github.com/kurtosis-tech/kurtosis/issues/695)) ([dc2d8cb](https://github.com/kurtosis-tech/kurtosis/commit/dc2d8cb59d305fa96a2784cd1219352ce235b420)) + +## [0.77.3](https://github.com/kurtosis-tech/kurtosis/compare/0.77.2...0.77.3) (2023-06-08) + + +### Features + +* Add `kurtosis service exec` command ([#690](https://github.com/kurtosis-tech/kurtosis/issues/690)) ([ece4937](https://github.com/kurtosis-tech/kurtosis/commit/ece49371552f0f9c03fe73b879363c0599f65106)) + +## [0.77.2](https://github.com/kurtosis-tech/kurtosis/compare/0.77.1...0.77.2) (2023-06-08) + + +### Features + +* added min resource constraint for kubernetes ([#687](https://github.com/kurtosis-tech/kurtosis/issues/687)) ([0aadb91](https://github.com/kurtosis-tech/kurtosis/commit/0aadb912c443c93fe27cebeb727a8ce5f16ced38)) +* Label issue based on severity ([#662](https://github.com/kurtosis-tech/kurtosis/issues/662)) ([13b51c6](https://github.com/kurtosis-tech/kurtosis/commit/13b51c6f409432e12b95e9275f5ece788e22989d)) + + +### Bug Fixes + +* Auto-restart engine when cluster is updated ([#661](https://github.com/kurtosis-tech/kurtosis/issues/661)) ([479b9f4](https://github.com/kurtosis-tech/kurtosis/commit/479b9f48507def91d76a17731aa84d76c69eff76)) +* display service name in exec ([#682](https://github.com/kurtosis-tech/kurtosis/issues/682)) ([6faafea](https://github.com/kurtosis-tech/kurtosis/commit/6faafea86afac1056e529b026743675a5bbfcbf6)) +* Fix error propagation in context switch ([#658](https://github.com/kurtosis-tech/kurtosis/issues/658)) ([a7c9bd1](https://github.com/kurtosis-tech/kurtosis/commit/a7c9bd1380d81e7f367daf964021a89086099872)) +* Fix typo in the configuration path of the issue labeler workflow ([#667](https://github.com/kurtosis-tech/kurtosis/issues/667)) ([ec6c8e8](https://github.com/kurtosis-tech/kurtosis/commit/ec6c8e885ada06b0adadd44b6d698320a7b43511)) +* Fix user service logs when backend is kubernetes ([#678](https://github.com/kurtosis-tech/kurtosis/issues/678)) ([099d046](https://github.com/kurtosis-tech/kurtosis/commit/099d04649f7922adf82dad295f9a701369ee7531)) +* fixed the error we see while running the package(s) in dry-mode ([#679](https://github.com/kurtosis-tech/kurtosis/issues/679)) ([af5138c](https://github.com/kurtosis-tech/kurtosis/commit/af5138c1c68ef245c1fd9fce6bd04827ef6c048f)) +* Kurtosis shell exec panics if stdin is not terminal ([#686](https://github.com/kurtosis-tech/kurtosis/issues/686)) ([5fad486](https://github.com/kurtosis-tech/kurtosis/commit/5fad4867f9b76498c04c4037ea367161f2c0bb8a)) + +## [0.77.1](https://github.com/kurtosis-tech/kurtosis/compare/0.77.0...0.77.1) (2023-05-30) + + +### Features + +* Implement PortSpec Wait on Kubernetes backend ([#640](https://github.com/kurtosis-tech/kurtosis/issues/640)) ([7c9989d](https://github.com/kurtosis-tech/kurtosis/commit/7c9989d3119c51c7325de077db1b4f44e4876ce0)) +* Run the golang testsuite against K8S (Minikube) ([#653](https://github.com/kurtosis-tech/kurtosis/issues/653)) ([8ddf5ef](https://github.com/kurtosis-tech/kurtosis/commit/8ddf5ef18536b7ae654309f94292ad377373092b)) + +## [0.77.0](https://github.com/kurtosis-tech/kurtosis/compare/0.76.9...0.77.0) (2023-05-25) + + +### ⚠ BREAKING CHANGES + +* Add Kubernetes implementation ([#638](https://github.com/kurtosis-tech/kurtosis/issues/638)) + +### Features + +* Add Kubernetes implementation ([#638](https://github.com/kurtosis-tech/kurtosis/issues/638)) ([8ad708b](https://github.com/kurtosis-tech/kurtosis/commit/8ad708bca139c79312de60643db1691938f55861)) + +## [0.76.9](https://github.com/kurtosis-tech/kurtosis/compare/0.76.8...0.76.9) (2023-05-23) + + +### Bug Fixes + +* 'engine stop' now waits for engine to report STOPPED status ([#635](https://github.com/kurtosis-tech/kurtosis/issues/635)) ([e16e123](https://github.com/kurtosis-tech/kurtosis/commit/e16e12304a260c0b6bcbcb6ab119e5b8380880db)) + +## [0.76.8](https://github.com/kurtosis-tech/kurtosis/compare/0.76.7...0.76.8) (2023-05-23) + + +### Features + +* Return error on SDK if Starlark run on any step ([#634](https://github.com/kurtosis-tech/kurtosis/issues/634)) ([8a01cff](https://github.com/kurtosis-tech/kurtosis/commit/8a01cfffc92c47d44d0a73593bf91d4c990f72ed)) + + +### Bug Fixes + +* Make printWarningIfArgumentIsDeprecated unit test deterministic ([#633](https://github.com/kurtosis-tech/kurtosis/issues/633)) ([46bbee5](https://github.com/kurtosis-tech/kurtosis/commit/46bbee5dcd67346f0007d6d83326fd9200fa9dda)) +* Rollback to previous cluster when cluster set fails ([#631](https://github.com/kurtosis-tech/kurtosis/issues/631)) ([0e212c9](https://github.com/kurtosis-tech/kurtosis/commit/0e212c93f05fc174a6ad47bafb25975e0b95b892)) + +## [0.76.7](https://github.com/kurtosis-tech/kurtosis/compare/0.76.6...0.76.7) (2023-05-17) + + +### Bug Fixes + +* Exclude resources dir from the internal testsuites ([#622](https://github.com/kurtosis-tech/kurtosis/issues/622)) ([ffd2031](https://github.com/kurtosis-tech/kurtosis/commit/ffd203174db8d515752ddf832a8dbfc924687520)) +* Remove the GRPC proxy port from the engine and from the APIC ([#626](https://github.com/kurtosis-tech/kurtosis/issues/626)) ([de284be](https://github.com/kurtosis-tech/kurtosis/commit/de284bed4f9031e51fb4ccafc934e39bea3879d5)) +* set MTU to 1440 to fix GitPod networking ([#627](https://github.com/kurtosis-tech/kurtosis/issues/627)) ([19ec18e](https://github.com/kurtosis-tech/kurtosis/commit/19ec18e4174555b51c917e13f34f7275c6ddab1a)) + +## [0.76.6](https://github.com/kurtosis-tech/kurtosis/compare/0.76.5...0.76.6) (2023-05-12) + + +### Bug Fixes + +* ips are on the range 172.16.0.0/16 ([#618](https://github.com/kurtosis-tech/kurtosis/issues/618)) ([b48cb73](https://github.com/kurtosis-tech/kurtosis/commit/b48cb73dadffdb23922c73b68fed1485840eb846)) + +## [0.76.5](https://github.com/kurtosis-tech/kurtosis/compare/0.76.4...0.76.5) (2023-05-11) + + +### Features + +* Support path argument autocomplete in all CLI commands ([#607](https://github.com/kurtosis-tech/kurtosis/issues/607)) ([e5a5fe1](https://github.com/kurtosis-tech/kurtosis/commit/e5a5fe1f4c690a4ceeea63e718fb4c446e921940)) + +## [0.76.4](https://github.com/kurtosis-tech/kurtosis/compare/0.76.3...0.76.4) (2023-05-11) + + +### Features + +* Add Windows support for CLI ([#608](https://github.com/kurtosis-tech/kurtosis/issues/608)) ([4cc1c56](https://github.com/kurtosis-tech/kurtosis/commit/4cc1c56e3cebf41c5a033df718938a4d805a3400)) +* added sign-up for kcloud ([#591](https://github.com/kurtosis-tech/kurtosis/issues/591)) ([16641e9](https://github.com/kurtosis-tech/kurtosis/commit/16641e9ed0947ea34d44b0c521b429ace5ab5b50)) +* Help developers to work across the project modules ([#596](https://github.com/kurtosis-tech/kurtosis/issues/596)) ([e7f845e](https://github.com/kurtosis-tech/kurtosis/commit/e7f845ecd67c8218b28ff284b12ac18949108364)) +* return deprecation warnings to users in yellow in colour. ([#586](https://github.com/kurtosis-tech/kurtosis/issues/586)) ([7609fd8](https://github.com/kurtosis-tech/kurtosis/commit/7609fd8c77994875eae77fd458f1744f267c17fb)) + + +### Bug Fixes + +* Enable autocomplete for the `files upload` path argument ([#598](https://github.com/kurtosis-tech/kurtosis/issues/598)) ([be52f9e](https://github.com/kurtosis-tech/kurtosis/commit/be52f9e73c5cd63e09f5c2343add165886bd7313)) +* kurtosis --> kurtosistech in readme ([#604](https://github.com/kurtosis-tech/kurtosis/issues/604)) ([d6c2ea2](https://github.com/kurtosis-tech/kurtosis/commit/d6c2ea2f6f8127c799701707e65c7697c8354452)) +* Pipe metric reporting logs to logger instead of stderr ([#576](https://github.com/kurtosis-tech/kurtosis/issues/576)) ([7060473](https://github.com/kurtosis-tech/kurtosis/commit/7060473563f12b9d097aeb20eb3e4c5cf3e58d55)) +* Refresh the README dev instructions ([#595](https://github.com/kurtosis-tech/kurtosis/issues/595)) ([0c71fac](https://github.com/kurtosis-tech/kurtosis/commit/0c71fac3ae3a36fdf6df56e567b3ba184a6756b6)) +* rename cloud-->kloud in readme ([#602](https://github.com/kurtosis-tech/kurtosis/issues/602)) ([a998d39](https://github.com/kurtosis-tech/kurtosis/commit/a998d39a3511cf6ba84759f4b91cb20795cefd3d)) +* Support redirects with cookies in the user support URLs validation test ([#600](https://github.com/kurtosis-tech/kurtosis/issues/600)) ([ce9718e](https://github.com/kurtosis-tech/kurtosis/commit/ce9718ed55e60cd227f036149da0c410ba99be09)), closes [#599](https://github.com/kurtosis-tech/kurtosis/issues/599) + +## [0.76.3](https://github.com/kurtosis-tech/kurtosis/compare/0.76.2...0.76.3) (2023-04-27) + + +### Bug Fixes + +* make api depend not on internal version of grpc-file-transfer ([#572](https://github.com/kurtosis-tech/kurtosis/issues/572)) ([8cb536e](https://github.com/kurtosis-tech/kurtosis/commit/8cb536e35930e11d0414e8ab49a2bfa86692fe2d)) + +## [0.76.2](https://github.com/kurtosis-tech/kurtosis/compare/0.76.1...0.76.2) (2023-04-27) + + +### Bug Fixes + +* fixed grpc-file-transfer Golang module name ([#570](https://github.com/kurtosis-tech/kurtosis/issues/570)) ([bcb0dc9](https://github.com/kurtosis-tech/kurtosis/commit/bcb0dc935ee8b22c0900d6cdaf844c6e78baab14)) + +## [0.76.1](https://github.com/kurtosis-tech/kurtosis/compare/0.76.0...0.76.1) (2023-04-26) + + +### Bug Fixes + +* random error message after execution ([#565](https://github.com/kurtosis-tech/kurtosis/issues/565)) ([daedaef](https://github.com/kurtosis-tech/kurtosis/commit/daedaef4a82ad49f0dcdf865c716b72e919d48c5)) + +## [0.76.0](https://github.com/kurtosis-tech/kurtosis/compare/0.75.9...0.76.0) (2023-04-26) + + +### ⚠ BREAKING CHANGES + +* Added automatic service's ports opening wait for TCP and UDP ports. All the declared service's TCP and UDP ports will be checked by default but this can be also deactivate. This change should not break anything in most cases but could be some cases were the default timeout is not enough and users will have to increase the wait timeout to fix the break ([#534](https://github.com/kurtosis-tech/kurtosis/issues/534)) + +### Features + +* Added automatic service's ports opening wait for TCP and UDP ports. All the declared service's TCP and UDP ports will be checked by default but this can be also deactivate. This change should not break anything in most cases but could be some cases were the default timeout is not enough and users will have to increase the wait timeout to fix the break ([#534](https://github.com/kurtosis-tech/kurtosis/issues/534)) ([a961b6e](https://github.com/kurtosis-tech/kurtosis/commit/a961b6e03edc91abad0a12a277bb083062fbe2a0)) + +## [0.75.9](https://github.com/kurtosis-tech/kurtosis/compare/0.75.8...0.75.9) (2023-04-24) + + +### Features + +* allow passing an exec to shell ([#550](https://github.com/kurtosis-tech/kurtosis/issues/550)) ([44c9187](https://github.com/kurtosis-tech/kurtosis/commit/44c91876dbee951de70368db33a379237a7f8cda)) +* Raise file size limit to 100mb for file downloads and uploads ([#542](https://github.com/kurtosis-tech/kurtosis/issues/542)) ([ec8534a](https://github.com/kurtosis-tech/kurtosis/commit/ec8534aeb187f3c17b69c344d96efe24cc187697)) +* replace runtime values in output with real values ([#541](https://github.com/kurtosis-tech/kurtosis/issues/541)) ([8df9666](https://github.com/kurtosis-tech/kurtosis/commit/8df966631afca0fbfe0bd345fe9a0576b55824f6)) + + +### Bug Fixes + +* restrict random network allocation to 10.0.0.0/8 following RFC 4096 ([#545](https://github.com/kurtosis-tech/kurtosis/issues/545)) ([003f190](https://github.com/kurtosis-tech/kurtosis/commit/003f190af636f76009fac34899d8b51ef5dad901)) + +## [0.75.8](https://github.com/kurtosis-tech/kurtosis/compare/0.75.7...0.75.8) (2023-04-20) + + +### Features + +* GRPC file streaming library ([#504](https://github.com/kurtosis-tech/kurtosis/issues/504)) ([ec30ada](https://github.com/kurtosis-tech/kurtosis/commit/ec30ada5e81e18442c60e420c4fb86435a79d2a5)) + + +### Bug Fixes + +* added telemetry about network partitioning for enclaves that get created ([#535](https://github.com/kurtosis-tech/kurtosis/issues/535)) ([379a1a6](https://github.com/kurtosis-tech/kurtosis/commit/379a1a69404f04c9f6d6235e1759c471951c0419)) + +## [0.75.7](https://github.com/kurtosis-tech/kurtosis/compare/0.75.6...0.75.7) (2023-04-19) + + +### Bug Fixes + +* prune non 0 patch versions for docs that aren't current minor version ([#528](https://github.com/kurtosis-tech/kurtosis/issues/528)) ([c65d691](https://github.com/kurtosis-tech/kurtosis/commit/c65d69168fcbcd3c7e470dedb4156594616e35a4)), closes [#487](https://github.com/kurtosis-tech/kurtosis/issues/487) + +## [0.75.6](https://github.com/kurtosis-tech/kurtosis/compare/0.75.5...0.75.6) (2023-04-19) + + +### Features + +* validate port ids before execution ([#519](https://github.com/kurtosis-tech/kurtosis/issues/519)) ([f6aceee](https://github.com/kurtosis-tech/kurtosis/commit/f6aceee42f65ce239b019d4179543aaf53b9e605)) + + +### Bug Fixes + +* Fix error message in recipe extraction logic to help with debugging ([#527](https://github.com/kurtosis-tech/kurtosis/issues/527)) ([45f9f8b](https://github.com/kurtosis-tech/kurtosis/commit/45f9f8b8d2b01d3480e444bd9319a048966802ca)) +* Fix NPE when stopping an already killled Portal process ([#526](https://github.com/kurtosis-tech/kurtosis/issues/526)) ([7307322](https://github.com/kurtosis-tech/kurtosis/commit/7307322bdf36e8dac21cf613c40fbab78e426685)) +* Pass Content-Type header to request ([#531](https://github.com/kurtosis-tech/kurtosis/issues/531)) ([b3a9294](https://github.com/kurtosis-tech/kurtosis/commit/b3a92943258493c0bc705c3755d8b9ae20715035)) + +## [0.75.5](https://github.com/kurtosis-tech/kurtosis/compare/0.75.4...0.75.5) (2023-04-18) + + +### Features + +* Add extractors to exec recipe ([#508](https://github.com/kurtosis-tech/kurtosis/issues/508)) ([b044093](https://github.com/kurtosis-tech/kurtosis/commit/b0440932e18397239212c63576bb15fbda00bd59)) + +## [0.75.4](https://github.com/kurtosis-tech/kurtosis/compare/0.75.3...0.75.4) (2023-04-18) + + +### Bug Fixes + +* Address flakiness of extractor test ([#510](https://github.com/kurtosis-tech/kurtosis/issues/510)) ([4508df3](https://github.com/kurtosis-tech/kurtosis/commit/4508df328b5f91310353cec3e7abb58483e40083)) +* Support ExecRecipe in ReadyCondition ([#507](https://github.com/kurtosis-tech/kurtosis/issues/507)) ([539e8e9](https://github.com/kurtosis-tech/kurtosis/commit/539e8e97185aa785d74c814bf587b06bd9f6ed04)) + +## [0.75.3](https://github.com/kurtosis-tech/kurtosis/compare/0.75.2...0.75.3) (2023-04-18) + + +### Bug Fixes + +* Re-enable `--platform=linux/amd64` for Engine and APIC docker image ([#516](https://github.com/kurtosis-tech/kurtosis/issues/516)) ([07a0d07](https://github.com/kurtosis-tech/kurtosis/commit/07a0d07250e30fbf422917005e706c1a10789750)) + +## [0.75.2](https://github.com/kurtosis-tech/kurtosis/compare/0.75.1...0.75.2) (2023-04-17) + + +### Bug Fixes + +* Fix argument extraction logic when argument is present but is of wrong type ([#514](https://github.com/kurtosis-tech/kurtosis/issues/514)) ([0c97d83](https://github.com/kurtosis-tech/kurtosis/commit/0c97d83daea233d1687bc7a56dfd39035c1fc4d3)) +* use subnetworking over partitioning ([#491](https://github.com/kurtosis-tech/kurtosis/issues/491)) ([327cdcf](https://github.com/kurtosis-tech/kurtosis/commit/327cdcfb5b6d97805bcd9bf4bbbee7eb2270af94)), closes [#443](https://github.com/kurtosis-tech/kurtosis/issues/443) +* wait command times out even if recipe is still executing ([#480](https://github.com/kurtosis-tech/kurtosis/issues/480)) ([9fd81fa](https://github.com/kurtosis-tech/kurtosis/commit/9fd81fadeb8662c39c20c2647b2fb9e2c5946506)) + +## [0.75.1](https://github.com/kurtosis-tech/kurtosis/compare/0.75.0...0.75.1) (2023-04-11) + + +### Bug Fixes + +* revert files download enclave flag to arg ([#489](https://github.com/kurtosis-tech/kurtosis/issues/489)) ([6844393](https://github.com/kurtosis-tech/kurtosis/commit/68443939d27e3eb249ae75eebb913b09877a53b8)), closes [#460](https://github.com/kurtosis-tech/kurtosis/issues/460) + +## [0.75.0](https://github.com/kurtosis-tech/kurtosis/compare/0.74.0...0.75.0) (2023-04-10) + + +### ⚠ BREAKING CHANGES + +* removed the Kurtosis CLI `config init` command ([#461](https://github.com/kurtosis-tech/kurtosis/issues/461)) + +### Code Refactoring + +* removed the Kurtosis CLI `config init` command ([#461](https://github.com/kurtosis-tech/kurtosis/issues/461)) ([06578e4](https://github.com/kurtosis-tech/kurtosis/commit/06578e4cad2a097daa8e1dd77c252b97b370606d)), closes [#435](https://github.com/kurtosis-tech/kurtosis/issues/435) + +## [0.74.0](https://github.com/kurtosis-tech/kurtosis/compare/0.73.2...0.74.0) (2023-04-03) + + +### ⚠ BREAKING CHANGES + +* renamed the `ReadyConditions` custom type to `ReadyCondition` ([#429](https://github.com/kurtosis-tech/kurtosis/issues/429)) + +### Features + +* Add linting validation for Markdown reference-style links ([#453](https://github.com/kurtosis-tech/kurtosis/issues/453)) ([7cbe728](https://github.com/kurtosis-tech/kurtosis/commit/7cbe72869c8f3ac86db0f13dea107ad5f54a5dd6)), closes [#448](https://github.com/kurtosis-tech/kurtosis/issues/448) + + +### Bug Fixes + +* colourized the cli output and display starlark messages to the log ([#414](https://github.com/kurtosis-tech/kurtosis/issues/414)) ([af072af](https://github.com/kurtosis-tech/kurtosis/commit/af072af845a887a21171988cb470d29cb70b4884)) + + +### Code Refactoring + +* renamed the `ReadyConditions` custom type to `ReadyCondition` ([#429](https://github.com/kurtosis-tech/kurtosis/issues/429)) ([4076ec4](https://github.com/kurtosis-tech/kurtosis/commit/4076ec4cbc9a04da7ba7060af0e9c5be89f866ff)) + +## [0.73.2](https://github.com/kurtosis-tech/kurtosis/compare/0.73.1...0.73.2) (2023-04-02) + + +### Bug Fixes + +* Fix two small bugs in the docs ([#451](https://github.com/kurtosis-tech/kurtosis/issues/451)) ([d960dee](https://github.com/kurtosis-tech/kurtosis/commit/d960dee0a4db4a253e766ae04f23f24ab08e985a)) + +## [0.73.1](https://github.com/kurtosis-tech/kurtosis/compare/0.73.0...0.73.1) (2023-04-02) + + +### Features + +* Reduce the word count & language complexity of the Github Issue templates ([#437](https://github.com/kurtosis-tech/kurtosis/issues/437)) ([b1fad7d](https://github.com/kurtosis-tech/kurtosis/commit/b1fad7d9207be855fbdbce9d70410aecf679d892)) + + +### Bug Fixes + +* Actually fix the broken Docusaurus links in the navbar and footer ([#450](https://github.com/kurtosis-tech/kurtosis/issues/450)) ([3436445](https://github.com/kurtosis-tech/kurtosis/commit/3436445f3f6351b66c9ef5d86a59accd19f4baaf)) +* Fix bug with release-please PR getting a modified Yarn lockfile ([#446](https://github.com/kurtosis-tech/kurtosis/issues/446)) ([bfa155b](https://github.com/kurtosis-tech/kurtosis/commit/bfa155bf4d4be19cff1f3635083d6390586b94fa)) +* Fix links that should be absolute ([#427](https://github.com/kurtosis-tech/kurtosis/issues/427)) ([492bea6](https://github.com/kurtosis-tech/kurtosis/commit/492bea61723b03377c1b981c946fd3fd1c83c70e)) +* Fixed many broken links in the docs ([#444](https://github.com/kurtosis-tech/kurtosis/issues/444)) ([9251cc9](https://github.com/kurtosis-tech/kurtosis/commit/9251cc9f49a323c8916112decc9cd9d9e1fcc430)) +* Improve error message when package arg fails deserialisation ([#418](https://github.com/kurtosis-tech/kurtosis/issues/418)) ([d54fd73](https://github.com/kurtosis-tech/kurtosis/commit/d54fd73e0cb3713214549d6d20f04d374d8bbb50)) +* Indent Caused by in stacktraces ([#417](https://github.com/kurtosis-tech/kurtosis/issues/417)) ([c165a15](https://github.com/kurtosis-tech/kurtosis/commit/c165a15ca24e5af523e27c2d34661025e4189590)) +* Remove no-dead-links Remark plugin ([#447](https://github.com/kurtosis-tech/kurtosis/issues/447)) ([b59b3f8](https://github.com/kurtosis-tech/kurtosis/commit/b59b3f8fd07fe3789595b580085841df54990b57)) +* Remove Quickstart, SDK, and CLI links from the navbar ([#449](https://github.com/kurtosis-tech/kurtosis/issues/449)) ([a7effc9](https://github.com/kurtosis-tech/kurtosis/commit/a7effc946c5db2eeacbcbaee4286c85989a7005f)) +* Try and fix Yarn lockfile violation that's causing Cloudflare publish to fail ([#445](https://github.com/kurtosis-tech/kurtosis/issues/445)) ([4db878b](https://github.com/kurtosis-tech/kurtosis/commit/4db878ba1c47e55af92206249775b573b8de7fd0)) + +## [0.73.0](https://github.com/kurtosis-tech/kurtosis/compare/0.72.2...0.73.0) (2023-03-31) + + +### ⚠ BREAKING CHANGES + +* Moved the `sevice_name` argument to the first position in the `exec`, `request`, and `wait` instructions, users will have to adapt these instructions calls if where using positional arguments. ([#412](https://github.com/kurtosis-tech/kurtosis/issues/412)) + +### Features + +* Add portal `status`, `start` and `stop` command ([#334](https://github.com/kurtosis-tech/kurtosis/issues/334)) ([beec527](https://github.com/kurtosis-tech/kurtosis/commit/beec5275f3344d81ea4c30553743d7524857ccf5)) +* clean the error for starlark output as well ([#413](https://github.com/kurtosis-tech/kurtosis/issues/413)) ([5953a23](https://github.com/kurtosis-tech/kurtosis/commit/5953a23413ec6ee07790e1330dd6f0389e959b6c)) + + +### Bug Fixes + +* clean error paths for users ([#369](https://github.com/kurtosis-tech/kurtosis/issues/369)) ([fedc8d0](https://github.com/kurtosis-tech/kurtosis/commit/fedc8d0a82b387498e00f5dabf40c7fbf40247f8)) + + +### Code Refactoring + +* Moved the `sevice_name` argument to the first position in the `exec`, `request`, and `wait` instructions, users will have to adapt these instructions calls if where using positional arguments. ([#412](https://github.com/kurtosis-tech/kurtosis/issues/412)) ([126ccbc](https://github.com/kurtosis-tech/kurtosis/commit/126ccbcc5920714af14bc47bc7190867d6279803)) + +## [0.72.2](https://github.com/kurtosis-tech/kurtosis/compare/0.72.1...0.72.2) (2023-03-30) + + +### Bug Fixes + +* Make GetCluster non fatal if it is unset ([#403](https://github.com/kurtosis-tech/kurtosis/issues/403)) ([3e9db8f](https://github.com/kurtosis-tech/kurtosis/commit/3e9db8f736c8d25f513d080c367f30011d5da511)) + +## [0.72.1](https://github.com/kurtosis-tech/kurtosis/compare/0.72.0...0.72.1) (2023-03-30) + + +### Features + +* Noop when switching to current context ([#390](https://github.com/kurtosis-tech/kurtosis/issues/390)) ([2003df9](https://github.com/kurtosis-tech/kurtosis/commit/2003df912278fe4fd30e29ab9011ebb39834d7b5)) + + +### Bug Fixes + +* Fix confusing warning about port mapping ([#396](https://github.com/kurtosis-tech/kurtosis/issues/396)) ([2bc2e13](https://github.com/kurtosis-tech/kurtosis/commit/2bc2e13de487be3e4458c2ac2c0d000ce0d12589)) +* fix help text and have flags instead of args for files download ([#395](https://github.com/kurtosis-tech/kurtosis/issues/395)) ([f9083cc](https://github.com/kurtosis-tech/kurtosis/commit/f9083cc34584dd2face61a7165bdfa2b8be2f0ba)), closes [#370](https://github.com/kurtosis-tech/kurtosis/issues/370) + +## [0.72.0](https://github.com/kurtosis-tech/kurtosis/compare/0.71.2...0.72.0) (2023-03-30) + + +### ⚠ BREAKING CHANGES + +* Change starlark args from struct to dict ([#376](https://github.com/kurtosis-tech/kurtosis/issues/376)) + +### Features + +* Restart engine post cluster set ([#393](https://github.com/kurtosis-tech/kurtosis/issues/393)) ([be82680](https://github.com/kurtosis-tech/kurtosis/commit/be82680880552add195954d2962c74e9fecefed0)) + + +### Code Refactoring + +* Change starlark args from struct to dict ([#376](https://github.com/kurtosis-tech/kurtosis/issues/376)) ([f350621](https://github.com/kurtosis-tech/kurtosis/commit/f350621f4080514caa96b93a0581186d07a306a6)) + +## [0.71.2](https://github.com/kurtosis-tech/kurtosis/compare/0.71.1...0.71.2) (2023-03-30) + + +### Bug Fixes + +* Fix engine local dependencies replace ([#389](https://github.com/kurtosis-tech/kurtosis/issues/389)) ([99e4160](https://github.com/kurtosis-tech/kurtosis/commit/99e41605b7f5445b453c5d55aeb2f4d043445666)) + +## [0.71.1](https://github.com/kurtosis-tech/kurtosis/compare/0.71.0...0.71.1) (2023-03-29) + + +### Features + +* add a timestamp at the end of dump dir if default is chosen ([#386](https://github.com/kurtosis-tech/kurtosis/issues/386)) ([6e1898e](https://github.com/kurtosis-tech/kurtosis/commit/6e1898e999e22ebb1b893b6e65f44d26d059b9d9)) +* best effort autocomplete for service logs after engine restart ([#374](https://github.com/kurtosis-tech/kurtosis/issues/374)) ([e2fb47c](https://github.com/kurtosis-tech/kurtosis/commit/e2fb47c927ec673afc63308a7eaa688c0c91bb80)), closes [#373](https://github.com/kurtosis-tech/kurtosis/issues/373) + + +### Bug Fixes + +* polish Github issue templates ([#380](https://github.com/kurtosis-tech/kurtosis/issues/380)) ([bd9a9d0](https://github.com/kurtosis-tech/kurtosis/commit/bd9a9d05afe5e93c792b8dbfe25e84166f175d65)) + +## [0.71.0](https://github.com/kurtosis-tech/kurtosis/compare/0.70.7...0.71.0) (2023-03-29) + + +### ⚠ BREAKING CHANGES + +* rename the argument `name` to `service_name` for `update_service`, `remove_service` and `add_service` ([#360](https://github.com/kurtosis-tech/kurtosis/issues/360)) + +### Features + +* Automatically map all service ports to local ports post Starlark run and service add ([#363](https://github.com/kurtosis-tech/kurtosis/issues/363)) ([7906aee](https://github.com/kurtosis-tech/kurtosis/commit/7906aee2d3aacb0afcaffb1e77847b9d4148e905)) +* rename the argument `name` to `service_name` for `update_service`, `remove_service` and `add_service` ([#360](https://github.com/kurtosis-tech/kurtosis/issues/360)) ([c80d3c0](https://github.com/kurtosis-tech/kurtosis/commit/c80d3c0da7e536590551e5f6c53c9caf4add781c)), closes [#200](https://github.com/kurtosis-tech/kurtosis/issues/200) + + +### Bug Fixes + +* Fixed broken quickstart code block ([#339](https://github.com/kurtosis-tech/kurtosis/issues/339)) ([00f5cd2](https://github.com/kurtosis-tech/kurtosis/commit/00f5cd2576bdf62da2fd071f3cba39f3b976075c)) +* Improve error message when cloning a git repo failed ([#375](https://github.com/kurtosis-tech/kurtosis/issues/375)) ([9702621](https://github.com/kurtosis-tech/kurtosis/commit/97026218c036486697bf6b6a8596774a84172b11)) + +## [0.70.7](https://github.com/kurtosis-tech/kurtosis/compare/0.70.6...0.70.7) (2023-03-28) + + +### Bug Fixes + +* added a fix for release failure ([#361](https://github.com/kurtosis-tech/kurtosis/issues/361)) ([04ee614](https://github.com/kurtosis-tech/kurtosis/commit/04ee6140471a7e6c4b3ea4d6b1e1cb75e4bb1374)) + +## [0.70.6](https://github.com/kurtosis-tech/kurtosis/compare/0.70.5...0.70.6) (2023-03-28) + + +### Features + +* add search on docs ([#159](https://github.com/kurtosis-tech/kurtosis/issues/159)) ([f80d036](https://github.com/kurtosis-tech/kurtosis/commit/f80d0361435c99707291c0e96c0c308326343330)) +* integrate lsp with monrepo ([#223](https://github.com/kurtosis-tech/kurtosis/issues/223)) ([b5ed670](https://github.com/kurtosis-tech/kurtosis/commit/b5ed6707b1c3254cefcfa9201fb76ff1116dedce)) + + +### Bug Fixes + +* fix typo in reindex workflow ([#357](https://github.com/kurtosis-tech/kurtosis/issues/357)) ([8900ff2](https://github.com/kurtosis-tech/kurtosis/commit/8900ff230240487e40e706fccc3b8e32b1d1082f)) +* remove file paths from error message ([#256](https://github.com/kurtosis-tech/kurtosis/issues/256)) ([cb603d8](https://github.com/kurtosis-tech/kurtosis/commit/cb603d836772812d602bfb86736a8145b85162e1)) +* remove trailing errors after starlark execution ([724ac35](https://github.com/kurtosis-tech/kurtosis/commit/724ac355e8cf64a070c3d62a0f593399b5ef2dde)) +* remove trailing errors after starlark execution ([#257](https://github.com/kurtosis-tech/kurtosis/issues/257)) ([724ac35](https://github.com/kurtosis-tech/kurtosis/commit/724ac355e8cf64a070c3d62a0f593399b5ef2dde)) + +## [0.70.5](https://github.com/kurtosis-tech/kurtosis/compare/0.70.4...0.70.5) (2023-03-28) + + +### Features + +* Print the running engine version while running Kurtosis Version ([#346](https://github.com/kurtosis-tech/kurtosis/issues/346)) ([9ef03cb](https://github.com/kurtosis-tech/kurtosis/commit/9ef03cb22e26d9dce556e1d31bacf9b3b30da736)) + +## [0.70.4](https://github.com/kurtosis-tech/kurtosis/compare/0.70.3...0.70.4) (2023-03-28) + + +### Features + +* Added extra name generation items ([#342](https://github.com/kurtosis-tech/kurtosis/issues/342)) ([0ed2923](https://github.com/kurtosis-tech/kurtosis/commit/0ed2923d9a16cb68b706e25112a741a4b7384944)) +* Publish multi-arch image for `files-artifacts-expander` ([#344](https://github.com/kurtosis-tech/kurtosis/issues/344)) ([9e2b369](https://github.com/kurtosis-tech/kurtosis/commit/9e2b369206b974d06e5a7c172b6363e5c6fb1d92)) + +## [0.70.3](https://github.com/kurtosis-tech/kurtosis/compare/0.70.2...0.70.3) (2023-03-27) + + +### Features + +* Added `bug, feature and docs` flags in the `kurtosis feedback` command ([#287](https://github.com/kurtosis-tech/kurtosis/issues/287)) ([963e9dd](https://github.com/kurtosis-tech/kurtosis/commit/963e9dd055a3ceabafde11a4d942e16f300d827c)) + + +### Bug Fixes + +* check service name contains allowed characters and errors cleanly ([#315](https://github.com/kurtosis-tech/kurtosis/issues/315)) ([94af4bd](https://github.com/kurtosis-tech/kurtosis/commit/94af4bda3aac9a1ed45e6ac503407d271ba1d73f)), closes [#164](https://github.com/kurtosis-tech/kurtosis/issues/164) + +## [0.70.2](https://github.com/kurtosis-tech/kurtosis/compare/0.70.1...0.70.2) (2023-03-27) + + +### Features + +* Automatically restart engine on context switch ([#329](https://github.com/kurtosis-tech/kurtosis/issues/329)) ([b0712cc](https://github.com/kurtosis-tech/kurtosis/commit/b0712cc42fca1b4ba322bf473da57db4eab8c462)) + + +### Bug Fixes + +* Fix info CLI log for portal not running ([#330](https://github.com/kurtosis-tech/kurtosis/issues/330)) ([0fb938e](https://github.com/kurtosis-tech/kurtosis/commit/0fb938e31c29778ac122675e7706e3ad1fd0fc93)) + +## [0.70.1](https://github.com/kurtosis-tech/kurtosis/compare/0.70.0...0.70.1) (2023-03-27) + + +### Features + +* Add context `rm` command ([#275](https://github.com/kurtosis-tech/kurtosis/issues/275)) ([c20ca12](https://github.com/kurtosis-tech/kurtosis/commit/c20ca121443a78ed6b266cd18b5d69997ee69e57)) +* Add context `switch` CLI command ([#317](https://github.com/kurtosis-tech/kurtosis/issues/317)) ([ebab7eb](https://github.com/kurtosis-tech/kurtosis/commit/ebab7ebb697e4c791b47bff14a4e32aaa04268b5)) +* add kurtosis engine logs command that dumps logs for all engines in target dir ([#313](https://github.com/kurtosis-tech/kurtosis/issues/313)) ([cbb588c](https://github.com/kurtosis-tech/kurtosis/commit/cbb588c01a6d8d8baffcb41c87b49716c23b7cfc)) +* result of add service contains a `name` property ([#314](https://github.com/kurtosis-tech/kurtosis/issues/314)) ([af8ca5f](https://github.com/kurtosis-tech/kurtosis/commit/af8ca5f1d7ec9564baf171ea3478b71e3d9f113b)) +* Tunnel remote APIC port to local machine using Kurtosis Portal ([#295](https://github.com/kurtosis-tech/kurtosis/issues/295)) ([4c3ba69](https://github.com/kurtosis-tech/kurtosis/commit/4c3ba69062b78c5f960b4b94fa4427d2b76f6f7a)) + + +### Bug Fixes + +* add example historical version ([#150](https://github.com/kurtosis-tech/kurtosis/issues/150)) ([1548489](https://github.com/kurtosis-tech/kurtosis/commit/1548489b87aa927051b4cd01190b92be48e0714d)) +* be clear about the engine that is being started ([#282](https://github.com/kurtosis-tech/kurtosis/issues/282)) ([5bc1b79](https://github.com/kurtosis-tech/kurtosis/commit/5bc1b79e94a5688dc908bd413a7f410e8aaf2346)) +* Fix starlark value reference bug ([#322](https://github.com/kurtosis-tech/kurtosis/issues/322)) ([63f6626](https://github.com/kurtosis-tech/kurtosis/commit/63f6626be54b71a9fc09e02ae07207c9a9309409)) +* name all args for add_services instruction in quickstart ([#316](https://github.com/kurtosis-tech/kurtosis/issues/316)) ([d413826](https://github.com/kurtosis-tech/kurtosis/commit/d41382635d3ad0c51dec6f937c2c26f105fcfe13)) +* reformat build prereqs in readme ([#290](https://github.com/kurtosis-tech/kurtosis/issues/290)) ([c286151](https://github.com/kurtosis-tech/kurtosis/commit/c28615144a40cfb369e5fb35d9722ecf912fedce)) + +## [0.70.0](https://github.com/kurtosis-tech/kurtosis/compare/0.69.2...0.70.0) (2023-03-22) + + +### ⚠ BREAKING CHANGES + +* This is a breaking change where we are removing the ExecRecipe.service_name, GetHttpRequestRecipe.service_name, and PostHttpRequestRecipe.service_name fields, we suggest users pass this value as an argument in the exec, request and wait instructions where this type is currently used. We are also deprecating the previous exec, request, and wait instructions signature that haven't the service_name field, users must add this field on these instructions call. Another change is that now the service_name field on the exec, request, and wait instructions is mandatory ([#301](https://github.com/kurtosis-tech/kurtosis/issues/301)) + +### Features + +* Kurtosis backend can now connect to a remote Docker backend ([#285](https://github.com/kurtosis-tech/kurtosis/issues/285)) ([98b04c8](https://github.com/kurtosis-tech/kurtosis/commit/98b04c8c98e92c0c7e2661ae1020cee1a1cf1e4b)) +* This is a breaking change where we are removing the ExecRecipe.service_name, GetHttpRequestRecipe.service_name, and PostHttpRequestRecipe.service_name fields, we suggest users pass this value as an argument in the exec, request and wait instructions where this type is currently used. We are also deprecating the previous exec, request, and wait instructions signature that haven't the service_name field, users must add this field on these instructions call. Another change is that now the service_name field on the exec, request, and wait instructions is mandatory ([#301](https://github.com/kurtosis-tech/kurtosis/issues/301)) ([eb7e88f](https://github.com/kurtosis-tech/kurtosis/commit/eb7e88f3309f6d98e8ddb4ff8aad6baa991ea450)) + +## [0.69.2](https://github.com/kurtosis-tech/kurtosis/compare/0.69.1...0.69.2) (2023-03-22) + + +### Features + +* Add context `add` command ([#278](https://github.com/kurtosis-tech/kurtosis/issues/278)) ([bd56cae](https://github.com/kurtosis-tech/kurtosis/commit/bd56cae2c7d29dff4c6011ed80521eddfd39277d)) +* build script check for go and node versions ([#240](https://github.com/kurtosis-tech/kurtosis/issues/240)) ([4749dbe](https://github.com/kurtosis-tech/kurtosis/commit/4749dbe62030eb17bebd02f81b1a0b822f7e843d)) + +## [0.69.1](https://github.com/kurtosis-tech/kurtosis/compare/0.69.0...0.69.1) (2023-03-22) + + +### Features + +* Add `context` root command and simple `ls` subcommand ([#241](https://github.com/kurtosis-tech/kurtosis/issues/241)) ([4097c25](https://github.com/kurtosis-tech/kurtosis/commit/4097c25ad57af61f16044b1193df28b5b94acc97)) + +## [0.69.0](https://github.com/kurtosis-tech/kurtosis/compare/0.68.13...0.69.0) (2023-03-21) + + +### ⚠ BREAKING CHANGES + +* Add acceptable code for request and exec ([#212](https://github.com/kurtosis-tech/kurtosis/issues/212)) +* The --enclave-identifier, --enclave-identifiers and --service-identifier flags have been renamed to , --enclave, --enclaves and --service respectively. Users will have to change any scripts or CI configurations that depend on those flags. +* Reduce wait default timeout from 15 minutes to 10 seconds ([#211](https://github.com/kurtosis-tech/kurtosis/issues/211)) + +### Features + +* Add acceptable code for request and exec ([#212](https://github.com/kurtosis-tech/kurtosis/issues/212)) ([9b00ac2](https://github.com/kurtosis-tech/kurtosis/commit/9b00ac2674ce4d602d1eafb4e00e789709917fd5)), closes [#201](https://github.com/kurtosis-tech/kurtosis/issues/201) [#188](https://github.com/kurtosis-tech/kurtosis/issues/188) +* Add library to manage context configurations ([#196](https://github.com/kurtosis-tech/kurtosis/issues/196)) ([c27038a](https://github.com/kurtosis-tech/kurtosis/commit/c27038a41ebb94940881139f990465fffdc0c8d1)) +* added a command that allows users to open the Kurtosis Twitter page ([#265](https://github.com/kurtosis-tech/kurtosis/issues/265)) ([c8bcc91](https://github.com/kurtosis-tech/kurtosis/commit/c8bcc91b8f4ff389df216e7f446be10d9100c78c)) +* PostHttpRequestRecipe accepts empty body ([#214](https://github.com/kurtosis-tech/kurtosis/issues/214)) ([b7991dc](https://github.com/kurtosis-tech/kurtosis/commit/b7991dc32c31fcac5307d10288bc3908a1b9fc40)) +* print files artifacts registered in an enclave during enclave inspect ([#228](https://github.com/kurtosis-tech/kurtosis/issues/228)) ([ef167d6](https://github.com/kurtosis-tech/kurtosis/commit/ef167d692ebac40d60819987d2f11c47fa4658dc)) +* Reduce wait default timeout from 15 minutes to 10 seconds ([#211](https://github.com/kurtosis-tech/kurtosis/issues/211)) ([4429284](https://github.com/kurtosis-tech/kurtosis/commit/4429284e35eea6757b22a79a833297ec224c5374)) +* rename enclave and service identifier flags ([#264](https://github.com/kurtosis-tech/kurtosis/issues/264)) ([436a44a](https://github.com/kurtosis-tech/kurtosis/commit/436a44a4e4bfa22d9fe5468859f336ecd696c73a)) +* update our bug report template ([c84058b](https://github.com/kurtosis-tech/kurtosis/commit/c84058b3e0240893534b150a21cbeb5fb807bfa1)) +* update our bug report template ([#237](https://github.com/kurtosis-tech/kurtosis/issues/237)) ([c84058b](https://github.com/kurtosis-tech/kurtosis/commit/c84058b3e0240893534b150a21cbeb5fb807bfa1)) + + +### Bug Fixes + +* address typo in our calendly banner link ([#276](https://github.com/kurtosis-tech/kurtosis/issues/276)) ([e1029c3](https://github.com/kurtosis-tech/kurtosis/commit/e1029c3fc41b37468395b16158ef3d0b6cf73082)) +* clarify actions for is user-facing changes in PR template ([#279](https://github.com/kurtosis-tech/kurtosis/issues/279)) ([969c3b8](https://github.com/kurtosis-tech/kurtosis/commit/969c3b870bc837b0ee0d6f6e0c1d800cec47419f)) +* deprecate --id flag in enclave add ([#247](https://github.com/kurtosis-tech/kurtosis/issues/247)) ([974ff18](https://github.com/kurtosis-tech/kurtosis/commit/974ff186478499806156a08772ec9bc997665b31)) +* Lock default context in contexts config ([#277](https://github.com/kurtosis-tech/kurtosis/issues/277)) ([8da3b94](https://github.com/kurtosis-tech/kurtosis/commit/8da3b94405e6d5e5f1fe659b137287e97ceb061d)) +* Update PR title workflow for merge queue ([#267](https://github.com/kurtosis-tech/kurtosis/issues/267)) ([00ccfec](https://github.com/kurtosis-tech/kurtosis/commit/00ccfecf5d26ee440010c4a6ffd32f7dd7b15d8b)) +* warn if engine version is greater than cli and error if cli > engine ([#243](https://github.com/kurtosis-tech/kurtosis/issues/243)) ([03352e1](https://github.com/kurtosis-tech/kurtosis/commit/03352e128c6521b32e48f4036cbfe4ba803fbf84)) + +## [0.68.13](https://github.com/kurtosis-tech/kurtosis/compare/0.68.12...0.68.13) (2023-03-16) + + +### Features + +* made the content-type field optional in PostHttpRequestRecipe ([#222](https://github.com/kurtosis-tech/kurtosis/issues/222)) ([d551398](https://github.com/kurtosis-tech/kurtosis/commit/d551398112aded68dd348c661fb14512080a9bdb)) + + +### Bug Fixes + +* add trailing commas to Starlark code ([#218](https://github.com/kurtosis-tech/kurtosis/issues/218)) ([1bd050c](https://github.com/kurtosis-tech/kurtosis/commit/1bd050c8de01fd24bae5ffaf786aa87b86bdf134)) +* collapse current behavior into background+motivation ([#216](https://github.com/kurtosis-tech/kurtosis/issues/216)) ([853aa5d](https://github.com/kurtosis-tech/kurtosis/commit/853aa5d9ee79b7f540897f2ca0ac80f5c31740ec)) +* print the upgrade CLI warning at most hourly ([#224](https://github.com/kurtosis-tech/kurtosis/issues/224)) ([f40ee90](https://github.com/kurtosis-tech/kurtosis/commit/f40ee90c4d1008a932daa902a264acf3e4b48510)) +* refer to the new repo name in remote subpackage tests ([#225](https://github.com/kurtosis-tech/kurtosis/issues/225)) ([cd81f2e](https://github.com/kurtosis-tech/kurtosis/commit/cd81f2ef8d721e94dd0b0c668d9ddaf64b03677d)) + +## [0.68.12](https://github.com/kurtosis-tech/kurtosis/compare/0.68.11...0.68.12) (2023-03-15) + + +### Bug Fixes + +* wait instruction hanging forever when `service_name` field is not passed ([#197](https://github.com/kurtosis-tech/kurtosis/issues/197)) ([826f072](https://github.com/kurtosis-tech/kurtosis/commit/826f0727a43ca1acc05aaded41eed307b04c7d96)) + +## [0.68.11](https://github.com/kurtosis-tech/kurtosis/compare/0.68.10...0.68.11) (2023-03-15) + + +### Features + +* colorize RUNNING|STOPPED statuses for Enclaves And Containers ([#178](https://github.com/kurtosis-tech/kurtosis/issues/178)) ([8254c7f](https://github.com/kurtosis-tech/kurtosis/commit/8254c7fbf35e38840c1ff5182017f19184eccae5)) + + +### Bug Fixes + +* remove api container stuff & colorize keys ([#195](https://github.com/kurtosis-tech/kurtosis/issues/195)) ([9ccb910](https://github.com/kurtosis-tech/kurtosis/commit/9ccb9102736eda2e8cb6645796cb9bfc73209ea1)) + +## [0.68.10](https://github.com/kurtosis-tech/kurtosis/compare/0.68.9...0.68.10) (2023-03-15) + + +### Bug Fixes + +* Tag docker images correctly after Kudet removal ([#206](https://github.com/kurtosis-tech/kurtosis/issues/206)) ([2e594a4](https://github.com/kurtosis-tech/kurtosis/commit/2e594a444a2eef5b058402edf675b7526a0ec675)) + +## [0.68.9](https://github.com/kurtosis-tech/kurtosis/compare/0.68.8...0.68.9) (2023-03-15) + + +### Features + +* Add a new pull request template ([#117](https://github.com/kurtosis-tech/kurtosis/issues/117)) ([45b2067](https://github.com/kurtosis-tech/kurtosis/commit/45b2067302f9fb38c2dda43dedbdbbcc7878fea6)) +* show enclave inspect immediately after run ([#170](https://github.com/kurtosis-tech/kurtosis/issues/170)) ([5790131](https://github.com/kurtosis-tech/kurtosis/commit/57901311eefdbe877e97deef4ee3e5ba1bd4c75a)) + + +### Bug Fixes + +* Add back fetch depth to change version GH action ([f5f32a2](https://github.com/kurtosis-tech/kurtosis/commit/f5f32a294fdf365cde2e998b03e37ab1a1b42d14)) +* Add back fetch depth to change version GH action ([#204](https://github.com/kurtosis-tech/kurtosis/issues/204)) ([f5f32a2](https://github.com/kurtosis-tech/kurtosis/commit/f5f32a294fdf365cde2e998b03e37ab1a1b42d14)) +* remove & service uuid from autocomplete ([#182](https://github.com/kurtosis-tech/kurtosis/issues/182)) ([3be2070](https://github.com/kurtosis-tech/kurtosis/commit/3be207091fcb99161a7e8b8712d885a3c1298954)) +* use with-subnetworks ([#163](https://github.com/kurtosis-tech/kurtosis/issues/163)) ([db6dd41](https://github.com/kurtosis-tech/kurtosis/commit/db6dd41e7415d30d0811516525395010bb02c6d5)) + +## [0.68.8](https://github.com/kurtosis-tech/kurtosis/compare/0.68.7...0.68.8) (2023-03-14) + + +### Bug Fixes + +* bump historical cli install down the sidebar ([cba11eb](https://github.com/kurtosis-tech/kurtosis/commit/cba11eb3fe5545166b4979aeb63e2c26dd3c375b)) +* bump historical cli install down the sidebar ([#152](https://github.com/kurtosis-tech/kurtosis/issues/152)) ([cba11eb](https://github.com/kurtosis-tech/kurtosis/commit/cba11eb3fe5545166b4979aeb63e2c26dd3c375b)) +* print enclave names even after restart during clean ([#156](https://github.com/kurtosis-tech/kurtosis/issues/156)) ([43ab71e](https://github.com/kurtosis-tech/kurtosis/commit/43ab71e3305f3c434f6d5718e4e2d2b664993ae2)) + +## [0.68.7](https://github.com/kurtosis-tech/kurtosis/compare/0.68.6...0.68.7) (2023-03-13) + + +### Bug Fixes + +* added instruction position while executing starlark package ([bc70e4e](https://github.com/kurtosis-tech/kurtosis/commit/bc70e4e1b5ad743edf9dcaa7b0feb0975e8f7eb0)) +* added instruction position while executing starlark package ([#143](https://github.com/kurtosis-tech/kurtosis/issues/143)) ([bc70e4e](https://github.com/kurtosis-tech/kurtosis/commit/bc70e4e1b5ad743edf9dcaa7b0feb0975e8f7eb0)) +* fix changelog for versioned docs going forward ([#142](https://github.com/kurtosis-tech/kurtosis/issues/142)) ([2fc3e72](https://github.com/kurtosis-tech/kurtosis/commit/2fc3e72248bbbbb1780ecf32db95a6c9fbe08972)) +* gramatical fix in analytics tracking logging ([#138](https://github.com/kurtosis-tech/kurtosis/issues/138)) ([23212a3](https://github.com/kurtosis-tech/kurtosis/commit/23212a3188445e3f358eef0e3ac388752eb9a0c7)) +* sort services by name ([#139](https://github.com/kurtosis-tech/kurtosis/issues/139)) ([d60ef67](https://github.com/kurtosis-tech/kurtosis/commit/d60ef67e0fa2e456d11b0a3925dd731a969928d6)) + +## [0.68.6](https://github.com/kurtosis-tech/kurtosis/compare/0.68.5...0.68.6) (2023-03-09) + + +### Features + +* Added `kurtosis feedback` CLI command ([#28](https://github.com/kurtosis-tech/kurtosis/issues/28)) ([55210ec](https://github.com/kurtosis-tech/kurtosis/commit/55210ec5660f6c642eda4baa422cf766fc584be5)) +* publish versioned brew formula ([#130](https://github.com/kurtosis-tech/kurtosis/issues/130)) ([a7d695d](https://github.com/kurtosis-tech/kurtosis/commit/a7d695d3fc58d7c4c3c3fd218bf9af98a3bc0086)) + +## [0.68.5](https://github.com/kurtosis-tech/kurtosis/compare/0.68.4...0.68.5) (2023-03-09) + + +### Bug Fixes + +* Use version.txt for kurtosis_version instead of Git tags ([#126](https://github.com/kurtosis-tech/kurtosis/issues/126)) ([f5bfe9e](https://github.com/kurtosis-tech/kurtosis/commit/f5bfe9e5795305c172a6fd02115825b2ea0b638a)) + +## [0.68.4](https://github.com/kurtosis-tech/kurtosis/compare/0.68.3...0.68.4) (2023-03-09) + + +### Bug Fixes + +* Pass correct latest tag to GoReleaser CLI build ([#122](https://github.com/kurtosis-tech/kurtosis/issues/122)) ([ec10c54](https://github.com/kurtosis-tech/kurtosis/commit/ec10c542d2ef97dd4c3ca0d542fa5af23fc44ca2)) + +## [0.68.3](https://github.com/kurtosis-tech/kurtosis/compare/0.68.2...0.68.3) (2023-03-08) + + +### Features + +* Use semver versioning for Golang API package ([#119](https://github.com/kurtosis-tech/kurtosis/issues/119)) ([1d4ff7f](https://github.com/kurtosis-tech/kurtosis/commit/1d4ff7fea55bcf25538b955275d776ff0b2f3678)) + + +### Bug Fixes + +* remove mentions about github discussions ([#95](https://github.com/kurtosis-tech/kurtosis/issues/95)) ([2387fa2](https://github.com/kurtosis-tech/kurtosis/commit/2387fa230bc5a6d240755acbbb9b5cbcc5489ea0)) + +## [0.68.2](https://github.com/kurtosis-tech/kurtosis/compare/0.68.1...0.68.2) (2023-03-08) + + +### Bug Fixes + +* fix push_cli_artifacts ci job ([#118](https://github.com/kurtosis-tech/kurtosis/issues/118)) ([b905870](https://github.com/kurtosis-tech/kurtosis/commit/b90587057b200e7f54d1ef5a7e815a1d94a7cf4c)) + +## [0.68.1](https://github.com/kurtosis-tech/kurtosis/compare/0.68.0...0.68.1) (2023-03-08) + + +### Features + +* docs are versioned ([#106](https://github.com/kurtosis-tech/kurtosis/issues/106)) ([7cd6a4e](https://github.com/kurtosis-tech/kurtosis/commit/7cd6a4e391d7b261cdb2d94d3d9dac2be7f3490b)) + +## [0.68.0](https://github.com/kurtosis-tech/kurtosis/compare/0.67.4...0.68.0) (2023-03-07) + + +### ⚠ BREAKING CHANGES + +* Migrate Kurtosis Print instruction to Starlark framework. This restrict the use of `print` to a single argument only. ([#80](https://github.com/kurtosis-tech/kurtosis/issues/80)) (#87) + +### Features + +* enclave clean has both name and uuid ([#101](https://github.com/kurtosis-tech/kurtosis/issues/101)) ([69114ab](https://github.com/kurtosis-tech/kurtosis/commit/69114ab455715092060d51d854f18241f0fb4060)) +* persist partition connection overrides to disk ([#98](https://github.com/kurtosis-tech/kurtosis/issues/98)) ([4af3b9f](https://github.com/kurtosis-tech/kurtosis/commit/4af3b9f31daf4962a1e4242a001d2d4bcc84f8d0)) + + +### Code Refactoring + +* Migrate Kurtosis Print instruction to Starlark framework. This restrict the use of `print` to a single argument only. ([#80](https://github.com/kurtosis-tech/kurtosis/issues/80)) ([#87](https://github.com/kurtosis-tech/kurtosis/issues/87)) ([868da1b](https://github.com/kurtosis-tech/kurtosis/commit/868da1b871f5b2610dfcc97618c13861a180cc80)) + +## [0.67.4](https://github.com/kurtosis-tech/kurtosis/compare/0.67.3...0.67.4) (2023-03-04) + + +### Features + +* added new `service_name` parameter for the `exec`, `request` and `wait` instructions. NOTE: the previous methods' signature will be maintained during a deprecation period, we suggest users update the methods' calls to this new signature. ([#66](https://github.com/kurtosis-tech/kurtosis/issues/66)) ([1b47ee3](https://github.com/kurtosis-tech/kurtosis/commit/1b47ee3bb3fd56711995596fb9f68c5a195291fb)) +* added the `id` flag in the `analytics` CLI command which allow users to get the `analytics ID` in an easy way ([#81](https://github.com/kurtosis-tech/kurtosis/issues/81)) ([766c094](https://github.com/kurtosis-tech/kurtosis/commit/766c0944a983a0f26e2f7bb3f24ce20f3db28d4b)) +* integrate nature theme based name to cli (render template and store service) for file artifacts ([#82](https://github.com/kurtosis-tech/kurtosis/issues/82)) ([aea5bef](https://github.com/kurtosis-tech/kurtosis/commit/aea5bef1fdbd16f88bc4021e243d60f24491b616)) +* integrate nature theme named to render_template and store_service ([aea5bef](https://github.com/kurtosis-tech/kurtosis/commit/aea5bef1fdbd16f88bc4021e243d60f24491b616)) +* introduce nature themed name for enclaves ([#59](https://github.com/kurtosis-tech/kurtosis/issues/59)) ([78e363f](https://github.com/kurtosis-tech/kurtosis/commit/78e363f554494891b28b4e277e3b04473a66af7b)) +* persist service partitions ([#84](https://github.com/kurtosis-tech/kurtosis/issues/84)) ([d46d92a](https://github.com/kurtosis-tech/kurtosis/commit/d46d92a1f0a1db3ba2099e31570983faa0d93874)) + + +### Bug Fixes + +* handle multiline errors that might happen with kurtosis clean ([#69](https://github.com/kurtosis-tech/kurtosis/issues/69)) ([f7400be](https://github.com/kurtosis-tech/kurtosis/commit/f7400beac0c7a7f2ec04486064d7bf0c63758cf5)) + +## [0.67.3](https://github.com/kurtosis-tech/kurtosis/compare/0.67.2...0.67.3) (2023-02-28) + + +### Features + +* Add new FR, docs, and Bug Report issues templates ([#52](https://github.com/kurtosis-tech/kurtosis/issues/52)) ([8854585](https://github.com/kurtosis-tech/kurtosis/commit/88545857213f25716abf4030f03cdd71db531c83)) +* made the name field optional for file artifacts in starlark ([#51](https://github.com/kurtosis-tech/kurtosis/issues/51)) ([1ded385](https://github.com/kurtosis-tech/kurtosis/commit/1ded385720423f58a168b44afb94279d1d2c3951)) + + +### Bug Fixes + +* Correct minor error in "locators" reference docs ([#71](https://github.com/kurtosis-tech/kurtosis/issues/71)) ([3d68919](https://github.com/kurtosis-tech/kurtosis/commit/3d68919aafbc16e8211cd7692d1820bbe7301070)) +* stamp enclave uuid at the end of enclave objects ([#74](https://github.com/kurtosis-tech/kurtosis/issues/74)) ([4f44d03](https://github.com/kurtosis-tech/kurtosis/commit/4f44d03769c877fc36349a79a47b347d2444cf75)) + +## [0.67.2](https://github.com/kurtosis-tech/kurtosis/compare/0.67.1...0.67.2) (2023-02-27) + + +### Features + +* added boilerplate method to generate unique file artifact name ([#40](https://github.com/kurtosis-tech/kurtosis/issues/40)) ([50cd25c](https://github.com/kurtosis-tech/kurtosis/commit/50cd25cddeccbadf450e7888155b3b39f58acd4b)) +* fix the output of kurtosis enclave dump ([#62](https://github.com/kurtosis-tech/kurtosis/issues/62)) ([7ae12cf](https://github.com/kurtosis-tech/kurtosis/commit/7ae12cf51f966a64b3684f3ad439befb8bf2d7c1)) + + +### Bug Fixes + +* enforced kurtosis locator validations when running remote kurtosis package ([#41](https://github.com/kurtosis-tech/kurtosis/issues/41)) ([e9af4d9](https://github.com/kurtosis-tech/kurtosis/commit/e9af4d9701e5ecc5b53811d839563140cdc5de22)) +* preserve cli provided ordering of completions throughout shells ([#61](https://github.com/kurtosis-tech/kurtosis/issues/61)) ([f312f2c](https://github.com/kurtosis-tech/kurtosis/commit/f312f2c276b335f64c87fd8e34a7fdca5814a75c)) + +## [0.67.1](https://github.com/kurtosis-tech/kurtosis/compare/0.67.0...0.67.1) (2023-02-23) + + +### Features + +* added Kurtosis Docs command ([#34](https://github.com/kurtosis-tech/kurtosis/issues/34)) ([2502bae](https://github.com/kurtosis-tech/kurtosis/commit/2502baecdfa57dabd8e3bb0d69569c38e6f27645)) + + +### Bug Fixes + +* better errors when enclave cleaning fails ([#47](https://github.com/kurtosis-tech/kurtosis/issues/47)) ([a15fe52](https://github.com/kurtosis-tech/kurtosis/commit/a15fe5282652e406e779dfad37fa9ee8cf8ed771)) +* enforce kurtosis.yml validations in import_module and read_file; package name inside kurtosis.yml must be valid and is same as the path where kurtosis.yml exists ([#24](https://github.com/kurtosis-tech/kurtosis/issues/24)) ([95d5548](https://github.com/kurtosis-tech/kurtosis/commit/95d554808eaf07928058285016bf6f3a5aff9359)) +* fix error message on importing/reading a package instead of a module ([#33](https://github.com/kurtosis-tech/kurtosis/issues/33)) ([1f906ae](https://github.com/kurtosis-tech/kurtosis/commit/1f906ae5dc70a48b670ddda8065e12b81a9bb55c)) +* fixed link to report docs issues ([#36](https://github.com/kurtosis-tech/kurtosis/issues/36)) ([dfccf10](https://github.com/kurtosis-tech/kurtosis/commit/dfccf10c01aa5c981fb60fce97725a427fc4d1be)) + +## [0.67.0](https://github.com/kurtosis-tech/kurtosis/compare/0.66.11...0.67.0) (2023-02-21) + + +### ⚠ BREAKING CHANGES + +* This is a breaking change where we are deprecating PacketDelay to introduce latency in favour of PacketDelayDistribution. Instead of using packet delay, use UniformPacketDelayDistribution for constant delays or NormalPacketDelayDistribution for normally distributed latencies + +## [0.66.11](https://github.com/kurtosis-tech/kurtosis/compare/0.66.10...0.66.11) (2023-02-21) + + +### Features + +* track enclave size after run has finished ([#15](https://github.com/kurtosis-tech/kurtosis/issues/15)) ([80f35c8](https://github.com/kurtosis-tech/kurtosis/commit/80f35c80797b00fd66b4d216b9807b63cf2739b7)) + + +### Bug Fixes + +* import_module and read_file should load files from kurtosis packages (kurtosis.yml must be present in the path). enforce that only kurtosis packages (directories containing kurtosis.yml) can be run. ([#16](https://github.com/kurtosis-tech/kurtosis/issues/16)) ([84f1042](https://github.com/kurtosis-tech/kurtosis/commit/84f1042aef2d79b388bb5eaf808df520a3e76462)) + +## [0.66.10](https://github.com/kurtosis-tech/kurtosis/compare/0.66.9...0.66.10) (2023-02-16) + + +### Features + +* made metrics opt in by default ([#5](https://github.com/kurtosis-tech/kurtosis/issues/5)) ([cd076fd](https://github.com/kurtosis-tech/kurtosis/commit/cd076fd515a05e594f338e693405d614718e59f4)) +* update metrics lib to track os, arch & backend type ([#11](https://github.com/kurtosis-tech/kurtosis/issues/11)) ([15cf9bb](https://github.com/kurtosis-tech/kurtosis/commit/15cf9bbec3b37a6235901d01e207be36366e8614)) + +## [0.66.9](https://github.com/kurtosis-tech/kurtosis/compare/0.66.8...0.66.9) (2023-02-15) + + +### Bug Fixes + +* Fix release process ([#3](https://github.com/kurtosis-tech/kurtosis/issues/3)) ([8a618d9](https://github.com/kurtosis-tech/kurtosis/commit/8a618d94bebe0553f744ab90b6e4c8fe2f8f7fdb)) + +## 0.66.8 (2023-02-15) + + +### Features + +* Initial implementation ([#1](https://github.com/kurtosis-tech/kurtosis/issues/1)) ([8a3fd81](https://github.com/kurtosis-tech/kurtosis/commit/8a3fd8123388de117f4a8c84622024923d410fc3)) diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/analytics-disable.md b/docs/versioned_docs/version-0.78.3/cli-reference/analytics-disable.md new file mode 100644 index 0000000000..bdd752902d --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/analytics-disable.md @@ -0,0 +1,13 @@ +--- +title: analytics disable +sidebar_label: analytics disable +slug: /analytics-disable +--- + +Kurtosis has functionality to collect product analytics metrics so we can make data-driven product decisions. These metrics are [anonymized, obfuscated, and never given to third parties](../explanations/metrics-philosophy.md)). + +Anonymous metrics collection is enabled by default, but you can turn it off by running: + +```bash +kurtosis analytics disable +``` diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/analytics-enable.md b/docs/versioned_docs/version-0.78.3/cli-reference/analytics-enable.md new file mode 100644 index 0000000000..318590a710 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/analytics-enable.md @@ -0,0 +1,13 @@ +--- +title: analytics enable +sidebar_label: analytics enable +slug: /analytics-enable +--- + +Kurtosis has functionality to collect product analytics metrics so we can make data-driven product decisions. These metrics are [anonymized, obfuscated, and never given to third parties](../explanations/metrics-philosophy.md)). + +If you previously disabled metrics collection, you can re-enable it via: + +```bash +kurtosis analytics enable +``` diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/analytics-id.md b/docs/versioned_docs/version-0.78.3/cli-reference/analytics-id.md new file mode 100644 index 0000000000..6b2a60a0a3 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/analytics-id.md @@ -0,0 +1,15 @@ +--- +title: analytics id +sidebar_label: analytics id +slug: /analytics-id +--- + +In addition to log outputs and screenshots, [product analytics metrics](../explanations/metrics-philosophy.md) may be useful for our team when debugging issues and shipping fixes for bugs. + +If you so choose, you may share with us your metrics user ID when letting us know about issues or bugs (in our [Github](https://github.com/kurtosis-tech/kurtosis/issues/new/choose) or on [Discord](https://discord.gg/rjkj8m5C)). Doing helps us debug issues, ship fixes quicker, and ultimately improve Kurtosis over time. + +To print your metrics user ID, simply run: + +```bash +kurtosis analytics id +``` diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/clean.md b/docs/versioned_docs/version-0.78.3/cli-reference/clean.md new file mode 100644 index 0000000000..8bcbe8f54d --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/clean.md @@ -0,0 +1,18 @@ +--- +title: clean +sidebar_label: clean +slug: /clean +--- + +```console +Removes stopped enclaves (and live ones if the 'all' flag is set), as well as stopped engine containers + +Usage: + kurtosis clean [flags] + +Flags: + -a, --all If set, removes running enclaves as well + -h, --help help for clean +``` + +NOTE: This will not stop the Kurtosis engine itself! To do so, use the [engine stop](./engine-stop.md) command. diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/completion.md b/docs/versioned_docs/version-0.78.3/cli-reference/completion.md new file mode 100644 index 0000000000..2891eaa291 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/completion.md @@ -0,0 +1,20 @@ +--- +title: completion +sidebar_label: completion +slug: /completion +--- + +Scripts used to create command-line completion for `bash`, `fish`, `powershell`, and `zsh` can be printed using: + +```bash +kurtosis completion [command] +``` + +The available commands are as follows: + +* `bash`: Generates the autocompletion script for bash +* `fish`: Generates the autocompletion script for fish +* `powershell`: Generates the autocompletion script for powershell +* `zsh`: Generates the autocompletion script for zsh + +Instructions for how to install command-line completion on your shell can be found [here](../guides/adding-command-line-completion.md) in our Guides section. diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/config-path.md b/docs/versioned_docs/version-0.78.3/cli-reference/config-path.md new file mode 100644 index 0000000000..21af20ad97 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/config-path.md @@ -0,0 +1,7 @@ +--- +title: config path +sidebar_label: config path +slug: /config-path +--- + +The `kurtosis config path` command displays the path to the Kurtosis CLI config YAML file. This file is used to configure Kurtosis CLI behaviour. diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/discord.md b/docs/versioned_docs/version-0.78.3/cli-reference/discord.md new file mode 100644 index 0000000000..291f08cb4b --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/discord.md @@ -0,0 +1,11 @@ +--- +title: discord +sidebar_label: discord +slug: /discord +--- + +The following command can be used to open our Discord server from the CLI where you can join our Discord to ask questions, chat with our team, and meet the community: + +```bash +kurtosis discord +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/docs.md b/docs/versioned_docs/version-0.78.3/cli-reference/docs.md new file mode 100644 index 0000000000..a41e0ee2af --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/docs.md @@ -0,0 +1,13 @@ +--- +title: docs +sidebar_label: docs +slug: /docs +--- + +To open our documentation in the browser from the CLI, run: + +```bash +kurtosis docs +``` + +where you can learn more about Kurtosis' architecture, APIs, Starlark, and much more. diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/dump.md b/docs/versioned_docs/version-0.78.3/cli-reference/dump.md new file mode 100644 index 0000000000..0cb0d36628 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/dump.md @@ -0,0 +1,17 @@ +--- +title: dump +sidebar_label: dump +slug: /dump +--- + +You might need to store the entire state of Kurtosis to disk at some point. You may want to have a log package if your CI fails, or you want to send debugging information to [the author of a Kurtosis package][packages-reference]. Whatever the case may be, you can run: + +```bash +kurtosis dump $OUTPUT_DIRECTORY +``` +You will get the container logs & configuration in the output directory for further analysis & sharing. This would contain all engines & enclaves. + +If you don't specify the `$OUTPUT_DIRECTORY` Kurtosis will dump it to a directory with a name following the schema `kurtosis-dump--TIMESTAMP`. + + +[packages-reference]: ../concepts-reference/packages.md diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/enclave-add.md b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-add.md new file mode 100644 index 0000000000..f307e77011 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-add.md @@ -0,0 +1,17 @@ +--- +title: enclave add +sidebar_label: enclave add +slug: /enclave-add +--- + +Your distributed applications run in [enclaves][enclaves-reference]. They are isolated from each other, to ensure they don't interfere with each other. To create a new, empty enclave, simply run: + +```bash +kurtosis enclave add +``` + +To create enclaves that support [subnetworks][subnetworks] use the `--with-subnetworks` flag. + + +[enclaves-reference]: ../concepts-reference/enclaves.md +[subnetworks]: ../concepts-reference/subnetworks.md diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/enclave-dump.md b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-dump.md new file mode 100644 index 0000000000..fa6a0e5168 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-dump.md @@ -0,0 +1,20 @@ +--- +title: enclave dump +sidebar_label: enclave dump +slug: /enclave-dump +--- + +You will likely need to store enclave logs to disk at some point. You may want to have a log package if your CI fails, or you want to send debugging information to [the author of a Kurtosis package][packages-reference]. Whatever the case may be, you can run: + +```bash +kurtosis enclave dump $THE_ENCLAVE_IDENTIFIER $OUTPUT_DIRECTORY +``` +where the `$THE_ENCLAVE_IDENTIFIER` is the [resource identifier](../concepts-reference/resource-identifier.md) for an enclave. + +You will get the container logs & configuration in the output directory for further analysis & sharing. + +If you don't specify the `$OUTPUT_DIRECTORY` Kurtosis will dump it to a directory with a name following the `ENCLAVE_NAME--ENCLAVE_UUID` scheme in the +current working directory. + + +[packages-reference]: ../concepts-reference/packages.md diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/enclave-inspect.md b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-inspect.md new file mode 100644 index 0000000000..6eefaec664 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-inspect.md @@ -0,0 +1,23 @@ +--- +title: enclave inspect +sidebar_label: enclave inspect +slug: /enclave-inspect +--- + +To view detailed information about a given enclave, including its status and contents, run: + +```bash +kurtosis enclave inspect $THE_ENCLAVE_IDENTIFIER +``` + +where `$THE_ENCLAVE_IDENTIFIER` is the [resource identifier](../concepts-reference/resource-identifier.md) for the enclave. + +Running the above command will print detailed information about: + +- The enclave's status (running or stopped) +- The services inside the enclave (if any), their status, and the information for accessing those services' ports from your local machine +- Any files artifacts registered within the specified enclave + +By default, UUIDs are shortened. To view the full UUIDs of your resources, add the following flag: +* `--full-uuids` + diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/enclave-ls.md b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-ls.md new file mode 100644 index 0000000000..efc139ee95 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-ls.md @@ -0,0 +1,13 @@ +--- +title: enclave ls +sidebar_label: enclave ls +slug: /enclave-ls +--- + +To print all enclaves (both stopped and running) inside of your Kurtosis engine, use: + +```bash +kurtosis enclave ls +``` + +The enclave UUIDs and names that are printed will be used in enclave manipulation commands and are refered to as [resource identifiers](../concepts-reference/resource-identifier.md). \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/enclave-rm.md b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-rm.md new file mode 100644 index 0000000000..7b9361433d --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-rm.md @@ -0,0 +1,14 @@ +--- +title: enclave rm +sidebar_label: enclave rm +slug: /enclave-rm +--- + +To remove an enclave and all resources associated with that particular enclave, use: + +```bash +kurtosis enclave rm $THE_ENCLAVE_IDENTIFIER +``` +where `$THE_ENCLAVE_IDENTIFIER` is the enclave [identifier](../concepts-reference/resource-identifier.md). + +Note that this command will only remove stopped enclaves. To destroy a running enclave, pass the `-f`/`--force` flag. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/enclave-stop.md b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-stop.md new file mode 100644 index 0000000000..0fff1dea13 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/enclave-stop.md @@ -0,0 +1,16 @@ +--- +title: enclave stop +sidebar_label: enclave stop +slug: /enclave-stop +--- + +To stop a particular enclave, use: + +```bash +kurtosis enclave stop $THE_ENCLAVE_IDENTIFIER +``` +where `$THE_ENCLAVE_IDENTIFIER` is the enclave [identifier](../concepts-reference/resource-identifier.md). + +:::caution +Enclaves that have been stopped cannot currently be restarted. The Kurtosis team is actively working on enabling this functionality. +::: diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/engine-logs.md b/docs/versioned_docs/version-0.78.3/cli-reference/engine-logs.md new file mode 100644 index 0000000000..96439f3242 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/engine-logs.md @@ -0,0 +1,13 @@ +--- +title: engine logs +sidebar_label: engine logs +slug: /engine-logs +--- + +To get logs for all existing (stopped or running) engines, use: + +```bash +kurtosis engine logs $OUTPUT_DIRECTORY +``` + +which will dump all the logs of the engine container to the directory specified by `$OUTPUT_DIRECTORY`. If a `$OUTPUT_DIRECTORY` is not specified, Kurtosis will default to writing the logs in a folder name following the schema `kurtosis-engine-logs--TIMESTAMP` in the working directory. diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/engine-restart.md b/docs/versioned_docs/version-0.78.3/cli-reference/engine-restart.md new file mode 100644 index 0000000000..5d2c0e6879 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/engine-restart.md @@ -0,0 +1,11 @@ +--- +title: engine restart +sidebar_label: engine restart +slug: /engine-restart +--- + +The CLI interacts with the Kurtosis engine, which is a very lightweight container. The CLI will start the engine container automatically for you and you should never need to start it manually, but you might need to restart the engine after a CLI upgrade. To do so, run: + +```bash +kurtosis engine restart +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/engine-start.md b/docs/versioned_docs/version-0.78.3/cli-reference/engine-start.md new file mode 100644 index 0000000000..6d4c4d1eb0 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/engine-start.md @@ -0,0 +1,16 @@ +--- +title: engine start +sidebar_label: engine start +slug: /engine-start +--- + +The Kurtosis engine starts automatically when you run any command that interacts with the engine, such as [`kurtosis enclave add`](./enclave-add.md), but there may be times where the engine has been stopped and you may need to start it again (e.g. starting the engine on a specific version). To do so, run: + +```bash +kurtosis engine start +``` +This command will do nothing if the Kurtosis engine is already running. + +You may optionally pass in the following flags with this command: +* `--log-level`: The level that the started engine should log at. Options include: `panic`, `fatal`, `error`, `warning`, `info`, `debug`, or `trace`. The engine logs at the `info` level by default. +* `--version`: The version (Docker tag) of the Kurtosis engine that should be started. If not set, the engine will start up with the default version. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/engine-status.md b/docs/versioned_docs/version-0.78.3/cli-reference/engine-status.md new file mode 100644 index 0000000000..537660351a --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/engine-status.md @@ -0,0 +1,11 @@ +--- +title: engine status +sidebar_label: engine status +slug: /engine-status +--- + +The engine's version and status can be printed with: + +```bash +kurtosis engine status +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/engine-stop.md b/docs/versioned_docs/version-0.78.3/cli-reference/engine-stop.md new file mode 100644 index 0000000000..80a222e0c7 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/engine-stop.md @@ -0,0 +1,13 @@ +--- +title: engine stop +sidebar_label: engine stop +slug: /engine-stop +--- + +To stop the engine, run: + +```bash +kurtosis engine stop +``` + +Note that this will do nothing if there is no engine running. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/feedback.md b/docs/versioned_docs/version-0.78.3/cli-reference/feedback.md new file mode 100644 index 0000000000..a8acd6661d --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/feedback.md @@ -0,0 +1,33 @@ +--- +title: feedback +sidebar_label: feedback +slug: /feedback +--- + +To quickly get in touch with us, simply run: +```bash +kurtosis feedback +``` +which will open the [Kurtosis GitHub create new issue page](https://github.com/kurtosis-tech/kurtosis/issues/new/choose), where you can file a bug report, submit a feature request, or let us know about any docs issues you may have come across. A link to our [Discord server](https://discord.gg/yUGgeE8s) will be made available there too. + +### Using `kurtosis feedback` + +The `kurtosis feedback` command can accept both an argument and various flags. To send our team feedback over GitHub straight from the CLI, simply pass in your feedback as an argument to the command like so: +```bash +kurtosis feedback [flags] "$YOUR_FEEDBACK" +``` +where `YOUR_FEEDBACK` is the feedback you would like to send to us. + +Running just `kurtosis feedback "my feedback"` (with no flags) will open the new issue creation page on [our GitHub](https://github.com/kurtosis-tech/kurtosis/issues/new/choose) where you can can select the issue type and have the description field pre-filled with `my feedback`. + +Below are a collection of valid flags you may use: +- The `--email` flag opens a draft email to our team, via your default mail client, that has the body of the email pre-filled with whatever you entered in the `"$YOUR_FEEDBACK"` arg. This is the default behavior when no flag is set. +- The `--calendly` flag can be used to open our [Calendly link](https://calendly.com/d/zgt-f2c-66p/kurtosis-onboarding) to schedule time with our team to help you get started, address feedback, and answer any questions you may have. +Additionally, the flags below can be used alone (will set the feedback type for GitHub which is the default feedback destination) and with the `--email` flag to specify the *type* of feedback you wish to provide: +- The `--bug` flag can be used when you wish to submit a bug report to us. When this `--bug` flag is set without any destination flag, the CLI will take you directly to the [bug report issue creation page](https://github.com/kurtosis-tech/kurtosis/issues/new?assignees=&labels=bug&template=bug-report.yml) in our GitHub. When this `--bug` flag is set alongside the `--email` flag, the CLI will open an email draft with the subject pre-filled with: `[BUG]`, which will help our team triage and prioritize your report. +- The `--feature` flag can be used when you wish to submit a feature request to us. When this `--feature` flag without any destination flag, the CLI will take you directly to the [feature request issue creation page](https://github.com/kurtosis-tech/kurtosis/issues/new?assignees=&labels=feature+request&template=feature-request.yml) in our GitHub. When this `--feature` flag is set alongside the `--email` flag, the CLI will open an email draft with the subject pre-filled with: `[FEATURE_REQUEST]`, which will help our team triage and prioritize your request. +- The `--docs` flag can be used when you wish to flag an issue with our documentation. When this `--docs` flag without any destination flag, the CLI will take you directly to the [docs issue creation page](https://github.com/kurtosis-tech/kurtosis/issues/new?assignees=leeederek&labels=docs&template=docs-issue.yml) in our GitHub. When this `--docs` flag is set alongside the `--email` flag, the CLI will open an email draft with the subject pre-filled with: `[DOCS]`, which will help our team triage and prioritize the issue. + +:::tip +To join our Discord community, use the [`kurtosis discord`](./discord.md) CLI command. +::: diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/files-download.md b/docs/versioned_docs/version-0.78.3/cli-reference/files-download.md new file mode 100644 index 0000000000..fa40f69cc8 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/files-download.md @@ -0,0 +1,16 @@ +--- +title: files download +sidebar_label: files download +slug: /files-download +--- + +To download a [files artifact](../concepts-reference/files-artifacts.md) using a resource identifier (e.g. name, UUID, shortened UUID) from an enclave to the host machine, use: + +```bash +kurtosis files download $THE_ENCLAVE_IDENTIFIER $THE_ARTIFACT_IDENTIFIER $FILE_DESTINATION_PATH +``` +where `$THE_ENCLAVE_IDENTIFIER` and the `$THE_ARTIFACT_IDENTIFIER` are [resource identifiers](../concepts-reference/resource-identifier.md) for the enclave and file artifact, respectively. + +:::tip +The file downloaded will be extracted by default. If you would prefer the file not to be extracted upon download, pass in the `--no-extract` flag. +::: \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/files-rendertemplate.md b/docs/versioned_docs/version-0.78.3/cli-reference/files-rendertemplate.md new file mode 100644 index 0000000000..42a19f02ef --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/files-rendertemplate.md @@ -0,0 +1,14 @@ +--- +title: files rendertemplate +sidebar_label: files rendertemplate +slug: /files-rendertemplate +--- +To render a [Golang template](https://pkg.go.dev/text/template) for customizing the output of a service within an enclave, use the following command: + +```bash +kurtosis files rendertemplate $THE_ENCLAVE_IDENTIFIER $TEMPLATE_FILEPATH $DATA_JSON_FILEPATH $DESTINATION_RELATIVE_FILEPATH +``` + +where `$THE_ENCLAVE_IDENTIFIER` is the [resource identifier](../concepts-reference/resource-identifier.md) for the enclave. + +The name of the rendered [files artifact](../concepts-reference/files-artifacts.md) is auto-generated by default. Pass in the `--name` flag to assign a string to the produced artifact. diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/files-storeservice.md b/docs/versioned_docs/version-0.78.3/cli-reference/files-storeservice.md new file mode 100644 index 0000000000..1564154d78 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/files-storeservice.md @@ -0,0 +1,13 @@ +--- +title: files storeservice +sidebar_label: files storeservice +slug: /files-storeservice +--- + +To instruct Kurtosis to copy a file or folder from a given absolute filepath in a given service and store it in the enclave for later use (e.g. with [`service add`](./service-add.md)), use: + +```bash +kurtosis files storeservice $THE_ENCLAVE_IDENTIFIER $THE_SERVICE_IDENTIFIER $ABSOLUTE_SOURCE_FILEPATH +``` + +where `$THE_ENCLAVE_IDENTIFIER` and the `$THE_SERVICE_IDENTIFIER` are [resource identifiers](../concepts-reference/resource-identifier.md) for the enclave and service, respectively. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/files-storeweb.md b/docs/versioned_docs/version-0.78.3/cli-reference/files-storeweb.md new file mode 100644 index 0000000000..3e676e515d --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/files-storeweb.md @@ -0,0 +1,13 @@ +--- +title: files storeweb +sidebar_label: files storeweb +slug: /files-storeweb +--- + +To download an archive file from the given URL and store it in the enclave for later use (e.g. with [`service add`](./service-add.md)), use: + +```bash +kurtosis files storeweb $THE_ENCLAVE_IDENTIFIER $URL +``` + +where `$THE_ENCLAVE_IDENTIFIER` is the [resource identifier](../concepts-reference/resource-identifier.md) for the enclave. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/files-upload.md b/docs/versioned_docs/version-0.78.3/cli-reference/files-upload.md new file mode 100644 index 0000000000..4875cd6694 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/files-upload.md @@ -0,0 +1,17 @@ +--- +title: files upload +sidebar_label: files upload +slug: /files-upload +--- + +Files can be stored as a [files artifact][files-artifacts] inside an enclave by uploading them: + +```bash +kurtosis files upload $THE_ENCLAVE_IDENTIFIER $PATH_TO_FILES +``` + +where `$THE_ENCLAVE_IDENTIFIER` is the [resource identifier][resource-identifier] for the enclave. + + +[files-artifacts]: ../concepts-reference/files-artifacts.md +[resource-identifier]: ../concepts-reference/resource-identifier.md diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/index.md b/docs/versioned_docs/version-0.78.3/cli-reference/index.md new file mode 100644 index 0000000000..fcaae662cf --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/index.md @@ -0,0 +1,136 @@ +--- +id: index +title: CLI Introduction +sidebar_label: Introduction +slug: /cli +sidebar_position: 1 +--- + +The Kurtosis CLI is a Go CLI wrapped around the Kurtosis Go [SDK][sdk-reference]. This section will go through the most common Kurtosis CLI commands and some useful tips on getting started. If you have not already done so, the CLI can be installed by following the instructions [here][installing-the-cli]. + + +:::tip +Kurtosis supports command-line completion; we recommend [installing it][adding-command-line-completion] for the best experience. +::: + +### Configuration file path +To locate where the Kurtosis configuration file is on your machine, simply use: + +```bash +kurtosis config path +``` +to print out the file path of the `kurtosis-config.yml` file. + +### Get the CLI version +The version of the CLI and the currently-running engine can be printed with the following: + +``` +kurtosis version +``` + +### Global Flags +The Kurtosis CLI supports two global flags - `help` and `cli-log-level`. These flags can be used with any Kurtosis CLI command. + +#### -h or --help +This flag prints the help text for all commands and subcommands. You can use this at any time to see information on the command you're trying to run. For example: +``` +kurtosis service -h +``` +
+ Example Output of the above command + +```bash +Manage services + +Usage: + kurtosis service [command] + +Available Commands: + add Adds a service to an enclave + logs Get service logs + rm Removes a service from an enclave + shell Gets a shell on a service + +Flags: + -h, --help help for service + +Global Flags: + --cli-log-level string Sets the level that the CLI will log at (panic|fatal|error|warning|info|debug|trace) (default "info") + +Use "kurtosis service [command] --help" for more information about a command. +``` +
+ + +#### cli-log-level +This flag sets the level of details that the Kurtosis CLI will print logs with - by default it only logs `info` level logs to the CLI. The following other log levels are supported by Kurtosis - +`panic|fatal|error|warning|info|debug|trace`. For example, logs with error level can be printed using the command below:- + +``` +kurtosis run --cli-level-log debug github.com/package-author/package-repo +``` + +
+ Example Output of the above command + +```bash +DEBU[2023-04-03T12:54:00-04:00] Instantiating a context aware backend with no remote backend config ends up returninga regular local Docker backend. +INFO[2023-04-03T12:54:00-04:00] No Kurtosis engine was found; attempting to start one... +DEBU[2023-04-03T12:54:00-04:00] Metrics user id filepath: '' +INFO[2023-04-03T12:54:00-04:00] Pulling image 'kurtosistech/engine:0.73.0'... +DEBU[2023-04-03T12:54:00-04:00] Binds: [/var/run/docker.sock:/var/run/docker.sock] +DEBU[2023-04-03T12:54:00-04:00] Created container with ID 'b9c8f6509ebe7831a96a926e0514f049884b30a8ff4359cd06d9592464d7f017' from image 'kurtosistech/engine:0.73.0' +DEBU[2023-04-03T12:54:01-04:00] Netstat availability-waiting command '[ -n "$(netstat -anp tcp | grep LISTEN | grep 9710)" ]' returned without a Docker error, but exited with non-0 exit code '1' and logs: +INFO[2023-04-03T12:54:02-04:00] Successfully started Kurtosis engine +DEBU[2023-04-03T12:54:02-04:00] Kurtosis Portal daemon is currently not reachable. If Kurtosis is being used ona local-only context, this is fine as Portal is not required for local-only contexts. +INFO[2023-04-03T12:54:02-04:00] Creating a new enclave for Starlark to run inside... +INFO[2023-04-03T12:54:04-04:00] Enclave 'murky-volcano' created successfully +INFO[2023-04-03T12:54:04-04:00] Executing Starlark package at '' as the passed argument '' looks like a directory +INFO[2023-04-03T12:54:04-04:00] Compressing package '' at '' for upload +INFO[2023-04-03T12:54:04-04:00] Uploading and executing package '' + +> print msg={"key": "value"} +{"key": "value"} + +Starlark code successfully run. No output was returned. +DEBU[2023-04-03T12:54:04-04:00] Successfully reached the end of the response stream. Closing. +DEBU[2023-04-03T12:54:04-04:00] Current context is local, not mapping enclave service ports +INFO[2023-04-03T12:54:04-04:00] ====================================================== +INFO[2023-04-03T12:54:04-04:00] || Created enclave: murky-volcano || +INFO[2023-04-03T12:54:04-04:00] ====================================================== +Name: murky-volcano +UUID: f2fa01a0293f +Status: RUNNING +Creation Time: Mon, 03 Apr 2023 12:54:02 EDT + +========================================= Files Artifacts ========================================= +UUID Name + +========================================== User Services ========================================== +UUID Name Ports Status +``` +
+ + +:::info +Users can use the `debug` `--cli-log-level` flag, , as shown above, to display the entire stack trace to the CLI. By default the entire stack trace is saved to the `kurtosis-cli.log` file. + +The sample error stack-trace that can be seen on the cli after `debug` level is shown below: + +```bash +DEBU[2023-04-03T12:58:03-04:00] Cluster setting filepath: '' +DEBU[2023-04-03T12:58:03-04:00] Kurtosis config YAML filepath: '' +DEBU[2023-04-03T12:58:03-04:00] Loaded Kurtosis Config &{overrides:0x1400000e510 shouldSendMetrics:true clusters:map[docker:0x14000097680 minikube:0x140000976b0]} +DEBU[2023-04-03T12:58:03-04:00] Instantiating a context aware backend with no remote backend config ends up returninga regular local Docker backend. +Error: An error occurred validating arg '' + --- at /root/project/cli/cli/command_framework/lowlevel/lowlevel_kurtosis_command.go:290 (LowlevelKurtosisCommand.MustGetCobraCommand.func2) --- +Caused by: Error reading filepath_or_dirpath '' + --- at /root/project/cli/cli/command_framework/highlevel/file_system_path_arg/file_system_path_arg.go:109 (getValidationFunc.func1) --- +Caused by: stat ../../../per/other/submodul/: no such file or directory +``` +::: + + +[adding-command-line-completion]: ../guides/adding-command-line-completion.md +[installing-the-cli]: ../guides/installing-the-cli.md +[sdk-reference]: ../sdk.md diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/run-starlark.md b/docs/versioned_docs/version-0.78.3/cli-reference/run-starlark.md new file mode 100644 index 0000000000..8b189c2176 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/run-starlark.md @@ -0,0 +1,88 @@ +--- +title: run +sidebar_label: run +slug: /run-starlark +--- + +Kurtosis can be used to run a Starlark script or a [runnable package](../concepts-reference/packages.md) in an enclave. + +A single Starlark script can be ran with: + +```bash +kurtosis run script.star +``` + +Adding the `--dry-run` flag will print the changes without executing them. + +A [Kurtosis package](../concepts-reference/packages.md) on your local machine can be run with: + +```bash +kurtosis run /path/to/package/on/your/machine +``` + +A [runnable Kurtosis package](../concepts-reference/packages.md) published to GitHub can be run like so: + +```bash +kurtosis run github.com/package-author/package-repo +``` + +:::tip +If you want to run a non-main branch, tag or commit use the following syntax +`kurtosis run github.com/package-author/package-repo@tag-branch-commit` +::: + +Arguments can be provided to a Kurtosis package (either local or from GitHub) by passing a JSON-serialized object with args argument, which is the second positional argument you pass to `kurtosis run` like: + +```bash +# Local package +kurtosis run /path/to/package/on/your/machine '{"company":"Kurtosis"}' + +# GitHub package +kurtosis run github.com/package-author/package-repo '{"company":"Kurtosis"}' +``` + +:::info +If the flag `--main-function-name` is set, the JSON-serialized object will be used for passing the function arguments. + +For example, if the main function signature (inside this file github.com/my-org/my-package/src/entry.star) has this shape: +```python +# the plan object is injected always as the first argument +def my_main_function(plan, first_argument, second_argument, their_argument): + # your code +``` + +It can be called like this: +```bash +# you don't have to pass the plan object as an argument because it will be automatically injected by default at the first position +kurtosis run main.star '{"first_argument": "Foo", "second_argument": "Bar", "their_argument": {"first-key:"first-value", "second-key":"second-value"}}' --main-file src/entry.star --main-function-name my_main_function +``` + +THIS IS A TEMPORARY OPTION AND IT WILL BE REMOVED SOON!!! +::: + +This command has options available to customize its execution: + +1. The `--dry-run` flag can be used to print the changes proposed by the script without executing them +1. The `--parallelism` flag can be used to specify to what degree of parallelism certain commands can be run. For example: if the script contains an [`add_services`][add-services-reference] instruction and is run with `--parallelism 100`, up to 100 services will be run at one time. +1. The `--enclave` flag can be used to instruct Kurtosis to run the script inside the specified enclave or create a new enclave (with the given enclave [identifier](../concepts-reference/resource-identifier.md)) if one does not exist. If this flag is not used, Kurtosis will create a new enclave with an auto-generated name, and run the script or package inside it. +1. The `--with-subnetworks` flag can be used to enable [subnetwork capabilties](../concepts-reference/subnetworks.md) within the specified enclave that the script or package is instructed to run within. This flag is false by default. +1. The `--verbosity` flag can be used to set the verbosity of the command output. The options include `BRIEF`, `DETAILED`, or `EXECUTABLE`. If unset, this flag defaults to `BRIEF` for a concise and explicit output. Use `DETAILED` to display the exhaustive list of arguments for each command. Meanwhile, `EXECUTABLE` will generate executable Starlark instructions. +1. The `--main-file` flag can be used to set the main file filepath, the "main" file is a file for the main method (i.e. the package's entrypoint) which will be executed first; the filepath has to be relative to the package's root. The default value is 'main.star'. This flag is only used for running packages. Example: if your main file is located in a path like this `github.com/my-org/my-package/src/internal/my-file.star` you should set `src/internal/my-file.star` as the relative path. +1. The `--main-function-name` flag can be used to set the main function name, which will be executed first as the entrypoint of the package or the module. The default value is 'run'. + +Example of using setting the --main-function-name flag + +For example, to run the `start_node` function in a `main.star` file, simple use: +```bash +kurtosis run main.star --main-function-name start_node +``` + +Where start-node is a function defined in `main.star` as so: +```python +# main.star code +def start_node(plan,args): + # your code +``` + + +[add-services-reference]: ../starlark-reference/plan.md#add_services diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/service-add.md b/docs/versioned_docs/version-0.78.3/cli-reference/service-add.md new file mode 100644 index 0000000000..48de849ba1 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/service-add.md @@ -0,0 +1,25 @@ +--- +title: service add +sidebar_label: service add +slug: /service-add +--- + +To add a service to an enclave, run: + +```bash +kurtosis service add $THE_ENCLAVE_IDENTIFIER $THE_SERVICE_IDENTIFIER $CONTAINER_IMAGE +``` + +where `$THE_ENCLAVE_IDENTIFIER` and the `$THE_SERVICE_IDENTIFIER` are [resource identifiers](../concepts-reference/resource-identifier.md) for the enclave and service, respectively. + +Much like `docker run`, this command has multiple options available to customize the service that's started: + +1. The `--entrypoint` flag can be passed in to override the binary the service runs +1. The `--env` flag can be used to specify a set of environment variables that should be set when running the service +1. The `--ports` flag can be used to set the ports that the service will listen on + +To override the service's CMD, add a `--` after the image name and then pass in your CMD args like so: + +```bash +kurtosis service add --entrypoint sh my-enclave test-service alpine -- -c "echo 'Hello world'" +``` \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/service-delete.md b/docs/versioned_docs/version-0.78.3/cli-reference/service-delete.md new file mode 100644 index 0000000000..7437aad52e --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/service-delete.md @@ -0,0 +1,15 @@ +--- +title: service delete +sidebar_label: service delete +slug: /service-delete +--- + +Services can be deleted from an enclave like so: + +```bash +kurtosis service rm $THE_ENCLAVE_IDENTIFIER $THE_SERVICE_IDENTIFIER +``` + +where `$THE_ENCLAVE_IDENTIFIER` and the `$THE_SERVICE_IDENTIFIER` are [resource identifiers](../concepts-reference/resource-identifier.md) for the enclave and service, respectively. + +**NOTE:** To avoid destroying debugging information, Kurtosis will leave removed services inside the Docker engine. They will be stopped and won't show up in the list of active services in the enclave, but you'll still be able to access them (e.g. using `service logs`) by their service GUID (available via `enclave inspect`). \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/service-exec.md b/docs/versioned_docs/version-0.78.3/cli-reference/service-exec.md new file mode 100644 index 0000000000..2548f9061f --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/service-exec.md @@ -0,0 +1,17 @@ +--- +title: service exec +sidebar_label: service exec +slug: /service-exec +--- + +To run a specific shell command inside a service container, run: + +```bash +kurtosis service exec $THE_ENCLAVE_IDENTIFIER $THE_SERVICE_IDENTIFIER 'COMMAND' +``` + +where `$THE_ENCLAVE_IDENTIFIER` and the `$THE_SERVICE_IDENTIFIER` are [resource identifiers](../concepts-reference/resource-identifier.md) for the enclave and service, respectively. + +The specified command should be appropriately quoted and will be passed as it is to the shell interpreter of the running service container. + +If the command returns a non-zero exit code, Kurtosis CLI will print an error and also return a non-zero exit code. diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/service-logs.md b/docs/versioned_docs/version-0.78.3/cli-reference/service-logs.md new file mode 100644 index 0000000000..9d07822bf2 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/service-logs.md @@ -0,0 +1,21 @@ +--- +title: service logs +sidebar_label: service logs +slug: /service-logs +--- + +To print the logs for a service, run: + +```bash +kurtosis service logs $THE_ENCLAVE_IDENTIFIER $THE_SERVICE_IDENTIFIER +``` + +where `$THE_ENCLAVE_IDENTIFIER` and the `$THE_SERVICE_IDENTIFIER` are [resource identifiers](../concepts-reference/resource-identifier.md) for the enclave and service, respectively. The service identifier (name or UUID) is printed upon inspecting an enclave. + +The following optional arguments can be used: +1. `-f`, `-follow` can be added to continue following the logs, similar to `tail -f`. +1. `--match=text` can be used for filtering the log lines containing the text. +1. `--regex-match="regex"` can be used for filtering the log lines containing the regex. This filter will also work for text but will have degraded performance. +1. `-v`, `--invert-match` can be used to invert the filter condition specified by either `--match` or `--regex-match`. Log lines NOT containing the match will be returned. + +Important: `--match` and `--regex-match` flags cannot be used at the same time. You should either use one or the other. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/service-shell.md b/docs/versioned_docs/version-0.78.3/cli-reference/service-shell.md new file mode 100644 index 0000000000..4f964b0120 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/service-shell.md @@ -0,0 +1,13 @@ +--- +title: service shell +sidebar_label: service shell +slug: /service-shell +--- + +To get access to a shell on a given service container, run: + +```bash +kurtosis service shell $THE_ENCLAVE_IDENTIFIER $THE_SERVICE_IDENTIFIER +``` + +where `$THE_ENCLAVE_IDENTIFIER` and the `$THE_SERVICE_IDENTIFIER` are [resource identifiers](../concepts-reference/resource-identifier.md) for the enclave and service, respectively. diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/twitter.md b/docs/versioned_docs/version-0.78.3/cli-reference/twitter.md new file mode 100644 index 0000000000..8fab8a256a --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/twitter.md @@ -0,0 +1,11 @@ +--- +title: twitter +sidebar_label: twitter +slug: /twitter +--- + +The following command can be used to open a link to our [Twitter account](https://twitter.com/KurtosisTech) from the CLI where you can follow along for announcements and exciting updates. + +```bash +kurtosis twitter +``` diff --git a/docs/versioned_docs/version-0.78.3/cli-reference/version.md b/docs/versioned_docs/version-0.78.3/cli-reference/version.md new file mode 100644 index 0000000000..7ccfe057d2 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/cli-reference/version.md @@ -0,0 +1,14 @@ +--- +title: version +sidebar_label: version +slug: /version +--- + +The `kurtosis version` command displays version information about the [CLI](./index.md) and the Kurtosis engine container. + +Example: + +```console +CLI Version: 0.70.7 +Running Engine Version: 0.70.7 +``` diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/args.md b/docs/versioned_docs/version-0.78.3/concepts-reference/args.md new file mode 100644 index 0000000000..684c757c51 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/args.md @@ -0,0 +1,37 @@ +--- +title: Args +sidebar_label: Args +--- + +Kurtosis [packages][packages-reference] can be parameterized with arguments. Arguments can be passed in via the CLI when running the package. + +To make your package take in arguments, first change your `run` function from: + +```python +def run(plan): +``` + +to: + +```python +def run(plan, args) +``` + +Then pass JSON-serialized arg values to `kurtosis run` in the CLI. For example: + +```bash +kurtosis run github.com/USERNAME/REPO '{"some_parameter":"some_value","some_other_param":5}' +``` + +Kurtosis will automatically JSON-deserialize the JSON string, and then pass it in to the `run` function in Starlark. + +The JSON passed in via the command line will be deserialized to a dictionary in Starlark (_not_ a `struct`). So to access the args above, your `main.star` might look like: + +```python +def run(plan, args): + plan.print("some_parameter value: " + args["some_parameter"]) + plan.print("some_other_param value: " + args["some_other_param"]) +``` + + +[packages-reference]: ./packages.md diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/enclaves.md b/docs/versioned_docs/version-0.78.3/concepts-reference/enclaves.md new file mode 100644 index 0000000000..4dabe60506 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/enclaves.md @@ -0,0 +1,20 @@ +--- +title: Enclaves +sidebar_label: Enclaves +--- + +An enclave is a Kurtosis primitive representing an isolated, ephemeral environment - like the Kurtosis version of a Kubernetes namespace. They are managed by the `enclave` family of CLI commands (e.g. [`kurtosis enclave add`][enclave-add-reference], [`kurtosis enclave ls`][enclave-ls-reference], [`kurtosis enclave inspect`][enclave-inspect-reference], etc.). + +Each enclave houses an arbitrary number of services and [files artifacts][files-artifacts-reference]. The contents of an enclave are manipulated using [Starlark][starlark-reference] via [functions on the `Plan` object](../starlark-reference/plan.md) + +When an enclave is removed via [`kurtosis enclave rm`][enclave-rm-reference] or [`kurtosis clean`][clean-reference], everything inside of it is destroyed as well. + + +[enclave-add-reference]: ../cli-reference/enclave-add.md +[enclave-ls-reference]: ../cli-reference/enclave-ls.md +[enclave-inspect-reference]: ../cli-reference/enclave-inspect.md +[enclave-rm-reference]: ../cli-reference/enclave-rm.md +[clean-reference]: ../cli-reference/clean.md +[files-artifacts-reference]: ./files-artifacts.md +[plan-starlark-reference]: ../starlark-reference/plan.md +[starlark-reference]: ./starlark.md diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/files-artifacts.md b/docs/versioned_docs/version-0.78.3/concepts-reference/files-artifacts.md new file mode 100644 index 0000000000..46037199f5 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/files-artifacts.md @@ -0,0 +1,26 @@ +--- +title: Files Artifacts +sidebar_label: Files Artifacts +--- + +Kurtosis enclaves can store files for later use. Files stored in a Kurtosis enclave are stored as compressed TGZ files. These TGZs are called "files artifacts". + +For example, a user can upload files on their machine to an enclave like so: + +```bash +kurtosis files upload $SOME_PATH +``` + +:::info +If `$SOME_PATH` is a file, that single file will be packaged inside the files artifact. If `$SOME_PATH` is a directory, all of the directory's contents will be packaged inside the files artifact. +::: + +Doing so will return a randomly-generated ID and name that can be used to reference the files artifact for later use. + +For example, the `--files` flag of `kurtosis service add` can be used to mount the contents of a files artifact at specified location. This command will mount the contents of files artifact `test-artifact` at the `/data` directory: + +```bash +kurtosis service add "some-enclave" "some-service-name" --files "/data:test-artifact" +``` + +The same files artifact can be reused many times because the contents of a files artifact is copied when it is used. \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/future-references.md b/docs/versioned_docs/version-0.78.3/concepts-reference/future-references.md new file mode 100644 index 0000000000..83ada84aea --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/future-references.md @@ -0,0 +1,47 @@ +--- +title: Future References +sidebar_label: Future References +--- + +Kurtosis uses [a multi-phase approach][multi-phase-runs-reference] when running [Starlark scripts][starlark-reference]. + +For the user, the important thing to remember is that any value returned by [a Kurtosis Starlark instruction][starlark-reference] is not the actual value - it is a special string referencing the _future_ value that will exist during the Execution Phase. + +For example: + +```python +service = add_service( + "my-service", + config = struct( + image = "hello-world", + ) +) +print(service.ip_address) +``` + +does not in fact print the actual IP address of the service, because the service does not exist during the Interpretation Phase. Instead, `service.ip_address` is a string referencing the future value of the service's IP address: + +``` +{{kurtosis:my-service.ip_address}} +``` + +Anywhere this future reference string is used, Kurtosis will slot in the actual value during the Execution Phase. For example, when the `print` statement is executed during the Execution Phase, Kurtosis will replace the future reference with the actual value so that the service's actual IP address gets printed: + +``` +> print "{{kurtosis:my-service.ip_address}}" +172.19.10.3 +``` + +:::caution +The format of these future reference strings is undefined and subject to change; users should not construct them manually! +::: + +All values that are available exclusively during the Execution Phase will be handled in Starlark as future reference strings. This includes: + +- Service information +- Files artifact information +- Execution-time values (e.g. values returned by HTTP requests or `exec`ing a command on a container) + + +[multi-phase-runs-reference]: ./multi-phase-runs.md +[starlark-reference]: ../starlark-reference/index.md diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/glossary.md b/docs/versioned_docs/version-0.78.3/concepts-reference/glossary.md new file mode 100644 index 0000000000..559187ac9c --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/glossary.md @@ -0,0 +1,38 @@ +--- +title: Glossary +sidebar_label: Glossary +--- + + + +### API Container +The container that runs inside of each enclave. Receives Starlark via API and manipulates the enclave according to the instructions in Starlark. + +### CLI +A command line interface, [installed by your favorite package manager](../guides/installing-the-cli.md), which wraps the Kurosis Go [SDK][sdk-reference] to allow you to manipulate the contents of Kurtosis. + +### Enclave +An environment, isolated from other enclaves, in which distributed systems are launched and manipulated. + +### Engine +The Kurtosis engine which receives instructions via API (e.g. "launch this service in this enclave", "create a new enclave", "destroy this enclave", etc.). + +### Locator +A URL-like string for referencing resources. Also see [the extended documentation][locators]. + +### Package +A directory containing [a `kurtosis.yml` file][kurtosis-yml] and any additional modules and static files that the package needs. Also see [the extended documentation][packages]. + +### Starlark +[A minimal, Python-like language invented at Google](https://github.com/bazelbuild/starlark) for configuring their build tool, Bazel. + +### User Service +A container, launched inside an enclave upon a request to the Kurtosis engine, that is started from whatever image the user pleases. + + + + +[locators]: ./locators.md +[kurtosis-yml]: ./kurtosis-yml.md +[packages]: ./packages.md +[sdk-reference]: ../sdk.md diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/kurtosis-yml.md b/docs/versioned_docs/version-0.78.3/concepts-reference/kurtosis-yml.md new file mode 100644 index 0000000000..61a913cbc7 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/kurtosis-yml.md @@ -0,0 +1,37 @@ +--- +title: kurtosis.yml +sidebar_label: kurtosis.yml +--- + +:::info +The `kurtosis.yml` is part of the Kurtosis package system. To read about the package system in detail, [see here][how-do-kurtosis-imports-work-explanation]. +::: + +The `kurtosis.yml` file is a manifest file necessary to turn a directory into [a Kurtosis package][package]. This is the spec for the `kurtosis.yml`: + + + +```yaml +# The locator naming this package. +name: github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml +``` + +Example usage: + +if kurtosis.yml is in the repository root: +```yaml +name: github.com/author/package-repo +``` + +if kurtosis.yml is in a directory other than repository root: +```yaml +name: github.com/author/package-repo/path/to/directory-with-kurtosis.yml +``` + +:::info +The key take away is that `/path/to/directory-with-kurtosis.yml` only needs to be provided if `kurtosis.yml` is not present in the repository's root. +::: + + +[package]: ./packages.md +[how-do-kurtosis-imports-work-explanation]: ../explanations/how-do-kurtosis-imports-work.md \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/locators.md b/docs/versioned_docs/version-0.78.3/concepts-reference/locators.md new file mode 100644 index 0000000000..fe97d222f3 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/locators.md @@ -0,0 +1,79 @@ +--- +title: Locators +sidebar_label: Locators +--- + +:::info +Locators are a part of the Kurtosis package system. To read about the package system in detail, [see here][how-do-kurtosis-imports-work-explanation]. +::: + +A locator is a URL-like string used to locate a resource inside [a Kurtosis package][packages]. For example, this locator: + +``` +github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml/some-file.star +``` + +references a file inside a GitHub repo called `package-repo`, owned by `package-author`, that lives at the path `/path/to/directory-with-kurtosis.yml/some-file.star` relative to the root of the repo. + + +Locators are used for identifying resources that will be used inside a Starlark script - namely by [`import_module`](../starlark-reference/import-module.md) and [`read_file`](../starlark-reference/read-file.md). + +:::caution +A GitHub URL is **not** a valid locator, because GitHub adds extra `/blob/main` paths to the URL that don't reflect the file's path in the repo. For example, a GitHub URL of: + +``` +https://github.com/kurtosis-tech/kurtosis/blob/main/starlark/test.star +``` + +would be the following as a Kurtosis locator (dropping the `https://` and `/blob/main` part): + +``` +github.com/kurtosis-tech/kurtosis/starlark/test.star +``` +::: + +:::info +Only locators pointing to public GitHub repositories are currently allowed. +::: + +Any Starlark script that wishes to use external resources must be +a part of a [Kurtosis package][packages]. + +All locators are absolute; "relative" locators do not exist. For a Starlark script to reference a local file (i.e. one that lives next to in the filesystem), the Starlark script must use the name of the package that it lives inside. + +For example, suppose we had a [Kurtosis package][packages] like so: + +``` +/ + package-repo + my-package + kurtosis.yml + main.star + helpers + random-script.star + not-a-package + random-script.star +``` + +with a `kurtosis.yml` file like so: + +```yaml +name: github.com/package-author/package-repo/my-package +``` + +The `main.star` file would import the `random-script.star` from the `helpers` subdirectory of `my-package` like so: + +```python +helpers = import_module("github.com/package-author/package-repo/my-package/helpers/random-script.star") +``` + +The import statement below will not succeed, this is because `main.star` cannot import from non-packages. +(see [how import works][how-do-kurtosis-imports-work-explanation] for more information) + +```python +helpers = import_module("github.com/package-author/package-repo/not-a-package/random-script.star") +``` + + +[packages]: ./packages.md +[how-do-kurtosis-imports-work-explanation]: ../explanations/how-do-kurtosis-imports-work.md diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/multi-phase-runs.md b/docs/versioned_docs/version-0.78.3/concepts-reference/multi-phase-runs.md new file mode 100644 index 0000000000..5da2b80a18 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/multi-phase-runs.md @@ -0,0 +1,29 @@ +--- +title: Multi-Phase Runs +sidebar_label: Multi-Phase Runs +--- + + + +Kurtosis environment definitions are encapsulated inside [Starlark scripts][starlark-reference], and these scripts can be bundled into [packages][packages]. + +Much like Spark, Gradle, Cypress, and Flink, a multi-phase approach is used when Kurtosis runs Starlark: + + +1. **Interpretation Phase:** The Starlark is uploaded to the Kurtosis engine and the Starlark code is run. Each [function call on the `Plan` object][plan-starlark-reference] adds a step to a plan of instructions to execute, _but the instruction isn't executed yet_. +1. **Validation Phase:** The plan of instructions is validated to ensure port dependencies are referencing existing ports, container images exist, duplicate services aren't being created, etc. +1. **Execution Phase:** The validated plan of instructions is executed, in the order they were defined. + +Practically, the user should be aware that: + +- Running [a function on the `Plan` object][plan-starlark-reference] does not execute the instruction on-the-spot; it instead adds the instruction to a plan of instructions to execute during the Execution Phase. +- Any value returned by a `Plan` function in Starlark is not the actual value - it is [a future reference that Kurtosis will replace during the Execution Phase when the value actually exists][future-references-reference]. + +To read about why Kurtosis uses this multi-phase approach, [see here][multi-phase-runs-explanation]. + + +[starlark-reference]: ./starlark.md +[plan-starlark-reference]: ../starlark-reference/plan.md +[packages]: ./packages.md +[multi-phase-runs-explanation]: ../explanations/why-multi-phase-runs.md +[future-references-reference]: ./future-references.md diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/packages.md b/docs/versioned_docs/version-0.78.3/concepts-reference/packages.md new file mode 100644 index 0000000000..d257d342f3 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/packages.md @@ -0,0 +1,102 @@ +--- +title: Packages +sidebar_label: Packages +--- + +:::info +Packages are a part of the Kurtosis package system. To read about the package system in detail, [see here][how-do-kurtosis-imports-work-explanation]. +::: + + + +A Kurtosis package is a: + +- A directory +- Plus all its contents +- That contains [a `kurtosis.yml` file][kurtosis-yml] with the package's name, which will be the [locator][locators] root for the package + +Kurtosis packages are [the system by which Starlark scripts can include external resources][how-do-kurtosis-imports-work-explanation]. + +Note that, when developing locally, the GitHub repo referred to in the package name does not need to exist. + +Kurtosis packages are shared simply by pushing to GitHub (e.g. [these are the packages we administer][kurtosis-managed-packages]). + +For example, suppose there is a repo called `package-repo` by the author `package-author` whose internal directory structure looks like so: + +``` +/ + package-repo + my-package + kurtosis.yml + main.star + helpers + helpers.star +``` + +whose `kurtosis.yml` file looked like so: + +```yaml +name: github.com/package-author/package-repo/my-package +``` + +The package would be called `github.com/package-author/package-repo/my-package`. It should get pushed to the `package-repo` repo owned by the `package-author` user on GitHub. + +Packages are referenced indirectly, as the [locators][locators] used to specify external resources in a Starlark script will contain the package name where the resource lives. + +For example: + +```python +helpers = import_module("github.com/package-author/package-repo/my-package/helpers/helpers.star") +``` + +would be used to import the `helpers.star` file into a Starlark script. + + +The Kurtosis engine will automatically download dependency packages from GitHub when running a Starlark script. + +### Runnable Packages +A Kurtosis package that has a `main.star` file next to its `kurtosis.yml` file is called a "runnable package". The `main.star` file of a runnable package must have a `run(plan)` method like so: + +```python +def run(plan): + print("Hello, world.") +``` + +:::info +More on the `plan` parameter [here][plan]. +::: + +Runnable packages can be executed from the CLI in one of three ways: + +```bash +# OPTION 1: Point to a directory with a `kurtosis.yml` and `main.star` on local filesystem +kurtosis run /path/to/runnable/package/root +``` + +```bash +# OPTION 2: Point to a `kurtosis.yml` on the local filesystem with a `main.star` next to it on local fileesystem +kurtosis run /path/to/runnable/package/root/kurtosis.yml +``` + +```bash +# OPTION 3: Pass in a remote package name to run from GitHub +kurtosis run github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml +``` + +:::tip +If you want to run a non-main branch, tag or commit use the following syntax +`kurtosis run github.com/package-author/package-repo@tag-branch-commit` +::: + +All these will call the `run(plan)` function of the package's `main.star`. + +### Arguments +Kurtosis packages can be parameterized with arguments by adding an `args` parameter to the `run` function. Read more about package arguments [here][args-reference]. + + +[kurtosis-yml]: ./kurtosis-yml.md +[locators]: ./locators.md +[kurtosis-managed-packages]: https://github.com/kurtosis-tech?q=package+in%3Aname&type=all&language=&sort= +[how-do-kurtosis-imports-work-explanation]: ../explanations/how-do-kurtosis-imports-work.md +[plan]: ./plan.md +[args-reference]: ./args.md diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/plan.md b/docs/versioned_docs/version-0.78.3/concepts-reference/plan.md new file mode 100644 index 0000000000..37dcf22b10 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/plan.md @@ -0,0 +1,52 @@ +--- +title: Plan +sidebar_label: Plan +--- + +The plan is a representation of the manipulations that Kurtosis should execute within an enclave. It is central to the [multi-phase run design of Kurtosis][multi-phase-runs]. Plans are built via [Starlark][starlark-reference] by calling [functions on the `Plan` object][plan-starlark-reference] like `add_service`, `remove_service`, or `upload_files`. + +Kurtosis injects the `Plan` object into the `run` method in the `main.star` of your package or your standalone script. The package or script author must ensure that the first argument is an argument called `plan`, and then use the enclave-modifying functions from it. The author also must pass the `plan` methods down to any other scripts or packages that require enclave-modifying functions. + +Here's an example :- + +Imagine you have a `kurtosis.yml` that looks like +```yaml +name: "github.com/test-author/test-package" +``` + +Further with a `main.star` at the root of the package that looks like +```py +datastore = import_module("github.com/test-author/test-package/lib/datastore.star") + +def run(plan): + datastore.create_datastore(plan) +``` + +and the `lib/datastore.star` looks like +```py +def create_datastore(plan): + plan.add_service( + name = "datastore-service", + config = ServiceConfig( + image = "kurtosistech/example-datastore-server" + ) + ) +``` + +To accept [arguments][arguments] in the `run` function, pass them as the second parameter like so + +```py +def run(plan, args): + pass +``` + +:::caution +Any value returned by a `plan` function is a [future-reference][future-reference]. This means that you can't run conditionals or interpretation time methods like `string.split` on it. +::: + + +[future-reference]: ./future-references.md +[arguments]: ./packages.md#arguments +[multi-phase-runs]: ./multi-phase-runs.md +[starlark-reference]: ./starlark.md +[plan-starlark-reference]: ../starlark-reference/plan.md diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/resource-identifier.md b/docs/versioned_docs/version-0.78.3/concepts-reference/resource-identifier.md new file mode 100644 index 0000000000..e0bd86eb48 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/resource-identifier.md @@ -0,0 +1,68 @@ +--- +title: Resource Identifier +sidebar_label: Resource Identifier +--- + +Kurtosis has multiple ways to identify a given resource within Kurtosis. These include UUIDs, shortened UUIDs and names. Together these are called resource identifiers. + +A resource identifier as mentioned above is the union of the following - + +- UUID - a UUID or a Universally Unique Identifier within Kurtosis is a 32 character-long hex-encoded string generated using [UUID v4][uuidv4]. Kurtosis automatically assigns a UUID to resources. +- Shortened UUID - A shortened UUID is the first 12 characters of a UUID. As the shortened UUID is just 12 characters, it isn't guaranteed to be unique. In case of conflicts, Kurtosis tells the user about the ambiguity and provides +a list of matching full UUIDs. +- Name - A name is what a user gives to the underlying resource. For some resources Kurtosis automatically generates the name if the user doesn't specify it. Note a name is only point-in-time unique; you can have the same name identifying different resources over time. In case of conflicts, Kurtosis tells the user about the ambiguity and provides a list of matching full UUIDs. + +For example, let's assume an enclave was created with the name `winter-sun`. If you run `kurtosis enclave inspect winter-sun` you would get something like - + +``` +UUID: edfdbf5766f6 +Enclave Name: winter-snow +Enclave Status: RUNNING +Creation Time: Tue, 24 Jan 2023 16:45:13 GMT +API Container Status: RUNNING +API Container Host GRPC Port: 127.0.0.1:54433 + +========================================== User Services ========================================== +UUID Name Ports Status +``` + +Notice how Kurtosis shows the shortened UUID by default. All CLI commands show +shortened UUIDs by default; if you want to see full UUIDs you can use the `--full-uuids` flag with the command. Rerunning the above command with `--full-uuids` you'd get + +``` +UUID: edfdbf5766f64a649efca11f51ebb4c1 +Enclave Name: winter-snow +Enclave Status: RUNNING +Creation Time: Tue, 24 Jan 2023 16:45:13 GMT +API Container Status: RUNNING +API Container Host GRPC Port: 127.0.0.1:54433 + +========================================== User Services ========================================== +UUID Name Ports Status +``` + +Whenever a user is querying Kurtosis using the CLI & SDK, the user can use any of UUID, shortened UUID & name. The CLI informs the user about this support by calling the relevant argument `resource-identifier`, like below + +``` +Usage: + kurtosis enclave inspect [flags] enclave-identifier + +Flags: + --full-uuids If true then Kurtosis prints full UUIDs instead of shortened UUIDs. Default false. + -h, --help help for inspect + +Global Flags: + --cli-log-level string Sets the level that the CLI will log at (panic|fatal|error|warning|info|debug|trace) (default "info") +``` + +Resource Identifiers are supported for the following resources inside of Kurtosis + +- [Files Artifacts][files-artifacts] +- [Services][services] +- [Enclaves][enclaves] + + +[uuidv4]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) +[files-artifacts]: ./files-artifacts.md +[services]: ./glossary.md#user-service +[enclaves]: ./glossary.md#enclave diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/starlark.md b/docs/versioned_docs/version-0.78.3/concepts-reference/starlark.md new file mode 100644 index 0000000000..53d0f9aa61 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/starlark.md @@ -0,0 +1,37 @@ +--- +title: Starlark +sidebar_label: Starlark +--- + +[Starlark](https://github.com/bazelbuild/starlark) is a minimal programming language, halfway between a configuration language and a general-purpose programming language. It was developed by Google to do configurations for the [Bazel build tool](https://bazel.build/rules/language), and has since [been adopted by Facebook for the Buck build system as well](https://github.com/facebookexperimental/starlark-rust). Starlark's syntax is a minimal subset of of Python, with a focus on readability. [This page](https://bazel.build/rules/language#differences_with_python) lists the differences between Starlark and Python. + +Kurtosis uses Starlark as the way for users to express manipulations to [enclave][enclaves-reference]. Users submit Starlark scripts to Kurtosis, the Starlark is interpreted, and the instructions in the script are executed. + +To read more about why we chose Starlark, see [this page][why-kurtosis-starlark]. + +How is Starlark implemented at Kurtosis? +---------------------------------------- +Starlark itself is very basic; Google designed it to be extended to fulfill a given usecase. For example, the Bazel language is actually an extension built on top of Starlark. + +We extended basic Starlark with [our own DSL](../starlark-reference/index.md) so that it could [fulfill the properties of reusable environment definitions](../explanations/reusable-environment-definitions.md). This gave us: + +- A [list of Kurtosis-specific functions][starlark-reference] for working with an environment +- The [ability to accept parameters][run-args-reference] +- Dependencies, so Kurtosis scripts can [import other scripts][locators-reference] +- A [GitHub-based packaging system](./packages.md), so environment definitions can be shared with each other + +Additionally, we built a [multi-phase engine][multi-phase-runs-reference] around the Starlark interpreter, to provide [users with benefits not normally available in a scripting language][multi-phase-runs-explanation]. + +:::tip Visual Studio Code (VS Code) Extension +We've released an [official Kurtosis Starlark VS Code extension][vscode-plugin] to enrich the developer experience when writing packages with Starlark. Features include: syntax highlighting, method signature suggestions, hover preview for functions, and auto-completion for Kurtosis custom types. +::: + + +[enclaves-reference]: ./enclaves.md +[why-kurtosis-starlark]: ../explanations/why-kurtosis-starlark.md +[starlark-reference]: ../starlark-reference/index.md +[run-args-reference]: ./packages.md#arguments +[locators-reference]: ./locators.md +[multi-phase-runs-reference]: ../concepts-reference/multi-phase-runs.md +[multi-phase-runs-explanation]: ../explanations/why-multi-phase-runs.md +[vscode-plugin]: https://marketplace.visualstudio.com/items?itemName=Kurtosis.kurtosis-extension diff --git a/docs/versioned_docs/version-0.78.3/concepts-reference/subnetworks.md b/docs/versioned_docs/version-0.78.3/concepts-reference/subnetworks.md new file mode 100644 index 0000000000..c7c5b46728 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/concepts-reference/subnetworks.md @@ -0,0 +1,41 @@ +--- +title: Subnetworks +sidebar_label: Subnetworks +--- + +:::tip + +Want to get started with subnetworks? See how to easily simulate a networking failure [here][networking-failure-guide] + +::: + +A service started inside a Kurtosis enclave will by default be able to communicate with all other services inside the same enclave. To change that behavior, Kurtosis exposes the concept of *subnetworks*. + +A subnetwork is a way to group together an arbitrary number of services from the same enclave. It is very lightweight and it can be instantiated by "tagging" each service with a subnetwork name (see [add_service][add-service] and [update_service][update-service]). A service added to an enclave without a subnetwork specified is added to the default subnetwork (called `default`). + +All services with the same "subnetwork tag" will belong to the same subnetwork, and networking can then be configured _accross subnetworks_. All services in the same subnetwork (including the `default` one) will always be able to communicate. + +The connection configuration between two subnetworks inherits a *default connection* defined in Kurtosis. It is set to allow all communications when the enclave starts but it can be changed using [set_connection][set-connection]. + +To have fine grained control, the connection between two specific subnetworks can be overridden also using the same [set_connection][set-connection]. The override can be removed using [remove_connection][remove-connection]. + +:::caution + +This functionaility is only available for Kurtosis running on Docker. Kurtosis running on Kubernetes cannot use subnetworks yet, and instructions requiring it will throw an error. + +::: + +:::caution + +This functionality must be enabled manually per enclave using the CLI. When running Starlark scripts or packages using this feature, add the `--with-subnetworks` optional flag. + +::: + + + + +[add-service]: ../starlark-reference/plan.md#add_service +[update-service]: ../starlark-reference/plan.md#update_service +[set-connection]: ../starlark-reference/plan.md#set_connection +[remove-connection]: ../starlark-reference/plan.md#remove_connection +[networking-failure-guide]: ../guides/simulating-networking-failure.md diff --git a/docs/versioned_docs/version-0.78.3/explanations/architecture.md b/docs/versioned_docs/version-0.78.3/explanations/architecture.md new file mode 100644 index 0000000000..88f86930e4 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/explanations/architecture.md @@ -0,0 +1,115 @@ +--- +title: Kurtosis Architecture +sidebar_label: Architecture +sidebar_position: 2 +--- + +![Kurtosis Architecture](/img/explanations/kurtosis-architecture.png) + +Kurtosis At A Macro Level +------------------------- +At a macro level, Kurtosis is a set of containers, deployed on top of a container orchestrator (e.g. Docker, Kubernetes), that expose APIs. All interaction with Kurtosis is done via APIs. After Kurtosis receives a request, it usually reads or modifies some state in the container orchestrator. Kurtosis therefore serves as an abstraction layer atop the container orchestrator. + +One Layer Deeper +---------------- +To understand what Kurtosis itself does, we'll need to understand environments. Kurtosis' philosophy is that [the distributed nature of modern software means that modern software development now happens at the environment level][why-we-built-kurtosis]. To respond to this need, environments are a first-class concept in Kurtosis: easy to create, easy to inspect, easy to modify, and easy to destroy. + +Therefore, the job of Kurtosis is to receive requests from the user and translate them to instructions for the underlying container orchestration engine. These requests can be simple commands that map one-to-one to instructions to the underlying container orchestrator (e.g. "add service X to environment Y"), or they can be Kurtosis-only commands that require complex interaction with the container orchestrator (e.g. "create a simulated network partition in environment X"). + +Enclaves +-------- +Kurtosis implements environments as a first-class concept using [enclaves][enclaves-reference]. An enclave can be thought of as an "environment container" - an isolated place for a user to run an environment that is easy to create, manage, and destroy. Each enclave is separated from the other enclaves: no network communication can happen between them. Enclaves are also cheap: Kurtosis can manage arbitrary numbers of enclaves, limited only by the underlying hardware. + +Example: Some enclaves running in, as displayed by [the Kurtosis CLI][cli-reference]: + +``` +UUID Name Status Creation Time +a72b68e510fe test RUNNING Thu, 30 Mar 2023 09:12:17 -03 +9e8c913754bf local RUNNING Thu, 30 Mar 2023 09:13:04 -03 +``` + +Engine Container +---------------- +The first type of container that Kurtosis creates is the Kurtosis engine container. This container's API is principally responsible for managing enclaves. This includes [creating enclaves][enclave-add-reference], [listing enclaves][enclave-ls-reference], [inspecting enclaves][enclave-inspect-reference], and [removing enclaves][enclave-rm-reference]. + +Example: A Kurtosis engine container running in Docker: + +```console +bfb5627ff511 kurtosistech/engine:0.70.7 "/bin/sh -c ./kurtos…" 10 hours ago Up 10 hours 0.0.0.0:9710-9711->9710-9711/tcp kurtosis-engine--f84ce1f4c5ea410080e774cfea0ea0a4 +``` + +Services +-------- +Enclaves contain distributed applications, and distributed applications are composed of services. In Kurtosis, a service is a container that exposes ports. Services may also depend on other services (e.g. an API server depending on a database). Each enclave can have an arbitrary numbers of services, limited only by the underlying hardware. + +Example: A pair of Nginx services running inside an enclave called `test`, as reported by the Kurtosis CLI: + +``` +UUID: 2e42f9fd7b854eabb04f71a15bd1b55f +Name: test +Status: RUNNING +Creation Time: Thu, 24 Nov 2022 11:11:34 -03 + +========================================== User Services ========================================== +GUID ID Ports Status +nginx-1669299161 nginx http: 80/tcp -> 127.0.0.1:60785 RUNNING +nginx2-1669299176 nginx2 http: 80/tcp -> 127.0.0.1:60794 RUNNING +``` + +API Container +------------- +The second type of container that Kurtosis creates is the API container. One API container is created per enclave, and each API container is responsible for managing interactions with its own enclave. All manipulation of an enclave's contents happens via API calls to the enclave's API container. + +Example: a Kurtosis API container running in Docker: + +``` +3c0b6ab7bb85 kurtosistech/core:0.70.7 "/bin/sh -c ./api-co…" 20 hours ago Up 20 hours 0.0.0.0:58419->7443/tcp, 0.0.0.0:58418->7444/tcp kurtosis-api--6babc3090ad04184b2094901a7ead7b4 +``` + +Starlark +-------- +Distributed system definitions are complex. Therefore, there are many, many ways to instantiate, configure, and manipulate an enclave. To provide the required power, manipulations to an enclave are expressed using [Starlark][starlark-reference] scripts. + +To manipulate an enclave, users upload Starlark scripts to the API container. The API container executes the instructions in the script, and the enclave's contents will be mutated. + +Example: This Starlark snippet from [the quickstart][quickstart] launches a Postgres container: + +```python +def run(plan, args): + postgres = plan.add_service( + service_name = "postgres", + config = ServiceConfig( + image = "postgres:15.2-alpine", + ports = { + "postgresql": PortSpec(5432, application_protocol = "postgresql"), + }, + env_vars = { + "POSTGRES_PASSWORD": "password", + }, + ), + ) +``` + +For a list of all the Kurtosis Starlark instructions, [see here][starlark-code-reference]. + +SDK +---------------- +All interactions with Kurtosis happen through API requests to the Kurtosis containers. To assist with calling the API, [we provide an SDK in various languages](https://github.com/kurtosis-tech/kurtosis/tree/main/api). Anything the Kurtosis can do will be available via the API and, therefore, via the SDK. + +To see documentation for our SDK, [go here][SDK-reference]. + +For day-to-day operation, we also provide [a CLI][cli-reference]. This is simply a Go CLI wrapped around the Go Kurtosis SDK. + + +[cli-reference]: ../cli-reference/index.md +[reusable-environment-definitions]: ./reusable-environment-definitions.md +[why-we-built-kurtosis]: ./why-we-built-kurtosis.md +[starlark-reference]: ../concepts-reference/starlark.md +[starlark-code-reference]: ../starlark-reference/index.md +[enclaves-reference]: ../concepts-reference/enclaves.md +[enclave-add-reference]: ../cli-reference/enclave-add.md +[enclave-ls-reference]: ../cli-reference/enclave-ls.md +[enclave-inspect-reference]: ../cli-reference/enclave-inspect.md +[enclave-rm-reference]: ../cli-reference/enclave-rm.md +[quickstart]: ../quickstart.md +[sdk-reference]: ../sdk.md diff --git a/docs/versioned_docs/version-0.78.3/explanations/how-do-kurtosis-imports-work.md b/docs/versioned_docs/version-0.78.3/explanations/how-do-kurtosis-imports-work.md new file mode 100644 index 0000000000..01c819391a --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/explanations/how-do-kurtosis-imports-work.md @@ -0,0 +1,144 @@ +--- +title: How Do Kurtosis Imports Work? +sidebar_label: How Do Kurtosis Imports Work? +--- + +### Background +Kurtosis allows a [Starlark script][starlark-reference] to use content from other files. This might be importing code from another Starlark file (via [the `import_module` instruction][import-module-starlark-reference]), or using contents of a static file (via [the `read_file` instruction][read-file-starlark-reference]). + +In both cases, the Kurtosis engine needs to know where to find the external file. There are two cases where external files might live: + +1. Locally: the external file lives on the same filesystem as the Starlark script that is trying to use it. +1. Remotely: the external file lives somewhere on the internet. + +Therefore, Kurtosis needs to handle both of these. + +:::info +This external files problem is not unique to Kurtosis. Every programming language faces the same challenge, and each programming language solves it differently. + +
+Click to see examples + +- In Javascript, local files are referenced via relative imports: + + ```javascript + import something from ../../someDirectory/someFile + ``` + + and remote files are downloaded as modules using `npm` or `yarn` and stored in the `node_modules` directory. The remote files will then be available via: + + ```javascript + import some-package + ``` + +- In Python, local files are handled via the [relative import syntax](https://docs.python.org/3/reference/import.html#package-relative-imports): + + ```python + from .moduleY import spam + from ..moduleA import foo + ``` + + and remote files are downloaded as packages using `pip`, stored somewhere on your machine, and made available via the `PYTHONPATH` variable. The package will then be available via regular import syntax: + + ```python + import some_package + ``` + +- In Java, the difference between local and remote files is less distinct because all files are packaged in JARs. Classes are imported using Java's import syntax: + + ```java + import com.docker.clients.Client; + ``` + + and the Java classpath is searched for each import to see if any JAR contains a matching file. It is the responsibility of the user to build the correct classpath, and various tools and dependency managers help developers download JARs and construct the classpath correctly. + +
+::: + +### Kurtosis Packages +Remote file imports in any language are always handled through a packaging system. This is because any language that allows remote external files must have a solution for identifying the remote files, downloading them locally, and making them available on the import path (`PYTHONPATH`, `node_modules`, classpath, etc.). Furthermore, authors must be able to bundle files together into a package, publish them, and share them. Thus, For Kurtosis to allow Starlark scripts to depend on remote external files, we needed a packaging system of our own. + +Of all the languages, we have been most impressed by [Go's packaging system (which Go calls "modules")](https://go.dev/blog/using-go-modules). In Go: + +- Modules are easy to create by adding a `go.mod` manifest file to a directory ([example](https://github.com/kurtosis-tech/kurtosis/blob/main/cli/cli/go.mod)) +- Dependencies are easy to declare in the `go.mod` file +- Modules are published to the world simply by pushing up to GitHub + +Kurtosis code needs to be easy to share, so we modelled our packaging system off Go's. + +In Kurtosis, a directory that has [a `kurtosis.yml` file][kurtosis-yml-reference] is the package root of a [Kurtosis package][packages-reference], and all the contents of that directory will be part of the package. Any Starlark script inside the package will have the ability to use external files (e.g. via `read_file` or `import_module`) by specifying [the locator][locators-reference] of the file. + +Each package will be named with the `name` key inside the `kurtosis.yml` file. Package names follow the format `github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml` as specified in [the `kurtosis.yml` documentation][kurtosis-yml-reference]. This package name is used to determine whether a file being imported is local (meaning "found inside the package") or remote (meaning "found from the internet"). The logic for resolving a `read_file`/`import_module` is as follows: + +- If the package name in the `kurtosis.yml` is a prefix of the [locator][locators-reference] used in `read_file`/`import_module`, then the file is assumed to be local inside the package. The package name in the locator (`github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml`) references the package root (which is the directory where the `kurtosis.yml` lives), and each subpath appended to the package name will traverse down in the repo. + +- If the package name is not a prefix of the [locator][locators-reference] used in `read_file`/`import_module`, then the file is assumed to be remote. Kurtosis will look at the `github.com/package-author/package-repo` prefix of the locator, clone the repository from GitHub, and use the file inside the package i.e a directory that contains kurtosis.yml. + +:::info +Since `kurtosis.yml` can live in any directory, users have the ability to create multiple packages per repo (sibling packages). We do not currently support a package importing a sibling package (i.e. if `foo` and `bar` packages are subdirectories of `repo`, then `bar` cannot import files from `foo`). Please let us know if you need this functionality. +::: + +Kurtosis does not allow referencing local files outside the package (i.e. in a directory above the package root with the `kurtosis.yml` file). This is to ensure that all files used in the package get pushed to GitHub when the package is published. + +### Packages in Practice +There are three ways to run Kurtosis Starlark. The first is by running a script directly: + +``` +kurtosis run some-script.star +``` + +Because only a script was specified, Kurtosis does not have the `kurtosis.yml` or package name necessary to resolve file imports. Therefore, any imports used in the script will fail. + +The second way is to run a runnable package by pointing to the package root: + +``` +# OPTION 1: Point to the directory containing the `kurtosis.yml` and `main.star` +kurtosis run /path/to/package/root # Can also be "." + +# OPTION 2: Point to a `kurtosis.yml` file directly, with a `main.star` next to it +kurtosis run /path/to/package/root/kurtosis.yml +``` + +In both cases, Kurtosis will run the `main.star` in the package root and resolve any file imports using the package name specified in the `kurtosis.yml`. All local imports (imports that have the package name as a prefix to the locator) will be resolved within the directory on your filesystem; this is very useful for local development. + +:::info +Not all packages have a `main.star` file, meaning not all packages are runnable; some packages are simply libraries intended to be imported in other packages. +::: + +The third way is to run a runnable package by its package name (can be found in the kurtosis.yml from the directory): + +``` +# if kurtosis.yml is in repository root +kurtosis run github.com/package-author/package-repo +``` + +``` +# if kurtosis.yml is in any other directory +kurtosis run github.com/package-author/package-repo/path/to/directory-with-kurtosis.yml +``` + +Kurtosis will clone the package from GitHub, run the `main.star`, and use the `kurtosis.yml` to resolve any imports. This method always uses the version on GitHub. + +:::tip +If you want to run a non-main branch, tag or commit use the following syntax +`kurtosis run github.com/package-author/package-repo@tag-branch-commit` +::: + + +:::tip +When you're developing locally, before your package has been pushed to GitHub, the package `name` can be anything you like - e.g. `github.com/test/test`. The only thing that is important for correctly resolving local file imports is that your `read_file`/`import_module` locators also are prefixed with `github.com/test/test`. + +Once you push to GitHub, however, your package `name` will need to match the author and repo. If they don't, your package will be broken when another user depends on your package because Kurtosis will go looking for a `github.com/test/test` package that likely doesn't exist. +::: + + +[starlark-reference]: ../concepts-reference/starlark.md +[kurtosis-yml-reference]: ../concepts-reference/kurtosis-yml.md +[packages-reference]: ../concepts-reference/packages.md +[locators-reference]: ../concepts-reference/locators.md +[import-module-starlark-reference]: ../starlark-reference/import-module.md +[read-file-starlark-reference]: ../starlark-reference/read-file.md diff --git a/docs/versioned_docs/version-0.78.3/explanations/metrics-philosophy.md b/docs/versioned_docs/version-0.78.3/explanations/metrics-philosophy.md new file mode 100644 index 0000000000..f3e5abc0d7 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/explanations/metrics-philosophy.md @@ -0,0 +1,17 @@ +--- +title: Metrics Philosophy +sidebar_label: Metrics Philosophy +--- + +Kurtosis is a small startup, which means that understanding how users are using the product is vital to our success. To this end, we've built the capability for Kurtosis to send product analytics metrics. + +However, user metrics are abused heavily in today's world - data is collected without the ability to disable analytics, intentionally deanonymized, and sold to third parties. We hate it as much as we're guessing you do. + +It was therefore important to us to collect our product analytic metrics ethically. Concretely, this means that we've made our metrics: + +1. Private: we will **never** give or sell your data to third parties +1. Anonymized: your user ID is a hash, so we don't know who you are +1. Obfuscated: potentially-sensitive parameters (e.g. enclave IDs) are hashed as well +1. Opt-out: Kurtosis allows you to [easily switch off analytics](../cli-reference/analytics-disable.md), even [in CI](../guides/running-in-ci.md) + +If that sounds fair to you, we'd really appreciate you helping us get the data to make our product better. In exchange, you have our word that we'll honor the trust you've placed in us by continuing to fulfill the metrics promises above. diff --git a/docs/versioned_docs/version-0.78.3/explanations/public-and-private-ips-and-ports.md b/docs/versioned_docs/version-0.78.3/explanations/public-and-private-ips-and-ports.md new file mode 100644 index 0000000000..c07f3db2e0 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/explanations/public-and-private-ips-and-ports.md @@ -0,0 +1,44 @@ +--- +title: How Private & Public IPs & Ports Work +sidebar_label: How Private & Public IPs & Ports Work +--- + +The IP addresses and ports that come out of Kurtosis can be confusing at times. This document will explain how Kurtosis handles public and private IPs and ports. + +### Private IPs +Each Docker or Kubernetes cluster has a private IP address range, from `0.0.0.0` to `255.255.255.255`. Each container gets IP addresses from this range, and containers talk to other containers using these IP addresses. These IP addresses have nothing to do with the outside world's IP addresses, and are purely internal to the cluster. + +These IP addresses are private to Docker/Kubernetes, so you will not be able to reach them from your host machine (i.e. outside the Docker/Kubernetes cluster). For example, a container with IP address `172.0.1.3` will _not_ be reachable by `curl` from your regular command line. + +### Private Ports +Containers can listen on ports. These ports do not conflict with other containers, nor do they conflict with ports on your host machine, outside the Docker/Kubernetes cluster. For example: + +- You might be running Container A running a server listening on port `3000`, and Container B running a server listening on port `3000`. Even though the containers are using the same port, they are treated separately inside of Docker/Kubernetes and do not conflict. +- You might be running a server on your host machine on port `3000`, and a container in Docker/Kubernetes listening on port `3000`. This is also fine, because the Docker/Kubernetes ports are private to the cluster. + +These container ports are private: you will not be able to access them from your host machine. + +### Public IPs & Ports +To simplify your work, Kurtosis allows you to connect to every private port of every container. This is accomplished by binding every private port to an [ephemeral port](https://unix.stackexchange.com/questions/65475/ephemeral-port-what-is-it-and-what-does-it-do) on your host machine. These ephemeral ports are called the "public ports" of the container because they allow the container to be accessed outside the Docker/Kubernetes cluster. To view the private & public port bindings of each container in Kurtosis, run `kurtosis enclave inspect` and look for the bindings in the "Ports" column: + +``` +========================================== User Services ========================================== +GUID ID Ports Status +cl-beacon-1670597432 cl-beacon http: 4000/tcp -> 127.0.0.1:55947 RUNNING + metrics: 5054/tcp -> 127.0.0.1:55948 + tcp-discovery: 9000/tcp -> 127.0.0.1:55949 + udp-discovery: 9000/udp -> 127.0.0.1:52875 +cl-validator-1670597459 cl-validator http: 5042/tcp -> 127.0.0.1:55955 RUNNING + metrics: 5064/tcp -> 127.0.0.1:55954 +el-1670597405 el engine-rpc: 8551/tcp -> 127.0.0.1:55930 RUNNING + rpc: 8545/tcp -> 127.0.0.1:55928 + tcp-discovery: 30303/tcp -> 127.0.0.1:55927 + udp-discovery: 30303/udp -> 127.0.0.1:57433 + ws: 8546/tcp -> 127.0.0.1:55929 +forkmon-1670597469 forkmon http: 80/tcp -> 127.0.0.1:55962 RUNNING +grafana-1670597488 grafana http: 3000/tcp -> 127.0.0.1:55998 RUNNING +``` + +The IP address used to reach these containers is your localhost address, `127.0.0.1`. This is the "public IP address" of each container in the cluster. + +The combination of public IP + port _will_ allow you to connect to a container from your command line. For example, from the output above, `curl 127.0.0.1:55947` on your command line would make a request to private port `4000` on the `cl-client-0-beacon` service. diff --git a/docs/versioned_docs/version-0.78.3/explanations/reusable-environment-definitions.md b/docs/versioned_docs/version-0.78.3/explanations/reusable-environment-definitions.md new file mode 100644 index 0000000000..ffc947fded --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/explanations/reusable-environment-definitions.md @@ -0,0 +1,57 @@ +--- +title: Reusable Environment Definitions +sidebar_label: Reusable Environment Definitions +--- + +Why are reusable environment definitions hard? +---------------------------------------------- +We have many tools for defining and modifying environments: Bash/Python scripts, Ansible, Docker Compose, Helm, and Terraform. Yet, none have proven successful at reuse across [the plethora of environments in today's world][why-we-built-kurtosis]. To see why, we'll focus on the three most common environment types: local Dev, ephemeral Test in CI, and Prod. + +Environment definitions in Dev, Test, and Prod share some common requirements: + +- They must be easy to read and write +- They must be parameterizable +- They must handle data (e.g. on-disk files, database dumps, etc.) +- They should do some amount of validation + +They also have distinct differences: + +- In Dev, environment definitions must be loose and easy to modify, are often not checked into source control, and are rarely shared due to the prototyping nature. However, developers _do_ want to leverage other public environment definitions to form their local development environments quickly (e.g. to combine public definitions for Postgres and Elasticsearch to form a Postgres+Elasticsearch local development environment). +- In Test, environment definitions should be source-controlled, but are rarely shared given how specific the environment definition is to the scenario being tested. The order in which events happen is very important, so determinism and ordering of events matter. +- In Prod, environment definitions must be source-controlled. They may be shared, but can only be modified by authorized individuals. They are nearly always declarative: idempotence is very important in Prod, along with the ability to make the minimal set of changes (e.g. add just a few new services without needing to restart the entire stack). + +Why aren't the current solutions reusable? +------------------------------------------ +With this lens, we see why none of the most common solutions can be reused across Dev, Test, and Prod: + +- Scripting can be used for Dev and Test, but instantiating just a part of the environment requires extensive parameterization. Scripting is also not declarative, and requires the author to build in idempotence. Validation and data-handling is left to the author. Finally, scripts can get very complex and require specialized knowledge to understand. +- Ansible behaves like scripting with idempotence and validation on top. It is better in the Prod usecase than scripting, but doesn't ease the Dev/Test usecase of instantiating just a part of the system. +- Docker Compose is great for Dev and even for some Test, but fails in Prod for its lack of idempotence and its requirement to bring the entire stack down and up each time. It has no validation, little parameterizability, and Docker Compose files cannot be plugged together. +- Helm is excellent for the Prod usecase for its idempotence, parameterizability, and emphasis on sharing, but Helm charts are complex and difficult to compose or decompose. Like Docker Compose, data-handling is via volumes only. The only execution mode is declarative, so Helm only fills the Test usecase when mixed with a procedural language. +- Terraform, like Helm, hits the Prod usecase very well. However, like Helm, Terraform can only be executed in declarative mode; Test usecases with Terraform therefore need a procedural langauge to sequence events. + +What does a reusable solution look like? +---------------------------------------- +Kurtosis believes that any environment definition that aims to be reusable across Dev, Test, and Prod must have six properties: + +1. **Composability:** The user should be able to combine two or more environment definitions to form a new one (e.g. Postgres + Elasticsearch). + - In Dev, Test, and Prod, this allows modularization of definitions +1. **Decomposability:** The user should be able to take an existing environment definition and strip out the parts they're not interested in to form a smaller environment definition (e.g. take the large Prod environment definition and instantiate only a small portion of it). + - In Dev, Test, and Prod, this consumers of third-party definitions can select only the sub-components of the definition that are of interest + - In Dev, developers can select just the parts of their Prod system that they're working on +1. **Safety:** The user should be able to know whether the environment definition will work before instantiating it (analogous to type-checking - e.g. verifying all the ports match up, all the IP addresses match up, all the container images are available, etc.). + - In Dev, Test, and Prod, this left-shifts classes of errors from runtime to validation time resulting in a tighter feedback loop +1. **Parameterizability:** An environment definition should be able to accept parameters (e.g. define the desired number of Elasticsearch nodes). + - In Dev, Test, and Prod, parameterizability is essential to keeping environment definitions DRY +1. **Pluggability of Data:** The data used across Dev, Test, and Prod varies so widely that the user should be able to configure which data to use. + - In Dev, Test, and Prod, this allows for a definition to be reusable even when the data isn't the same +1. **Portability:** An environment definition author should be able to share their work and be confident that it can be consumed. + - In Dev, Test, and Prod, this allows for reuse of definitions + - In Test, test cases that failed on a CI machine can be reproduced on a developer's machine + +Kurtosis environment definitions (written in [Starlark][starlark-reference]) are designed with these six properties in mind. + + + +[starlark-reference]: ../concepts-reference/starlark.md +[why-we-built-kurtosis]: ./why-we-built-kurtosis.md diff --git a/docs/versioned_docs/version-0.78.3/explanations/why-kurtosis-starlark.md b/docs/versioned_docs/version-0.78.3/explanations/why-kurtosis-starlark.md new file mode 100644 index 0000000000..5ea91aff58 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/explanations/why-kurtosis-starlark.md @@ -0,0 +1,56 @@ +--- +title: Why Kurtosis Starlark? +sidebar_label: Why Kurtosis Starlark? +--- + +Background +---------- +Distributed systems are very complex, and made up of many components. This means there are many, many instantiation, configuration, and manipulation actions possible with a distributed system. + +Kurtosis [aims to provide a single solution across Dev, Test, and Prod][what-we-built-kurtosis]. We therefore needed a consistent way to represent all the various ways to manipulate a distributed system across Dev, Test, and Prod. + +Additionally, we believe that [anything intended to work across Dev, Test, and Prod must have certain properties][reusable-environment-definitions]. We therefore needed something that would fulfill these properties. + +With these constraints in mind, we went searching for a way to represent distributed system manipulations. + +Attempt 1: Declarative Languages +-------------------------------- +We first looked at declarative languages like YAML, Jsonnet, Dhall, and CUE. + +To use them, we'd need to write our own DSL (and accompanying parser) on top of the language to do what we needed. We knew that our "parameterizability" requirement meant users would need conditional/looping logic, but we were unhappy with how difficult parameters, conditionals, and loops were in these languages. + +The conditionals and parameters in the CircleCI YAML DSL seem to be a cautionary tale of starting with a declarative language and adding logic constructs later. [Others](https://github.com/tektoncd/experimental/issues/185#issuecomment-535338943) seemed [to agree](https://solutionspace.blog/2021/12/04/every-simple-language-will-eventually-end-up-turing-complete/): when dealing with configuration, start with a Turing-complete language because you will eventually need it. + +Attempt 2: General-Purpose Languages +------------------------------------ +We next looked at letting users declare environment definitions in their preferred general-purpose language, like Pulumi. This would require a large effort from our side to support many different languages, but we would do it if it was the right choice. + +However, we ultimately rejected this option. We found that general-purpose programming languages: + +1. **Are TOO powerful:** the user could inadvertently write code that was nondeterministic and hard to debug. +1. **Are a security risk:** we'd need to run user code to construct an environment, and running arbitrary user code is a security risk in one general-purpose language let alone in various. +1. **Aren't friendly for the author:** to make an environment definition usable by any consumer, the author would have to bundle their definition inside a container. Containerization makes development more painful - the user must know about Dockerfiles, their best practices, and how to build them locally - and requires a CI job to publish the container images up to Dockerhub. +1. **Aren't friendly for the environment definition consumer:** a developer investigating a third-party environment definition could easily be faced with a language they're not familiar with. Worse, general-purpose languages have many patterns for accomplishing the same task, so the consumer would need to understand the class/object/function architecture. + +Attempt 3: Starlark +------------------- +When we discovered Starlark, the fit was obvious. Starlark: + +- Is syntactically valid Python, which most developers are familiar with (and Python syntax highlighting Just Works) +- [Intentionally removes many Python features][starlark-differences-with-python], to make Starlark easier to read and understand +- Has [several properties that are very useful for Kurtosis](https://github.com/bazelbuild/starlark#design-principles), thanks to Starlark's origin as a build system configuration language +- [Has been around in Google since at least 2017](https://blog.bazel.build/2017/03/21/design-of-skylark.html), meaning it's well-vetted +- Is used for both Google and Facebook's build system, meaning it isn't going away any time soon +- [Is used by several other companies beyond Google and Facebook](https://github.com/bazelbuild/starlark/blob/master/users.md#users) + + +Conclusion +---------- +So far, both our users and our team have been very happy with our decision to go with Starlark. If you've never used Starlark before, [the quickstart][quickstart] will be a good introduction. + + +[what-we-built-kurtosis]: ./why-we-built-kurtosis.md +[reusable-environment-definitions]: ./reusable-environment-definitions.md +[starlark-differences-with-python]: https://bazel.build/rules/language#differences_with_python + +[quickstart]: ../quickstart.md diff --git a/docs/versioned_docs/version-0.78.3/explanations/why-multi-phase-runs.md b/docs/versioned_docs/version-0.78.3/explanations/why-multi-phase-runs.md new file mode 100644 index 0000000000..1243e22367 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/explanations/why-multi-phase-runs.md @@ -0,0 +1,40 @@ +--- +title: Why Multi-Phase Runs? +sidebar_label: Why Multi-Phase Runs? +--- + +Kurtosis runs its [Starlark environment definitions][starlark-reference] in [multiple phases][multi-phase-runs-reference]. + +This can create pitfalls for users not accustomed to the multi-phase idea. For example, the following code has a bug: + +```python +service = add_service( + "my-service", + config = struct( + image = "hello-world", + ) +) + +if service.ip_address == "1.2.3.4": + print("IP address matched") +``` + +The `if` statement will never evaluate to true because `service.ip_address` is in fact a [future reference string][future-references-reference] that will never equal `1.2.3.4`. + +We chose this multi-phase approach despite its complexity because it provides significant advantages over traditional scripting: + +- Kurtosis can show the user the plan to execute before any changes are made. +- Kurtosis can validate the entire plan, saving the user from errors like container image typos, service name typos, and port typos before any changes are made. +- Kurtosis can optimize performance (e.g. downloading all container images before anything is executed, which is especially important on timing-sensitive tests). + +In the future, the multi-phase approach will also: + +- Give the user the power to have new services defined in the plan depend on existing services already running in the enclave. +- Give the user the power to remove and edit parts of the plan they don't like (useful when consuming third-party definitions). +- Allow users to "time-travel" through the plan, discovering what the environment will look like at any point during plan execution. +- Permit compiling a Kurtosis plan down to an idempotent, declarative format (e.g. Helm, Terraform, or Docker Compose). + + +[starlark-reference]: ../concepts-reference/starlark.md +[multi-phase-runs-reference]: ../concepts-reference/multi-phase-runs.md +[future-references-reference]: ../concepts-reference/future-references.md diff --git a/docs/versioned_docs/version-0.78.3/explanations/why-we-built-kurtosis.md b/docs/versioned_docs/version-0.78.3/explanations/why-we-built-kurtosis.md new file mode 100644 index 0000000000..eb46d857e9 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/explanations/why-we-built-kurtosis.md @@ -0,0 +1,26 @@ +--- +title: Why We Built Kurtosis +sidebar_label: Why We Built Kurtosis +sidebar_position: 1 +--- + +Kurtosis is a distributed application development platform. Its goal is to make building a distributed application as easy as developing a single-server app. + +Our philosophy is that the distributed nature of modern software means that modern software development now happens at the environment level. Spinning up a single service container in isolation is difficult because it has implicit dependencies on other resources: services, volume data, secrets, certificates, and network rules. Therefore, the environment - not the container - is the fundamental unit of modern software. + +This fact becomes apparent when we look at the software development lifecycle. Developers used to write code on their machine and ship a large binary to a few long-lived, difficult-to-maintain environments like Prod or Staging. Now, the decline of on-prem hardware, rise of containerization, and availability of flexible cloud compute enable the many environments of today: Prod, pre-Prod, Staging, Dev, and even ephemeral preview, CI test, and local dev. + +The problem is that our tools are woefully outdated. The term "DevOps" was coined during the Agile revolution in the early 2000's. It signified making Dev responsible for end-to-end software delivery, rather than building software and throwing it over the wall to Ops to run. The idea was to shorten feedback loops, and it worked. However, our systems have become so complex that companies are now hiring "DevOps engineers" to manage the Docker, AWS, Terraform, and Kubernetes underlying all modern software. Though we call them "DevOps engineers", we are recreating Ops and separating Dev and Ops once more. + +Docker and Kubernetes are each great at serving developers in different parts of the development cycle: Docker for development/testing, Kubernetes for production. However, the separation between the two entails different distributed app definitions, and different tooling. In dev/test, this means Docker Compose and Docker observability tooling. In production, this means Helm definitions and manually-configured observability tools like Istio, Datadog, or Honeycomb. + +Kurtosis aims to be at one level of abstraction higher. + +![Why Kurtosis](/img/home/kurtosis-utility.png) + +In our vision, a developer should have a single platform for prototyping, testing, debugging, deploying to Prod, and observing the live system. Our goal with Kurtosis is to bring DevOps back. + +To read more about our beliefs on reusable environments, [go here][reusable-environment-definitions]. To get started using Kurtosis, see [the quickstart][quickstart]. + +[reusable-environment-definitions]: ./reusable-environment-definitions.md +[quickstart]: ../quickstart.md diff --git a/docs/versioned_docs/version-0.78.3/guides/adding-command-line-completion.md b/docs/versioned_docs/version-0.78.3/guides/adding-command-line-completion.md new file mode 100644 index 0000000000..4a28979888 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/adding-command-line-completion.md @@ -0,0 +1,141 @@ +--- +title: Adding Command-Line Completion +sidebar_label: Adding Command-Line Completion +sidebar_position: 4 +--- + + + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +[The Kurtosis CLI](../cli-reference/index.md) supports command-line completion for `bash`, `zsh`, and `fish`. With completion installed, you will be able to: + +- Complete subcommands (e.g. typing `kurtosis` and pressing TAB will suggest subcommands) +- Complete dynamic arguments (e.g. typing `kurtosis enclave inspect` and pressing TAB will list the names of existing enclaves if any) + +The process for installing completion is specific to each shell: + + + + +1. Print your Bash version: + ```bash + bash --version + ``` +1. If your Bash version is less than 4.1, upgrade it: + * On Mac, upgrade Mac via Homebrew: + ```bash + brew install bash + ``` + * On Linux, [upgrade it via the package manager for your distro](https://www.configserverfirewall.com/linux-tutorials/update-bash-linux/) +1. Check if you have [bash-completion](https://github.com/scop/bash-completion) installed: + ```bash + type _init_completion + ``` +1. If you get an error like `-bash: type: _init_completion: not found`, install Bash completion: + * On Mac: + 1. Install the completion library: + ```bash + brew install bash-completion@2 + ``` + 1. Add the following to your `~/.bash_profile`: + ```bash + export BREW_PREFIX="$(brew --prefix)" + [[ -r "${BREW_PREFIX}/etc/profile.d/bash_completion.sh" ]] && source "${BREW_PREFIX}/etc/profile.d/bash_completion.sh" + ``` + 1. Close and re-open your terminal window to reload your shell. + 1. Verify that you now have the completion installed: + ```bash + type _init_completion + ``` + * On Linux, install it using the package manager for your distro using [these installation instructions](https://github.com/scop/bash-completion#installation) +1. Skip this step if you are installing using Homebrew and have `bash-completion@2` installed. Otherwise, proceed to source the output of `kurtosis completion bash` in your Bash config file: + * On Mac, add the following to your `~/.bash_profile` file: + ```bash + # Add Kurtosis command-line completion + source <(kurtosis completion bash) + ``` + * On Linux, add the following to your `~/.bashrc` file: + ```bash + # Add Kurtosis command-line completion + source <(kurtosis completion bash) + ``` +1. If you have an alias set up for Kurtosis, add completion for that as well (we'll assume the alias `kt` in the examples below): + * On Mac, add the following to your `~/.bash_profile` file: + ```bash + # Add command-line completion to Kurtosis alias + complete -F __start_kurtosis kt + ``` + * On Linux, add the following to your `~/.bashrc` file: + ```bash + # Add command-line completion to Kurtosis alias + complete -F __start_kurtosis kt + ``` +1. Close and re-open your terminal window to reload your shell and apply the changes. + + + + + +1. Add the following to your `~/.zshrc` file: + ```zsh + # Add Kurtosis command-line completion + source <(kurtosis completion zsh) + compdef _kurtosis kurtosis + ``` +1. If you have an alias set up for Kurtosis, add the following to your `~/.zshrc` file (we'll assume the alias `kt` in this example): + ```zsh + # Add command-line completion to Kurtosis alias + compdef __start_kurtosis kt + ``` +1. Close and re-open your terminal window to reload your shell and apply the changes. +1. If you get an error like `complete:13: command not found: compdef`, add the following to the top of your `~/.zshrc` and close and re-open your terminal window to reload your shell: + ```zsh + autoload -Uz compinit + compinit + ``` + + + + +1. Add the following to your `~/.config/fish/config.fish` file: + ```fish + # Add Kurtosis command-line completion + kurtosis completion fish | source + ``` +1. Close and re-open your terminal window to reload your shell and apply the changes. + + + + +If necessary, tab completion can be installed manually in two steps as follows, by first generating the +tab completion code (specific to the shell) and then sourcing that code into the shell. + +1. The code needed to enable tab completion can be generated by the `kurtosis` cli by + running `kurtosis completion ` command, e.g. for `bash`: + ``` + kurtosis completion bash + ``` + +1. `source`ing the output of the command will enable command-line completion, and adding the `source` + command to your shell config file will enable it across shell instances. + ``` + # Add Kurtosis command-line completion to your shell config file + source <(kurtosis completion bash) + ``` + + + diff --git a/docs/versioned_docs/version-0.78.3/guides/how-to-local-eth-testnet.md b/docs/versioned_docs/version-0.78.3/guides/how-to-local-eth-testnet.md new file mode 100644 index 0000000000..2fcc5d1dee --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/how-to-local-eth-testnet.md @@ -0,0 +1,332 @@ +--- +title: How to set up a local Ethereum testnet +sidebar_label: Setting up local Ethereum testnet +slug: /how-to-local-eth-testnet +toc_max_heading_level: 2 +sidebar_position: 6 +--- + +## Introduction + +This guide walks you through the process of instantiating a configurable local Ethereum testnet, deploying a smart contract to it, and using the testnet to run tests against your dApp. This guide is designed for dApp developers who want to develop and test their dApps locally against different network configurations before deploying to a live testnet or the mainnet. + +In this guide, you will: +* Instantiate a local Ethereum testnet with the [`eth-network-package`](https://github.com/kurtosis-tech/eth-network-package) using [Kurtosis](https://www.kurtosis.com/), +* Connect your Hardhat dApp development environment to the local testnet to compile, deploy, and test a dApp, and +* Configure the local testnet, including parameters like number of nodes and specific EL/CL client pairings, to enable development and testing workflows against various network configurations. + +### What is Kurtosis? + +[Kurtosis](https://www.kurtosis.com/) is a composable build system designed for configuring multi-container test environments. It specifically enables developers to create reproducible environments that require dynamic setup logic, such as blockchain testnets. + +In this guide, the Kurtosis eth-network-package spins up a local Ethereum testnet with support for the [`geth`](https://geth.ethereum.org/) Execution Layer (EL) client, as well as [`teku`](https://consensys.net/knowledge-base/ethereum-2/teku/), [`lighthouse`](https://lighthouse.sigmaprime.io/), and [`lodestar`](https://lodestar.chainsafe.io/) Consensus Layer (CL) clients. This package serves as a configurable and composable alternative to networks in frameworks like Hardhat Network, Ganache, and Anvil. Kurtosis offers developers greater control and flexibility over the testnets they use, which is a major reason why the [Ethereum Foundation used Kurtosis to test the Merge](https://www.kurtosis.com/blog/testing-the-ethereum-merge) and continues to use it for testing network upgrades. + +## Setting up Kurtosis + +Before you proceed, make sure you have: +* [Installed and started the Docker engine](https://docs.kurtosis.com/next/install#i-install--start-docker) on your local machine +* [Installed the Kurtosis CLI](https://docs.kurtosis.com/next/install#ii-install-the-cli) (or upgraded it to the latest release, if you already have the CLI installed) +* Installed[Node.js](https://nodejs.org/en), [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable), and [npx](https://www.npmjs.com/package/npx) (for your dApp environment) + +## Instantiating a local Ethereum testnet + +To spin up a local Ethereum testnet, run: +```bash +kurtosis --enclave local-eth-testnet run github.com/kurtosis-tech/eth-network-package +``` +:::info +This command names your network: "local-eth-testnet” using the `--enclave` flag. +::: + +Kurtosis will print the steps its taking under the hood as it works to interpret, validate, and then execute the instructions. At the end, you should see an output that resembles the following: +```bash +INFO[2023-04-04T18:09:44-04:00] ====================================================== +INFO[2023-04-04T18:09:44-04:00] || Created enclave: local-eth-testnet || +INFO[2023-04-04T18:09:44-04:00] ====================================================== +Name: local-eth-testnet +UUID: 39372d756ae8 +Status: RUNNING +Creation Time: Tue, 04 Apr 2023 18:09:03 EDT + +========================================= Files Artifacts ========================================= +UUID Name +d4085a064230 cl-genesis-data +1c62cb792e4c el-genesis-data +bd60489b73a7 genesis-generation-config-cl +b2e593fe5228 genesis-generation-config-el +d552a54acf78 geth-prefunded-keys +5f7e661eb838 prysm-password +054e7338bb59 validator-keystore-0 + +========================================== User Services ========================================== +UUID Name Ports Status +e20f129ee0c5 cl-client-0-beacon http: 4000/tcp -> RUNNING + metrics: 5054/tcp -> + tcp-discovery: 9000/tcp -> 127.0.0.1:54263 + udp-discovery: 9000/udp -> 127.0.0.1:60470 +a8b6c926cdb4 cl-client-0-validator http: 5042/tcp -> 127.0.0.1:54267 RUNNING + metrics: 5064/tcp -> +d7b802f623e8 el-client-0 engine-rpc: 8551/tcp -> 127.0.0.1:54253 RUNNING + rpc: 8545/tcp -> 127.0.0.1:54251 + tcp-discovery: 30303/tcp -> 127.0.0.1:54254 + udp-discovery: 30303/udp -> 127.0.0.1:53834 + ws: 8546/tcp -> 127.0.0.1:54252 +514a829c0a84 prelaunch-data-generator-1680646157905431468 STOPPED +62bd62d0aa7a prelaunch-data-generator-1680646157915424301 STOPPED +05e9619e0e90 prelaunch-data-generator-1680646157922872635 STOPPED + +``` + +Congratulations! You used Kurtosis to instantiate a local Ethereum testnet, with a CL (`lighthouse`) and EL client (`geth`), over Docker. + +### Review + +In this section, you executed a command that directed Kurtosis to use the [`eth-network-package` hosted remotely on GitHub](https://github.com/kurtosis-tech/eth-network-package) to spin up a local Ethereum testnet within a Kurtosis [Enclave](https://docs.kurtosis.com/concepts-reference/enclaves/). Inside your enclave, you will find both "file artifacts" and "user services". + +The [File Artifacts](https://docs.kurtosis.com/concepts-reference/files-artifacts/) in your enclave include all the data generated and utilized to bootstrap the EL and CL clients. The data was created using the `prelaunch-data-generator` service built from this [Docker image](https://github.com/ethpandaops/ethereum-genesis-generator) + +User services display all the containerized services operating in your enclave. You will notice that a single node, featuring both an EL client and a CL client, has been created. + +## Connect your dApp development environment to the local Ethereum testnet + +### Setup the dApp development environment + +Now that you have a running local testnet, you can connect your dApp development environment to use your local testnet. The Hardhat framework will be used in this guide to deploy a blackjack dApp to your local testnet. + +To set up your dApp development environment, clone the repository that contains our sample dApp and install its dependencies, run: +```bash +git clone https://github.com/kurtosis-tech/awesome-kurtosis.git && cd awesome-kurtosis/smart-contract-example && yarn +``` + +The [smart-contract-example](https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/smart-contract-example) folder used here contains the typical setup for a dApp developer using the [Hardhat](https://hardhat.org/) framework: +* [`contracts/`](https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/smart-contract-example/contracts) contains a few simple smart contracts for a Blackjack dApp +* [`scripts/`](https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/smart-contract-example/scripts) contains a script to deploy a token contract to your local Ethereum network +* [`test/`](https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/smart-contract-example/test) contains a simple .js test for your token contract to confirm each player in our Blackjack dApp has 1000 minted for them +* []`hardhat.config.ts`](https://github.com/kurtosis-tech/awesome-kurtosis/blob/main/smart-contract-example/hardhat.config.ts) configures your Hardhat setup + +### Configure Hardhat to use the local testnet + +WWith your dApp development environment set up, you will now connect Hardhat to use the local Ethereum testnet generated using Kurtosis. To accomplish this, replace `<$YOUR_PORT>` in the `localnet` struct in your `hardhat.config.ts` config file with the port of the rpc uri output from any `el-client-` service. In this sample case, the port would be `64248`. Your port will be different. + +Example in `hardhat.config.ts`: +```typescript +localnet: { +url: 'http://127.0.0.1:<$YOUR_PORT>',// TODO: REPLACE $YOUR_PORT WITH THE PORT OF A NODE URI PRODUCED BY THE ETH NETWORK KURTOSIS PACKAGE + +// These are private keys associated with prefunded test accounts created by the eth-network-package +// +accounts: [ + "ef5177cd0b6b21c87db5a0bf35d4084a8a57a9d6a064f86d51ac85f2b873a4e2", + "48fcc39ae27a0e8bf0274021ae6ebd8fe4a0e12623d61464c498900b28feb567", + "7988b3a148716ff800414935b305436493e1f25237a2a03e5eebc343735e2f31", + "b3c409b6b0b3aa5e65ab2dc1930534608239a478106acf6f3d9178e9f9b00b35", + "df9bb6de5d3dc59595bcaa676397d837ff49441d211878c024eabda2cd067c9f", + "7da08f856b5956d40a72968f93396f6acff17193f013e8053f6fbb6c08c194d6", + ], +}, +``` +Once you save your file, your Hardhat dApp development environment is now connected to your local Ethereum testnet! You can verify that your testnet is working by running: +```bash +npx hardhat balances --network localnet +``` +The output should look something like this: +```bash +0x878705ba3f8Bc32FCf7F4CAa1A35E72AF65CF766 has balance 10000000000000000000000000 +0x4E9A3d9D1cd2A2b2371b8b3F489aE72259886f1A has balance 10000000000000000000000000 +0xdF8466f277964Bb7a0FFD819403302C34DCD530A has balance 10000000000000000000000000 +0x5c613e39Fc0Ad91AfDA24587e6f52192d75FBA50 has balance 10000000000000000000000000 +0x375ae6107f8cC4cF34842B71C6F746a362Ad8EAc has balance 10000000000000000000000000 +0x1F6298457C5d76270325B724Da5d1953923a6B88 has balance 10000000000000000000000000 +``` + +This confirms that Hardhat is using your local testnet and detects the pre-funded accounts created by the `eth-network-package`. + +### Deploy and test your dApp locally +With the dApp development environment fully connected to the local Ethereum testnet, you can now run development and testing workflows against your dApp using the local testnet. + +To compile and deploy the `ChipToken.sol` smart contract for local prototyping and development, run: +```bash +npx hardhat compile +npx hardhat run scripts/deploy.ts --network localnet +``` +The output should look something like: +```bash +ChipToken deployed to: 0xAb2A01BC351770D09611Ac80f1DE076D56E0487d +``` + +Now try running the `simple.js` test against your local dApp to confirm each player in our Blackjack dApp has 1000 minted for them: + +The output should look something like this: + +```bash +npx hardhat test --network localnet +``` +The output should look something like this: +```bash +ChipToken + mint + ✔ should mint 1000 chips for PLAYER ONE + + 1 passing (654ms) +``` + +### Review +At this point, you’ve now set up a dApp development environment, connected it to a local Ethereum network created by Kurtosis, and have compiled, deployed, and ran a simple test against your dApp. + +Now let’s explore how you can configure the underlying network for testing our dApps under varying network configurations. + +## Configuring the local Ethereum testnet + +### Changing the client configurations and number of nodes + +Your local Ethereum testnet can be configured to use different EL and CL client pairs, as well as a varying number of nodes, depending on the scenario and specific network configuration you want to develop or test. This means that, once set up, you can spin up a customized local testnet and use it to run the same workflows (deployment, tests, etc.) under various network configurations to ensure everything works as expected. To learn more about the other parameters you can modify, visit this link. + +Give it a try! You can pass various configuration options to the `eth-network-package` via a JSON file. This network params JSON file provides the specific configurations that Kurtosis will use to set up the local Ethereum network. + +Take the default configuration file and edit it to spin up two nodes with different EL/CL pairs: +* Node 1 with `geth`/`lighthouse` +* Node 2 with `geth`/`lodestar` +* Node 3 with `geth`/`teku` + +This configuration creates a heterogeneous network of Ethereum node implementations for testing your dApp. Your configuration file should now look like: +``` +{ + "participants":[{ + "el_client_type": "geth", + "el_client_image": "", + "el_client_log_level": "", + "cl_client_type": "lighthouse", + "cl_client_image": "", + "cl_client_log_level": "", + "beacon_extra_params": [], + "el_extra_params": [], + "validator_extra_params": [], + "builder_network_params": null + }, + { + "el_client_type": "geth", + "el_client_image": "", + "el_client_log_level": "", + "cl_client_type": "lodestar", + "cl_client_image": "", + "cl_client_log_level": "", + "beacon_extra_params": [], + "el_extra_params": [], + "validator_extra_params": [], + "builder_network_params": null + }, + { + "el_client_type": "geth", + "el_client_image": "", + "el_client_log_level": "", + "cl_client_type": "teku", + "cl_client_image": "", + "cl_client_log_level": "", + "beacon_extra_params": [], + "el_extra_params": [], + "validator_extra_params": [], + "builder_network_params": null + }], + "network_params":{ + "preregistered_validator_keys_mnemonic": "giant issue aisle success illegal bike spike question tent bar rely arctic volcano long crawl hungry vocal artwork sniff fantasy very lucky have athlete", + "num_validator_keys_per_node": 64, + "network_id": "3151908", + "deposit_contract_address": "0x4242424242424242424242424242424242424242", + "seconds_per_slot": 12, + "genesis_delay": 120, + "capella_fork_epoch": 5 + } +} +``` +Each `participants` struct maps to a node in the network, so 3 `participants` structs will tell Kurtosis to spin up 3 nodes in your network. Each `participants` struct will allow you to specify the EL and CL pair used for that specific node. + +The `network_params` struct configures the network settings that are used to create the genesis files for each node as well as other settings like the seconds per slot of the network. + +Save your edited params file in any directory you wish (in the example below, it is saved to the desktop) and then use it to run your Kurtosis package by running: + +```bash +kurtosis clean -a && kurtosis run --enclave local-eth-testnet github.com/kurtosis-tech/eth-network-package "$(cat ~/eth-network-params.json)" +``` +:::TIP +Note that the `kurtosis clean -a` command is used here to instruct Kurtosis to destroy the old testnet and its contents before starting a new one up. +::: +Again, Kurtosis will work for a bit and print out the individual steps that are taking place. Eventually, the output should look something like: +```bash +Starlark code successfully run. No output was returned. +INFO[2023-04-07T11:43:16-04:00] ========================================================== +INFO[2023-04-07T11:43:16-04:00] || Created enclave: local-eth-testnet || +INFO[2023-04-07T11:43:16-04:00] ========================================================== +Name: local-eth-testnet +UUID: bef8c192008e +Status: RUNNING +Creation Time: Fri, 07 Apr 2023 11:41:58 EDT + +========================================= Files Artifacts ========================================= +UUID Name +cc495a8e364a cl-genesis-data +7033fcdb5471 el-genesis-data +a3aef43fc738 genesis-generation-config-cl +8e968005fc9d genesis-generation-config-el +3182cca9d3cd geth-prefunded-keys +8421166e234f prysm-password +d9e6e8d44d99 validator-keystore-0 +23f5ba517394 validator-keystore-1 +4d28dea40b5c validator-keystore-2 + +========================================== User Services ========================================== +UUID Name Ports Status +485e6fde55ae cl-client-0-beacon http: 4000/tcp -> http://127.0.0.1:65010 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:65011 + tcp-discovery: 9000/tcp -> 127.0.0.1:65012 + udp-discovery: 9000/udp -> 127.0.0.1:54455 +73739bd158b2 cl-client-0-validator http: 5042/tcp -> 127.0.0.1:65016 RUNNING + metrics: 5064/tcp -> http://127.0.0.1:65017 +1b0a233cd011 cl-client-1-beacon http: 4000/tcp -> 127.0.0.1:65021 RUNNING + metrics: 8008/tcp -> 127.0.0.1:65023 + tcp-discovery: 9000/tcp -> 127.0.0.1:65024 + udp-discovery: 9000/udp -> 127.0.0.1:56031 + validator-metrics: 5064/tcp -> 127.0.0.1:65022 +949b8220cd53 cl-client-1-validator http: 4000/tcp -> 127.0.0.1:65028 RUNNING + metrics: 8008/tcp -> 127.0.0.1:65030 + tcp-discovery: 9000/tcp -> 127.0.0.1:65031 + udp-discovery: 9000/udp -> 127.0.0.1:60784 + validator-metrics: 5064/tcp -> 127.0.0.1:65029 +c34417bea5fa cl-client-2 http: 4000/tcp -> 127.0.0.1:65037 RUNNING + metrics: 8008/tcp -> 127.0.0.1:65035 + tcp-discovery: 9000/tcp -> 127.0.0.1:65036 + udp-discovery: 9000/udp -> 127.0.0.1:63581 +e19738e6329d el-client-0 engine-rpc: 8551/tcp -> 127.0.0.1:64986 RUNNING + rpc: 8545/tcp -> 127.0.0.1:64988 + tcp-discovery: 30303/tcp -> 127.0.0.1:64987 + udp-discovery: 30303/udp -> 127.0.0.1:55706 + ws: 8546/tcp -> 127.0.0.1:64989 +e904687449d9 el-client-1 engine-rpc: 8551/tcp -> 127.0.0.1:64993 RUNNING + rpc: 8545/tcp -> 127.0.0.1:64995 + tcp-discovery: 30303/tcp -> 127.0.0.1:64994 + udp-discovery: 30303/udp -> 127.0.0.1:58096 + ws: 8546/tcp -> 127.0.0.1:64996 +ad6f401126fa el-client-2 engine-rpc: 8551/tcp -> 127.0.0.1:65003 RUNNING + rpc: 8545/tcp -> 127.0.0.1:65001 + tcp-discovery: 30303/tcp -> 127.0.0.1:65000 + udp-discovery: 30303/udp -> 127.0.0.1:57269 + ws: 8546/tcp -> 127.0.0.1:65002 +12d04a9dbb69 prelaunch-data-generator-1680882122181135513 STOPPED +5b45f9c0504b prelaunch-data-generator-1680882122192182847 STOPPED +3d4aaa75e218 prelaunch-data-generator-1680882122201668972 STOPPED +``` +Congratulations! You’ve successfully configured your local testnet to have 3 nodes instead of 1. To run the same workflows you did before against your dApp (deploy & test), perform the same operations we did before by replacing the `<$YOUR_PORT>` in the `localnet` struct in your `hardhat.config.ts` config file with the port of the rpc uri output from any `el-client-` service in your new, 3-node local testnet. + + +## Conclusion + +And that's it! To recap this short guide, you: +* Created a local Ethereum testnet over Docker using Kurtosis +* Connected your local dApp development environment to the local Ethereum network +* Deployed a dApp and ran a simple test against it on the local Ethereum network +* Configured the underlying Ethereum network to have 3 nodes + +We’d love to hear from you on what went well for you, what could be improved, or to answer any of your questions. Don’t hesitate to reach out via [Github](https://github.com/kurtosis-tech/kurtosis/issues/new/choose) or [email us](mailto:feedback@kurtosistech.com)! + +### Other examples and guides +We encourage you to check out our [quickstart](https://docs.kurtosis.com/quickstart) (where you’ll build a Postgres database and API on top) and our other examples in our [awesome-kurtosis repository](https://github.com/kurtosis-tech/awesome-kurtosis) where you’ll find some great examples, including packages for: +* [Spinning up the same local Ethereum testnet](https://github.com/kurtosis-tech/eth2-package), but with additional services connected such as a transaction spammer (to simulate transactions), a fork monitor, and a connected Grafana and Prometheus instance diff --git a/docs/versioned_docs/version-0.78.3/guides/how-to-parameterize-cassandra.md b/docs/versioned_docs/version-0.78.3/guides/how-to-parameterize-cassandra.md new file mode 100644 index 0000000000..e94721dd29 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/how-to-parameterize-cassandra.md @@ -0,0 +1,397 @@ +--- +title: How to set up an n-node Cassandra environment +sidebar_label: Setting up an n-node Cassandra cluster +slug: /how-to-parameterize-cassandra +toc_max_heading_level: 2 +sidebar_position: 5 +--- + +Introduction +------------ +In this guide, you will set up a 3-node Cassandra cluster in Docker and parameterize the environment definition so it can easily be modified for use in different tests that require an _n_-node Cassandra cluster. Then we will show you how to run remotely hosted packages authored by others, and go through how to package and publish our work to Github for others to use as well. + +Specifically, you're going to configure your test environments with a way that allows you to both: +1. Parameterize the environment so another developer using the environment can specify how many nodes they’d like for their system to have, and +2. Make the environment definition composable so that your environments can be included in tests with other services for different scenarios & use cases. + +**Without Kurtosis** + +One way to accomplish the above would be to write shell scripts over docker, or over binaries running on bare metal. In this case, we’d have to build these capabilities into our scripts and handle cross-system issues (laptop vs CI) ourselves. + +**With Kurtosis** + +In this guide, we’re going to use Kurtosis. Kurtosis has composability, parameterizability, and portability built into its environment definition system and runtime. With Kurtosis we can ensure that these environments are runnable on your own laptop or in your favorite CI provider. + +Setup +----- +Before you proceed, make sure you have: +* [Installed and started the Docker engine on your local machine][starting-docker] +* [Installed the Kurtosis CLI (or upgraded it to the latest release, if you already have the CLI installed)][installing-the-cli] + +:::tip Use the Starlark VS Code Extension +Feel free to use the [official Kurtosis Starlark VS Code extension][vscode-plugin] when writing Starlark with VSCode for features like syntax highlighting, method signature suggestions, hover preview for functions, and auto-completion for Kurtosis custom types. +::: + +Instantiate a 3-node Cassandra cluster +-------------------------------------- +First, create and `cd` into a directory to hold the project you'll be working on: + +```bash +mkdir kurtosis-cass-cluster && cd kurtosis-cass-cluster +``` + +Next, create a [Starlark][starlark] file called `main.star` inside your new directory with the following contents: + +```python +DEFAULT_NUMBER_OF_NODES = 3 +CASSANDRA_NODE_PREFIX= "cassandra-node-" +CASSANDRA_NODE_IMAGE = "cassandra:4.0" + + +CLUSTER_COMM_PORT_ID = "cluster" +CLUSTER_COM_PORT_NUMBER = 7000 +CLUSTER_COM_PORT_PROTOCOL = "TCP" + + +CLIENT_COMM_PORT_ID = "client" +CLIENT_COM_PORT_NUMBER = 9042 +CLIENT_COM_PORT_PROTOCOL = "TCP" + + +FIRST_NODE_INDEX = 0 + +def run(plan, args): + num_nodes = DEFAULT_NUMBER_OF_NODES + + # Simple check to verify that we have at least 1 node in our cluster + if num_nodes == 0: + fail("Need at least 1 node to Start Cassandra cluster got 0") + + # Iteratively add each node to the cluster, with the given names and serviceConfig specified below + for node in range(0, num_nodes): + node_name = get_service_name(node) + config = get_service_config(num_nodes) + plan.add_service(name = node_name, config = config) + + node_tool_check = "nodetool status | grep UN | wc -l | tr -d '\n'" + + check_nodes_are_up = ExecRecipe( + command = ["/bin/sh", "-c", node_tool_check], + ) + + # Wait for the nodes to be up and ready to establish connections and receive traffic + plan.wait( + service_name = get_first_node_name(), + recipe = check_nodes_are_up, + field = "output", + assertion = "==", + target_value = str(num_nodes), + timeout = "8m", + ) + + return {"node_names": [get_service_name(x) for x in range(num_nodes)]} + +def get_service_name(node_idx): + return CASSANDRA_NODE_PREFIX + str(node_idx) + +def get_service_config(num_nodes): + seeds = ["cassandra-node-"+str(x) for x in range(0, num_nodes)] + return ServiceConfig( + image = CASSANDRA_NODE_IMAGE, + ports = { + CLUSTER_COMM_PORT_ID : PortSpec(number = CLUSTER_COM_PORT_NUMBER, transport_protocol = CLUSTER_COM_PORT_PROTOCOL), + CLIENT_COMM_PORT_ID : PortSpec(number = CLIENT_COM_PORT_NUMBER, transport_protocol = CLIENT_COM_PORT_PROTOCOL), + }, + env_vars = { + "CASSANDRA_SEEDS":",".join(seeds), + # without this set Cassandra tries to take 8G and OOMs + "MAX_HEAP_SIZE": "512M", + "HEAP_NEWSIZE": "1M", + } + ) + +def get_first_node_name(): + return get_service_name(FIRST_NODE_INDEX) +``` + +Finally, save your newly created file and, from the working directory you created, run the following command: + +```bash +kurtosis run --enclave cassandra-cluster main.star +``` + +:::info +Kurtosis will run validation checks against your code to ensure that it will work before spinning up the containers for our 3-node Cassandra cluster. We won’t dive into the details of how validation checks are used by Kurtosis in this guide, but you can read more about them [here][multi-phase-runs]. +::: + +Your output will look something like: + +```bash +INFO[2023-03-28T17:44:20-03:00] Creating a new enclave for Starlark to run inside... +INFO[2023-03-28T17:44:24-03:00] Enclave 'cassandra-cluster' created successfully + +> add_service name="cassandra-node-0" config=ServiceConfig(image="cassandra:4.0", ports={"client": PortSpec(number=9042, transport_protocol="TCP"), "cluster": PortSpec(number=7000, transport_protocol="TCP")}, env_vars={"CASSANDRA_SEEDS": "cassandra-node-0,cassandra-node-1,cassandra-node-2", "HEAP_NEWSIZE": "1M", "MAX_HEAP_SIZE": "512M"}) +Service 'cassandra-node-0' added with service UUID 'ec084228aa2b4e63aea84c10b9c37963' + +> add_service name="cassandra-node-1" config=ServiceConfig(image="cassandra:4.0", ports={"client": PortSpec(number=9042, transport_protocol="TCP"), "cluster": PortSpec(number=7000, transport_protocol="TCP")}, env_vars={"CASSANDRA_SEEDS": "cassandra-node-0,cassandra-node-1,cassandra-node-2", "HEAP_NEWSIZE": "1M", "MAX_HEAP_SIZE": "512M"}) +Service 'cassandra-node-1' added with service UUID 'f605cff291ef495f884c43f9ee9a980c' + +> add_service name="cassandra-node-2" config=ServiceConfig(image="cassandra:4.0", ports={"client": PortSpec(number=9042, transport_protocol="TCP"), "cluster": PortSpec(number=7000, transport_protocol="TCP")}, env_vars={"CASSANDRA_SEEDS": "cassandra-node-0,cassandra-node-1,cassandra-node-2", "HEAP_NEWSIZE": "1M", "MAX_HEAP_SIZE": "512M"}) +Service 'cassandra-node-2' added with service UUID '4bcf767e82f546e3acfa597510efb0e5' + +> wait recipe=ExecRecipe(command=["/bin/sh", "-c", "nodetool status | grep UN | wc -l | tr -d '\n'"]) field="output" assertion="==" target_value="3" timeout="8m" +Wait took 33 tries (52.05875544s in total). Assertion passed with following: +Command returned with exit code '0' and the following output: 3 + +Starlark code successfully run. Output was: +{ + "node_names": [ + "cassandra-node-0", + "cassandra-node-1", + "cassandra-node-2" + ] +} +Name: cassandra-cluster +UUID: c8027468561c +Status: RUNNING +Creation Time: Tue, 28 Mar 2023 16:29:54 -03 + +========================================= Files Artifacts ========================================= +UUID Name + +========================================== User Services ========================================== +UUID Name Ports Status +ec084228aa2b cassandra-node-0 client: 9042/tcp -> 127.0.0.1:52503 RUNNING + cluster: 7000/tcp -> 127.0.0.1:52502 +f605cff291ef cassandra-node-1 client: 9042/tcp -> 127.0.0.1:52508 RUNNING + cluster: 7000/tcp -> 127.0.0.1:52507 +4bcf767e82f5 cassandra-node-2 client: 9042/tcp -> 127.0.0.1:52513 RUNNING + cluster: 7000/tcp -> 127.0.0.1:52512 +``` + + +Congratulations! You’ve used Kurtosis to spin up a three-node Cassandra cluster over Docker. + +### Review +In this section, you created a [Starlark][starlark] file with instructions for Kurtosis to do the following: +1. Spin up 3 Cassandra containers (one for each node), +2. Bootstrap each node to the cluster, +3. Map the default Cassandra node container ports to ephemeral local machine ports (described in their respective `ServiceConfig`), and +4. Verify using `nodetool` that the cluster is up, running, and has 3 nodes (just as we specified) before returning the names of our nodes. + +You now have a simple environment definition for Kurtosis to spin up a 3-node Cassandra cluster. You may now be wondering: but what if I need to change the number of nodes? + +Fortunately, Kurtosis environment definitions can be parameterized. We’ll see just how easy it is to do so in the next section. + +Parameterize your Cassandra cluster +---------------------------------- + +Kurtosis enables users to parameterize environment definitions out-of-the-box. If you need to run tests against multiple different configurations of your environment, you'll be to do so without needing maintain different Bash scripts or `docker-compose.yml` files per test. + +You can parameterize our Cassandra cluster environment definition by adding 2 lines of code to your `main.star` Starlark file. + +Let’s add in those extra lines now. + +In your `main.star` file, add the following lines in the code block that describes the `plan` object: + +```python +def run(plan, args): + # Default number of Cassandra nodes in our cluster + num_nodes = 3 + + ### <----------- NEW CODE -----------> ### + if "num_nodes" in args: + num_nodes = args["num_nodes"] + ### <----------- NEW CODE -----------> ### + + for node in range(0, num_nodes): + node_name = get_service_name(node) + config = get_service_config(num_nodes) + plan.add_service( + name = node_name, + config = config, + ) + + # ... +``` + +Now save your newly edited `main.star` file and run the following command to blow away your old enclave and spin up a new one with 5 nodes: + +```bash +kurtosis clean -a && kurtosis run --enclave cassandra-cluster main.star '{"num_nodes": 5}' +``` + +It may take a while, but you should now see the following result: + +```bash +INFO[2023-03-28T21:45:46-03:00] Cleaning enclaves... +INFO[2023-03-28T21:45:47-03:00] Successfully removed the following enclaves: +e4c49d41cb0f4c54b9e36ff9c0cba18d cassandra-cluster +INFO[2023-03-28T21:45:47-03:00] Successfully cleaned enclaves +INFO[2023-03-28T21:45:47-03:00] Cleaning old Kurtosis engine containers... +INFO[2023-03-28T21:45:47-03:00] Successfully cleaned old Kurtosis engine containers +INFO[2023-03-28T21:45:47-03:00] Creating a new enclave for Starlark to run inside... +INFO[2023-03-28T21:45:51-03:00] Enclave 'cassandra-cluster' created successfully + +> add_service name="cassandra-node-0" config=ServiceConfig(image="cassandra:4.0", ports={"client": PortSpec(number=9042, transport_protocol="TCP"), "cluster": PortSpec(number=7000, transport_protocol="TCP")}, env_vars={"CASSANDRA_SEEDS": "cassandra-node-0,cassandra-node-1,cassandra-node-2,cassandra-node-3,cassandra-node-4", "HEAP_NEWSIZE": "1M", "MAX_HEAP_SIZE": "512M"}) +Service 'cassandra-node-0' added with service UUID '9a9213d1d84645bf8c76d179e6b2cade' + +> add_service name="cassandra-node-1" config=ServiceConfig(image="cassandra:4.0", ports={"client": PortSpec(number=9042, transport_protocol="TCP"), "cluster": PortSpec(number=7000, transport_protocol="TCP")}, env_vars={"CASSANDRA_SEEDS": "cassandra-node-0,cassandra-node-1,cassandra-node-2,cassandra-node-3,cassandra-node-4", "HEAP_NEWSIZE": "1M", "MAX_HEAP_SIZE": "512M"}) +Service 'cassandra-node-1' added with service UUID '66c6907c6a8a495b9496eaa37c1de42a' + +> add_service name="cassandra-node-2" config=ServiceConfig(image="cassandra:4.0", ports={"client": PortSpec(number=9042, transport_protocol="TCP"), "cluster": PortSpec(number=7000, transport_protocol="TCP")}, env_vars={"CASSANDRA_SEEDS": "cassandra-node-0,cassandra-node-1,cassandra-node-2,cassandra-node-3,cassandra-node-4", "HEAP_NEWSIZE": "1M", "MAX_HEAP_SIZE": "512M"}) +Service 'cassandra-node-2' added with service UUID 'fe9be7991edd40f891e7c2d7f3e14456' + +> add_service name="cassandra-node-3" config=ServiceConfig(image="cassandra:4.0", ports={"client": PortSpec(number=9042, transport_protocol="TCP"), "cluster": PortSpec(number=7000, transport_protocol="TCP")}, env_vars={"CASSANDRA_SEEDS": "cassandra-node-0,cassandra-node-1,cassandra-node-2,cassandra-node-3,cassandra-node-4", "HEAP_NEWSIZE": "1M", "MAX_HEAP_SIZE": "512M"}) +Service 'cassandra-node-3' added with service UUID 'daff154657ce46378928749312275edf' + +> add_service name="cassandra-node-4" config=ServiceConfig(image="cassandra:4.0", ports={"client": PortSpec(number=9042, transport_protocol="TCP"), "cluster": PortSpec(number=7000, transport_protocol="TCP")}, env_vars={"CASSANDRA_SEEDS": "cassandra-node-0,cassandra-node-1,cassandra-node-2,cassandra-node-3,cassandra-node-4", "HEAP_NEWSIZE": "1M", "MAX_HEAP_SIZE": "512M"}) +Service 'cassandra-node-4' added with service UUID '8ecd6c4b75a64764a87f2ce9d23cd8f0' + +> wait recipe=ExecRecipe(command=["/bin/sh", "-c", "nodetool status | grep UN | wc -l | tr -d '\n'"]) field="output" assertion="==" target_value="5" timeout="15m" +Wait took 33 tries (52.686225608s in total). Assertion passed with following: +Command returned with exit code '0' and the following output: 5 + +Starlark code successfully run. Output was: +{ + "node_names": [ + "cassandra-node-0", + "cassandra-node-1", + "cassandra-node-2", + "cassandra-node-3", + "cassandra-node-4" + ] +} +INFO[2023-03-28T21:46:55-03:00] ========================================================== +INFO[2023-03-28T21:46:55-03:00] || Created enclave: cassandra-cluster || +INFO[2023-03-28T21:46:55-03:00] ========================================================== +Name: cassandra-cluster +UUID: c7985e32b076 +Status: RUNNING +Creation Time: Tue, 28 Mar 2023 21:45:47 -03 + +========================================= Files Artifacts ========================================= +UUID Name + +========================================== User Services ========================================== +UUID Name Ports Status +9a9213d1d846 cassandra-node-0 client: 9042/tcp -> 127.0.0.1:54740 RUNNING + cluster: 7000/tcp -> 127.0.0.1:54741 +66c6907c6a8a cassandra-node-1 client: 9042/tcp -> 127.0.0.1:54746 RUNNING + cluster: 7000/tcp -> 127.0.0.1:54745 +fe9be7991edd cassandra-node-2 client: 9042/tcp -> 127.0.0.1:54761 RUNNING + cluster: 7000/tcp -> 127.0.0.1:54760 +daff154657ce cassandra-node-3 client: 9042/tcp -> 127.0.0.1:54768 RUNNING + cluster: 7000/tcp -> 127.0.0.1:54769 +8ecd6c4b75a6 cassandra-node-4 client: 9042/tcp -> 127.0.0.1:54773 RUNNING + cluster: 7000/tcp -> 127.0.0.1:54774 +``` + +Congratulations! You’ve just parameterized your Cassandra cluster environment definition and used it to instantiate a 5-node Cassandra cluster. You can run the same command with 2 nodes, or 4 nodes, and it will just work. **Kurtosis environment definitions are completely reproducible and fully parametrizable.** + +:::caution +Depending on how many nodes you wish to spin up, the max heap size of each node may cumulatively consume more memory on your local machine than you have available, causing the Starlark script to time-out. Modifying the `MAX_HEAP_SIZE` property in the `ServiceConfig` for the Cassandra nodes may help, depending on your needs. +::: + +### Review +How did that work? + +The plan object contains all enclave-modifying methods like `add_service`, `remove_service`, `upload_files`, etc. To use arguments, you accessed them via the second parameter of the `run` function, like so: + +```python +def run(plan, args): + ... +``` + +…which is what you used in your `main.star` file originally! + +What you did next was add an `if statement` with the `hasattr()` function to tell Kurtosis that if an argument is passed in at runtime by a user, then override the default `num_nodes` variable, which we set as 3, with the user-specified value. + +In our case, you passed in: + +```bash +'{"num_nodes": 5}' +``` + +which told Kurtosis to run your `main.star` file with 5 nodes instead of the default of 3 that we began with. + +:::tip +Note that to pass parameters to the run(plan,args) function, a JSON object needs to be passed in as the 2nd position argument after the script or package path: +```bash +kurtosis run my_package.star '{"arg": "my_name"}' +``` +::: + +In this section, we showed how to use Kurtosis to parameterize an environment definition. Next, we’ll walk through another property of Kurtosis environments: composability. + +Making and using composable environment definitions +--------------------------------------------------- +You’ve now written an environment definition using Starlark to instantiate a 3-node Cassandra cluster over Docker, and then modified it slightly to parameterize that definition for other use cases (n-node Cassandra cluster). + +However, the benefits of parametrized and reproducible environment properties are amplified when you’re able to share your definition with others to use, or when you use definitions that others (friends, colleagues, etc) have already written. + +To quickly demonstrate the latter capability, run: + +```bash +kurtosis clean -a && kurtosis run --enclave cassandra-cluster github.com/kurtosis-tech/cassandra-package '{"num_nodes": 5}' +``` + +which should give you the same result you got when you ran your local `main.star` file with 5 nodes specified as an argument. However this time, you’re actually using a `main.star` file hosted [remotely on Github][github-cass-package]! + +**Any Kurtosis environment definition can be converted into a runnable, shareable artifact that we call a Kurtosis Package.** + +While this guide won’t cover the steps needed to convert your Starlark file and export it for others to use as a Kurtosis Package, you can check out our docs to learn more about how to turn a Starlark file into a [runnable Kurtosis package][runnable-packages]. + +### Review +You just executed a remote-hosted `main.star` from a Kurtosis package on [Github][github-cass-package]. That remote-hosted `main.star` file has the same code as our local `main.star` file and, with only a [locator][locator], Kurtosis knew that you were referencing a publicly-hosted runnable package. + +The entirety of what you wrote locally in your `main.star` file can be packaged up and pushed to the internet (Github) for anyone to use to instantiate an n-node cassandra cluster by adding a [`kurtosis.yml`][kurtosis-yml] manifest to your directory and publishing the entire directory to Github. Read more about how to do this [here][runnable-packages]. + +Turning your Starlark code into a runnable Kurtosis package and making it available on Github means any developer will be able to use your Kurtosis package as a building block in their own environment definition or to run different tests using various configurations of nodes in a Cassandra cluster. + +This behavior is bi-directional as well. Meaning, you can import any remotely hosted Kurtosis package and use its code inside your own Kurtosis package with the `import_module` instruction like so: + +```python +lib = import_module("github.com/foo/bar/src/lib.star") + +def run(plan,args) +lib.some_function() +lib.some_variable() +``` + +**Package distribution via remote-hosted git repositories is one way in which Kurtosis enables environments to be easily composed and connected together without end users needing to know the inner workings of each setup.** + +Conclusion +---------- +And that’s it! To recap this short guide, you: +1. Wrote an environment definition that instructs Kurtosis to set up a 3 node Cassandra cluster in an isolated environment called an Enclave (over Docker), +2. Added a few lines of code to our `main.star` file to parametrize your environment definition to increase the flexibility and use cases with which it can be used, and, +3. Executed a remotely-hosted Starlark file that was part of what's called a [Kurtosis Package][packages] to demonstrate how your environment definition can be shared with other developers. + +We’d love to hear from you on what went well for you, what could be improved, or to answer any of your questions. Don’t hesitate to reach out via Github (`kurtosis feedback`) or in our [Discord server](https://discord.com/channels/783719264308953108/783719264308953111). + +### Other exercises you can do with your Cassandra cluster +With your parameterized, reusable environment definition for a multi-node Cassandra cluster, feel free to: +* Turn your local `main.star` file into a runnable Kurtosis package and upload it on Github for others to use following [these instructions][runnable-packages] +* Use our [Go or Typescript SDK][sdk-reference] to write backend integration tests, like this [network partitioning test][network-partitioning-test] + +### Other examples +We encourage you to check out our [quickstart][quickstart] (where you’ll build a postgres database and API on top) and our other examples in our [awesome-kurtosis repository][awesome-kurtosis] where you will find other Kurtosis packages for you to check out as well, including a package that spins up a local [Ethereum testnet][eth-package-example] or one that sets up a [voting app using a Redis cluster][redis-package-example]. + + +[quickstart]: ../quickstart.md +[awesome-kurtosis]: https://github.com/kurtosis-tech/awesome-kurtosis +[multi-phase-runs]: ../concepts-reference/multi-phase-runs.md +[github-cass-package]: https://github.com/kurtosis-tech/cassandra-package/blob/main/main.star +[runnable-packages]: ../concepts-reference/packages.md#runnable-packages +[kurtosis-yml]: ../concepts-reference/kurtosis-yml.md +[locator]: ../concepts-reference/locators.md +[packages]: ../concepts-reference/packages.md +[sdk-reference]: ../sdk.md +[network-partitioning-test]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/cassandra-network-partition-test +[redis-package-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/redis-voting-app +[eth-package-example]: https://github.com/kurtosis-tech/eth-network-package +[installing-the-cli]: ./installing-the-cli.md#ii-install-the-cli +[starting-docker]: ./installing-the-cli.md#i-install--start-docker +[starlark]: ../concepts-reference/starlark.md +[vscode-plugin]: https://marketplace.visualstudio.com/items?itemName=Kurtosis.kurtosis-extension diff --git a/docs/versioned_docs/version-0.78.3/guides/installing-historical-versions.md b/docs/versioned_docs/version-0.78.3/guides/installing-historical-versions.md new file mode 100644 index 0000000000..325d0bb4a3 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/installing-historical-versions.md @@ -0,0 +1,95 @@ +--- +title: Installing Historical Versions +sidebar_label: Installing Historical Versions +slug: /install-historical +sidebar_position: 3 +--- + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +Occasionally, using historical versions of Kurtosis is necessary. For example, when working with a [Starlark](../concepts-reference/starlark.md) Kurtosis package that was initially developed with an older version of Kurtosis, we might want rollback our Kurtosis version to ensure the version of Kurtosis we are running is compatible with the Kurtosis package. + +The instructions in this guide will walk you through installing and using a historical version of Kurtosis. To see what versions are available, reference our [changelog](../changelog.md). + +If you're looking to install the latest version of Kurtosis, [see here][install-kurtosis]. + + + + + +1. Uninstall your current version of Kurtosis + ``` + brew uninstall kurtosis-tech/tap/kurtosis-cli + ``` + +2. Install an earlier version of Kurtosis (eg. `0.68.6`) + ``` + brew install kurtosis-tech/tap/kurtosis-cli@ + ``` + + + + +:::caution + +If you already have `kurtosis-cli` package installed, we recommend uninstalling it first using: + +```bash +sudo apt remove kurtosis-cli +``` + +::: + +```bash +echo "deb [trusted=yes] https://apt.fury.io/kurtosis-tech/ /" | sudo tee /etc/apt/sources.list.d/kurtosis.list +sudo apt update +sudo apt remove kurtosis-cli +sudo apt install kurtosis-cli= -V +``` + + + + +:::caution + +If you already have `kurtosis-cli` package installed, we recommend uninstalling it first using: + +```bash +sudo yum remove kurtosis-cli +``` + +::: + +```bash +echo '[kurtosis] +name=Kurtosis +baseurl=https://yum.fury.io/kurtosis-tech/ +enabled=1 +gpgcheck=0' | sudo tee /etc/yum.repos.d/kurtosis.repo +sudo yum remove kurtosis-cli +sudo yum install kurtosis-cli- +``` + + + + +Download the appropriate artifact from [the release artifacts page][release-artifacts]. + + + + + +The Kurtosis CLI cannot be installed directly on Windows. Windows users are encouraged to use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) to use Kurtosis. + + + + + + +[install-kurtosis]: ./installing-the-cli.md +[release-artifacts]: https://github.com/kurtosis-tech/kurtosis-cli-release-artifacts/releases diff --git a/docs/versioned_docs/version-0.78.3/guides/installing-the-cli.md b/docs/versioned_docs/version-0.78.3/guides/installing-the-cli.md new file mode 100644 index 0000000000..287878bc87 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/installing-the-cli.md @@ -0,0 +1,116 @@ +--- +title: Installing Kurtosis +sidebar_label: Installing Kurtosis +slug: /install +sidebar_position: 1 +--- + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +The instructions in this guide will walk you through installing the latest version of Kurtosis. + +If you already have Kurtosis installed and you're looking to upgrade to latest, [see here][upgrade-guide]. + +If you're looking to install a historical version instead, [see here][install-historical-guide]. + +I. Install & Start Docker +----------------- + +1. If you don't already have Docker installed, follow the instructions [here][docker-install] to install the Docker application specific to your machine (e.g. Apple Intel, Apple M1, etc.). +1. Start the Docker daemon (e.g. open Docker Desktop) +1. Verify that Docker is running: + ```bash + docker image ls + ``` + +II. Install the CLI +------------------------- + + + + +``` +brew install kurtosis-tech/tap/kurtosis-cli +``` + +:::info +Homebrew might warn you that your Xcode is outdated or missing entirely. [This is a Homebrew requirement](https://docs.brew.sh/Installation), and has nothing to do with Kurtosis (which ships as prebuilt binaries). + +To install or update your Xcode, run: + +```bash +xcode-select --install +``` +::: + + + + +```bash +echo "deb [trusted=yes] https://apt.fury.io/kurtosis-tech/ /" | sudo tee /etc/apt/sources.list.d/kurtosis.list +sudo apt update +sudo apt install kurtosis-cli +``` + + + + +```bash +echo '[kurtosis] +name=Kurtosis +baseurl=https://yum.fury.io/kurtosis-tech/ +enabled=1 +gpgcheck=0' | sudo tee /etc/yum.repos.d/kurtosis.repo +sudo yum install kurtosis-cli +``` + + + + +Download the appropriate artifact from [the release artifacts page][release-artifacts]. + + + + + +Windows users are encouraged to use [Windows Subsystem for Linux (WSL)][windows-susbsystem-for-linux] to use Kurtosis. +If you want to run a native executable, you can download the latest build for your architechture [here](https://github.com/kurtosis-tech/kurtosis-cli-release-artifacts/tags). + +Or do it using PowerShell: + +```bash +Invoke-WebRequest -Uri "https://github.com/kurtosis-tech/kurtosis-cli-release-artifacts/releases/download/REPLACE_VERSION/kurtosis-cli_REPLACE_VERSION_windows_REPLACE_ARCH.tar.gz" -OutFile kurtosis.tar.gz +tar -xvzf kurtosis.tar.gz +kurtosis.exe +``` + + + + + +III. (Optional) Add command-line completion +-------------------------------- +Kurtosis supports command-line completion to allow completing subcommands and dynamic values (e.g. enclave name during `enclave inspect`). This isn't required, but we believe it significantly enhances the Kurtosis experience for those who are using . If you'd like to install it, see [these instructions][installing-command-line-completion]. + +Run the quickstart +------------------ +If you're new to Kurtosis, you might like the [quickstart][quickstart] as a good onboarding to get started with Kurtosis. + + +[cli-changelog]: ../changelog.md +[metrics-philosophy]: ../explanations/metrics-philosophy.md +[analytics-disable]: ../cli-reference/analytics-disable.md +[quickstart]: ../quickstart.md +[installing-command-line-completion]: ./adding-command-line-completion.md +[install-historical-guide]: ./installing-historical-versions.md +[upgrade-guide]: ./upgrading-the-cli.md + +[release-artifacts]: https://github.com/kurtosis-tech/kurtosis-cli-release-artifacts/releases +[windows-susbsystem-for-linux]: https://learn.microsoft.com/en-us/windows/wsl/ +[docker-install]: https://docs.docker.com/get-docker/ diff --git a/docs/versioned_docs/version-0.78.3/guides/running-in-ci.md b/docs/versioned_docs/version-0.78.3/guides/running-in-ci.md new file mode 100644 index 0000000000..33fb592fc4 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/running-in-ci.md @@ -0,0 +1,55 @@ +--- +title: Running Kurtosis in CI +sidebar_label: Running in CI +slug: /ci +--- + +Running Kurtosis on your local machine is nice, but executing it as part of CI is even better. This guide will walk you through modifying your CI config file to use Kurtosis in your CI environment: + +I. Installing The CLI +---------------------------- +You'll need the Kurtosis CLI inside your CI environment. This can be accomplished by following [the installation instructions](installing-the-cli.md) for whichever package manager your CI container uses. E.g. if you're using Github Actions with an Ubuntu executor, you'd add the instructions for installing the Kurtosis CLI via the `apt` package manager to your CI config file. + +II. Start The Engine +---------------------------- +You'll need the Kurtosis engine to be running to interact with Kurtosis, both for the [CLI](../cli-reference/index.md) and [using the Kurtosis SDK](../sdk.md). Add `kurtosis engine start` in your CI config file after the CLI installation commands so that your Kurtosis commands work. + +III. Run Your Custom Logic +--------------------------------- +This will be specific to whatever you want to run in CI. E.g. if you have Javascript Mocha tests that use Kurtosis, you'd put that in your CI config file after installing the Kurtosis CLI & starting the engine. + +IV. Capturing Enclave Output +----------------------------------- +Naturally, if your job fails you'll want to see what was going on inside of Kurtosis at the time of failure. The `kurtosis enclave dump` command allows us to capture container logs & specs from an enclave, so that we can dump the state of the enclaves and attach them to the CI job for further debugging. The specifics of how to attach files to a CI job from within the job will vary depending on which CI provider you're using, but will look something like the following (which is for CircleCI): + +```yaml + # Run our custom logic (in this case, running a package), but don't exit immediately if it fails so that + # we can upload the 'enclave dump' results before the CI job ends + - run: | + if ! kurtosis run --enclave-name my-enclave github.com/kurtosis-tech/datastore-army-package; then + touch /tmp/testsuite-failed + fi + + # Dump enclave data so we can debug any issues that arise + - run: | + cd /tmp + + # Write enclave information to /tmp/my-enclave + kurtosis enclave dump my-enclave my-enclave + + # Zip up the data so we can attach it to the CI job + zip -r my-enclave.zip my-enclave + + # Attach the ZIP file to the CI job + - store_artifacts: + path: /tmp/my-enclave.zip + destination: my-enclave.zip + + # Now that we've uploaded the enclave data, fail the job if the testsuite failed + - run: "! [ -f /tmp/testsuite-failed ]" +``` + +Example +------- +- [CircleCI](https://github.com/kurtosis-tech/eth2-package/blob/main/.circleci/config.yml#L19) +- More CI examples coming soon... diff --git a/docs/versioned_docs/version-0.78.3/guides/running-in-k8s.md b/docs/versioned_docs/version-0.78.3/guides/running-in-k8s.md new file mode 100644 index 0000000000..2711e440ef --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/running-in-k8s.md @@ -0,0 +1,67 @@ +--- +title: Running Kurtosis in Kubernetes +sidebar_label: Running in Kubernetes +slug: /k8s +--- + +This guide assumes that you have [Kurtosis installed](./installing-the-cli.md). + +I. Create a Kubernetes Cluster +----------------- + +There are severals diferent ways to deploy a Kubernetes cluster: + +1. Deploy it on an onprem cluster and manage the machine provisioning yourself +1. Deploy it on the cloud, managing the Kubernetes nodes on cloud instances yourself (e.g. EC2, AVM, GCE, etc) +1. Deploy it on a managed Kuberenetes cluster, managing scaling and configurations yourself (e.g. EKS, AKS, GKE) + +:::tip Kurtosis Kloud Early Access +If you're looking to run a stress-free "Kurtosis on Kubernetes in the cloud", look no further! We're excited to launch an early access offering for [Kurtosis Kloud](https://mp2k8nqxxgj.typeform.com/to/U1HcXT1H). Once you [sign up](https://mp2k8nqxxgj.typeform.com/to/U1HcXT1H), we'll reach out to you with the next steps. +::: + + +II. Add you Kubernetes Cluster credentials to your `kubeconfig` +------------------------- + +This step will depend highly on how your cluster was created. But generally you will need to either: + +1. Manually edit the `kubeconfig` file to contain cluster and authentication data. For more information, see [Kubernetes docs](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). +1. Use your cloud provider's CLI to automatically edit the `kubeconfig` file so that it contains your cluster and authentication data. For example, you if you are using Amazon's managed Kubernetes service (called EKS), [this tutorial](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html) is comprehensive. + + +III. Add your cluster information to `kurtosis-config.yml` +-------------------------------- + +1. Open the file located at `"$(kurtosis config path)"`. This should look like `/Users/YOUR_USER/Library/Application Support/kurtosis/kurtosis-config.yml` on MacOS. +1. Paste the following contents, changing `NAME-OF-YOUR-CLUSTER` to the cluster you created and save: +```yaml +config-version: 2 +should-send-metrics: true +kurtosis-clusters: + docker: + type: "docker" + minikube: + type: "kubernetes" + config: + kubernetes-cluster-name: "minikube" + storage-class: "standard" + enclave-size-in-megabytes: 10 + cloud: + type: "kubernetes" + config: + kubernetes-cluster-name: "NAME-OF-YOUR-CLUSTER" + storage-class: "standard" + enclave-size-in-megabytes: 10 +``` + +IV. Configure Kurtosis +-------------------------------- + +1. Run `kurtosis cluster set cloud`. This will start the engine remotely. +1. *In another terminal*, run `kurtosis gateway`. This will act as a middle man between your computer's ports and your services deployed on Kubernetes ports and has to stay running as a separate proccess. + +Done! Now you can run any Kurtosis command or package just like if you were doing it locally. + +:::tip Kurtosis Kloud Early Access +To switch back to using Kurtosis locally, simply use: `kurtosis cluster set docker` +::: \ No newline at end of file diff --git a/docs/versioned_docs/version-0.78.3/guides/simulating-networking-failure.md b/docs/versioned_docs/version-0.78.3/guides/simulating-networking-failure.md new file mode 100644 index 0000000000..a9f373c7fe --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/simulating-networking-failure.md @@ -0,0 +1,181 @@ +--- +title: Simulating A Networking Failure +sidebar_label: Simulating a networking failure +--- + +Using Kurtosis you can control which services can communicate inside and across [subnetworks][subnetworks-reference]. Kurtosis provides arbitrarily fine grained control over which services can communicate with each other. This can be useful to simulate network faults, [partition tolerance][cap-theorem] or even partial network outages, including package drops. + +This guide illustrates the concept of Kurtosis subnetworks by simluating a partial networking failure within a distributed system. + +Step 1: Start all services in an enclave +----------------------------------------- + +The example system is composed of a Cassandra cluster with 3 nodes, 2 redundant services serving the main application and a single port proxy to load balance the requests. + +```python +MAIN_SUBNETWORK = "main_subnetwork" +SECONDARY_SUBNETWORK = "secondary_subnetwork" + +def run(args): + add_service( + name="cassandra_node_1", + config=ServiceConfig( + ... + subnetwork=MAIN_SUBNETWORK, + ), + ) + add_service( + name="cassandra_node_2", + config=ServiceConfig( + ... + subnetwork=MAIN_SUBNETWORK, + ), + ) + add_service( + name="cassandra_node_3", + config=ServiceConfig( + ... + subnetwork=MAIN_SUBNETWORK, + ), + ) + add_service( + name="app_service_1", + config=ServiceConfig( + ... + subnetwork=MAIN_SUBNETWORK, + ), + ) + add_service( + name="app_service_2", + config=ServiceConfig( + ... + subnetwork=MAIN_SUBNETWORK, + ), + ) + add_service( + name="single_port_proxy", + config=ServiceConfig( + ... + subnetwork=MAIN_SUBNETWORK, + ), + ) +``` + +When all the services are added to the Kurtosis enclave, it will look something like: + +``` + Kurtosis enclave + ----------------------------------------------------- + | main_subnetwork | + |-----------------------------------------------------| + | | + | cassandra_node_1 | + | cassandra_node_2 | + | cassandra_node_3 | + | app_service_1 | + | app_service_2 | + | single_port_proxy | + | | + ----------------------------------------------------- +``` + +At the start, all connections are allowed. +- all the Cassandra nodes can communicate with each other +- the two services can reach all Cassandra nodes +- the single port proxy is playing its role of dispatching requests to both `app_service_1` and `app_service_2` + +Setp 2: Add a second subnetwork by updating services +---------------------------------------------------- + +Subnetworks make it easy to simulate a network failure that completely isolates `cassandra_node_2` and `app_service_2` from the rest of the system. + +First,`cassandra_node_2` and `app_service_2` need to be assigned to a distinct subnetwork, `secondary_subnetwork`. This can be done by updating those services. + +This can be done by "updating" those services. + +```python +MAIN_SUBNETWORK = "main_subnetwork" +SECONDARY_SUBNETWORK = "secondary_subnetwork" + +def run(args): + # ... + # all the services are added using the code snippet above + # ... + + update_service( + name="cassandra_node_2", + config=UpdateServiceConfig( + subnetwork=SECONDARY_SUBNETWORK, + ), + ) + update_service( + name="app_service_2", + config=UpdateServiceConfig( + subnetwork=SECONDARY_SUBNETWORK, + ), + ) +``` + +Kurtosis has the concept of a *default connection* between subnetworks. The default connection is the connection configuration that all pairs of subnetworks will inherit. At enclave creation, the default connection is set to allow communication between subnetworks. In this case, when the `cassandra_node_2` and `app_service_2` are assigned `secondary_subnetwork`, nothing changes. `main_subnetwork` and `secondary_subnetwork` can continue to communicate because the default connection is unblocked. + +``` + Kurtosis enclave + ----------------------------------------------------- + | main_subnetwork | secondary_subnetwork | + |-----------------------------------------------------| + | . | + | cassandra_node_1 . | + | . cassandra_node_2 | + | cassandra_node_3 . | + | app_service_1 . | + | . app_service_2 | + | single_port_proxy . | + | . | + ----------------------------------------------------- +``` + +Setp 3: Configure the connection between the two subnetworks +------------------------------------------------------------ + +The creation of `main_subnetwork` and `secondary_subnetwork` now makes it possible to reconfigure the connection between them. Communications between the two subnetworks can now be blocked partially or completely by overriding the default connection for those two specific subnetworks. + +```python +MAIN_SUBNETWORK = "main_subnetwork" +SECONDARY_SUBNETWORK = "secondary_subnetwork" + +def run(args): + # ... + # all the services are added and `cassandra_node_2` and `app_service_2` are updated using the code snippet above + # ... + + set_connection( + (MAIN_SUBNETWORK, SECONDARY_SUBNETWORK), + config=ConnectionConfig( + packet_loss_percentage=90.0, # 90% of the packet are dropped + ), + ) +``` + +The result is the following: `cassandra_node_2` and `app_service_2` are partially unreachable and the resilience of the system can be tested. + +``` + Kurtosis enclave + ----------------------------------------------------- + | main_subnetwork | secondary_subnetwork | + |-------------------------|---------------------------| + | | | + | cassandra_node_1 | | + | | cassandra_node_2 | + | cassandra_node_3 | | + | app_service_1 | | + | | app_service_2 | + | single_port_proxy | | + | | | + ----------------------------------------------------- +``` + + + +[subnetworks-reference]: ../concepts-reference/subnetworks.md + +[cap-theorem]: https://en.wikipedia.org/wiki/CAP_theorem diff --git a/docs/versioned_docs/version-0.78.3/guides/upgrading-the-cli.md b/docs/versioned_docs/version-0.78.3/guides/upgrading-the-cli.md new file mode 100644 index 0000000000..fac7bad869 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/guides/upgrading-the-cli.md @@ -0,0 +1,88 @@ +--- +title: Upgrading Kurtosis +sidebar_label: Upgrading Kurtosis +slug: /upgrade +sidebar_position: 2 +--- + + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +The instructions in this guide assume you already have Kurtosis installed, and will walk you through upgrading to the latest version of Kurtosis. + +If you're looking to install Kurtosis, [see here][install-guide]. + +I. Check breaking changes +--------------------------------- +You can check the version of the CLI you're running with `kurtosis version`. Before upgrading to the latest version, check [the changelog to see if there are any breaking changes][cli-changelog] before proceeding with the steps below to upgrade. + +II. Upgrade the CLI +------------------------- + + + + +```bash +brew update && brew upgrade kurtosis-tech/tap/kurtosis-cli +``` + + + + +```bash +apt install --only-upgrade kurtosis-cli +``` + + + + +```bash +yum upgrade kurtosis-cli +``` + + + + +Download the appropriate artifact from [the release artifacts page][release-artifacts]. + + + + + +The Kurtosis CLI cannot be installed directly on Windows. Windows users are encouraged to use [Windows Subsystem for Linux (WSL)][windows-susbsystem-for-linux] to use Kurtosis. + + + + + +III. Restart the engine +----------------------- +If you upgraded the CLI through a minor version (the `Y` in a `X.Y.Z` version), you may need to restart your Kurtosis engine after the upgrade. + +If this is needed, the Kurtosis CLI will prompt you with an error like so: + +```text +The engine server API version that the CLI expects, 1.7.4, doesn't match the running engine server API version, 1.6.8; this would cause broken functionality so you'll need to restart the engine to get the correct version by running 'kurtosis engine restart' +``` + +The fix is to [restart the engine][kurtosis-engine-restart] like so: + +``` +kurtosis engine restart +``` + + +[install-guide]: ./installing-the-cli.md +[cli-changelog]: ../changelog.md +[metrics-philosophy]: ../explanations/metrics-philosophy.md +[quickstart]: ../quickstart.md +[installing-command-line-completion]: ./adding-command-line-completion.md + +[release-artifacts]: https://github.com/kurtosis-tech/kurtosis-cli-release-artifacts/releases +[windows-susbsystem-for-linux]: https://learn.microsoft.com/en-us/windows/wsl/ + +[kurtosis-engine-restart]: ../cli-reference/engine-restart.md diff --git a/docs/versioned_docs/version-0.78.3/home.md b/docs/versioned_docs/version-0.78.3/home.md new file mode 100644 index 0000000000..7ac9e388ad --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/home.md @@ -0,0 +1,44 @@ +--- +title: Introduction +sidebar_label: Introduction +slug: '/' +sidebar_position: 1 +hide_table_of_contents: true +--- +## What is Kurtosis? +[Kurtosis](https://www.kurtosis.com) is a composable build system for multi-container test environments. Kurtosis makes it easier for developers to set up test environments that require dynamic setup logic (e.g. passing IPs or runtime-generated data between services) or programmatic data seeding. + +Go [here](./explanations/why-we-built-kurtosis.md) to learn more what inspired us to build Kurtosis. + +## Why use Kurtosis? + +Developers usually set up these types of dynamic environments with a free-form scripting language like bash or Python, interacting with the Docker CLI or Docker Compose. Kurtosis is designed to make these setups easier to maintain and reuse in different test scenarios. + +In Kurtosis, test environments have these properties: +- Environment-level portability: the entire test environment always runs the same way, regardless of the host machine +- Composability: environments can be composed and connected together without needing to know the inner details of each setup +- Parameterizability: environments can be parameterized, so that they're easy to modify for use across different test scenarios + +## Architecture + +#### Kurtosis has a definition language of: +- An instruction set of useful primitives for setting up and manipulating environments +- A scriptable Python-like SDK in Starlark, a build language used by Google’s Bazel +- A package management system for shareability and composability + +#### Kurtosis has a validator with: +- Compile-time safety to quickly catch errors in test environment definitions +- The ability to dry-run test environment definitions to verify what will be run, before running + +#### Kurtosis has a runtime to: +- Run multi-container test environments over Docker or Kubernetes, depending on how you wish to scale +- Enable debugging and investigation of problems live, as they're happening in your test environment +- Manage file dependencies to ensure complete portability of test environments across different test runs and backends + +#### Try out Kurtosis now + +Try Kurtosis now with our [quickstart](./quickstart.md). + +:::info +If you have questions, need help, or simply want to learn more, schedule a live session with us, go [here](https://calendly.com/d/zgt-f2c-66p/kurtosis-onboarding). +::: diff --git a/docs/versioned_docs/version-0.78.3/package-index.md b/docs/versioned_docs/version-0.78.3/package-index.md new file mode 100644 index 0000000000..f3afaef774 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/package-index.md @@ -0,0 +1,15 @@ +--- +title: Package Index +sidebar_label: Package Index +slug: /package-index +--- + +This page lists where you can find many different types of Kurtosis [packages][packages-concepts-reference]: + +- [Awesome Kurtosis][awesome-kurtosis]: A repo containing many different examples of Kurtosis usage across web2 and web3 +- [Official Kurtosis packages on Github](https://github.com/kurtosis-tech?q=package+in%3Aname&type=&language=): The multitude of Kurtosis-maintained packages, including the rising [AutoGPT package](https://github.com/kurtosis-tech/autogpt-package) +- [Third-party packages on Github](https://github.com/search?q=-user%3Akurtosis-tech+path%3A**%2Fkurtosis.yml&type=code): Kurtosis packages written by non-Kurtosis parties + + +[awesome-kurtosis]: https://github.com/kurtosis-tech/awesome-kurtosis +[packages-concepts-reference]: ./concepts-reference/packages.md diff --git a/docs/versioned_docs/version-0.78.3/quickstart.md b/docs/versioned_docs/version-0.78.3/quickstart.md new file mode 100644 index 0000000000..ec816881c4 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/quickstart.md @@ -0,0 +1,974 @@ +--- +title: Quickstart +sidebar_label: Quickstart +slug: /quickstart +toc_max_heading_level: 2 +--- + +Introduction +------------ + +Welcome to the [Kurtosis][homepage] quickstart! This guide will take ~15 minutes and will walk you through building a basic Kurtosis package. This guide is in a "code along" format, meaning we assume the user will be following the code examples and running Kurtosis CLI commands on your local machine. Everything you will run in this guide is free, public, and does not contain any sensitive data. + +For a quick read on what Kurtosis is and what problems Kurtosis aims to solve, our [introduction page][homepage] will be a great starting point, alongside our [motivations behind starting Kurtosis][why-we-built-kurtosis-explanation]. + +:::tip What You'll Do + +- Start a containerized Postgres database in Kurtosis +- Seed your database with test data using task sequencing +- Connect an API server to your database using dynamic service dependencies +- Parameterize your application setup in order to automate loading data into your API +::: + +
TL;DR Version + +This quickstart is in a "code along" format. You can also dive straight into running the end results and exploring the code too. + +**Open the Playground: [Start](https://gitpod.io/?autostart=true&editor=code#https://github.com/kurtosis-tech/quickstart-gitpod)** + +Click on the "New Workspace" button! You don't have to worry about the Context URL, Editor or Class. It's all pre-configured for you. + +
+ +If you ever get stuck, every Kurtosis command accepts a `-h` flag to print helptext. If that doesn't help, you can get in touch with us in our [Discord server](https://discord.com/channels/783719264308953108/783719264308953111) or on [Github](https://github.com/kurtosis-tech/kurtosis/issues/new/choose)! + +Setup +----- + +#### Requirements +Before you proceed, please make sure you have: +- [Installed and started the Docker engine][installing-docker-guide] +- [Installed the Kurtosis CLI][installing-kurtosis-guide] (or [upgraded to latest][upgrading-kurtosis-guide] if you already have it) + +Hello, World +------------ +First, create and `cd` into a directory to hold the project you'll be working on: + +```bash +mkdir kurtosis-quickstart && cd kurtosis-quickstart +``` + +Next, create a Starlark file called `main.star` inside your new directory with the following contents (more on Starlark in the "Review" section coming up soon): + +```python +def run(plan, args): + plan.print("Hello, world") +``` + +:::tip +If you're using Visual Studio Code, you may find our [Kurtosis VS Code Extension][vscode-plugin] helpful when writing Starlark. +If you're using Vim, you can add the following to your `.vimrc` to get Starlark syntax highlighting: + +``` +" Add syntax highlighting for Starlark files +autocmd FileType *.star setlocal filetype=python +``` + +::: + +Finally, [run][kurtosis-run-reference] the script (we'll explain enclaves in the "Review" section too): + +```bash +kurtosis run --enclave quickstart main.star +``` + +Kurtosis will work for a bit, and then deliver you the following result: + +```text +INFO[2023-03-15T04:27:01-03:00] Creating a new enclave for Starlark to run inside... +INFO[2023-03-15T04:27:05-03:00] Enclave 'quickstart' created successfully + +> print msg="Hello, world" +Hello, world + +Starlark code successfully run. No output was returned. +INFO[2023-03-15T04:27:05-03:00] =================================================== +INFO[2023-03-15T04:27:05-03:00] || Created enclave: quickstart || +INFO[2023-03-15T04:27:05-03:00] =================================================== +Name: quickstart +UUID: a78f2ce1ca68 +Status: RUNNING +Creation Time: Wed, 15 Mar 2023 04:27:01 -03 + +========================================= Files Artifacts ========================================= +UUID Name + +========================================== User Services ========================================== +UUID Name Ports Status +``` + +Congratulations - you've written your first Kurtosis code! + +### Review: Hello, World +:::info +You'll use these "Review" sections to explain what happened in the section. +::: + +In this section, you created a `main.star` file that simply told Kurtosis to print `Hello, world`. The `.star` extension corresponds to [Starlark][starlark-reference], a Python dialect also used by Google and Meta for configuring build systems. + +When you ran `main.star`, you got `Created enclave: quickstart`. An [enclave][enclaves-reference] is a Kurtosis primitive that can be thought of as an *ephemeral test environment*, on top of Docker or Kubernetes, for a distributed application. The distributed applications that you define with Starlark will run inside enclaves. If you'd like, you can tear down your enclave and any of their artifacts by running: `kurtosis clean -a` (more on the `kurtosis clean` command [here][kurtosis-clean-reference]). + +Enclaves are intended to be easy to create, easy to destroy, cheap to run, and isolated from each other. Use enclaves liberally! + +Run Postgres +-------------- +The heart of any application is the database. To introduce you to Kurtosis, we'll start by launching a Postgres server using Kurtosis. + +Replace the contents of your `main.star` file with the following: + +```python +POSTGRES_PORT_ID = "postgres" +POSTGRES_DB = "app_db" +POSTGRES_USER = "app_user" +POSTGRES_PASSWORD = "password" + +def run(plan, args): + # Add a Postgres server + postgres = plan.add_service( + name = "postgres", + config = ServiceConfig( + image = "postgres:15.2-alpine", + ports = { + POSTGRES_PORT_ID: PortSpec(5432, application_protocol = "postgresql"), + }, + env_vars = { + "POSTGRES_DB": POSTGRES_DB, + "POSTGRES_USER": POSTGRES_USER, + "POSTGRES_PASSWORD": POSTGRES_PASSWORD, + }, + ), + ) +``` + +Before you run the above command, remember that you still have the `quickstart` enclave hanging around from the previous section. To [clean up the previous enclave][kurtosis-clean-reference] and execute our new `main.star` file above, run: + +```bash +kurtosis clean -a && kurtosis run --enclave quickstart main.star +``` + +:::info +The `--enclave` flag is used to specify the enclave to use for that particular run. If one doesn't exist, Kurtosis will create an enclave with that name - which is what is happening here. Read more about `kurtosis run` [here][kurtosis-run-reference]. + +This entire "clean-and-run" process will be your dev loop for the rest of the quickstart as you add more services and operations to our distributed application. +::: + +You'll see in the result that the `quickstart` enclave now contains a Postgres instance: + +```text +Name: quickstart +UUID: a30106a0bb87 +Status: RUNNING +Creation Time: Tue, 14 Mar 2023 20:23:54 -03 + +========================================= Files Artifacts ========================================= +UUID Name + +========================================== User Services ========================================== +UUID Name Ports Status +b6fc024deefe postgres postgres: 5432/tcp -> postgresql://127.0.0.1:59299 RUNNING +``` + +### Review: Run Postgres +So what actually happened? Three things actually: + +1. **Interpretation:** Kurtosis first ran your Starlark to build [a plan](./concepts-reference/plan.md) for what you wanted done (in this case, starting a Postgres instance) +1. **Validation:** Kurtosis then ran several validations against your plan, including validating that the Postgres image exists +1. **Execution:** Kurtosis finally executed the validated plan inside the enclave to start a Postgres container + +Note that Kurtosis did not execute anything until _after_ Interpretation and Validation completed. You can think of Interpretation and Validation like Kurtosis' "compilation" step for your distributed application: you can catch many errors before any containers run, which shortens the dev loop and reduces the resource burden on your machine. + +We call this approach [multi-phase runs][multi-phase-runs-reference]. While multi-phase runs has powerful benefits over traditional scripting, it also means _you cannot reference Execution values like IP address in Starlark_ because they simply don't exist at Interpretation time. We'll explore how Kurtosis gracefully handles values generated during the Execution phase at the Interpretation phase later on in the quickstart. + +**This section introduced Kurtosis' ability to validate that definitions work as intended, _before_ they are run - helping developers catch errors sooner & save resources when configuring multi-container test environments.** + +Add some data +------------- +A database without data is a fancy heater, so let's add some. + +Your two options for seeding a Postgres database are: + +1. Making a sequence of PSQL commands via the `psql` binary +1. Using `pg_restore` to load a package of data + +Both are possible in Kurtosis, but for this tutorial we'll use `pg_restore` to seed your database with a TAR of DVD rental information, [courtesy of postgresqltutorial.com](https://www.postgresqltutorial.com/postgresql-getting-started/postgresql-sample-database/). + +#### Without Kurtosis +Normally going this route (using `pg_restore`) requires downloading the seed data to your local machine, starting Postgres, writing a pile of Bash to copy the seed data to the Postgres server, and then finally running the `pg_restore` command. If you forget to check if the database is available, you may get flakes when you try to use the seeding logic in a test. + +Alternatively, you could use Docker Compose to volume-mount the data TAR into the Postgres server, but you'd still need to handle Postgres availability and sequencing the `pg_restore` afterwards. + +#### With Kurtosis +By contrast, Kurtosis Starlark scripts can use data as a first-class primitive and sequence tasks such as `pg_restore` into the plan. + +Let's see it in action, and we'll explain what's happening afterwards. + +First, in your working directory (`kurtosis-quickstart`), next to your `main.star` file, create a file called `kurtosis.yml` with the following contents: + +```bash +name: "github.com/john-snow/kurtosis-quickstart" +``` + +Then update your `main.star` with the following: + +```python +data_package_module = import_module("github.com/kurtosis-tech/awesome-kurtosis/data-package/main.star") + +POSTGRES_PORT_ID = "postgres" +POSTGRES_DB = "app_db" +POSTGRES_USER = "app_user" +POSTGRES_PASSWORD = "password" + +SEED_DATA_DIRPATH = "/seed-data" + +def run(plan, args): + # Make data available for use in Kurtosis + data_package_module_result = data_package_module.run(plan, {}) + + # Add a Postgres server + postgres = plan.add_service( + name = "postgres", + config = ServiceConfig( + image = "postgres:15.2-alpine", + ports = { + POSTGRES_PORT_ID: PortSpec(5432, application_protocol = "postgresql"), + }, + env_vars = { + "POSTGRES_DB": POSTGRES_DB, + "POSTGRES_USER": POSTGRES_USER, + "POSTGRES_PASSWORD": POSTGRES_PASSWORD, + }, + files = { + SEED_DATA_DIRPATH: data_package_module_result.files_artifact, + } + ), + ) + + # Load the data into Postgres + postgres_flags = ["-U", POSTGRES_USER,"-d", POSTGRES_DB] + plan.exec( + service_name = "postgres", + recipe = ExecRecipe(command = ["pg_restore"] + postgres_flags + [ + "--no-owner", + "--role=" + POSTGRES_USER, + SEED_DATA_DIRPATH + "/" + data_package_module_result.tar_filename, + ]), + ) +``` + +Now, run the following to see what happens: + +```bash +kurtosis clean -a && kurtosis run --enclave quickstart . +``` + +(Notice you are using `.` instead of `main.star`) + +The output should also look more interesting as your plan has grown bigger: + +```text +INFO[2023-03-15T04:34:06-03:00] Cleaning enclaves... +INFO[2023-03-15T04:34:06-03:00] Successfully removed the following enclaves: +60601dd9906e40d6af5f16b233a56ae7 quickstart +INFO[2023-03-15T04:34:06-03:00] Successfully cleaned enclaves +INFO[2023-03-15T04:34:06-03:00] Cleaning old Kurtosis engine containers... +INFO[2023-03-15T04:34:06-03:00] Successfully cleaned old Kurtosis engine containers +INFO[2023-03-15T04:34:06-03:00] Creating a new enclave for Starlark to run inside... +INFO[2023-03-15T04:34:10-03:00] Enclave 'quickstart' created successfully +INFO[2023-03-15T04:34:10-03:00] Executing Starlark package at '/tmp/kurtosis-quickstart' as the passed argument '.' looks like a directory +INFO[2023-03-15T04:34:10-03:00] Compressing package 'github.com/john-snow/kurtosis-quickstart' at '.' for upload +INFO[2023-03-15T04:34:10-03:00] Uploading and executing package 'github.com/john-snow/kurtosis-quickstart' + +> upload_files src="github.com/kurtosis-tech/awesome-kurtosis/data-package/dvd-rental-data.tar" +Files with artifact name 'howling-thunder' uploaded with artifact UUID '32810fc8c131414882c52b044318b2fd' + +> add_service name="postgres" config=ServiceConfig(image="postgres:15.2-alpine", ports={"postgres": PortSpec(number=5432, application_protocol="postgresql")}, files={"/seed-data": "howling-thunder"}, env_vars={"POSTGRES_DB": "app_db", "POSTGRES_PASSWORD": "password", "POSTGRES_USER": "app_user"}) +Service 'postgres' added with service UUID 'f1d9cab2ca344d1fbb0fc00b2423f45f' + +> exec recipe=ExecRecipe(command=["pg_restore", "-U", "app_user", "-d", "app_db", "--no-owner", "--role=app_user", "/seed-data/dvd-rental-data.tar"]) +Command returned with exit code '0' with no output + +Starlark code successfully run. No output was returned. +INFO[2023-03-15T04:34:21-03:00] =================================================== +INFO[2023-03-15T04:34:21-03:00] || Created enclave: quickstart || +INFO[2023-03-15T04:34:21-03:00] =================================================== +Name: quickstart +UUID: 995fe0ca69fe +Status: RUNNING +Creation Time: Wed, 15 Mar 2023 04:34:06 -03 + +========================================= Files Artifacts ========================================= +UUID Name +32810fc8c131 howling-thunder + +========================================== User Services ========================================== +UUID Name Ports Status +f1d9cab2ca34 postgres postgres: 5432/tcp -> postgresql://127.0.0.1:62914 RUNNING +``` + +Does your Postgres have data now? Let's find out by opening a shell on the Postgres container and logging into the database: + +```bash +kurtosis service shell quickstart postgres +``` + +From there, listing the tables in the Postgres can be done with: + +``` bash +psql -U app_user -d app_db -c '\dt' +``` + +...which will reveal that many new tables now exist: + +```text + List of relations + Schema | Name | Type | Owner +--------+---------------+-------+---------- + public | actor | table | app_user + public | address | table | app_user + public | category | table | app_user + public | city | table | app_user + public | country | table | app_user + public | customer | table | app_user + public | film | table | app_user + public | film_actor | table | app_user + public | film_category | table | app_user + public | inventory | table | app_user + public | language | table | app_user + public | payment | table | app_user + public | rental | table | app_user + public | staff | table | app_user + public | store | table | app_user +(15 rows) +``` + +Feel free to explore the Postgres container. When you're done run either `exit` or press Ctrl-D. + +### Review: Add some data +So what just happened? + +#### We created a Kurtosis package + +By creating a [`kurtosis.yml`][kurtosis-yml-reference] file in your working directory, you turned your working directory into a [Kurtosis package][packages-reference] (specifically, a [runnable package][runnable-packages-reference]). After you did this, your newly created Kurtosis package could now declare dependencies on external packages using [Kurtosis’ built-in packaging/dependency system][how-do-imports-work-explanation]. + +To see this in action, the first line in your local `main.star` file was used to import, and therefore declare a dependency on, an external package called `data-package` using a [locator][locators-reference]: + +```python +data_package_module = import_module("github.com/kurtosis-tech/awesome-kurtosis/data-package/main.star") +``` +... which we then ran locally: +```python +data_package_module_result = data_package_module.run(plan, {}) +``` + +This external Kurtosis package, named ["data-package"][data-package-example] contains the seed data for your Postgres instance that we [referenced earlier](#add-some-data) as a `.tar` file. + +:::info +Special note here that we used a locator to import an external package from your [`awesome-kurtosis` repository][awesome-kurtosis-repo] and _not_ a regular URL. Learn more about how they differ [here][locators-reference]. +::: + +#### You imported seed data into your Kurtosis package +The [`main.star` file][data-package-example-main.star] in that external "data-package" contained Starlark instructions to store the `.tar` data as a [files artifact][files-artifacts-reference] using the [`files_upload` Starlark instruction][kurtosis-files-upload-reference]: + +```python +TAR_FILENAME = "dvd-rental-data.tar" +def run(plan, args): + dvd_rental_data = plan.upload_files("github.com/kurtosis-tech/awesome-kurtosis/data-package/" + TAR_FILENAME) + + result = struct( + files_artifact = dvd_rental_data, # Needed to mount the data on a service + tar_filename = TAR_FILENAME, # Useful to reference the data TAR contained in the files artifact + ) + + return result +``` + +A [files artifact][files-artifacts-reference] is Kurtosis' first-class data primitive and is a TGZ of arbitrary files living inside an enclave. So long as a files artifact exists, Kurtosis knows how to mount its contents on a service. + +#### You mounted and seeded the data into your Postgres instance +Next, you mounted the seed data, stored in your enclave now as a files artifact, into your Postgres instance using the `ServiceConfig.files` option: + +```python +postgres = plan.add_service( + name = "postgres", + config = ServiceConfig( + # ...omitted... + files = { + SEED_DATA_DIRPATH: data_package_module_result.files_artifact, + } + ), +) +``` + +Then to seed the data, you used the [`exec` Starlark instruction][exec-reference]: +```python +plan.exec( + service_name = "postgres", + recipe = ExecRecipe(command = ["pg_restore"] + postgres_flags + [ + "--no-owner", + "--role=" + POSTGRES_USER, + SEED_DATA_DIRPATH + "/" + data_package_module_result.tar_filename, + ] + ), +``` +**Here, you saw one of Kurtosis' most loved features: the ability to modularize and share your distributed application logic using only a Github repository.** We won't dive into all the usecases now, but [the examples here][awesome-kurtosis-repo] can serve as a good source of inspiration. + +Add an API +---------- +Databases don't come alone, however. In this section we'll add a [PostgREST API][postgrest] in front of the database and see how Kurtosis handles inter-service dependencies. + +Replace the contents of your `main.star` with this: + +```python +data_package_module = import_module("github.com/kurtosis-tech/awesome-kurtosis/data-package/main.star") + +POSTGRES_PORT_ID = "postgres" +POSTGRES_DB = "app_db" +POSTGRES_USER = "app_user" +POSTGRES_PASSWORD = "password" + +SEED_DATA_DIRPATH = "/seed-data" + +POSTGREST_PORT_ID = "http" + +def run(plan, args): + # Make data available for use in Kurtosis + data_package_module_result = data_package_module.run(plan, {}) + + # Add a Postgres server + postgres = plan.add_service( + name = "postgres", + config = ServiceConfig( + image = "postgres:15.2-alpine", + ports = { + POSTGRES_PORT_ID: PortSpec(5432, application_protocol = "postgresql"), + }, + env_vars = { + "POSTGRES_DB": POSTGRES_DB, + "POSTGRES_USER": POSTGRES_USER, + "POSTGRES_PASSWORD": POSTGRES_PASSWORD, + }, + files = { + SEED_DATA_DIRPATH: data_package_module_result.files_artifact, + } + ), + ) + + # Load the data into Postgres + postgres_flags = ["-U", POSTGRES_USER,"-d", POSTGRES_DB] + plan.exec( + service_name = "postgres", + recipe = ExecRecipe(command = ["pg_restore"] + postgres_flags + [ + "--no-owner", + "--role=" + POSTGRES_USER, + SEED_DATA_DIRPATH + "/" + data_package_module_result.tar_filename, + ]), + ) + + # Add PostgREST + postgres_url = "postgresql://{}:{}@{}:{}/{}".format( + "postgres", + POSTGRES_PASSWORD, + postgres.ip_address, + postgres.ports[POSTGRES_PORT_ID].number, + POSTGRES_DB, + ) + api = plan.add_service( + name = "api", # Naming our PostgREST service "api" + config = ServiceConfig( + image = "postgrest/postgrest:v10.2.0.20230209", + env_vars = { + "PGRST_DB_URI": postgres_url, + "PGRST_DB_ANON_ROLE": POSTGRES_USER, + }, + ports = {POSTGREST_PORT_ID: PortSpec(3000, application_protocol = "http")}, + ) + ) + +``` + +Now, run the same dev loop command as before (and don't worry about the result, we'll explain that later): + +```bash +kurtosis clean -a && kurtosis run --enclave quickstart . +``` + +We just got a failure, just like we might when building a real system! + +```text +> add_service name="api" config=ServiceConfig(image="postgrest/postgrest:v10.2.0.20230209", ports={"http": PortSpec(number=3000, application_protocol="http")}, env_vars={"PGRST_DB_ANON_ROLE": "app_user", "PGRST_DB_URI": "postgresql://postgres:password@{{kurtosis:4d65eca66b5749df8988419ae31dda21:ip_address.runtime_value}}:5432/app_db"}) +There was an error executing Starlark code +An error occurred executing instruction (number 4) at DEFAULT_PACKAGE_ID_FOR_SCRIPT[54:27]: + add_service(name="api", config=ServiceConfig(image="postgrest/postgrest:v10.2.0.20230209", ports={"http": PortSpec(number=3000, application_protocol="http")}, env_vars={"PGRST_DB_ANON_ROLE": "app_user", "PGRST_DB_URI": "postgresql://postgres:password@{{kurtosis:4d65eca66b5749df8988419ae31dda21:ip_address.runtime_value}}:5432/app_db"})) + Caused by: Unexpected error occurred starting service 'api' + Caused by: An error occurred waiting for all TCP and UDP ports being open for service 'api' with private IP '10.1.0.4'; as the most common error is a wrong service configuration, here you can find the service logs: + == SERVICE 'api' LOGS =================================== + 09/May/2023:19:18:41 +0000: Attempting to connect to the database... + 09/May/2023:19:18:41 +0000: {"code":"PGRST000","details":"connection to server at \"10.1.0.3\", port 5432 failed: FATAL: password authentication failed for user \"postgres\"\n","hint":null,"message":"Database connection error. Retrying the connection."} + 09/May/2023:19:18:41 +0000: connection to server at "10.1.0.3", port 5432 failed: FATAL: password authentication failed for user "postgres" + + postgrest: thread killed + + == FINISHED SERVICE 'api' LOGS =================================== + Caused by: An error occurred while waiting for all TCP and UDP ports to be open + Caused by: Unsuccessful ports check for IP '10.1.0.4' and port spec '{number:3000 transportProtocol:0 applicationProtocol:0xc006662e10 wait:0xc00662d510}', even after '2' retries with '500' milliseconds in between retries. Timeout '15s' has been reached + Caused by: An error occurred while calling network address '10.1.0.4:3000' with port protocol 'TCP' and using time out '14.499139733s' + Caused by: dial tcp 10.1.0.4:3000: i/o timeout + +Error encountered running Starlark code. +``` + +Here, Kurtosis is telling us that the `add_service` instruction on line `54` of your `main.star` (the one for ensuring PostgREST is up) is timing out when was checking for ports opening. + +:::info +Fun fact: this failure was encountered at the last step in Kurtosis' [multi-phase run approach][multi-phase-runs-reference], which is also called the Execution step that we mentioned earlier [when we got Postgres up and running](#review-run-postgres). +::: + + +#### Investigating the issue +If you check the service's logs, printed in the error message right after this header `== SERVICE 'api' LOGS ===================================`, you will see that there is an authentication error + +The enclave state is usually a good place to find mor clues. If you look at the bottom of your output you'll see the following state of the enclave: + +```text + +Name: quickstart +UUID: 5b360f940bcc +Status: RUNNING +Creation Time: Tue, 14 Mar 2023 22:15:19 -03 + +========================================= Files Artifacts ========================================= +UUID Name +323c9a71ebbf crimson-haze + +========================================== User Services ========================================== +UUID Name Ports Status +45b355fc810b postgres postgres: 5432/tcp -> postgresql://127.0.0.1:59821 RUNNING +``` + +From the above, we can see that the PostgREST service (named: `api`) is not in the 'User Services' list, so we can infer that it crashed when it was starting. + +You can also grab the PostgREST logs... + +```bash +kurtosis service logs quickstart api +``` + +...we can see that the PostgREST is dying: + +```text +15/Mar/2023:01:15:30 +0000: Attempting to connect to the database... +15/Mar/2023:01:15:30 +0000: {"code":"PGRST000","details":"FATAL: password authentication failed for user \"postgres\"\n","hint":null,"message":"Database connection error. Retrying the connection."} +15/Mar/2023:01:15:30 +0000: FATAL: password authentication failed for user "postgres" + +postgrest: thread killed +``` + +Looking back to your Starlark code, you can see the problem: it's creating the Postgres database with a user called `app_user`, but it's telling PostgREST to try and connect through a user called `postgres`: + +```python +POSTGRES_USER = "app_user" + +# ... + +def run(plan, args): + # ... + + # Add a Postgres server + postgres = plan.add_service( + name = "postgres", + config = ServiceConfig( + # ... + env_vars = { + # ... + "POSTGRES_USER": POSTGRES_USER, + # ... + }, + # ... + ), + ) + + # ... + + postgres_url = "postgresql://{}:{}@{}:{}/{}".format( + "postgres", # <---------- THE PROBLEM IS HERE + POSTGRES_PASSWORD, + postgres.ip_address, + postgres.ports[POSTGRES_PORT_ID].number, + POSTGRES_DB, + ) +``` + +In the line declaring the `postgres_url` variable in your `main.star` file, replace the `"postgres",` string with `POSTGRES_USER,` to use the correct username we specified at the beginning of our file. Then re-run your dev loop: + +```bash +kurtosis clean -a && kurtosis run --enclave quickstart . +``` + +Now at the bottom of the output we can see that the PostgREST service is `RUNNING` correctly: + +```text +Name: quickstart +UUID: 11c0ac047299 +Status: RUNNING +Creation Time: Tue, 14 Mar 2023 22:30:02 -03 + +========================================= Files Artifacts ========================================= +UUID Name +323c9a71ebbf crimson-haze + +========================================== User Services ========================================== +UUID Name Ports Status +ce90b471a982 postgres postgres: 5432/tcp -> postgresql://127.0.0.1:59883 RUNNING +98094b33cd9a api http: 3000/tcp -> http://127.0.0.1:59887 RUNNING +``` + +### Review: Add an API +In this section, you spun up a new PostgREST service (that we named `api` for readability) with a dependency on the Postgres service. Normally, PostgREST needs to know the IP address or hostname of the Postgres service, and we said earlier that Starlark (the Interpretation phase) can never know Execution values. + +So how did the services get connected? + +Answer: Execution-time values are represented at Interpretation time as [future references][future-references-reference] that Kurtosis will replace at Execution time with the actual value. In this case, the `postgres_url` variable here... + +```python +postgres_url = "postgresql://{}:{}@{}:{}/{}".format( + POSTGRES_USER, + POSTGRES_PASSWORD, + postgres.ip_address, + postgres.ports[POSTGRES_PORT_ID].number, + POSTGRES_DB, +) +``` + +...used the `postgres.ip_address` and `postgres.ports[POSTGRES_PORT_ID].number` future references returned by adding the Postgres service, so that when `postgres_url` was used as an environment variable during PostgREST startup... + +```python +api = plan.add_service( + name = "api", # Naming our PostgREST service "api" + config = ServiceConfig( + # ... + env_vars = { + "PGRST_DB_URI": postgres_url, # <-------- HERE + "PGRST_DB_ANON_ROLE": POSTGRES_USER, + }, + # ... + ) +) +``` + +...Kurtosis simply swapped in the correct Postgres container Execution-time values. While future references take some getting used to, [we've found the feedback loop speedup to be very worth it][why-multi-phase-runs-explanation]. + +**What you've just seen is Kurtosis' powerful ability to gracefully handle data generated at runtime to set up service dependencies in multi-container test environments. You also saw how seamless it was to to run on-box CLI commands on a container.** + +Modifying data +-------------- +Now that you have an API, you should be able to interact with the data. + +[Inspect][kurtosis-enclave-inspect-reference] your enclave: + +```bash +kurtosis enclave inspect quickstart +``` + +Notice how Kurtosis automatically exposed the PostgREST container's `http` port to your machine: + +```text +28a923400e50 api http: 3000/tcp -> http://127.0.0.1:59992 RUNNING +``` + +:::info +In this output the `http` port is exposed as URL `http://127.0.0.1:59992`, but your port number will be different. +::: + +You can paste the URL from your output into your browser (or Cmd+click if you're using [iTerm][iterm]) to verify that you are indeed talking to the PostgREST inside your `quickstart` enclave: + +```json +{"swagger":"2.0","info":{"description":"","title":"standard public schema","version":"10.2.0.20230209 (pre-release) (a1e2fe3)"},"host":"0.0.0.0:3000","basePath":"/","schemes":["http"],"consumes":["application/json","application/vnd.pgrst.object+json","text/csv"],"produces":["application/json","application/vnd.pgrst.object+json","text/csv"],"paths":{"/":{"get":{"tags":["Introspection"],"summary":"OpenAPI description (this document)","produces":["application/openapi+json","application/json"],"responses":{"200":{"description":"OK"}}}},"/actor":{"get":{"tags":["actor"],"parameters":[{"$ref":"#/parameters/rowFilter.actor.actor_id"},{"$ref":"#/parameters/rowFilter.actor.first_name"},{"$ref":"#/parameters/rowFilter.actor.last_name"},{"$ref":"#/parameters/rowFilter.actor.last_update"},{"$ref":"#/parameters/select"},{"$ref":"#/parameters/order"},{"$ref":"#/parameters/range"},{"$ref":"#/parameters/rangeUnit"},{"$ref":"#/parameters/offset"},{"$ref":"#/parameters/limit"},{"$ref":"#/parameters/preferCount"}], ... +``` + +Now make a request to insert a row into the database (replacing `$YOUR_PORT` with the `http` port from your `enclave inspect` output for the PostgREST service that we named `api`)... + +```bash +curl -XPOST -H "content-type: application/json" http://127.0.0.1:$YOUR_PORT/actor --data '{"first_name": "Kevin", "last_name": "Bacon"}' +``` + +...and then query for it (again replacing `$YOUR_PORT` with your port)... + +```bash +curl -XGET "http://127.0.0.1:$YOUR_PORT/actor?first_name=eq.Kevin&last_name=eq.Bacon" +``` + +...to get it back: + +```text +[{"actor_id":201,"first_name":"Kevin","last_name":"Bacon","last_update":"2023-03-15T02:08:14.315732"}] +``` + +Of course, it'd be much nicer to formalize this in Kurtosis. Replace your `main.star` with the following: + +```python +data_package_module = import_module("github.com/kurtosis-tech/awesome-kurtosis/data-package/main.star") + +POSTGRES_PORT_ID = "postgres" +POSTGRES_DB = "app_db" +POSTGRES_USER = "app_user" +POSTGRES_PASSWORD = "password" + +SEED_DATA_DIRPATH = "/seed-data" + +POSTGREST_PORT_ID = "http" + +def run(plan, args): + # Make data available for use in Kurtosis + data_package_module_result = data_package_module.run(plan, {}) + + # Add a Postgres server + postgres = plan.add_service( + name = "postgres", + config = ServiceConfig( + image = "postgres:15.2-alpine", + ports = { + POSTGRES_PORT_ID: PortSpec(5432, application_protocol = "postgresql"), + }, + env_vars = { + "POSTGRES_DB": POSTGRES_DB, + "POSTGRES_USER": POSTGRES_USER, + "POSTGRES_PASSWORD": POSTGRES_PASSWORD, + }, + files = { + SEED_DATA_DIRPATH: data_package_module_result.files_artifact, + } + ), + ) + + # Load the data into Postgres + postgres_flags = ["-U", POSTGRES_USER,"-d", POSTGRES_DB] + plan.exec( + service_name = "postgres", + recipe = ExecRecipe(command = ["pg_restore"] + postgres_flags + [ + "--no-owner", + "--role=" + POSTGRES_USER, + SEED_DATA_DIRPATH + "/" + data_package_module_result.tar_filename, + ]), + ) + + # Add PostgREST + postgres_url = "postgresql://{}:{}@{}:{}/{}".format( + POSTGRES_USER, + POSTGRES_PASSWORD, + postgres.hostname, + postgres.ports[POSTGRES_PORT_ID].number, + POSTGRES_DB, + ) + api = plan.add_service( + name = "api", + config = ServiceConfig( + image = "postgrest/postgrest:v10.2.0.20230209", + env_vars = { + "PGRST_DB_URI": postgres_url, + "PGRST_DB_ANON_ROLE": POSTGRES_USER, + }, + ports = {POSTGREST_PORT_ID: PortSpec(3000, application_protocol = "http")}, + ) + ) + + # Insert data + if "actors" in args: + insert_data(plan, args["actors"]) + +def insert_data(plan, data): + plan.request( + service_name = "api", + recipe = PostHttpRequestRecipe( + port_id = POSTGREST_PORT_ID, + endpoint = "/actor", + content_type = "application/json", + body = json.encode(data), + ) + ) +``` + +Now clean and run, only this time with extra args to `kurtosis run`: + +```bash +kurtosis clean -a && kurtosis run --enclave quickstart . '{"actors": [{"first_name":"Kevin", "last_name": "Bacon"}, {"first_name":"Steve", "last_name":"Buscemi"}]}' +``` + +Using the new `http` URL on the `api` service in the output, query for the rows you just added (replacing `$YOUR_PORT` with your correct PostgREST `http` port number)... + +```bash +curl -XGET "http://127.0.0.1:$YOUR_PORT/actor?or=(last_name.eq.Buscemi,last_name.eq.Bacon)" +``` + +...to yield: + +```text +[{"actor_id":201,"first_name":"Kevin","last_name":"Bacon","last_update":"2023-03-15T02:29:53.454697"}, + {"actor_id":202,"first_name":"Steve","last_name":"Buscemi","last_update":"2023-03-15T02:29:53.454697"}] +``` + +### Review +How did this work? + +Mechanically, we first created a JSON string of data using Starlark's `json.encode` builtin. Then we used [the `request` Starlark instruction][request-reference] to shove the string at PostgREST, which writes it to the database: + +```python +plan.request( + service_name = "api", + recipe = PostHttpRequestRecipe( + port_id = POSTGREST_PORT_ID, + endpoint = "/actor", + content_type = "application/json", + body = json.encode(data), + ) +) +``` + +At a higher level, Kurtosis automatically deserialized the `{"actors": [{"first_name":"Kevin", "last_name": "Bacon"}, {"first_name":"Steve", "last_name":"Buscemi"}]}` string passed as a parameter to `kurtosis run`, and put the deserialized object in the `args` parameter to the `run` function in `main.star`: + +```python +def run(plan, args): +``` + +**This section showed how to interact with your test environment, and also how to parametrize it for others to easily modify and re-use.** + + + + + + +Conclusion +---------- +And that's it - you've written your very first distributed application in Kurtosis! + +Let's review. In this tutorial you have: + +- Started a Postgres database in an ephemeral, isolated test environment +- Seeded your database by importing an external Starlark package from the internet +- Set up an API server for your database and gracefully handled dynamically generated dependency data +- Inserted & queried data via the API +- Parameterized data insertion for future use + +This was still just an introduction to Kurtosis. To dig deeper, visit other sections of our docs where you can read about [what Kurtosis is][homepage], understand the [architecture][architecture-explanation], and hear our [inspiration for starting Kurtosis][why-we-built-kurtosis-explanation]. + +To learn more about how Kurtosis is used, we encourage you to check out our [`awesome-kurtosis` repository][awesome-kurtosis-repo], where you will find real-world examples of Kurtosis in action, including: +- How to run a simple [Go test][go-test-example] or [Typescript test][ts-test-example] against the app we just built +- The [Ethereum package][ethereum-package], used by the Ethereum Foundation, which can be used to set up local testnets +- A parameterized package for standing up an [n-node Cassandra cluster with Grafana and Prometheus][cassandra-package-example] out-of-the-box +- The [NEAR package][near-package] for local dApp development in the NEAR ecosystem + +Finally, we'd love to hear from you. Please don't hesitate to share with us what went well, and what didn't, using `kurtosis feedback` to file an issue in our [Github](https://github.com/kurtosis-tech/kurtosis/issues/new/choose) or to [chat with our cofounder, Kevin](https://calendly.com/d/zgt-f2c-66p/kurtosis-onboarding). + +Lastly, feel free to [star us on Github](https://github.com/kurtosis-tech/kurtosis), [join the community in our Discord](https://discord.com/channels/783719264308953108/783719264308953111), and [follow us on Twitter](https://twitter.com/KurtosisTech)! + +Thank you for trying our quickstart. We hope you enjoyed it. + + + + +[installing-kurtosis-guide]: ./guides/installing-the-cli.md#ii-install-the-cli +[installing-docker-guide]: ./guides/installing-the-cli.md#i-install--start-docker +[upgrading-kurtosis-guide]: ./guides/upgrading-the-cli.md + + +[architecture-explanation]: ./explanations/architecture.md +[enclaves-reference]: ./concepts-reference/enclaves.md +[services-explanation]: ./explanations/architecture.md#services +[reusable-environment-definitions-explanation]: ./explanations/reusable-environment-definitions.md +[why-we-built-kurtosis-explanation]: ./explanations/why-we-built-kurtosis.md +[how-do-imports-work-explanation]: ./explanations/how-do-kurtosis-imports-work.md +[why-multi-phase-runs-explanation]: ./explanations/why-multi-phase-runs.md + + + +[cli-reference]: /cli +[kurtosis-run-reference]: ./cli-reference/run-starlark.md +[kurtosis-clean-reference]: ./cli-reference/clean.md +[kurtosis-enclave-inspect-reference]: ./cli-reference/enclave-inspect.md +[kurtosis-files-upload-reference]: ./cli-reference/files-upload.md +[kurtosis-feedback-reference]: ./cli-reference/feedback.md +[kurtosis-twitter]: ./cli-reference/twitter.md +[starlark-reference]: ./concepts-reference/starlark.md + + +[request-reference]: ./starlark-reference/plan.md#request +[exec-reference]: ./starlark-reference/plan.md#exec + + +[multi-phase-runs-reference]: ./concepts-reference/multi-phase-runs.md +[kurtosis-yml-reference]: ./concepts-reference/kurtosis-yml.md +[packages-reference]: ./concepts-reference/packages.md +[runnable-packages-reference]: ./concepts-reference/packages.md#runnable-packages +[locators-reference]: ./concepts-reference/locators.md +[plan-reference]: ./concepts-reference/plan.md +[future-references-reference]: ./concepts-reference/future-references.md +[files-artifacts-reference]: ./concepts-reference/files-artifacts.md + + + +[awesome-kurtosis-repo]: https://github.com/kurtosis-tech/awesome-kurtosis +[data-package-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/data-package +[data-package-example-main.star]: https://github.com/kurtosis-tech/awesome-kurtosis/blob/main/data-package/main.star +[data-package-example-seed-tar]: https://github.com/kurtosis-tech/awesome-kurtosis/blob/main/data-package/dvd-rental-data.tar +[cassandra-package-example]: https://github.com/kurtosis-tech/cassandra-package +[go-test-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/quickstart/go-test +[ts-test-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/quickstart/ts-test + + +[homepage]: home.md +[kurtosis-managed-packages]: https://github.com/kurtosis-tech?q=in%3Aname+package&type=all&language=&sort= +[wild-kurtosis-packages]: https://github.com/search?q=filename%3Akurtosis.yml&type=code +[bazel-github]: https://github.com/bazelbuild/bazel/ +[starlark-github-repo]: https://github.com/bazelbuild/starlark +[postgrest]: https://postgrest.org/en/stable/ +[ethereum-package]: https://github.com/kurtosis-tech/eth2-package +[waku-package]: https://github.com/logos-co/wakurtosis +[near-package]: https://github.com/kurtosis-tech/near-package +[iterm]: https://iterm2.com/ +[vscode-plugin]: https://marketplace.visualstudio.com/items?itemName=Kurtosis.kurtosis-extension diff --git a/docs/versioned_docs/version-0.78.3/sdk.md b/docs/versioned_docs/version-0.78.3/sdk.md new file mode 100644 index 0000000000..f2980cadff --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/sdk.md @@ -0,0 +1,540 @@ +--- +title: SDK +sidebar_label: SDK +slug: /SDK +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +Interactions with Kurtosis happen via API. To facilitate interaction with Kurtosis, we provide [client libraries][kurtosis-client-libs] for interacting with the Kurtosis API. These can be used to, for example, write Kurtosis tests using your test framework of choice. + +This page documents the objects and functions in the client libraries. + +:::tip +The sidebar on the right can be used to quickly navigate classes. +::: + +KurtosisContext +--------------- +A connection to a Kurtosis engine, used for manipulating enclaves. + +### `createEnclave(String enclaveName, boolean isSubnetworkingEnabled) -> [EnclaveContext][enclavecontext] enclaveContext` +Creates a new Kurtosis enclave using the given parameters. + +**Args** +* `enclaveName`: The name to give the new enclave. +* `isSubnetworkingEnabled`: If set to true, the enclave will be set up to allow for subnetworking. This will make service addition & removal take slightly longer, but will enable [subnetworking](./concepts-reference/subnetworks.md) and allow the use of [`Plan.set_connection`](./starlark-reference/plan.md#set_connection) in the Starlark scripts you run. + +**Returns** +* `enclaveContext`: An [EnclaveContext][enclavecontext] object representing the new enclave. + +### `getEnclaveContext(String enclaveIdentifier) -> [EnclaveContext][enclavecontext] enclaveContext` +Gets the [EnclaveContext][enclavecontext] object for the given enclave ID. + +**Args** +* `enclaveIdentifier`: The [identifier][identifier] of the enclave. + +**Returns** +* `enclaveContext`: The [EnclaveContext][enclavecontext] representation of the enclave. + +### `getEnclaves() -> Enclaves enclaves` +Gets the enclaves that the Kurtosis engine knows about. + +**Returns** +* `enclaves`: The [Enclaves][enclaves] representation of all enclaves that Kurtosis the engine knows about. + +### `getEnclave(String enclaveIdentifier) -> EnclaveInfo enclaveInfo` +Gets information about the enclave for the given identifier + +**Args** +* `enclaveIdentifier`: The [identifier][identifier] of the enclave. + +**Returns** +* `enclaves`: The [EnclaveInfo][enclaveinfo] object representing the enclave + +### `stopEnclave(String enclaveIdentifier)` +Stops the enclave with the given [identifier][identifier], but doesn't destroy the enclave objects (containers, networks, etc.) so they can be further examined. + +**NOTE:** Any [EnclaveContext][enclavecontext] objects representing the stopped enclave will become unusable. + +**Args** +* `enclaveIdentifier`: [Identifier][identifier] of the enclave to stop. + +### `destroyEnclave(String enclaveIdentifier)` +Stops the enclave with the given [identifier][identifier] and destroys the enclave objects (containers, networks, etc.). + +**NOTE:** Any [EnclaveContext][enclavecontext] objects representing the stopped enclave will become unusable. + +**Args** +* `enclaveIdentifier`: [Identifier][identifier] of the enclave to destroy. + +### `clean(boolean shouldCleanAll) -> []EnclaveNameAndUuid RemovedEnclaveNameAndUuids` +Destroys enclaves in the Kurtosis engine. + +**Args** +* `shouldCleanAll`: If set to true, destroys running enclaves in addition to stopped ones. + +**Returns** +* `RemovedEnclaveNameAndUuids`: A list of enclave uuids and names that were removed succesfully + +### `getServiceLogs(String enclaveIdentifier, Set serviceUuids, Boolean shouldFollowLogs, LogLineFilter logLineFilter) -> ServiceLogsStreamContent serviceLogsStreamContent` +Get and start a service container logs stream (showed in ascending order, with the oldest line first) from services identified by their UUID. + +**Args** +* `enclaveIdentifier`: [Identifier][identifier] of the services' enclave. +* `serviceUuids`: A set of service UUIDs identifying the services from which logs should be retrieved. +* `shouldFollowLogs`: If it's true, the stream will constantly send the new log lines. if it's false, the stream will be closed after the last created log line is sent. +* `logLineFilter`: The [filter][loglinefilter] that will be used for filtering the returned log lines + +**Returns** +* `serviceLogsStreamContent`: The [ServiceLogsStreamContent][servicelogsstreamcontent] object which wrap all the information coming from the logs stream. + +### `getExistingAndHistoricalEnclaveIdentifiers() -> EnclaveIdentifiers enclaveIdentifiers` + +Get all (active & deleted) historical [identifiers][identifier] for the currently +running Kurtosis engine. + +**Returns** +* `enclaveIdentifiers` The [EnclaveIdentifiers][enclave-identifiers] which provides user-friendly ways to lookup enclave identifier information. + +EnclaveIdentifiers +------------------- +This class is a representation of identifiers of enclaves. + +### `getEnclaveUuidForIdentifier(string identifier) -> EnclaveUUID enclaveUuid, Error` +Returns the UUID that matches the given identifier. If there are no matches it returns +an error instead. + +**Args** +* `identifier`: A enclave identifier string + +**Returns** +* `enclaveUuid`: The UUID for the enclave identified by the `identifier`. + +### `getOrderedListOfNames() -> []String enclaveNames` +Returns an ordered list of names for all the enclaves registered with the engine. This is useful +if users want to enumerate all enclave names, say for an autocomplete like function. + +**Returns** +* `enclaveNames`: This is a sorted list of enclave names + +ServiceLogsStreamContent +------------------------ +This class is the representation of the content sent during a service logs stream communication. This wrapper includes the service's logs content and the not found service UUIDs. + +### `getServiceLogsByServiceUuids() -> Map> serviceLogsByServiceUuids` +Returns the user service logs content grouped by the service's UUID. + +**Returns** +* `serviceLogsByServiceUuids`: A map containing a list of the [ServiceLog][servicelog] objects grouped by service UUID. + +### `getNotFoundServiceUuids() -> Set notFoundServiceUuids` +Returns the not found service UUIDs. The UUIDs may not be found either because they don't exist, or because the services haven't sent any logs. + +**Returns** +* `notFoundServiceUuids`: A set of not found service UUIDs + +ServiceLog +---------- +This class represent single service's log line information + +### `getContent() -> String content` + +**Returns** +* `content`: The log line string content + +LogLineFilter +------------- +This class is used to specify the match used for filtering the service's log lines. There are a couple of helpful constructors that can be used to generate the filter type + +### `NewDoesContainTextLogLineFilter(String text) -> LogLineFilter logLineFilter` +Returns a LogLineFilter type which must be used for filtering the log lines containing the text match + +**Args** +* `text`: The text that will be used to match in the log lines + +**Returns** +* `logLineFilter`: The does-contain-text-match log line filter + +### `NewDoesNotContainTextLogLineFilter(String text) -> LogLineFilter logLineFilter` +Returns a LogLineFilter type which must be used for filtering the log lines that do not contain the text match + +**Args** +* `text`: The text that will be used to match in the log lines + +**Returns** +* `logLineFilter`: The does-not-contain-text-match log line filter + +### `NewDoesContainMatchRegexLogLineFilter(String regex) -> LogLineFilter logLineFilter` +Returns a LogLineFilter type which must be used for filtering the log lines containing the regex match, [re2 syntax regex may be used][google_re2_syntax_docs] + +**Args** +* `regex`: The regex expression that will be used to match in the log lines + +**Returns** +* `logLineFilter`: The does-contain-regex-match log line filter + +### `NewDoesNotContainMatchRegexLogLineFilter(String regex) -> LogLineFilter logLineFilter` +Returns a LogLineFilter type which must be used for filtering the log lines that do not contain the regex match, [re2 syntax regex may be used][google_re2_syntax_docs] + +**Args** +* `regex`: The regex expression that will be used to match in the log lines + +**Returns** +* `logLineFilter`: The does-not-contain-regex-match log line filter + +Enclaves +-------- + +This Kurtosis provided class is a collection of various different [EnclaveInfo][enclaveinfo] objects, by UUID, shortened UUID, and name. + +### Map `enclavesByUuid` + +A map from UUIDs to the enclave info for the enclave with the given UUID. + +### Map `enclavesByName` + +A map from names to the enclave info for the enclave with the given name + +### Map `enclavesByShortenedUuid` + +A map from shortened UUID (first 12 characters of UUID) to the enclave infos of the enclaves it matches too. + +EnclaveInfo +----------- + +This Kurtosis provided class contains information about enclaves. This class just contains data and no methods to manipulate enclaves. Users must use [EnclaveContext][enclavecontext] to modify the state of an enclave. + +### `getEnclaveUuid() -> EnclaveUuid` +Gets the UUID of the enclave that this [EnclaveInfo][enclaveinfo] object represents. + +### `getShortenedUuid() -> String` +Gets the shortened UUID of the enclave that this [EnclaveInfo][enclaveinfo] object represents. + +### `getName() -> String` +Gets the name of the enclave that this [EnclaveInfo][enclaveinfo] object represents. + +### `getCreationTime() -> Timestamp` +Gets the timestamp at which the enclave that this [EnclaveInfo][enclaveinfo] object represents was created. + +### `getCreationTime() -> Timestamp` +Gets the timestamp at which the enclave that this [EnclaveInfo][enclaveinfo] object represents was created. + +### `getContainersStatus() -> Status` +Gets the current status of the container running the enclave represented by this [EnclaveInfo][enclaveinfo]. Is one of 'EMPTY', 'RUNNING' and 'STOPPED'. + +EnclaveContext +-------------- +This Kurtosis-provided class is the lowest-level representation of a Kurtosis enclave, and provides methods for inspecting and manipulating the contents of the enclave. + +### `getEnclaveUuid() -> EnclaveUuid` +Gets the UUID of the enclave that this [EnclaveContext][enclavecontext] object represents. + +### `getEnclaveName() -> String` +Gets the name of the enclave that this [EnclaveContext][enclavecontext] object represents. + +### `runStarlarkScript(String mainFunctionName, String serializedStarlarkScript, Boolean dryRun) -> (Stream responseLines, Error error)` + +Run a provided Starlark script inside the enclave. + +**Args** + +* `mainFunctionName`: The main function name, an empty string can be passed to use the default value 'run' +* `serializedStarlarkScript`: The Starlark script provided as a string +* `dryRun`: When set to true, the Kurtosis instructions are not executed. + +**Returns** + +* `responseLines`: A stream of [StarlarkRunResponseLine][starlarkrunresponseline] objects + +### `runStarlarkPackage(String packageRootPath, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun) -> (Stream responseLines, Error error)` + +Run a provided Starlark script inside the enclave. + +**Args** + +* `packageRootPath`: The path to the root of the package +* `relativePathToMainFile`: The relative filepath (relative to the package's root) to the main file, and empty string can be passed to use the default value 'main.star'. Example: if your main file is located in a path like this `github.com/my-org/my-package/src/internal/my-file.star` you should set `src/internal/my-file.star` as the relative path. +* `mainFunctionName`: The main function name, an empty string can be passed to use the default value 'run'. +* `serializedParams`: The parameters to pass to the package for the run. It should be a serialized JSON string. +* `dryRun`: When set to true, the Kurtosis instructions are not executed. + +**Returns** + +* `responseLines`: A stream of [StarlarkRunResponseLine][starlarkrunresponseline] objects + +### `runStarlarkRemotePackage(String packageId, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun) -> (Stream responseLines, Error error)` + +Run a Starlark script hosted in a remote github.com repo inside the enclave. + +**Args** + +* `packageId`: The ID of the package pointing to the github.com repo hosting the package. For example `github.com/kurtosistech/datastore-army-package` +* `relativePathToMainFile`: The relative filepath (relative to the package's root) to the main file, and empty string can be passed to use the default value 'main.star'. Example: if your main file is located in a path like this `github.com/my-org/my-package/src/internal/my-file.star` you should set `src/internal/my-file.star` as the relative path. +* `mainFunctionName`: The main function name, an empty string can be passed to use the default value 'run'. +* `serializedParams`: The parameters to pass to the package for the run. It should be a serialized JSON string. +* `dryRun`: When set to true, the Kurtosis instructions are not executed. + +**Returns** + +* `responseLines`: A stream of [StarlarkRunResponseLine][starlarkrunresponseline] objects + +### `runStarlarkScriptBlocking(String mainFunctionName, String serializedStarlarkScript, Boolean dryRun) -> (StarlarkRunResult runResult, Error error)` + +Convenience wrapper around [EnclaveContext.runStarlarkScript][enclavecontext_runstarlarkscript], that blocks until the execution of the script is finished and returns a single [StarlarkRunResult][starlarkrunresult] object containing the result of the run. + +### `runStarlarkPackageBlocking(String packageRootPath, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun) -> (StarlarkRunResult runResult, Error error)` + +Convenience wrapper around [EnclaveContext.runStarlarkPackage][enclavecontext_runstarlarkpackage], that blocks until the execution of the package is finished and returns a single [StarlarkRunResult][starlarkrunresult] object containing the result of the run. + +### `runStarlarkRemotePackageBlocking(String packageId, String relativePathToMainFile, String mainFunctionName, String serializedParams, Boolean dryRun) -> (StarlarkRunResult runResult, Error error)` + +Convenience wrapper around [EnclaveContext.runStarlarkRemotePackage][enclavecontext_runstarlarkremotepackage], that blocks until the execution of the package is finished and returns a single [StarlarkRunResult][starlarkrunresult] object containing the result of the run. + +### `getServiceContext(String serviceIdentifier) -> ServiceContext serviceContext` +Gets relevant information about a service (identified by the given service [identifier][identifier]) that is running in the enclave. + +**Args** + +* `serviceIdentifier`: The [identifier(name, UUID or short name)][identifier] of the target service + +**Returns** + +The [ServiceContext][servicecontext] representation of a service running in a Docker container. + +### `getServices() -> Map serviceIdentifiers` +Gets the Name and UUID of the current services in the enclave. + +**Returns** + +* `serviceIdentifiers`: A map of objects containing a mapping of Name -> UUID for all the services inside the enclave + +### `uploadFiles(String pathToUpload, String artifactName) -> FilesArtifactUUID, FilesArtifactName, Error` +Uploads a filepath or directory path as a [files artifact](./concepts-reference/files-artifacts.md). The resulting files artifact can be used in [`ServiceConfig.files`](./starlark-reference/service-config.md) when adding a service. + +If a directory is specified, the contents of the directory will be uploaded to the archive without additional nesting. Empty directories cannot be uploaded. + +**Args** + +* `pathToUpload`: Filepath or dirpath on the local machine to compress and upload to Kurtosis. +* `artifactName`: The name to refer the artifact with. + +**Returns** + +* `FilesArtifactUUID`: A UUID identifying the new files artifact, which can be used in [`ServiceConfig.files`](./starlark-reference/service-config.md). +* `FilesArtifactName`: The name of the file-artifact, it is auto-generated if `artitfactName` is an empty string. + +### `storeWebFiles(String urlToDownload, String artifactName)` +Downloads a files-containing `.tgz` from the given URL as a [files artifact](./concepts-reference/files-artifacts.md). The resulting files artifact can be used in [`ServiceConfig.files`](./starlark-reference/service-config.md) when adding a service. + +**Args** + +* `urlToDownload`: The URL on the web where the files-containing `.tgz` should be downloaded from. +* `artifactName`: The name to refer the artifact with. + +**Returns** + +* `UUID`: A UUID identifying the new files artifact, which can be used in [`ServiceConfig.files`](./starlark-reference/service-config.md). + +### `getExistingAndHistoricalServiceIdentifiers() -> ServiceIdentifiers serviceIdentifiers` + +Get all (active & deleted) historical [identifiers][identifier] for services for the enclave represented by the [EnclaveContext][enclavecontext]. + +**Returns** +* `serviceIdentifiers`: The [ServiceIdentifiers][service-identifiers] which provides user-friendly ways to lookup service identifier information. + +### `getAllFilesArtifactNamesAndUuids() -> []FilesArtifactNameAndUuid filesArtifactNamesAndUuids` + +Get a list of all files artifacts that are registered with the enclave represented by the [EnclaveContext][enclavecontext] + +**Returns** +* `filesArtifactNameAndUuids`: A list of files artifact names and their corresponding uuids. + +ServiceIdentifiers +------------------- +This class is a representation of service identifiers for a given enclave. + +### `getServiceUuidForIdentifier(string identifier) -> ServiceUUID serviceUUID, Error` +Returns the UUID that matches the given identifier. If there are no matches it returns +an error instead. + +**Args** +* `identifier`: A service identifier string + +**Returns** +* `enclaveUuid`: The UUID for the service identified by the `identifier`. + +### `getOrderedListOfNames() -> []String serviceNames` +Returns an ordered list of names for all the services in the enclave. This is useful +if users want to enumerate all service names, say for an autocomplete like function. + +**Returns** +* `serviceNames`: This is a sorted list of service names + +StarlarkRunResponseLine +----------------------- + +This is a union object representing a single line returned by Kurtosis' Starlark runner. All Starlark run endpoints will return a stream of this object. + +Each line is one of: + +### [StarlarkInstruction][starlarkinstruction] `instruction` +An instruction that is _about to be_ executed. + +### [StarlarkInstructionResult][starlarkinstructionresult] `instructionResult` +The result of an instruction that was successfully executed + +### [StarlarkError][starlarkerror] `error` +The error that was thrown running the Starlark code + +### [StarlarkRunProgress][starlarkrunprogress] `progressInfo` +Regularly during the run of the code, Kurtosis' Starlark engine will send progress information through the stream to account for progress that was made running the code. + +StarlarkInstruction +------------------- + +`StarlarkInstruction` represents a Starlark instruction that is currently being executed. It contains the following fields: + +* `instructionName`: the name of the instruction + +* `instructionPosition`: the position of the instruction in the source code. It iscomposed of (filename, line number, column number) + +* `arguments`: The list of arguments provided to this instruction. Each argument is composed of an optional name (if it was named in the source script) and its serialized value + +* `executableInstruction`: A single string representing the instruction in valid Starlark code + +StarlarkInstructionResult +------------------------- + +`StarlarkInstructionResult` is the result of an instruction that was successfully run against Kurtosis engine. It is a single string field corresponding to the output of the instruction. + +StarlarkError +------------- + +Errors can be of three kind: + +* Interpretation error: these errors happens before Kurtosis was able to execute the script. It typically means there's a syntax error in the provided Starlark code. The error message should point the users to where the code is incorrect. + +* Validation error: these errors happens after interpretation was successful, but before the execution actually started in Kurtosis. Before starting the execution, Kurtosis runs some validation on the instructions that are about to be executed. The error message should contain more information on which instruction is incorrect. + +* Execution error: these errors happens during the execution of the script against Kurtosis engine. More information is available in the error message. + +StarlarkRunProgress +------------------- + +`StarlarkRunProgress` accounts for progress that is made during a Starlark run. It contains three fields: + +* `totalSteps`: The total number of steps for this run + +* `currentStepNumber`: The number of the step that is currently being executed + +* `currentStepInfo`: A string field with some information on the current step being executed. + +StarlarkRunResult +----------------- + +`StarlarkRunResult` is the object returned by the blocking functions to run Starlark code. It is similar to [StarlarkRunResponseLine][starlarkrunresponseline] except that it is not a union object: + +* `instructions`: the [Starlark Instruction][starlarkinstruction] that were run + +* `insterpretationError`: a potential Starlark Interpretation error (see [StarlarkError][starlarkerror] + +* `validationErrors`: potential Starlark Validation errors (see [StarlarkError][starlarkerror] + +* `executionError`: a potential Starlark Execution error (see [StarlarkError][starlarkerror] + +* `runOutput`: The full output of the run, composed of the concatenated output for each instruction that was executed (separated by a newline) + +ServiceContext +-------------- +This Kurtosis-provided class is the lowest-level representation of a service running inside a Docker container. It is your handle for retrieving container information and manipulating the container. + +### `getServiceName() -> ServiceName` +Gets the Name that Kurtosis uses to identify the service. + +**Returns** + +The service's Name. + +### `getServiceUuid() -> ServiceUUID` +Gets the UUID (Universally Unique Identifier) that Kurtosis creates and uses to identify the service. +The differences with the Name is that this one is created by Kurtosis, users can't specify it, and this never can be repeated, every new execution of the same service will have a new UUID + +**Returns** + +The service's UUID. + +### `getPrivateIpAddress() -> String` +Gets the IP address where the service is reachable at from _inside_ the enclave that the container is running inside. This IP address is how other containers inside the enclave can connect to the service. + +**Returns** + +The service's private IP address. + +### `getPrivatePorts() -> Map` +Gets the ports that the service is reachable at from _inside_ the enclave that the container is running inside. These ports are how other containers inside the enclave can connect to the service. + +**Returns** + +The ports that the service is reachable at from inside the enclave, identified by the user-chosen port ID set in [`ServiceConfig.ports`](./starlark-reference/service-config.md) when the service was created. + +### `getMaybePublicIpAddress() -> String` +If the service declared used ports in [`ServiceConfig.ports`](./starlark-reference/service-config.md), then this function returns the IP address where the service is reachable at from _outside_ the enclave that the container is running inside. This IP address is how clients on the host machine can connect to the service. If no used ports were declared, this will be empty. + +**Returns** + +The service's public IP address, or an empty value if the service didn't declare any used ports. + +### `getPublicPorts() -> Map` +Gets the ports that the service is reachable at from _outside_ the enclave that the container is running inside. These ports are how clients on the host machine can connect to the service. If the service didn't declare any used ports in [`ServiceConfig.ports`](./starlark-reference/service-config.md), this value will be an empty map. + +**Returns** + +The ports (if any) that the service is reachable at from outside the enclave, identified by the user-chosen ID set in [`ServiceConfig.ports`](./starlark-reference/service-config.md) when the service was created. + +### `execCommand(List command) -> (int exitCode, String logs)` +Uses [Docker exec](https://docs.docker.com/engine/reference/commandline/exec/) functionality to execute a command inside the service's running Docker container. + +**Args** + +* `command`: The args of the command to execute in the container. + +**Returns** + +* `exitCode`: The exit code of the command. +* `logs`: The output of the run command, assuming a UTF-8 encoding. **NOTE:** Commands that output non-UTF-8 output will likely be garbled! + + + + + + +[kurtosis-client-libs]: https://github.com/kurtosis-tech/kurtosis/tree/main/api + +[servicelogsstreamcontent]: #servicelogsstreamcontent +[servicelog]: #servicelog + +[enclavecontext]: #enclavecontext +[enclavecontext_runstarlarkscript]: #runstarlarkscriptstring-mainfunctionname-string-serializedstarlarkscript-boolean-dryrun---streamstarlarkrunresponseline-responselines-error-error +[enclavecontext_runstarlarkpackage]: #runstarlarkscriptstring-mainfunctionname-string-serializedstarlarkscript-boolean-dryrun---streamstarlarkrunresponseline-responselines-error-error +[enclavecontext_runstarlarkremotepackage]: #runstarlarkscriptstring-mainfunctionname-string-serializedstarlarkscript-boolean-dryrun---streamstarlarkrunresponseline-responselines-error-error + +[starlarkrunresponseline]: #starlarkrunresponseline +[starlarkinstruction]: #starlarkinstruction +[starlarkinstructionresult]: #starlarkinstructionresult +[starlarkerror]: #starlarkerror +[starlarkrunprogress]: #starlarkrunprogress +[starlarkrunresult]: #starlarkrunresult + +[servicecontext]: #servicecontext +[servicecontext_getpublicports]: #getpublicports---mapportid-portspec + +[loglinefilter]: #loglinefilter +[google_re2_syntax_docs]: https://github.com/google/re2/wiki/Syntax + +[enclaveinfo]: #enclaveinfo +[enclaves]: #enclaves + +[identifier]: ./concepts-reference/resource-identifier.md +[enclave-identifiers]: #enclaveidentifiers +[service-identifiers]: #serviceidentifiers diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/args.md b/docs/versioned_docs/version-0.78.3/starlark-reference/args.md new file mode 100644 index 0000000000..0ab714b614 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/args.md @@ -0,0 +1,9 @@ +--- +title: Args +sidebar_label: Args +--- + +The value of the `args` variable in a `run(plan, args)` definition contains the JSON-deserialized argument values passed in to `kurtosis run`. Read about how it works [here][args-concepts-reference]. + + +[args-concepts-reference]: ../concepts-reference/args.md diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/connection-config.md b/docs/versioned_docs/version-0.78.3/starlark-reference/connection-config.md new file mode 100644 index 0000000000..750f11fb65 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/connection-config.md @@ -0,0 +1,31 @@ +--- +title: ConnectionConfig +sidebar_label: ConnectionConfig +--- + +The `ConnectionConfig` is used to configure a connection between two [subnetworks][subnetworks-reference] (see [set_connection][set-connection-reference]). + +```python +connection_config = ConnectionConfig( + # Percentage of packet lost each way between subnetworks + # OPTIONAL + # DEFAULT: 0.0 + packet_loss_percentage = 50.0, + + # Amount of delay added to packets each way between subnetworks + # OPTIONAL: Valid value are UniformPacketDelayDistribution or NormalPacketDelayDistribution + packet_delay_distribution = UniformPacketDelayDistribution( + # Delay in ms + ms = 500, + ), +) +``` + +:::tip +See [`kurtosis.connection`][connection-prebuilt-enums] for pre-built `ConnectionConfig` objects +::: + + +[subnetworks-reference]: ../concepts-reference/subnetworks.md +[set-connection-reference]: ./plan.md#set_connection +[connection-prebuilt-enums]: ./kurtosis.md#connection diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/exec-recipe.md b/docs/versioned_docs/version-0.78.3/starlark-reference/exec-recipe.md new file mode 100644 index 0000000000..0bf1575e00 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/exec-recipe.md @@ -0,0 +1,39 @@ +--- +title: ExecRecipe +sidebar_label: ExecRecipe +--- + +The ExecRecipe can be used to run the `command` on the service (see [exec][exec-reference] +or [wait][wait-reference]) + +```python +exec_recipe = ExecRecipe( + # The actual command to execute. + # Each item corresponds to one shell argument, so ["echo", "Hello world"] behaves as if you ran "echo 'Hello World'" in the shell. + # MANDATORY + command = ["echo", "Hello, World"], + + # The extract dictionary can be used for filtering specific parts of a response + # assigning that output to a key-value pair, where the key is the reference + # variable and the value is the specific output. + # + # Specifcally: the key is the way you refer to the extraction later on and + # the value is a 'jq' string that contains logic to extract parts from response + # body that you get from the exec_recipe used + # + # To lean more about jq, please visit https://devdocs.io/jq/ + # OPTIONAL (DEFAULT:{}) + extract = { + "extractfield" : ".name.id", + }, +) +``` + +:::tip +If you are trying to run a complex `command` with `|`, you should prefix the command with `/bin/sh -c` and wrap the actual command in a string; for example: `command = ["echo", "a", "|", "grep a"]` should +be rewritten as `command = ["/bin/sh", "-c", "echo a | grep a"]`. Not doing so makes everything after the `echo` as args of that command, instead of following the behavior you would expect from a shell. +::: + + +[exec-reference]: ./plan.md#exec +[wait-reference]: ./plan.md#wait diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/get-http-request-recipe.md b/docs/versioned_docs/version-0.78.3/starlark-reference/get-http-request-recipe.md new file mode 100644 index 0000000000..049c0dbee9 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/get-http-request-recipe.md @@ -0,0 +1,63 @@ +--- +title: GetHttpRequestRecipe +sidebar_label: GetHttpRequestRecipe +--- + +The `GetHttpRequestRecipe` can be used to make `GET` requests to an endpoint, filter for the specific part of the response you care about, and assign that specific output to a key for later use. This can be useful for writing assertions, for example (i.e. validating the response you end up receiving looks the way you expect/intended). + +```python +get_request_recipe = GetHttpRequestRecipe( + # The port ID that is the server port for the request + # MANDATORY + port_id = "my_port", + + # The endpoint for the request + # MANDATORY + endpoint = "/endpoint?input=data", + + # The extract dictionary can be used for filtering specific parts of a HTTP GET + # request and assigning that output to a key-value pair, where the key is the + # reference variable and the value is the specific output. + # + # Specifcally: the key is the way you refer to the extraction later on and + # the value is a 'jq' string that contains logic to extract parts from response + # body that you get from the HTTP GET request. + # + # To lean more about jq, please visit https://devdocs.io/jq/ + # OPTIONAL (DEFAULT:{}) + extract = { + "extractfield" : ".name.id", + }, +) +``` + +:::info +Important - the `port_id` field accepts user-defined port IDs that are assigned to a port in a service's port map, using `ServiceConfig`. For example, if our service's `ServiceConfig` has the following port mappings: + +``` + test-service-config = ServiceConfig( + ports = { + // "port_id": port_number + "http": 5000, + "grpc": 3000, + ... + }, + ... + ) +``` + +The user-defined port IDs in the above `ServiceConfig` are: `http` and `grpc`. Both of these user-defined port IDs can therefore be used to create http request recipes (`GET` OR `POST`), such as: + +``` + recipe = GetHttpRequestRecipe( + port_id = "http", + service_name = "service-using-test-service-config", + endpoint = "/ping", + ... + ) +``` + +The above recipe, when used with `request` or `wait` instruction, will make a `GET` request to a service (the `service_name` field must be passed as an instruction's argument) on port `5000` with the path `/ping`. +::: + + diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/import-module.md b/docs/versioned_docs/version-0.78.3/starlark-reference/import-module.md new file mode 100644 index 0000000000..8662b39212 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/import-module.md @@ -0,0 +1,24 @@ +--- +title: import_module +sidebar_label: import_module +--- + + +The `import_module` function imports the symbols from a Starlark script specified by the given [locator][locators-reference], and requires that the calling Starlark script is part of a [package][packages-reference]. + +```python +# Import the code to namespaced object +lib = import_module("github.com/foo/bar/src/lib.star") + +# Use code from the imported module +lib.some_function() +lib.some_variable +``` + +NOTE: We chose not to use the normal Starlark `load` primitive due to its lack of namespacing. By default, the symbols imported by `load` are imported to the global namespace of the script that's importing them. We preferred module imports to be namespaced, in the same way that Python does by default with its `import` statement. + + + + +[packages-reference]: ../concepts-reference/packages.md +[locators-reference]: ../concepts-reference/locators.md diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/index.md b/docs/versioned_docs/version-0.78.3/starlark-reference/index.md new file mode 100644 index 0000000000..a62127dfae --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/index.md @@ -0,0 +1,61 @@ +--- +id: index +title: Starlark Introduction +sidebar_label: Introduction +slug: /starlark-reference +sidebar_position: 1 +--- + +This section details the Kurtosis Starlark DSL used to manipulate the contents of enclaves. Feel free to use the [official Kurtosis Starlark VS Code extension][vscode-plugin] when writing Starlark with VSCode for features like syntax highlighting, method signature suggestions, hover preview for functions, and auto-completion for Kurtosis custom types. + +Parameter Naming Convention +--------------------------- + +In Python, it is very common to name function parameters that are optional. E.g.: + +```python +def do_something(required_arg, optional_arg="default_value") +``` + +In Kurtosis Starlark, all parameters can be referenced by name regardless of whether they are required or not. We do this to allow for ease-of-reading clarity. Mandatory and optional parameters will be indicated in the comment above the field. Example: + +```python +def make_pizza( + # If true, the crust will be thin; if false, the crust will be regular + # MANDATORY + thin_crust = True, +) +``` + +Similarly, all function arguments can be provided either positionally or by name. + +For example, this function... + +```python +def make_pizza(size, topping = "pepperoni") +``` + +...can be called in any of the following ways: + +```python +# 1. Only the required argument filled, positionally +make_pizza("16cm") + +# 2. Only the required argument filled, by name +make_pizza(size = "16cm") + +# 3. Both arguments filled, positionally +make_pizza("16cm", "mushroom") + +# 4. Both arguments filled, mixing position and name +make_pizza("16cm", topping = "mushroom") + +# 5. Both arguments filled, by name +make_pizza(size = "16cm", topping = "mushroom") +``` + +We recommend the last style (naming both positional and optional args), for reading clarity. + + + +[vscode-plugin]: https://marketplace.visualstudio.com/items?itemName=Kurtosis.kurtosis-extension diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/kurtosis.md b/docs/versioned_docs/version-0.78.3/starlark-reference/kurtosis.md new file mode 100644 index 0000000000..734aff7e8d --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/kurtosis.md @@ -0,0 +1,21 @@ +--- +title: kurtosis +sidebar_label: kurtosis +--- + +The `kurtosis` object is an object available in every Kurtosis script that contains prebuilt constants that you might find useful. Each section here represents a property of the `kurtosis` object (e.g. `kurtosis.connection`). + +connection +---------- + +#### `ALLOWED` + +`kurtosis.connection.ALLOWED` is equivalent to [ConnectionConfig][connection-config] with `packet_loss_percentage` set to `0` and `packet_delay` set to `PacketDelay(delay_ms=0)`. It represents a [ConnectionConfig][connection-config] that _allows_ all connection between two [subnetworks][subnetworks-reference] with no delay and packet loss. + +#### `BLOCKED` + +`kurtosis.connection.BLOCKED` is equivalent to [ConnectionConfig][connection-config] with `packet_loss_percentage` set to `100` and `packet_delay` set to `PacketDelay(delay_ms=0)`. It represents a [ConnectionConfig][connection-config] that _blocks_ all connection between two [subnetworks][subnetworks-reference]. + + +[connection-config]: ./connection-config.md +[subnetworks-reference]: ../concepts-reference/subnetworks.md diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/normal-packet-delay-distribution.md b/docs/versioned_docs/version-0.78.3/starlark-reference/normal-packet-delay-distribution.md new file mode 100644 index 0000000000..9ee4c954c3 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/normal-packet-delay-distribution.md @@ -0,0 +1,33 @@ +--- +title: NormalPacketDelayDistribution +sidebar_label: NormalPacketDelayDistribution +--- + +The `NormalPacketDelayDistribution` creates a packet delay distribution that follows a normal distribution. This can be used in conjunction with [`ConnectionConfig`][connection-config] to introduce latency between two [`subnetworks`][subnetworks-reference]. See [`set_connection`][set-connection-reference] instruction to learn more about its usage. + +```python + +delay = NormalPacketDelayDistribution( + # Non-Negative Integer + # Amount of mean delay added to outgoing packets from the subnetwork + # MANDATORY + mean_ms = 1000, + + # Non-Negative Integer + # Amount of variance (jitter) added to outgoing packets from the subnetwork + # MANDATORY + std_dev_ms = 10, + + # Non-Negative Float + # Percentage of correlation observed among packets. It means that the delay observed in next packet + # will exhibit a corrlation factor of 10.0% with the previous packet. + # OPTIONAL + # DEFAULT = 0.0 + correlation = 10.0, +) +``` + + +[connection-config]: ./connection-config.md +[subnetworks-reference]: ../concepts-reference/subnetworks.md +[set-connection-reference]: ./plan.md#set_connection diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/plan.md b/docs/versioned_docs/version-0.78.3/starlark-reference/plan.md new file mode 100644 index 0000000000..7edabede6b --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/plan.md @@ -0,0 +1,619 @@ +--- +title: Plan +sidebar_label: Plan +--- + +The `Plan` object is an object representing the steps that Kurtosis will take inside the enclave during [the Execution phase][multi-phase-runs-reference]. + +Kurtosis injects a `Plan` object into the `run` function in the `main.star` of your Starlark script. Kurtosis relies on the first argument of your `run` function being named `plan` (lowercase); all your Starlark scripts must follow this convention. + +To use the `Plan` object in inner functions, simply pass the variable down. + +Note that the function calls listed here merely add a step to the plan. They do _not_ run the actual execution. Per Kurtosis' [multi-phase run design][multi-phase-runs-reference], this will only happen during the Execution phase. Therefore, all plan functions will return [future references][future-references-reference]. + +add_service +----------- + +The `add_service` instruction adds a service to the Kurtosis enclave within which the script executes, and returns a [`Service`][service-starlark-reference] object containing information about the newly-added service. + +```python +# Returns a Service object (see the Service page in the sidebar) +service = plan.add_service( + # The service name of the service being created. + # The service name is a reference to the service, which can be used in the future to refer to the service. + # Service names of active services are unique per enclave. + # MANDATORY + name = "example-datastore-server-1", + + # The configuration for this service, as specified via a ServiceConfig object (see the ServiceConfig page in the sidebar) + # MANDATORY + config = service_config, +) +``` + +For detailed information about the parameters the `config` argument accepts, see [ServiceConfig][starlark-types-service-config]. + +For detailed information about what `add_service` returns, see [Service][service-starlark-reference]. + +Example: + +```python +dependency = plan.add_service( + name = "dependency", + config = ServiceConfig( + image = "dependency", + ports = { + "http": PortSpec(number = 80), + }, + ), +) + +dependency_http_port = dependency.ports["http"] + +plan.add_service( + name = "dependant", + config = ServiceConfig( + env_vars = { + "DEPENDENCY_URL": "http://{}:{}".format(dependency.ip_address, dependency_http_port.number), + }, + ), +) +``` + +add_services +------------ + +The `add_services` instruction behaves like `add_service`, but adds the services in parallel. + +The default parallelism is 4, but this can be increased using [the `--parallelism` flag of the `run` CLI command][cli-run-reference]. + +`add_services` takes a dictionary of service names -> [`ServiceConfig`][starlark-types-service-config] objects as input, and returns a dictionary +of service names -> [`Service`][service-starlark-reference] objects. + +```python +all_services = plan.add_services( + # A map of service_name -> ServiceConfig for all services that needs to be added. + # See the 'ServiceConfig' page in the sidebar for more information on this type. + # MANDATORY + configs = { + "example-datastore-server-1": datastore_server_config_1, + "example-datastore-server-2": datastore_server_config_2, + }, +) +``` + +For detailed information about the `ServiceConfig` object, see [here][starlark-types-service-config]. + +For detailed information about the `Service` objects that `add_services`, see [Service][service-starlark-reference]. + + +:::caution + +`add_services` will succeed if and only if all services are successfully added. If any one fails (perhaps due to timeouts a ready condition failing), the entire batch of +services will be rolled back and the instruction will return an execution error. + +::: + +assert +------ + +The `assert` instruction throws an [Execution phase error][multi-phase-runs-reference] if the defined assertion fails. + +```python +plan.assert( + # The value currently being asserted. + # MANDATORY + value = "test1", + + # The assertion is the comparison operation between value and target_value. + # Valid values are "==", "!=", ">=", "<=", ">", "<" or "IN" and "NOT_IN" (if target_value is list). + # MANDATORY + assertion = "==", + + # The target value that value will be compared against. + # MANDATORY + target_value = "test2", +) # This fails in runtime given that "test1" == "test2" is false + +plan.assert( + # Value can also be a runtime value derived from a `get_value` call + value = response["body"], + assertion = "==", + target_value = 200, +) +``` + +:::caution + +Asserts are typed, so running + +```python +plan.assert( + value = "0", + assertion = "==", + target_value = 0, +) +``` + +Will fail. If needed, you can use the `extract` feature to parse the types of your outputs. +::: + +exec +---- + +The `exec` instruction executes a command on a container as if they were running in a shell on the container. + +```python +exec_recipe = ExecRecipe( + # The actual command to execute. + # Each item corresponds to one shell argument, so ["echo", "Hello world"] behaves as if you ran "echo" "Hello world" in the shell. + # MANDATORY + command = ["echo", "Hello, world"], +) + +result = plan.exec( + # A Service name designating a service that already exists inside the enclave + # If it does not, a validation error will be thrown + # MANDATORY + service_name = "my-service", + + # The recipe that will determine the exec to be performed. + # Valid values are of the following types: (ExecRecipe) + # MANDATORY + recipe = exec_recipe, + + # If the recipe returns a code that does not belong on this list, this instruction will fail. + # OPTIONAL (Defaults to [0]) + acceptable_codes = [0, 0], # Here both 0 and 1 are valid codes that we want to accept and not fail the instruction + + # If False, instruction will never fail based on code (acceptable_codes will be ignored). + # You can chain this call with assert to check codes after request is done. + # OPTIONAL (Defaults to False) + skip_code_check = False, +) + +plan.print(result["output"]) +plan.print(result["code"]) +``` + +The instruction returns a `dict` whose values are [future reference][future-references-reference] to the output and exit code of the command. `result["output"]` is a future reference to the output of the command, and `result["code"]` is a future reference to the exit code. + +They can be chained to [`assert`][assert] and [`wait`][wait]: + +```python +exec_recipe = ExecRecipe( + command = ["echo", "Hello, world"], +) + +result = plan.exec(service_name="my_service", recipe=exec_recipe) +plan.assert(result["code"], "==", 0) + +plan.wait(service_name="my_service", recipe=exec_recipe, field="output", assertion="!=", target_value="Greetings, world") +``` + +print +----- + +The `print` instruction will print a value during [the Execution phase][multi-phase-runs-reference]. When the `print` instruction is executed during the Execution Phase, [future references][future-references-reference] will be replaced with their execution-time values. + +``` +plan.print("Any string here") +``` + + +remove_connection +----------------- + +As opposed to `set_connection`, `remove_connection` removes a connection override between two [subnetworks][subnetworks-reference]. The default connection cannot be removed; it can only be updated using [set_connection][set-connection]. + +```python +remove_connection( + # The subnetwork connection that will be removed + # If any of those two subnetworks does not currently have services, this instruction will not do anything. + # MANDATORY + subnetworks = ("subnetwork_1", "subnetwork_2"), + +) +``` + +remove_service +-------------- + +The `remove_service` instruction removes a service from the enclave in which the instruction executes in. + +```python +plan.remove_service( + # The service name of the service to be removed. + # MANDATORY + name = "my_service", +) +``` + +render_templates +---------------- + +The `render_templates` instruction combines a template and data to produce a [files artifact][files-artifacts-reference]. Files artifacts can be used with the `files` property of the `ServiceConfig` object, allowing for reuse of config files across services. + +```python +# Example data to slot into the template +template_data = { + "Name" : "Stranger", + "Answer": 6, + "Numbers": [1, 2, 3], + "UnixTimeStamp": 1257894000, + "LargeFloat": 1231231243.43, + "Alive": True, +} + +artifact_name = plan.render_templates( + # A dictionary where: + # - Each key is a filepath that will be produced inside the output files artifact + # - Each value is the template + data required to produce the filepath + # Multiple filepaths can be specified to produce a files artifact with multiple files inside. + # MANDATORY + config = { + "/foo/bar/output.txt": struct( + # The template to render, which should be formatted in Go template format: + # https://pkg.go.dev/text/template#pkg-overview + # MANDATORY + template="Hello {{.Name}}. The sum of {{.Numbers}} is {{.Answer}}. My favorite moment in history {{.UnixTimeStamp}}. My favorite number {{.LargeFloat}}. Am I Alive? {{.Alive}}", + + # The data to slot into the template, can be a struct or a dict + # The keys should exactly match the keys in the template. + # MANDATORY + data=template_data, + ), + }, + + # The name to give the files artifact that will be produced. + # If not specified, it will be auto-generated. + # OPTIONAL + name = "my-artifact", +) +``` + +The return value is a [future reference][future-references-reference] to the name of the [files artifact][files-artifacts-reference] that was generated, which can be used with the `files` property of the service config of the `add_service` command. + +request +------- + +The `request` instruction executes either a POST or GET HTTP request, saving its result in a [future references][future-references-reference]. + +To make a GET or POST request, simply set the `recipe` field to use the specified [GetHttpRequestRecipe][starlark-types-get-http-recipe] or the [PostHttpRequestRecipe][starlark-types-post-http-recipe]. + +```python +http_response = plan.request( + # A service name designating a service that already exists inside the enclave + # If it does not, a validation error will be thrown + # MANDATORY + service_name = "my_service", + + # The recipe that will determine the request to be performed. + # Valid values are of the following types: (GetHttpRequestRecipe, PostHttpRequestRecipe) + # MANDATORY + recipe = request_recipe, + + # If the recipe returns a code that does not belong on this list, this instruction will fail. + # OPTIONAL (Defaults to [200, 201, ...]) + acceptable_codes = [200, 500], # Here both 200 and 500 are valid codes that we want to accept and not fail the instruction + + # If False, instruction will never fail based on code (acceptable_codes will be ignored). + # You can chain this call with assert to check codes after request is done. + # OPTIONAL (defaults to False) + skip_code_check = false, +) +plan.print(get_response["body"]) # Prints the body of the request +plan.print(get_response["code"]) # Prints the result code of the request (e.g. 200, 500) +plan.print(get_response["extract.extracted-field"]) # Prints the result of running ".name.id" query, that is saved with key "extracted-field" +``` + +The instruction returns a response, which is a `dict` with following key-value pair; the values are a [future reference][future-references-reference] +* `response["code"]` - returns the future reference to the `status code` of the response +* `response["body"]` - returns the future reference to the `body` of the the response +* `response["extract.some-custom-field"]` - it is an optional field and returns the future reference to the value extracted from `body`, which is explained below. + +#### extract + +`jq`'s [regular expressions](https://stedolan.github.io/jq/manual/) is used to extract the information from the response `body` and is assigned to a custom field. **The `response["body"]` must be a valid json object for manipulating data using `extractions`**. A valid `response["body"]` can be used for extractions. See below for an example of how this can be done for the [PostHttpRequestRecipe][starlark-types-post-http-recipe]: + + ```python + # Assuming response["body"] looks like {"result": {"foo": ["hello/world/welcome"]}} +post_request_recipe = PostHttpRequestRecipe( + ... + extract = { + "second-element-from-list-head": '.result.foo | .[0] | split ("/") | .[1]', + }, +) +post_response = plan.request( + service_name = "my_service", + recipe = post_request_recipe, +) +# response["extract.second-element-from-list-head"] is "world" +# response["body"] is {"result": {"foo": ["hello/world/welcome"]}} +# response["code"] is 200 +``` + +NOTE: In the above example, `response` also has a custom field `extract.second-element-from-list-head` and the value is `world` which is extracted from the `response[body]`. + +These fields can be used in conjunction with [`assert`][assert] and [`wait`][wait] instructions, like so: +```python +# Following the example above, response["extract.second-element-from-list-head"] is world +post_response = plan.request( + service_name = "my_service", + recipe = post_request_recipe, +) + +# Assert if the extracted field in the response is world +plan.assert(response["extract.second-element-from-list-head"], "==", "world") + +# Make a post request and check if the extracted field in the response is world +plan.wait(service_name="my_service", recipe=post_request_recipe, field="extract.second-element-from-list-head", assertion="==", target_value="world") +``` + +NOTE: `jq` returns a typed output that translates into the correspondent Starlark type. You can cast it using `jq` to match +your desired output type: + +```python +# Assuming response["body"] looks like {"url": "posts/1"}} +post_request_recipe = PostHttpRequestRecipe( + ... + extract = { + "post-number": '.url | split ("/") | .[1]', + "post-number-as-int": '.url | split ("/") | .[1] | tonumber', + }, +) +response = plan.request( + service_name = "my_service", + recipe = post_request_recipe, +) +# response["extract.post-number"] is "1" (starlark.String) +# response["extract.post-number-as-int"] is 1 (starlark.Int) +``` + +For more details see [ `jq`'s builtin operators and functions](https://stedolan.github.io/jq/manual/#Builtinoperatorsandfunctions) + +set_connection +-------------- + +Kurtosis uses a *default connection* to configure networking for any created subnetwork. +The `set_connection` can be used for two purposes: + +1. Used with the `subnetworks` argument, it will override the default connection between the two specified [subnetworks][subnetworks-reference]. + +```python +set_connection( + # The subnetwork connection that will be be overridden + # OPTIONAL: See 2. below + subnetworks = ("subnetwork_1", "subnetwork_2"), + + # The configuration for this connection. See the 'ConnectionConfig' section of 'Starlark Types' from the sidecar for more information. + # MANDATORY + config = connection_config, +) +``` + +2. Used with only the `config` argument, it will update the *default connection*. + +:::caution + +Doing so will _immediately_ affect all subnetwork connections that were not previously overridden. + +::: + +```python +set_connection( + # The configuration for this connection. See the 'ConnectionConfig' section of 'Starlark Types' from the sidecar for more information. + # MANDATORY + config = connection_config, +) +``` + +See [ConnectionConfig][starlark-types-connection-config] for more information on the mandatory `config` argument. + +:::important + +Say we are overriding a connection between two subnetworks, as shown below: + +```python + +connection_config = ConnectionConfig( + packet_delay_distribution = UniformPacketDelayDistribution( + ms = 500, + ), +) + +set_connection( + subnetworks = ("subnetworkA", "subnetworkB"), + config = connection_config, +) + +``` +If serviceA is in subnetworkA and serviceB is in subnetworkB, the effective latency for a TCP request between serviceA and serviceB will be 1000ms = 500ms x 2. This is because the latency is applied to both the request (serviceA -> serviceB) and the response (serviceB -> serviceA) +::: + +start_service +------------- + +The `start_service` instruction restarts a service that was stopped temporarily by [`stop_service`][stop-service]. + +```python +plan.start_service( + # The service name of the service to be restarted. + # MANDATORY + name = "my_service", +) +``` + +:::caution + +`start_service` is only available with the Docker backend. + +::: + + +stop_service +------------ + +The `stop_service` instruction stops a service temporarily. The container ends but its configuration stays around so it can be restarted quickly using [`start_service`][start-service]. + +```python +plan.stop_service( + # The service name of the service to be stopped. + # MANDATORY + name = "my_service", +) +``` + +:::caution + +`stop_service` is only available with the Docker backend. + +::: + +store_service_files +------------------- + +The `store_service_files` instruction copies files or directories from an existing service in the enclave into a [files artifact][files-artifacts-reference]. This is useful when work produced on one container is needed elsewhere. + +```python +artifact_name = plan.store_service_files( + # The service name of a preexisting service from which the file will be copied. + # MANDATORY + service_name = "example-service-name", + + # The path on the service's container that will be copied into a files artifact. + # MANDATORY + src = "/tmp/foo", + + # The name to give the files artifact that will be produced. + # If not specified, it will be auto-generated. + # OPTIONAL + name = "my-favorite-artifact-name", +) +``` + +The return value is a [future reference][future-references-reference] to the name of the [files artifact][files-artifacts-reference] that was generated, which can be used with the `files` property of the service config of the `add_service` command. + +update_service +-------------- + +The `update_service` instruction updates an existing service without restarting it. For now, only the [service subnetwork][subnetworks-reference] can be updated live. In this case, the service will be moved to the corresponding subnetwork. + +```python +update_service( + # A Service name designating a service that already exists inside the enclave + # If it does not, a validation error will be thrown + # MANDATORY + name = "example-datastore-server-1", + + # The changes to apply to this service. See the 'UpdateServiceConfig' section of 'Starlark Types' from the sidecar for more information. + # MANDATORY + config = update_service_config, +) +``` + +See [UpdateServiceConfig][starlark-types-update-service-config] for more information on the mandatory `config` argument. + +upload_files +------------ + +`upload_files` instruction packages the files specified by the [locator][locators-reference] into a [files artifact][files-artifacts-reference] that gets stored inside the enclave. This is particularly useful when a static file needs to be loaded to a service container. + +```python +artifact_name = plan.upload_files( + # The file to upload into a files artifact + # Must be a Kurtosis locator. + # MANDATORY + src = "github.com/foo/bar/static/example.txt", + + # The name to give the files artifact that will be produced. + # If not specified, it will be auto-generated. + # OPTIONAL + name = "my-artifact", +) +``` + +The return value is a [future reference][future-references-reference] to the name of the [files artifact][files-artifacts-reference] that was generated, which can be used with the `files` property of the service config of the `add_service` command. + +wait +---- + +The `wait` instruction fails the Starlark script or package with an execution error if the provided [assertion][assert] does not succeed within a given period of time. If the assertion succeeds, `wait` returns a [future references][future-references-reference] with the result the last run of the assertion. + +This instruction is best used for asserting the system has reached a desired state, e.g. in testing. To wait until a service is ready, you are better off using automatic port availability waiting via [`PortSpec.wait`][starlark-types-port-spec] or [`ServiceConfig.ready_conditions`][starlark-types-update-service-config], as these will short-circuit a parallel [`add_services`][add-services] call if they fail. + +To learn more about the accepted recipe types, please see [`ExecRecipe`][starlark-types-exec-recipe], [`GetHttpRequestRecipe`][starlark-types-get-http-recipe] or [`PostHttpRequestRecipe`][starlark-types-post-http-recipe]. + + +```python +# This fails in runtime if response["code"] != 200 for each request in a 5 minute time span +response = plan.wait( + # A Service name designating a service that already exists inside the enclave + # If it does not, a validation error will be thrown + # MANDATORY + service_name = "example-datastore-server-1", + + # The recipe that will be run until assert passes. + # Valid values are of the following types: (ExecRecipe, GetHttpRequestRecipe, PostHttpRequestRecipe) + # MANDATORY + recipe = recipe, + + # Wait will use the response's field to do the asssertions. To learn more about available fields, + # that can be used for assertions, please refer to exec and request instructions. + # MANDATORY + field = "code", + + # The assertion is the comparison operation between value and target_value. + # Valid values are "==", "!=", ">=", "<=", ">", "<" or "IN" and "NOT_IN" (if target_value is list). + # MANDATORY + assertion = "==", + + # The target value that value will be compared against. + # MANDATORY + target_value = 200, + + # The interval value is the initial interval suggestion for the command to wait between calls + # It follows a exponential backoff process, where the i-th backoff interval is rand(0.5, 1.5)*interval*2^i + # Follows Go "time.Duration" format https://pkg.go.dev/time#ParseDuration + # OPTIONAL (Default: "1s") + interval = "1s", + + # The timeout value is the maximum time that the command waits for the assertion to be true + # Follows Go "time.Duration" format https://pkg.go.dev/time#ParseDuration + # OPTIONAL (Default: "10s") + timeout = "5m", +) +# If this point of the code is reached, the assertion has passed therefore the print statement will print "200" +plan.print(response["code"]) +``` + + + +[add-service]: #add_service +[add-services]: #add_services +[assert]: #assert +[extract]: #extract +[set-connection]: #set_connection +[start-service]: #start_service +[stop-service]: #stop_service +[wait]: #wait + +[cli-run-reference]: ../cli-reference/run-starlark.md + +[files-artifacts-reference]: ../concepts-reference/files-artifacts.md +[future-references-reference]: ../concepts-reference/future-references.md +[packages-reference]: ../concepts-reference/packages.md +[locators-reference]: ../concepts-reference/locators.md +[multi-phase-runs-reference]: ../concepts-reference/multi-phase-runs.md +[ready-condition]: ./ready-condition.md +[service-config]: ./service-config.md +[subnetworks-reference]: ../concepts-reference/subnetworks.md + +[starlark-types-connection-config]: ./connection-config.md +[starlark-types-service-config]: ./service-config.md +[starlark-types-update-service-config]: ./update-service-config.md +[starlark-types-exec-recipe]: ./exec-recipe.md +[starlark-types-post-http-recipe]: ./post-http-request-recipe.md +[starlark-types-get-http-recipe]: ./get-http-request-recipe.md +[service-starlark-reference]: ./service.md +[starlark-types-port-spec]: ./port-spec.md diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/port-spec.md b/docs/versioned_docs/version-0.78.3/starlark-reference/port-spec.md new file mode 100644 index 0000000000..39a99b8e53 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/port-spec.md @@ -0,0 +1,44 @@ +--- +title: PortSpec +sidebar_label: PortSpec +--- + +The `PortSpec` constructor creates a `PortSpec` object that encapsulates information pertaining to a port. + +```python +port_spec = PortSpec( + # The port number which we want to expose + # MANDATORY + number = 3000, + + # Transport protocol for the port (can be either "TCP" or "UDP") + # OPTIONAL (DEFAULT:"TCP") + transport_protocol = "TCP", + + # Application protocol for the port that will be displayed in front of URLs containing the port + # For example: + # "http" to get a URL of "http://..." + # "postgresql" to get a URL of "postgresql://..." + # OPTIONAL (DEFAULT:"http") + application_protocol = "http", + + # Kurtosis will automatically perform a check to ensure all declared UDP and TCP ports are open and ready for traffic and connections upon startup. + # You may specify a custom wait timeout duration or disable the feature entirely. + # You may specify a custom wait timeout duration with a string: + # wait = "2m" + # Or, you can disable this feature by setting the value to None: + # wait = None + # The feature is enabled by default with a default timeout of 15s + # OPTIONAL (DEFAULT:"15s") + wait = "4s" +) +``` +The above constructor returns a `PortSpec` object that defines information about a port for use in [`add_service`](../concepts-reference/subnetworks.md). + +The `wait` field represents the timeout duration that Kurtosis will use when checking whether or not a service's declared UDP or TCP port are open and ready for traffic and connections upon startup. This is the default way to perform a readiness check using Kurtosis. However, there are other ways to perform a readiness check. Specifically, you can also use [`ServiceConfig.ReadyConditions`][ready-conditions] to check if a service is ready with a a REST call, or you can use the [Wait][wait] instruction if you need to perform a one-off readiness check after service startup. + + +[future-references-reference]: ../concepts-reference/future-references.md +[add-service-reference]: ./plan.md#add_service +[ready-conditions]: ./ready-condition.md +[wait]: ./plan.md#wait diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/post-http-request-recipe.md b/docs/versioned_docs/version-0.78.3/starlark-reference/post-http-request-recipe.md new file mode 100644 index 0000000000..1481ee043a --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/post-http-request-recipe.md @@ -0,0 +1,43 @@ +--- +title: PostHttpRequestRecipe +sidebar_label: PostHttpRequestRecipe +--- + +The `PostHttpRequestRecipe` can be used to make `POST` requests to an endpoint. + +```python +post_request_recipe = PostHttpRequestRecipe( + # The port ID that is the server port for the request + # MANDATORY + port_id = "my_port", + + # The endpoint for the request + # MANDATORY + endpoint = "/endpoint", + + # The content type header of the request (e.g. application/json, text/plain, etc) + # OPTIONAL (DEFAULT:"application/json") + content_type = "application/json", + + # The body of the request + # OPTIONAL (DEFAULT:"") + body = "{\"data\": \"this is sample body for POST\"}", + + # The extract dictionary takes in key-value pairs where: + # Key is a way you refer to the extraction later on + # Value is a 'jq' string that contains logic to extract from response body + # # To lean more about jq, please visit https://devdocs.io/jq/ + # OPTIONAL (DEFAULT:{}) + extract = { + "extractfield" : ".name.id", + }, +) +``` + +:::caution + +Make sure that the endpoint returns valid JSON response for both POST and GET requests. + +::: + + diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/read-file.md b/docs/versioned_docs/version-0.78.3/starlark-reference/read-file.md new file mode 100644 index 0000000000..27dc261cb8 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/read-file.md @@ -0,0 +1,19 @@ +--- +title: read_file +sidebar_label: read_file +--- + +The `read_file` function reads the contents of a file specified by the given [locator][locators-reference], and requires that the Starlark script is part of a [package][packages-reference]. `read_file` executes [at interpretation time][multi-phase-runs-reference] so the file contents won't be displayed in the preview. + +```python +contents = read_file( + # The Kurtosis locator of the file to read. + # MANDATORY + src = "github.com/kurtosis-tech/datastore-army-package/README.md", +) +``` + + +[locators-reference]: ../concepts-reference/locators.md +[multi-phase-runs-reference]: ../concepts-reference/multi-phase-runs.md +[packages-reference]: ../concepts-reference/packages.md diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/ready-condition.md b/docs/versioned_docs/version-0.78.3/starlark-reference/ready-condition.md new file mode 100644 index 0000000000..7defa0e7c4 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/ready-condition.md @@ -0,0 +1,88 @@ +--- +title: ReadyCondition +sidebar_label: ReadyCondition +--- + +The `ReadyCondition` can be used to execute a readiness check after a service is started to confirm that it is ready to receive connections and traffic. + +As you will see below, using `ReadyCondition` is a flexible and highly configurable way to define a readiness check for a given service. However, if all you need is a check upon service startup for whether or not a port is open and ready for traffic, then we recommend relying on the default `wait` field in the [PortSpec constructor][port-spec] (as part of the [ServiceConfig][service-config] type). + +```python +ready_conditions = ReadyCondition( + + # The recipe that will be used to check service's readiness. + # Valid values are of the following types: (ExecRecipe, GetHttpRequestRecipe or PostHttpRequestRecipe) + # MANDATORY + recipe = GetHttpRequestRecipe( + port_id = "http", + endpoint = "/ping", + ), + + # The `field's value` will be used to do the asssertions. To learn more about available fields, + # that can be used for assertions, please refer to exec and request instructions. + # MANDATORY + field = "code", + + # The assertion is the comparison operation between value and target_value. + # Valid values are "==", "!=", ">=", "<=", ">", "<" or "IN" and "NOT_IN" (if target_value is list). + # MANDATORY + assertion = "==", + + # The target value that value will be compared against. + # MANDATORY + target_value = 200, + + # The interval value is the initial interval suggestion for the command to wait between calls + # It follows a exponential backoff process, where the i-th backoff interval is rand(0.5, 1.5)*interval*2^i + # Follows Go "time.Duration" format https://pkg.go.dev/time#ParseDuration + # OPTIONAL (Default: "1s") + interval = "1s", + + # The timeout value is the maximum time that the readiness check waits for the assertion to be true + # Follows Go "time.Duration" format https://pkg.go.dev/time#ParseDuration + # OPTIONAL (Default: "15m") + timeout = "5m", +) +``` + +An example of using `ReadyCondition`: + +```python +def run(plan): + # we define the recipe first + get_recipe = GetHttpRequestRecipe( + port_id = "http-port", + endpoint = "?input=foo/bar", + extract = { + "exploded-slash": ".query.input | split(\"/\") | .[1]" + } + ) + + # then the ready conditions using the ReadyCondition type which contain the recipe already created + ready_conditions_config = ReadyCondition( + recipe = get_recipe, + field = "code", + assertion = "==", + target_value = 200, + interval = "10s", + timeout = "200s", + ) + + # we set the ready conditions in the ServiceConfig + service_config = ServiceConfig( + image = "mendhak/http-https-echo:26", + ports = { + "http-port": PortSpec(number = 8080, transport_protocol = "TCP") + }, + ready_conditions= ready_conditions_config, + ) + + # finally we execute the add_service instruction using all the pre-configured data + plan.add_service(name = "web-server", config = service_config) +``` + + + +[service-config]: ./service-config.md +[port-spec]: ./port-spec.md +[wait]: ./plan.md#wait diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/service-config.md b/docs/versioned_docs/version-0.78.3/starlark-reference/service-config.md new file mode 100644 index 0000000000..81d21a1c91 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/service-config.md @@ -0,0 +1,118 @@ +--- +title: ServiceConfig +sidebar_label: ServiceConfig +--- + +The `ServiceConfig` is used to configure a service when it is added to an enclave (see [add_service][add-service-reference]). + +```python +config = ServiceConfig( + # The name of the container image that Kurtosis should use when creating the service’s container. + # MANDATORY + image = "kurtosistech/example-datastore-server", + + # The ports that the container should listen on, identified by a user-friendly ID that can be used to select the port again in the future. + # If no ports are provided, no ports will be exposed on the host machine, unless there is an EXPOSE in the Dockerfile + # OPTIONAL (Default: {}) + ports = { + "grpc": PortSpec( + # The port number which we want to expose + # MANDATORY + number = 3000, + + # Transport protocol for the port (can be either "TCP" or "UDP") + # Optional (DEFAULT:"TCP") + transport_protocol = "TCP", + + # Application protocol for the port + # Optional + application_protocol = "http", + ), + }, + + # A mapping of path_on_container_where_contents_will_be_mounted -> files_artifact_id_to_mount + # For more info on what a files artifact is, see below + # OPTIONAL (Default: {}) + files = { + "path/to/file/1": files_artifact_1, + "path/to/file/2": files_artifact_2, + }, + + # The ENTRYPOINT statement hardcoded in a container image's Dockerfile might not be suitable for your needs. + # This field allows you to override the ENTRYPOINT when the container starts. + # OPTIONAL (Default: []) + entrypoint = [ + "bash", + ], + + # The CMD statement hardcoded in a container image's Dockerfile might not be suitable for your needs. + # This field allows you to override the CMD when the container starts. + # OPTIONAL (Default: []) + cmd = [ + "-c", + "sleep 99", + ], + + # Defines environment variables that should be set inside the Docker container running the service. + # This can be necessary for starting containers from Docker images you don’t control, as they’ll often be parameterized with environment variables. + # OPTIONAL (Default: {}) + env_vars = { + "VAR_1": "VALUE_1", + "VAR_2": "VALUE_2", + }, + + # ENTRYPOINT, CMD, and ENV variables sometimes need to refer to the container's own IP address. + # If this placeholder string is referenced inside the 'entrypoint', 'cmd', or 'env_vars' properties, the Kurtosis engine will replace it at launch time + # with the container's actual IP address. + # OPTIONAL (Default: "KURTOSIS_IP_ADDR_PLACEHOLDER") + private_ip_address_placeholder = "KURTOSIS_IP_ADDRESS_PLACEHOLDER", + + # The maximum amount of CPUs the service can use, in millicpu/millicore. + # OPTIONAL (Default: no limit) + max_cpu = 1000, + + # The mimimum amout of CPUs the service must have, in millicpu/millicore. + # CAUTION: This is only available for Kubernetes, and will be ignored for Docker. + # OPTIONAL (Default: no limit) + min_cpu = 500, + + # The maximum amount of memory, in megabytes, the service can use. + # OPTIONAL (Default: no limit) + max_memory = 1024, + + # The minimum amount of memory, in megabytes, the service must have. + # CAUTION: This is only available for Kubernetes, and will be ignored for Docker. + # OPTIONAL (Default: no limit) + min_memory = 512, + + # Defines the subnetwork in which the service will be started. + # OPTIONAL (Default: "default") + subnetwork = "service_subnetwork", + + # This field can be used to check the service's readiness after the service has started, + # to confirm that it is ready to receive connections and traffic + # OPTIONAL (Default: no ready conditions) + ready_conditions = ReadyCondition(...) +) +``` +The `ports` dictionary argument accepts a key value pair, where `key` is a user defined unique port identifier and `value` is a [PortSpec][port-spec] object. + +The `files` dictionary argument accepts a key value pair, where `key` is the path where the contents of the artifact will be mounted to and `value` is a file artifact name. (see [upload_files][upload-files-reference], [render_templates][render-templates-reference] and [store_service_files][store-service-reference] to learn more about on how to create file artifacts) + +For more info about the `subnetwork` argument, see [Kurtosis subnetworks][subnetworks-reference]. + +You can view more information on [configuring the `ReadyCondition` type here][ready-condition]. + +:::tip +If you are trying to use a more complex versions of `cmd` and are running into issues, we recommend using `cmd` in combination with `entrypoint`. You can +set the `entrypoint` to `["/bin/sh", "-c"]` and then set the `cmd` to the command as you would type it in your shell. For example, `cmd = ["echo foo | grep foo"]` +::: + + +[add-service-reference]: ./plan.md#add_service +[port-spec]: ./port-spec.md +[upload-files-reference]: ./plan.md#upload_files +[render-templates-reference]: ./plan.md#render_templates +[store-service-reference]: ./plan.md#store_service_files +[subnetworks-reference]: ../concepts-reference/subnetworks.md +[ready-condition]: ./ready-condition.md diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/service.md b/docs/versioned_docs/version-0.78.3/starlark-reference/service.md new file mode 100644 index 0000000000..7024aad037 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/service.md @@ -0,0 +1,40 @@ +--- +title: Service +sidebar_label: Service +--- + +The `Service` object encapsulates service information returned by the [`Plan.add_service`][add-service-starlark-reference] and [`Plan.add_services`][add-services-starlark-reference] functions. + +It has the following properties (all of which are [future references][future-references-concepts-reference], because [runtime values don't exist at interpretation time][multi-phase-runs-concepts-reference]): + +```python +# The hostname of the service +service.hostname + + +# The IP address of the service +service.ip_address + + +# The name of the service +service.name + + +# A dictionary of port IDs -> PortSpec objects, as specified in the "ports" field +# of the ServiceConfig used to create the service +# (see the PortSpec and ServiceConfig entries in the sidebar for more information) +service.ports + +# For example: +some_port_spec = service.ports["some-port-id"] +``` + +Note that you cannot manually create a `Service` object; it is only returned by Kurtosis via `Plan.add_service` and `Plan.add_services`. + + + +[add-service-starlark-reference]: ./plan.md#add_service +[add-services-starlark-reference]: ./plan.md#add_services + +[future-references-concepts-reference]: ../concepts-reference/future-references.md +[multi-phase-runs-concepts-reference]: ../concepts-reference/multi-phase-runs.md diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/standard-library.md b/docs/versioned_docs/version-0.78.3/starlark-reference/standard-library.md new file mode 100644 index 0000000000..aa2b85ca94 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/standard-library.md @@ -0,0 +1,14 @@ +--- +title: Standard Library +sidebar_label: Standard Library +sidebar_position: 2 +--- + +The following Starlark libraries are available in Kurtosis by default: + +1. The Starlark [time](https://github.com/google/starlark-go/blob/master/lib/time/time.go#L18-L52) module (a collection of time-related functions) +2. The Starlark [json](https://github.com/google/starlark-go/blob/master/lib/json/json.go#L28-L74) module (allows `encode`, `decode` and `indent` JSON) +4. The Starlark [struct](https://github.com/google/starlark-go/blob/master/starlarkstruct/struct.go) builtin (allows you to create `structs` like the one used in [`add_service`][add-service-reference]) + + +[add-service-reference]: ./plan.md#add_services diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/uniform-packet-delay-distribution.md b/docs/versioned_docs/version-0.78.3/starlark-reference/uniform-packet-delay-distribution.md new file mode 100644 index 0000000000..e06ed9bdb8 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/uniform-packet-delay-distribution.md @@ -0,0 +1,21 @@ +--- +title: UniformPacketDelayDistribution +sidebar_label: UniformPacketDelayDistribution +--- + +The `UniformPacketDelayDistribution` creates a packet delay distribution with constant delay in `ms`. This can be used in conjuction with [`ConnectionConfig`][connection-config] to introduce latency between two [`subnetworks`][subnetworks-reference]. See [`set_connection`][set-connection-reference] instruction to learn more about its usage. + +```python + +delay = UniformPacketDelayDistribution( + # Non-Negative Integer + # Amount of constant delay added to outgoing packets from the subnetwork + # MANDATORY + ms = 1000, +) +``` + + +[connection-config]: ./connection-config.md +[subnetworks-reference]: ../concepts-reference/subnetworks.md +[set-connection-reference]: ./plan.md#set_connection diff --git a/docs/versioned_docs/version-0.78.3/starlark-reference/update-service-config.md b/docs/versioned_docs/version-0.78.3/starlark-reference/update-service-config.md new file mode 100644 index 0000000000..13daab5db2 --- /dev/null +++ b/docs/versioned_docs/version-0.78.3/starlark-reference/update-service-config.md @@ -0,0 +1,19 @@ +--- +title: UpdateServiceConfig +sidebar_label: UpdateServiceConfig +--- + +The `UpdateServiceConfig` contains the attributes of [ServiceConfig][service-config] that are live-updatable. For now, only the [`subnetwork`][subnetworks-reference] attribute of a service can be updated once the service is started. + +```python +update_service_config = UpdateServiceConfig( + # The subnetwork to which the service will be moved. + # "default" can be used to move the service to the default subnetwork + # MANDATORY + subnetwork = "subnetwork_1", +) +``` + + +[service-config]: ./service-config.md +[subnetworks-reference]: ../concepts-reference/subnetworks.md diff --git a/docs/versioned_sidebars/version-0.78.3-sidebars.json b/docs/versioned_sidebars/version-0.78.3-sidebars.json new file mode 100644 index 0000000000..57ab50ac97 --- /dev/null +++ b/docs/versioned_sidebars/version-0.78.3-sidebars.json @@ -0,0 +1,78 @@ +{ + "main": [ + "home", + { + "type": "link", + "label": "Kurtosis for Web3", + "href": "https://web3.kurtosis.com" + }, + "quickstart", + { + "type": "category", + "label": "Guides", + "collapsed": true, + "items": [ + { + "type": "autogenerated", + "dirName": "guides" + } + ] + }, + { + "type": "category", + "label": "Explanations", + "collapsed": true, + "items": [ + { + "type": "autogenerated", + "dirName": "explanations" + } + ] + }, + { + "type": "category", + "label": "CLI Reference", + "collapsed": true, + "link": { + "type": "doc", + "id": "cli-reference/index" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "cli-reference" + } + ] + }, + { + "type": "category", + "label": "Starlark Reference", + "collapsed": true, + "link": { + "type": "doc", + "id": "starlark-reference/index" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "starlark-reference" + } + ] + }, + { + "type": "category", + "label": "Concepts Reference", + "collapsed": true, + "items": [ + { + "type": "autogenerated", + "dirName": "concepts-reference" + } + ] + }, + "sdk", + "best-practices", + "package-index", + "changelog" + ] +} diff --git a/docs/versions.json b/docs/versions.json index 0349349dc6..9032e4d9c7 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "0.78.3", "0.78.2", "0.78.1", "0.78.0",